diff --git a/mkdocs.yml b/mkdocs.yml index bf25c9e3c1..cfabb32e50 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -540,7 +540,7 @@ extra: - title: Getting Started url: /platform/developer-guide/latest/custom-apps-development/vc-shell/Getting-started/creating-first-custom-app/ - title: Connecting to Platform - url: /platform/developer-guide/latest/custom-apps-development/vc-shell/How-tos/Connecting-to-Platform/ + url: /platform/developer-guide/latest/custom-apps-development/vc-shell/Guides/creating-custom-applications/#initial-configuration - title: Deployment on Virto Cloud content: - links: diff --git a/platform/developer-guide/docs/Fundamentals/Modularity/06-module-manifest-file.md b/platform/developer-guide/docs/Fundamentals/Modularity/06-module-manifest-file.md index 1d6c3ab1b4..0f8e3a09c7 100644 --- a/platform/developer-guide/docs/Fundamentals/Modularity/06-module-manifest-file.md +++ b/platform/developer-guide/docs/Fundamentals/Modularity/06-module-manifest-file.md @@ -132,12 +132,11 @@ The **module.manifest** file can be configured using a number of required and op -## Adding new app +## Apps section -To add a new web, add the app section into the **module.manifest** file: +Apps are entries that show up in the Platform's **Apps** menu. Each app declares its identity, icon, and permission inside the `` section of **module.manifest**. The Platform serves the app's static content from the deployed module and binds it to the `/apps/[id]` URL. -```xml -... +```xml title="module.manifest" Reports @@ -146,17 +145,26 @@ To add a new web, add the app section into the **module.manifest** file: PowerBiReports:access -... ``` -You can use the following attributes: +### App attributes -* `id`: A unique identifier for the app, which distinguishes it from other apps in the system. -* `title`: The name or title of the app that is displayed to the users. -* `description`: A short description of the app that gives users an overview of what the app does and its purpose. -* `iconUrl`: The URL or path to the app's icon or logo used to identify the app in the system. -* `permission`: The permissions or access rights required to use the app, which are used to control who can access the app and its features. -* `contentPath`: The default path to the app's content specifying where the app's files are stored. If the ContentPath is set to `[VcModuleWeb]/Content/[Id]`, the app's content is stored in the **Content** folder of the **VcModuleWeb** module, with the app's Id appended to the end of the path. +| Attribute | Description | +| --- | --- | +| `id` | A unique app identifier within the Platform. Becomes part of the runtime URL `/apps/[id]`. | +| `title` | The name shown to users in the Apps menu. | +| `description` | A short description shown next to the title. | +| `iconUrl` | The URL or path to the app's icon. Typically `/apps/[id]/` for assets shipped with the app, or `Modules/$(ModuleId)/Content/` for module-level icons. | +| `permission` | The permission a user must have to see and open the app. | +| `contentPath` | Optional override for the path to the app's content, relative to the module's install directory. When omitted, the Platform serves the app from **Content/[id]** and throws a module initialization error if the folder is missing. | +| `supportEmbeddedMode` | Optional. When `true`, allows the app to be opened inside the AngularJS-based back office in embedded mode. See [Enabling Embedded Mode for VC-Shell Instances](../../Tutorials-and-How-tos/How-tos/enable-embedded-mode-for-vc-shell.md). | + +### Registration procedures + +Two registration paths exist depending on what kind of app you ship: + +* [Register your own app](../../custom-apps-development/register-your-own-app.md): For custom back-office apps you build yourself, packaged into a module via the Virto Commerce CLI (vc-build). VC-Shell is the recommended framework, but other frontend toolchains, such as Vue, React, or Angular, are also supported. +* [Register a third-party app](../../custom-apps-development/register-third-party-app.md): For Apps menu entries that hand the user off to an external service via a static redirect, for example, the [Power BI Reports module](https://github.com/VirtoCommerce/vc-module-power-bi-reports). diff --git a/platform/developer-guide/docs/custom-apps-development/how-to-register-new-app.md b/platform/developer-guide/docs/custom-apps-development/how-to-register-new-app.md deleted file mode 100644 index 306da85f89..0000000000 --- a/platform/developer-guide/docs/custom-apps-development/how-to-register-new-app.md +++ /dev/null @@ -1,72 +0,0 @@ -# How to Register New App - -Using the Reports application as an example, let's look at the application installation process. - -## Prerequisites - -Before adding a new web app, make sure the following prerequisites have been installed: - -* [Virto Commerce Platform 3.264+](https://github.com/VirtoCommerce/vc-platform) -* [Virto Commerce CLI (VC-BUILD) 3.12+](https://github.com/VirtoCommerce/vc-build) -* [VC-Shell framework](https://github.com/VirtoCommerce/vc-shell) - -## Registration process - -To register a new app: - -1. Add a web app in the [module.manifest](../Fundamentals/Modularity/06-module-manifest-file.md): - - 1. Add the app section in the **module.manifest**. - - ```xml - ... - - - Reports - Power BI Commerce Reports - /apps/reports/power_bi_logo.svg - PowerBiReports:access - - - ... - ``` - -
Attributes description - - | `id` | A unique identifier for the app, which distinguishes it from other apps in the system. | - |---------------- |---------------------------------------------------------------------------------------------- | - | `title` | The name or title of the app that is displayed to the users. | - | `description` | A short description of the app that gives users an overview of what the app does and its purpose.| - | `iconUrl` | The URL or path to the app's icon or logo used to identify the app in the system. | - | `permission` | The permissions or access rights required to use the app, which are used to control
who can access the app and its features. | - | `contentPath` | The default path to the app's content, which is used to specify where the app's files
are stored and accessed. In this example, the ContentPath is set to [VcModuleWeb]/Content/[Id],
which means that the app's content will be stored in the Content folder of the VcModuleWeb module,
with the app's Id appended to the end of the path. | - -
- - 1. Open Platform. - 1. Click ![Dots](media/nine-dots-icon1.png){: width="25"} in the top left corner. - 1. Find the added app. - - ![image](media/app-menu-2.png) - -1. Create Content/[app_id] folder in the web project. Virto Commerce reads the manifest and adds binding to this folder. You can put any web content here. It can be a VC-Shell or any other HTML application. - - ```xml - vc-module-power-bi-reports\src\VirtoCommerce.PowerBiReports.Web\Content\reports - ``` - - ![image](media/app-folder.png) - -1. Build, compress, and deploy. Use the Virto Commerce CLI (vc-build) to create a module package. - - ![image](media/vc-build.png) - -1. Invoke Rest API. Virto Commerce provides an API to returns list of available apps. - - ```ps - curl -X GET "https://mycustomdomain.com/api/platform/apps" -H "accept: text/plain" - ``` - - ![image](media/rest-api.png) - -New app is ready to go. diff --git a/platform/developer-guide/docs/custom-apps-development/media/pagebuilder-app-in-rest-api.png b/platform/developer-guide/docs/custom-apps-development/media/pagebuilder-app-in-rest-api.png new file mode 100644 index 0000000000..368650b05b Binary files /dev/null and b/platform/developer-guide/docs/custom-apps-development/media/pagebuilder-app-in-rest-api.png differ diff --git a/platform/developer-guide/docs/custom-apps-development/media/pagebuilder-compress.png b/platform/developer-guide/docs/custom-apps-development/media/pagebuilder-compress.png new file mode 100644 index 0000000000..ea310bad9b Binary files /dev/null and b/platform/developer-guide/docs/custom-apps-development/media/pagebuilder-compress.png differ diff --git a/platform/developer-guide/docs/custom-apps-development/media/pagebuilder-in-menu.png b/platform/developer-guide/docs/custom-apps-development/media/pagebuilder-in-menu.png new file mode 100644 index 0000000000..73e76e462c Binary files /dev/null and b/platform/developer-guide/docs/custom-apps-development/media/pagebuilder-in-menu.png differ diff --git a/platform/developer-guide/docs/custom-apps-development/media/pagebuilder-web-project.png b/platform/developer-guide/docs/custom-apps-development/media/pagebuilder-web-project.png new file mode 100644 index 0000000000..36108a256a Binary files /dev/null and b/platform/developer-guide/docs/custom-apps-development/media/pagebuilder-web-project.png differ diff --git a/platform/developer-guide/docs/custom-apps-development/register-third-party-app.md b/platform/developer-guide/docs/custom-apps-development/register-third-party-app.md new file mode 100644 index 0000000000..54f2cbc128 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/register-third-party-app.md @@ -0,0 +1,122 @@ +# Register a Third-Party App + +A third-party app is an entry in the Platform's **Apps** menu that hands the user off to an external service instead of opening a custom-built application. The Platform binds **Content/[app_id]** to the `/apps/[app_id]` URL, so a tiny static **index.html** in that folder can redirect the browser to a server-side endpoint or an external URL. + +The [Power BI Reports module](https://github.com/VirtoCommerce/vc-module-power-bi-reports) uses this pattern: its **Content/reports/index.html** issues a meta-refresh to **/api/power-bi-reports/redirect**, where a controller reads the configured Power BI URL and issues an HTTP redirect to it. + +If your goal is to ship a custom back-office app rather than launch an external service, see [Register your own app](register-your-own-app.md) instead. + +## Prerequisites + +Before adding a third-party app, make sure the following prerequisites have been installed: + +* [Virto Commerce Platform 3.264+](https://github.com/VirtoCommerce/vc-platform) +* [Virto Commerce CLI (VC-BUILD) 3.12+](https://github.com/VirtoCommerce/vc-build) + +## Registration steps + +To register a third-party app: + +1. [Declare the app in module.manifest](#declare-the-app-in-modulemanifest). +1. [Provide the redirect index.html](#provide-the-redirect-indexhtml). +1. [Build, package, and deploy](#build-package-and-deploy). +1. [Verify the app appears in the Apps menu](#verify-the-app-appears-in-the-apps-menu). + +### Declare the app in module.manifest + +Add an `` entry inside `` in **module.manifest**. For example: + +```xml title="module.manifest" + + + Reports + Power BI Commerce Reports + /apps/reports/power_bi_logo.svg + PowerBiReports:access + + +``` + +For a description of every supported attribute, see [Apps section in Module.manifest](../Fundamentals/Modularity/06-module-manifest-file.md#apps-section). + +### Provide the redirect index.html + +Create a **Content/[app_id]** folder in the Web project and place an **index.html** in it. + +Use a meta-refresh to forward the browser to your target URL. For example, to redirect to a controller endpoint that completes the integration server-side: + +```html title="src/VirtoCommerce.PowerBiReports.Web/Content/reports/index.html" + + + + + + Redirecting to Power BI Reports + + +

Redirecting to Power BI Reports...

+

If you are not redirected automatically, please click here.

+ + +``` + +![Folder layout](media/app-folder.png) + +The controller behind `/api/power-bi-reports/redirect` issues the final HTTP redirect: + +```csharp title="PowerBiReportsController.cs" +[Route("api/power-bi-reports")] +public class PowerBiReportsController : Controller +{ + private readonly ISettingsManager _settingsManager; + + public PowerBiReportsController(ISettingsManager settingsManager) + { + _settingsManager = settingsManager; + } + + [HttpGet] + [Route("redirect")] + [Authorize(ModuleConstants.Security.Permissions.Read)] + public ActionResult Redirect() + { + var redirectToPowerBIUrl = _settingsManager.GetValue(ModuleConstants.Settings.General.PowerBiReportsUrl); + + if (string.IsNullOrEmpty(redirectToPowerBIUrl)) + { + return NotFound("PowerBiReportsUrl is not configured in Platform Settings"); + } + + return Redirect(redirectToPowerBIUrl); + } +} +``` + +### Build, package, and deploy + +Use the Virto Commerce CLI (vc-build) to package the module: + +```bash +vc-build Compile +vc-build Compress +``` + +The packaging step includes everything under **Content/[app_id]/**, so the redirect file ships inside the module zip. Deploy the resulting package as you would any other module. + +![vc-build](media/vc-build.png) + +### Verify the app appears in the Apps menu + +1. Open Platform. +1. Click ![Dots](media/nine-dots-icon1.png){: width="25"} in the top left corner. +1. Click the registered app and confirm the browser redirects to the target URL. + + ![Apps menu](media/app-menu-2.png) + +You can also confirm the app via REST API: + +```bash +curl -X GET "https://mycustomdomain.com/api/platform/apps" -H "accept: application/json" +``` + +![REST API response](media/rest-api.png) diff --git a/platform/developer-guide/docs/custom-apps-development/register-your-own-app.md b/platform/developer-guide/docs/custom-apps-development/register-your-own-app.md new file mode 100644 index 0000000000..bbddd647e5 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/register-your-own-app.md @@ -0,0 +1,111 @@ +# Register Your Own App + +This guide shows how to register a custom app you build yourself, packaged inside a Platform module. The Virto Commerce CLI (vc-build) builds the source, copies the output into the module, and the Platform serves it from the **Apps** menu under the `/apps/[app_id]` URL. + +The recommended framework is [VC-Shell](https://github.com/VirtoCommerce/vc-shell), and the steps below use it as the example. + +If your goal is to add an Apps menu entry that hands the user off to an external service rather than ship a custom-built app, see [Register a third-party app](register-third-party-app.md) instead. + +## Prerequisites + +Before adding a new app, make sure the following prerequisites have been installed: + +* [Virto Commerce Platform 3.264+](https://github.com/VirtoCommerce/vc-platform) +* [Virto Commerce CLI (VC-BUILD) 3.12+](https://github.com/VirtoCommerce/vc-build) + +Optional, depending on the frontend toolchain you choose: + +* [VC-Shell framework](https://github.com/VirtoCommerce/vc-shell) + +## Registration steps + +To register your own app: + +1. [Declare the app in module.manifest](#declare-the-app-in-modulemanifest). +1. [Place source code in the Web project](#place-source-code-in-the-web-project). +1. [Build, package, and deploy](#build-package-and-deploy). +1. [Verify the app appears in the Apps menu](#verify-the-app-appears-in-the-apps-menu). + +### Declare the app in module.manifest + +Add an `` entry inside `` in **module.manifest**. For example: + +```xml title="module.manifest" + + + Page Builder Shell + Page Builder Shell + /apps/page-builder-shell/assets/images/logo-only.svg + none + false + + + Page Builder Designer + Page Builder Designer + /apps/page-builder-designer/assets/images/logo-only.svg + none + false + + +``` + +This example, taken from the [Page Builder module](https://github.com/VirtoCommerce/vc-module-pagebuilder), declares two apps in a single module. Each app gets its own `` entry, source folder, and runtime URL. It also shows that the registration mechanism is not tied to VC-Shell: `page-builder-shell` is a VC-Shell app and `page-builder-designer` is an Angular app, but both are registered the same way. + +For a description of every supported attribute, see [Apps section in Module.manifest](../Fundamentals/Modularity/06-module-manifest-file.md#apps-section). + +### Place source code in the Web project + +The vc-build `BuildCustomApp` target resolves the source folder in this order: + +1. **Apps/[app_id]** under the Web project, for example, **src/VirtoCommerce.PageBuilderModule.Web/Apps/page-builder-shell/** and **src/VirtoCommerce.PageBuilderModule.Web/Apps/page-builder-designer/**. This is the canonical layout and the only one supported when the manifest declares more than one app. +1. **App** under the Web project, for example, **src/VirtoCommerce.News.Web/App/**. This legacy fallback applies only when the manifest declares a single app. + +The package manager is auto-detected from the project's lockfile, so yarn, pnpm, npm, and bun are all supported with no configuration. Projects with non-conventional setups can override the defaults; run `vc-build --help` to see the available parameters. + +To bootstrap a VC-Shell app, run the scaffolder from the Web project's directory and pass the app id as the project name: + +```bash +npx @vc-shell/create-vc-app page-builder-shell +``` + +The scaffolder creates **Apps/page-builder-shell/** automatically, matching the canonical layout. Run it once per app id when the manifest declares multiple apps. For details on the scaffolder, see [Creating Custom VC-Shell Applications](vc-shell/Guides/creating-custom-applications.md). + +![Folder layout](media/pagebuilder-web-project.png) + +### Build, package, and deploy + +Run vc-build at the module root: + +```bash +vc-build Compile +vc-build Compress +``` + +`Compile` invokes the `BuildCustomApp` target, which: + +1. Detects the project's package manager from the lockfile and runs install and build in the resolved source folder. +1. Copies the build output into **Content/[app_id]** in the Web project. + +`Compress` then packages the module into a zip in which the app sits at **Content/[app_id]/**. Deploy the resulting package as you would any other module. + +![vc-build](media/pagebuilder-compress.png) + +### Verify the app appears in the Apps menu + +1. Open Platform. +1. Click ![Dots](media/nine-dots-icon1.png){: width="25"} in the top left corner. +1. Find the registered app. + + ![Apps menu](media/pagebuilder-in-menu.png) + +You can also confirm the app via REST API: + +```bash +curl -X GET "https://mycustomdomain.com/api/platform/apps" -H "accept: application/json" +``` + +![REST API response](media/pagebuilder-app-in-rest-api.png) + +## Optional: enable embedded mode + +To make a VC-Shell app open inside the AngularJS-based back office instead of as a standalone tab, see [Enabling Embedded Mode for VC-Shell Instances](../Tutorials-and-How-tos/How-tos/enable-embedded-mode-for-vc-shell.md). diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/Essentials/composables/useApiClient.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/Essentials/composables/useApiClient.md index d6da9aa2ff..535c7283c0 100644 --- a/platform/developer-guide/docs/custom-apps-development/vc-shell/Essentials/composables/useApiClient.md +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/Essentials/composables/useApiClient.md @@ -81,4 +81,4 @@ npm run generate-api-client --APP_PLATFORM_URL=https://api.example.com/ --APP_PL ## Related Resources - [API Client Integration](../API-Integration/api-client-integration.md) - Guide for generating API clients -- [Connecting to Platform](/platform/developer-guide/latest/custom-apps-development/vc-shell/How-tos/Connecting-to-Platform) - Guide for connecting to VirtoCommerce Platform +- [Connecting to Platform](/platform/developer-guide/latest/custom-apps-development/vc-shell/Guides/creating-custom-applications/#initial-configuration) - Guide for connecting to VirtoCommerce Platform diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/How-tos/Connecting-to-Platform.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/How-tos/Connecting-to-Platform.md deleted file mode 100644 index f0aa7d13a1..0000000000 --- a/platform/developer-guide/docs/custom-apps-development/vc-shell/How-tos/Connecting-to-Platform.md +++ /dev/null @@ -1,20 +0,0 @@ -# Connect Custom App to Platform - -!!! note "Prerequisites" - [Create custom app](../Getting-started/creating-first-custom-app.md) - -To connect your custom app to the VC Platform, add `APP_PLATFORM_URL` environment variable to your app. This variable should contain the URL of the VC Platform. - -This variable is located in the **.env** file in the root of your app. If you don't have this file, you should create it as follows: - -=== "Option 1" - - ```title=".env" - APP_PLATFORM_URL=https://your_platform_url_here - ``` - -=== "Option 2" - - ```bash - $ echo "APP_PLATFORM_URL=https://your_platform_url_here" >> .env - ``` \ No newline at end of file diff --git a/platform/developer-guide/docs/index.md b/platform/developer-guide/docs/index.md index ede858a2af..8e36974db7 100644 --- a/platform/developer-guide/docs/index.md +++ b/platform/developer-guide/docs/index.md @@ -13,6 +13,6 @@ This segment will help you learn how to set up, build, develop, and maintain you | ![API reference](media/api-overview.png) |
  • [REST API](https://virtostart-demo-admin.govirto.com/docs/index.html)
  • [GraphQL API](GraphQL-Storefront-API-Reference-xAPI/index.md)
  • [Interact with REST API via Swagger](Tutorials-and-How-tos/How-tos/swagger-api.md)
  • [Interact with GraphQL API via GraphiQL](GraphQL-Storefront-API-Reference-xAPI/graphiql.md), [curl](GraphQL-Storefront-API-Reference-xAPI/curl.md), or [Postman](GraphQL-Storefront-API-Reference-xAPI/postman.md)
| | ![Tutorials and how-tos](media/tutorials-overview.png) |
  • [Create custom modules from template](Tutorials-and-How-tos/Tutorials/creating-custom-module.md), [from scratch](Tutorials-and-How-tos/Tutorials/create-new-module-from-scratch.md) or [via Docker](Tutorials-and-How-tos/How-tos/docker-modules-development.md)
  • [Debug VC code without source code](Tutorials-and-How-tos/How-tos/debugging.md)
  • [Perform health checks](Tutorials-and-How-tos/How-tos/health-checks.md)
| | ![CLI tools](media/cli-overview.png) |
  • [Explore Virto Commerce Global Tool](CLI-tools/overview.md)
  • [Explore how to interact with VirtoCloud](CLI-tools/virto-cloud.md)
  • [Install, update, and uninstall platform dependencies](CLI-tools/package-management.md)
| -| ![Custom apps development](media/custom-apps-overview.png) |
  • [Create first custom app via VC-Shell](custom-apps-development/vc-shell/Getting-started/creating-first-custom-app.md)
  • [Connect to Platform](custom-apps-development/vc-shell/How-tos/Connecting-to-Platform.md)
  • [Generate API client](custom-apps-development/vc-shell/Essentials/Usage-Guides/using-api-clients-with-useapiclient.md)
| +| ![Custom apps development](media/custom-apps-overview.png) |
  • [Create first custom app via VC-Shell](custom-apps-development/vc-shell/Getting-started/creating-first-custom-app.md)
  • [Connect to Platform](custom-apps-development/vc-shell/Guides/creating-custom-applications.md#initial-configuration)
  • [Generate API client](custom-apps-development/vc-shell/Essentials/Usage-Guides/using-api-clients-with-useapiclient.md)
| diff --git a/platform/developer-guide/mkdocs.yml b/platform/developer-guide/mkdocs.yml index 7ff154c035..1574e08e2c 100644 --- a/platform/developer-guide/mkdocs.yml +++ b/platform/developer-guide/mkdocs.yml @@ -913,7 +913,8 @@ nav: - Useful Tips: Updating-Virto-Commerce-Based-Project/tips.md - Custom Apps Development: - Overview: custom-apps-development/overview.md - - Registering New App: custom-apps-development/how-to-register-new-app.md + - Register Your Own App: custom-apps-development/register-your-own-app.md + - Register a Third-Party App: custom-apps-development/register-third-party-app.md - VC-Shell: - Overview: custom-apps-development/vc-shell/vc-shell-overview.md - Getting Started: @@ -1043,5 +1044,3 @@ nav: - VcWidget: custom-apps-development/vc-shell/Essentials/ui-components/vc-widget.md - Extensibility: - Modularity: custom-apps-development/vc-shell/Extensibility/modularity.md - - How-tos: - - Connecting to Platform: custom-apps-development/vc-shell/How-tos/Connecting-to-Platform.md