Correct information about custom apps source code placement, build & third-party apps integration

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:

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 `<apps>` 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"
 <apps>
     <app id="reports">
         <title>Reports</title>
@@ -146,17 +145,26 @@ To add a new web, add the app section into the **module.manifest** file:
         <permission>PowerBiReports:access</permission>
     </app>
 </apps>
-...
 ```
 
-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]/<file>` for assets shipped with the app, or `Modules/$(ModuleId)/Content/<file>` 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).
 
 
 

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 `<app>` entry inside `<apps>` in **module.manifest**. For example:
+
+```xml title="module.manifest"
+<apps>
+    <app id="reports">
+        <title>Reports</title>
+        <description>Power BI Commerce Reports</description>
+        <iconUrl>/apps/reports/power_bi_logo.svg</iconUrl>
+        <permission>PowerBiReports:access</permission>
+    </app>
+</apps>
+```
+
+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"
+<!DOCTYPE html>
+<html>
+<head>
+    <meta charset="UTF-8">
+    <meta http-equiv="refresh" content="0; URL=/api/power-bi-reports/redirect">
+    <title>Redirecting to Power BI Reports</title>
+</head>
+<body>
+    <h1>Redirecting to Power BI Reports...</h1>
+    <p>If you are not redirected automatically, please click <a href="/api/power-bi-reports/redirect">here</a>.</p>
+</body>
+</html>
+```
+
+![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<string>(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)

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 `<app>` entry inside `<apps>` in **module.manifest**. For example:
+
+```xml title="module.manifest"
+<apps>
+    <app id="page-builder-shell">
+        <title>Page Builder Shell</title>
+        <description>Page Builder Shell</description>
+        <iconUrl>/apps/page-builder-shell/assets/images/logo-only.svg</iconUrl>
+        <permission>none</permission>
+        <supportEmbeddedMode>false</supportEmbeddedMode>
+    </app>
+    <app id="page-builder-designer">
+        <title>Page Builder Designer</title>
+        <description>Page Builder Designer</description>
+        <iconUrl>/apps/page-builder-designer/assets/images/logo-only.svg</iconUrl>
+        <permission>none</permission>
+        <supportEmbeddedMode>false</supportEmbeddedMode>
+    </app>
+</apps>
+```
+
+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 `<app>` 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).

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