Overview¶
This guide describes how to reference other custom VC-Shell applications to incorporate their logic into your custom app. It also explores various techniques for extending components, composables, and other essential logic.
This guide covers the following key steps:
- Incorporating and setting up custom application.
- Replacing API clients used by other custom applications.
- Extending other apps views using dynamic views.
- Extending composables.
In this guide, we'll use the example of the vc-app-extend
project, which extends the functionality of the vc-app
project from the sample
folder.
Incorporate and set up custom applications¶
All applications developed on the VC-Shell framework can seamlessly become part of other custom applications, allowing you to reuse or override key elements such as navigation menu items, API clients, blades, composables, UI components, and more.
To include and set up custom applications:
-
Reference custom application. In our example, we add:
- Reference to the
vc-app
, representing the application to extend. Offers
, representing the module.
vc-app-extend/src/main.ts - Reference to the
-
Verify the result:
Now you have successfully incorporated and set up the custom application. Your custom app can now leverage the modules and functionalities of the vc-app
, providing you with the flexibility to extend and customize your application as needed.
Using modules from other applications
Replace API Clients used by other custom applications¶
When referencing other applications, you might need to access new fields or functionalities in TypeScript strongly typed API clients. In some scenarios, when you are extending the Virtocommerce REST API used by a referenced application (as explained in our domain model extension article), you may need to access new fields or functionalities. If the same API type is used by the application you are referencing, you can regenerate the API client to include these changes.
Note
Before replacing the original API types used by @vc-app with updated ones, it might be useful to understand how Vite aliases work. Vite aliases provide a mechanism to replace the original API types used by the @vc-app
with updated ones. For more information about aliases in Vite, refer to the Vite documentation.
To replace the original API types used by @vc-app
with updated ones, generate the API client using the vc-shell/api-client-generator package:
-
Add the API generator as a development dependency using the following command:
Note
Alternatively, you can manually add
"@vc-shell/api-client-generator"
and"cross-env"
as development dependencies in your package.json file.cross-env is a tool that sets and uses environment variables across platforms.
-
Add a script to the
scripts
section of your application's package.json file: -
Set the
APP_PLATFORM_URL
in your project's .env file. -
Execute the command to generate the API client:
You can now use the generated API client in your custom application.
Example changes after API client generation¶
After generating the API client for your @vc-app-extend
application, you can see the following changes in the Offer
class:
-
Original
@vc-app
application Offer class: -
Generated API client Offer class for
vc-app-extend
application:
This demonstrates that the Offer class in the @vc-app-extend
application now includes an additional field newField
, which was not present in the original @vc-app application
's Offer class.
Override command processing logic¶
To customize your applications to specific requirements, you can customize the command processing logic. This involves overriding default behaviors. The modules underlying your application rely on API client packages as peerDependencies. To replace the API they use, add an alias to your main application's Vite configuration file, vite.config.ts
:
vc-app-extend/vite.config.ts | |
---|---|
Now other custom application modules use your generated API.
Extend other apps views using dynamic views¶
You can enhance the interactivity and functionality of your applications by adding new buttons and controls to forms, extending the user interface. If the referenced application uses blades built on dynamic views , you can extend these views with new UI elements, including fields, forms, lists, and more, without the need to directly modify the source code of the application you are extending.
In the example below, we focus on the Offers
module, along with the useOffersList
and useOfferDetails
composables that we are extending. Let's add a control that will display data from a new field of the generated API client.
-
Define overrides:
-
Add overrides to
createDynamicAppModule
: -
Initialize the extended module:
-
Verify the result:
This process allows you to seamlessly extend views from the referenced application without the need to directly modify the source code, providing flexibility in customizing your application.
Using dynamic view for extending views from the other apps
Extend composables¶
Composables are functions with an internal state that changes over time and methods that modify this state. You cannot directly modify the state. The only way to change the state is by calling one of the composable's methods. However, because the state is reactive, thanks to Vue's Composition API, you can watch and react to these changes when necessary to update the UI or perform other operations.
This pattern encapsulates the state and business logic and exposes it through easy-to-use methods.
In most cases, the composables defined in the referenced app and bound to specific blades are reusable and shareable across various applications. For example, the useOffer
composable defined in the Vendor Portal application can be extended with new methods or logic in another custom app.
Example¶
To illustrate composable extension, let's add a button to the toolbar:
-
Define overrides:
-
Extend the composable:
-
Integrate the extended composable:
-
Verify the result: