From 84e734cbaa725fc9c8478fc6c3e13689d8ac7106 Mon Sep 17 00:00:00 2001 From: Wim Jongeneel Date: Mon, 18 May 2026 11:07:04 +0200 Subject: [PATCH 1/8] Document embedded client --- .../refguide/runtime/mendix-client/_index.md | 2 + .../mendix-client/embedding-the-client.md | 211 ++++++++++++++++++ 2 files changed, 213 insertions(+) create mode 100644 content/en/docs/refguide/runtime/mendix-client/embedding-the-client.md diff --git a/content/en/docs/refguide/runtime/mendix-client/_index.md b/content/en/docs/refguide/runtime/mendix-client/_index.md index c7fafd036a0..3fdc4b8f92b 100644 --- a/content/en/docs/refguide/runtime/mendix-client/_index.md +++ b/content/en/docs/refguide/runtime/mendix-client/_index.md @@ -29,6 +29,8 @@ The Mendix Dojo Client is bootstrapped by loading a `mxui.js` script from an HTM The Mendix React client is bootstrapped in different way. It loads the `index.js` file which loads the `common.js` with the Mendix client. More JavaScript files that contain page, layout, and nanoflow definitions will be loaded after this. +When you want to mount a Mendix web app inside another web application, you can also use the embedded client. For more information, see [Embedding the Client](/refguide/mendix-client/embedding-the-client/). + For **mobile applications**, the Mendix Client acts as a React Native application. This means that apps created by Mendix consist of two parts: a *wrapper* and a *bundle*. The wrapper is a native iOS or Android application that loads the bundle and exposes platform functionality to it. The bundle includes Client Core, Pluggable Widgets, and application-specific resources like nanoflows and pages. The three supported types of wrappers for mobile applications are as follows: diff --git a/content/en/docs/refguide/runtime/mendix-client/embedding-the-client.md b/content/en/docs/refguide/runtime/mendix-client/embedding-the-client.md new file mode 100644 index 00000000000..c19a2d43fb6 --- /dev/null +++ b/content/en/docs/refguide/runtime/mendix-client/embedding-the-client.md @@ -0,0 +1,211 @@ +--- +title: "Embedding the Client" +url: /refguide/mendix-client/embedding-the-client/ +description: "Describes how to load a Mendix web app into another web application by using the embedded client." +weight: 30 +--- + +## Introduction + +The embedded client lets you load a Mendix web app inside another web application without using the standard Mendix shell page. + +In this setup, the host application owns the surrounding page and the Mendix app owns the region where it is mounted. + +This page describes how to do the following: + +* Configure an Embedded navigation profile in your Mendix app +* Load the embedded client from a host application +* Pass page parameters to the embedded home page +* Mount and unmount the client at the correct lifecycle moment +* Handle common integration issues + +## Prerequisites + +Before you start, make sure you have the following: + +* A Mendix version that supports the embedded client +* A Mendix web app that you can run locally or deploy +* A host web app that can create a DOM element and load JavaScript by using a dynamic import + +## How the Embedded Client Works + +When your app contains an Embedded navigation profile, the Mendix runtime exposes an embedded entry bundle at `/dist/embedded-index.js`. + +Your host application is responsible for the following: + +* Choosing the Mendix runtime URL +* Loading the embedded bundle with a dynamic import +* Creating a DOM element that Mendix can render into +* Calling `render(...)` on the embedded bundle +* Calling the returned unmount function when the host component is removed +* Showing any loading or error state in the host UI + +The same integration pattern works in React, Vue, plain JavaScript, and other frontend frameworks. + +## Configuring the Embedded Navigation Profile + +To enable the embedded client for your Mendix app, do the following: + +1. Open your app in Studio Pro. +2. Open **App** > **Navigation**. +3. Click **Add navigation profile**. +4. Select **Embedded**. +5. Configure the **Default home page** for the Embedded profile. +6. Configure the error page for the Embedded profile (optional). +7. Run or deploy the app. + +After you add the Embedded profile, the Mendix runtime serves the following bundle: + +```text +/dist/embedded-index.js +``` + +For example, if your runtime URL is `http://localhost:8081`, the embedded bundle is served from `http://localhost:8081/dist/embedded-index.js`. + +The Embedded profile defines the starting page for the embedded app. It also defines which page is shown if the embedded app reaches an error state during startup or navigation. + +## Configuring the Embedded Home Page + +The Embedded profile uses its own home page. This is the first page shown when the host calls `render(...)`. + +If your embedded home page requires page parameters, pass those values from the host application by using the `parameters` object in the `render(...)` configuration. + +## Passing Parameters to the Embedded Home Page + +You can pass page parameters for the embedded home page in the `parameters` object. + +For example: + +```js +const DEFAULT_REMOTE_URL = "https://your-mendix-runtime.example.com"; + +export async function mountEmbeddedMendix(container) { + const configuredRemoteUrl = window.__MENDIX_REMOTE_URL__ ?? DEFAULT_REMOTE_URL; + const remoteUrl = configuredRemoteUrl.replace(/\/+$/, ""); + + const embeddedModule = await import(`${remoteUrl}/dist/embedded-index.js`); + + return embeddedModule.render(container, { + remoteUrl: `${remoteUrl}/`, + minHeight: "620px", + parameters: { + customerId: "12345" + } + }); +} +``` + +The parameter names in `parameters` must match the page parameters expected by the embedded home page. + +## Creating a Host Container + +Create an element in the host application where the Mendix app will be mounted. + +For example: + +```html +
+``` + +Or in a framework component: + +```tsx +
+``` + +The host only needs to provide a real DOM node. + +## Loading and Rendering the Embedded Client + +The embedded bundle exposes a `render(...)` function. A minimal framework-agnostic integration looks like this: + +```js +const DEFAULT_REMOTE_URL = "https://your-mendix-runtime.example.com"; + +export async function mountEmbeddedMendix(container) { + const configuredRemoteUrl = window.__MENDIX_REMOTE_URL__ ?? DEFAULT_REMOTE_URL; + const remoteUrl = configuredRemoteUrl.replace(/\/+$/, ""); + + const embeddedModule = await import(`${remoteUrl}/dist/embedded-index.js`); + + return embeddedModule.render(container, { + remoteUrl: `${remoteUrl}/`, + minHeight: "620px", + parameters: { + customerId: "12345" + } + }); +} +``` + +This code does the following: + +* Resolves the runtime URL +* Loads the embedded bundle from the Mendix runtime +* Passes page parameters to the embedded home page +* Calls `render(...)` with the container element +* Returns the unmount function from the embedded client + +{{% alert color="info" %}} +If your host application uses Vite, add the `/* @vite-ignore */` comment to the dynamic import so Vite does not try to resolve the runtime URL during the host build. +{{% /alert %}} + +## Mounting and Cleaning Up + +Call the embedding logic only after the container exists and store the returned unmount function. + +Typical lifecycle hooks include the following: + +* React: `useEffect(...)` +* Vue: `onMounted(...)` and `onBeforeUnmount(...)` +* Plain JavaScript: after locating the container with `getElementById(...)` and during your own teardown flow + +For example: + +```js +const container = document.getElementById("embedded-mendix-host"); +const unmount = await mountEmbeddedMendix(container); + +// Call this when the host view is removed. +unmount(); +``` + +## Handling Errors + +The most common integration failure is that the Mendix runtime is not serving `embedded-index.js`. Wrap the load and render steps in a `try/catch` block. + +```js +const remoteUrl = "https://your-mendix-runtime.example.com"; + +try { + const embeddedModule = await import(`${remoteUrl}/dist/embedded-index.js`); + const unmount = await embeddedModule.render(container, { + remoteUrl: `${remoteUrl}/`, + minHeight: "620px", + parameters: { + customerId: "12345" + } + }); +} catch (error) { + console.error(error); + showError(`Unable to load the embedded Mendix bundle from ${remoteUrl}/dist/embedded-index.js.`); +} +``` + +At minimum, the host should do the following: + +* Log the technical error +* Show a visible error message in the host UI +* Keep the surrounding page intact + +## Cross-Origin Requests + +If the host app and the Mendix runtime use different origins, make sure the Mendix runtime accepts requests from the host origin. This is required because the host app loads the embedded bundle and subsequent client resources from the Mendix runtime. For more information, see [Configure CORS](/refguide/configure-cors/). + +## Read More + +* [Mendix Client](/refguide/mendix-client/) +* [Mendix React Client](/refguide/mendix-client/react/) +* [Navigation](/refguide/navigation/) +* [Setting Up Navigation](/refguide/setting-up-the-navigation-structure/) +* [Configure CORS](/refguide/configure-cors/) \ No newline at end of file From 28d3db7826482faa6054e77eeb63cf15434f58a9 Mon Sep 17 00:00:00 2001 From: Wim Jongeneel Date: Mon, 18 May 2026 11:08:27 +0200 Subject: [PATCH 2/8] Add beta warning --- .../refguide/runtime/mendix-client/embedding-the-client.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/content/en/docs/refguide/runtime/mendix-client/embedding-the-client.md b/content/en/docs/refguide/runtime/mendix-client/embedding-the-client.md index c19a2d43fb6..2acd712e3b4 100644 --- a/content/en/docs/refguide/runtime/mendix-client/embedding-the-client.md +++ b/content/en/docs/refguide/runtime/mendix-client/embedding-the-client.md @@ -3,8 +3,13 @@ title: "Embedding the Client" url: /refguide/mendix-client/embedding-the-client/ description: "Describes how to load a Mendix web app into another web application by using the embedded client." weight: 30 +beta: true --- +{{% alert color="warning" %}} +This feature is in Public Beta. For more information, see [Release Status](/releasenotes/release-status/). +{{% /alert %}} + ## Introduction The embedded client lets you load a Mendix web app inside another web application without using the standard Mendix shell page. From 0b96ed7e50ddcc3eb4788d1eb656559d24937ec5 Mon Sep 17 00:00:00 2001 From: Wim Jongeneel Date: Mon, 18 May 2026 11:15:44 +0200 Subject: [PATCH 3/8] Improve doc --- .../mendix-client/embedding-the-client.md | 39 +++---------------- 1 file changed, 5 insertions(+), 34 deletions(-) diff --git a/content/en/docs/refguide/runtime/mendix-client/embedding-the-client.md b/content/en/docs/refguide/runtime/mendix-client/embedding-the-client.md index 2acd712e3b4..e35c70ea755 100644 --- a/content/en/docs/refguide/runtime/mendix-client/embedding-the-client.md +++ b/content/en/docs/refguide/runtime/mendix-client/embedding-the-client.md @@ -22,7 +22,6 @@ This page describes how to do the following: * Load the embedded client from a host application * Pass page parameters to the embedded home page * Mount and unmount the client at the correct lifecycle moment -* Handle common integration issues ## Prerequisites @@ -69,6 +68,8 @@ For example, if your runtime URL is `http://localhost:8081`, the embedded bundle The Embedded profile defines the starting page for the embedded app. It also defines which page is shown if the embedded app reaches an error state during startup or navigation. +If you configure an error page, it is shown when the parameters passed in `render(...)` do not match the expected parameter types of the embedded home page. It is also shown when the selected home page is not accessible for the signed-in user. + ## Configuring the Embedded Home Page The Embedded profile uses its own home page. This is the first page shown when the host calls `render(...)`. @@ -85,8 +86,7 @@ For example: const DEFAULT_REMOTE_URL = "https://your-mendix-runtime.example.com"; export async function mountEmbeddedMendix(container) { - const configuredRemoteUrl = window.__MENDIX_REMOTE_URL__ ?? DEFAULT_REMOTE_URL; - const remoteUrl = configuredRemoteUrl.replace(/\/+$/, ""); + const remoteUrl = window.__MENDIX_REMOTE_URL__ ?? DEFAULT_REMOTE_URL; const embeddedModule = await import(`${remoteUrl}/dist/embedded-index.js`); @@ -128,8 +128,7 @@ The embedded bundle exposes a `render(...)` function. A minimal framework-agnost const DEFAULT_REMOTE_URL = "https://your-mendix-runtime.example.com"; export async function mountEmbeddedMendix(container) { - const configuredRemoteUrl = window.__MENDIX_REMOTE_URL__ ?? DEFAULT_REMOTE_URL; - const remoteUrl = configuredRemoteUrl.replace(/\/+$/, ""); + const remoteUrl = window.__MENDIX_REMOTE_URL__ ?? DEFAULT_REMOTE_URL; const embeddedModule = await import(`${remoteUrl}/dist/embedded-index.js`); @@ -175,34 +174,6 @@ const unmount = await mountEmbeddedMendix(container); unmount(); ``` -## Handling Errors - -The most common integration failure is that the Mendix runtime is not serving `embedded-index.js`. Wrap the load and render steps in a `try/catch` block. - -```js -const remoteUrl = "https://your-mendix-runtime.example.com"; - -try { - const embeddedModule = await import(`${remoteUrl}/dist/embedded-index.js`); - const unmount = await embeddedModule.render(container, { - remoteUrl: `${remoteUrl}/`, - minHeight: "620px", - parameters: { - customerId: "12345" - } - }); -} catch (error) { - console.error(error); - showError(`Unable to load the embedded Mendix bundle from ${remoteUrl}/dist/embedded-index.js.`); -} -``` - -At minimum, the host should do the following: - -* Log the technical error -* Show a visible error message in the host UI -* Keep the surrounding page intact - ## Cross-Origin Requests If the host app and the Mendix runtime use different origins, make sure the Mendix runtime accepts requests from the host origin. This is required because the host app loads the embedded bundle and subsequent client resources from the Mendix runtime. For more information, see [Configure CORS](/refguide/configure-cors/). @@ -213,4 +184,4 @@ If the host app and the Mendix runtime use different origins, make sure the Mend * [Mendix React Client](/refguide/mendix-client/react/) * [Navigation](/refguide/navigation/) * [Setting Up Navigation](/refguide/setting-up-the-navigation-structure/) -* [Configure CORS](/refguide/configure-cors/) \ No newline at end of file +* [Configure CORS](/refguide/configure-cors/) From 4603acd9abb0b7904f66886d33a8b7a02df46ccf Mon Sep 17 00:00:00 2001 From: Wim Jongeneel Date: Mon, 18 May 2026 11:21:52 +0200 Subject: [PATCH 4/8] Add section on CSP --- .../refguide/runtime/mendix-client/embedding-the-client.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/content/en/docs/refguide/runtime/mendix-client/embedding-the-client.md b/content/en/docs/refguide/runtime/mendix-client/embedding-the-client.md index e35c70ea755..6c0183150f2 100644 --- a/content/en/docs/refguide/runtime/mendix-client/embedding-the-client.md +++ b/content/en/docs/refguide/runtime/mendix-client/embedding-the-client.md @@ -178,6 +178,10 @@ unmount(); If the host app and the Mendix runtime use different origins, make sure the Mendix runtime accepts requests from the host origin. This is required because the host app loads the embedded bundle and subsequent client resources from the Mendix runtime. For more information, see [Configure CORS](/refguide/configure-cors/). +## Content Security Policy + +If the host app uses Content Security Policy (CSP), make sure its policy allows JavaScript to load from the Mendix runtime domain. This is required because the host app loads the embedded bundle and other client resources from that domain. For more information, see [Content Security Policy](/howto/security/csp/). + ## Read More * [Mendix Client](/refguide/mendix-client/) From b9f0b0658410a9c7662a104a40288461277d19ad Mon Sep 17 00:00:00 2001 From: Wim Jongeneel Date: Mon, 18 May 2026 11:38:34 +0200 Subject: [PATCH 5/8] Add section on styling --- .../runtime/mendix-client/embedding-the-client.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/content/en/docs/refguide/runtime/mendix-client/embedding-the-client.md b/content/en/docs/refguide/runtime/mendix-client/embedding-the-client.md index 6c0183150f2..03c421ecf5f 100644 --- a/content/en/docs/refguide/runtime/mendix-client/embedding-the-client.md +++ b/content/en/docs/refguide/runtime/mendix-client/embedding-the-client.md @@ -174,6 +174,20 @@ const unmount = await mountEmbeddedMendix(container); unmount(); ``` +## CSS Behavior + +The embedded client runs inside a shadow root so that its styles stay isolated from the host app. + +To make common app styling keep working, Mendix rewrites CSS selectors that target `:root`, `html`, or `body` so they target `:host` instead. This allows CSS variables and other top-level styles to keep applying inside the embedded app. + +If a selector depends on attributes on `html` or `body`, those attributes are mirrored to the shadow root so those selectors can still work when the app is embedded. + +`@font-face` declarations are handled differently. Because shadow roots do not support font declarations in the same way, Mendix moves those declarations to a `style` tag in the host page's `head`. + +{{% alert color="info" %}} +Not all custom CSS will behave exactly the same when an app is embedded. However, Atlas styling is supported. +{{% /alert %}} + ## Cross-Origin Requests If the host app and the Mendix runtime use different origins, make sure the Mendix runtime accepts requests from the host origin. This is required because the host app loads the embedded bundle and subsequent client resources from the Mendix runtime. For more information, see [Configure CORS](/refguide/configure-cors/). From 1e7f869377c51950e23f3d9757195e809cc341f8 Mon Sep 17 00:00:00 2001 From: Wim Jongeneel Date: Mon, 18 May 2026 11:45:33 +0200 Subject: [PATCH 6/8] Add section on navigation --- .../refguide/runtime/mendix-client/embedding-the-client.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/content/en/docs/refguide/runtime/mendix-client/embedding-the-client.md b/content/en/docs/refguide/runtime/mendix-client/embedding-the-client.md index 03c421ecf5f..bfacbe9d746 100644 --- a/content/en/docs/refguide/runtime/mendix-client/embedding-the-client.md +++ b/content/en/docs/refguide/runtime/mendix-client/embedding-the-client.md @@ -188,6 +188,12 @@ If a selector depends on attributes on `html` or `body`, those attributes are mi Not all custom CSS will behave exactly the same when an app is embedded. However, Atlas styling is supported. {{% /alert %}} +## Embedded Navigation + +An embedded app does not react to changes in the browser address bar or to the browser's back and forward buttons. This is because the embedded app runs as a component inside the host app, and the host app should control browser navigation. + +The embedded Mendix app can still navigate internally. For example, it can open other pages by using [Show Page](/refguide/show-page/) actions or buttons that open a page. + ## Cross-Origin Requests If the host app and the Mendix runtime use different origins, make sure the Mendix runtime accepts requests from the host origin. This is required because the host app loads the embedded bundle and subsequent client resources from the Mendix runtime. For more information, see [Configure CORS](/refguide/configure-cors/). From 6d4e0fb577c18b997638f19860838fe863f4bf76 Mon Sep 17 00:00:00 2001 From: Wim Jongeneel Date: Mon, 18 May 2026 12:01:21 +0200 Subject: [PATCH 7/8] Proofread --- .../mendix-client/embedding-the-client.md | 55 +++---------------- 1 file changed, 8 insertions(+), 47 deletions(-) diff --git a/content/en/docs/refguide/runtime/mendix-client/embedding-the-client.md b/content/en/docs/refguide/runtime/mendix-client/embedding-the-client.md index bfacbe9d746..00404a3c063 100644 --- a/content/en/docs/refguide/runtime/mendix-client/embedding-the-client.md +++ b/content/en/docs/refguide/runtime/mendix-client/embedding-the-client.md @@ -12,25 +12,18 @@ This feature is in Public Beta. For more information, see [Release Status](/rele ## Introduction -The embedded client lets you load a Mendix web app inside another web application without using the standard Mendix shell page. +The embedded client lets you use a Mendix web app as a component inside another web application, without using the standard Mendix shell page. This makes it easier to add Mendix capabilities to broader digital experiences, support micro-frontend architectures, and integrate Mendix seamlessly with existing portals, products, or custom frontends. In this setup, the host application owns the surrounding page and browser-level experience, while the Mendix app owns the region where it is mounted. -In this setup, the host application owns the surrounding page and the Mendix app owns the region where it is mounted. - -This page describes how to do the following: +This page describes the following: * Configure an Embedded navigation profile in your Mendix app * Load the embedded client from a host application * Pass page parameters to the embedded home page +* Understand how CSS behaves in an embedded app +* Understand how navigation behaves in an embedded app +* Configure host app requirements such as CORS and CSP * Mount and unmount the client at the correct lifecycle moment -## Prerequisites - -Before you start, make sure you have the following: - -* A Mendix version that supports the embedded client -* A Mendix web app that you can run locally or deploy -* A host web app that can create a DOM element and load JavaScript by using a dynamic import - ## How the Embedded Client Works When your app contains an Embedded navigation profile, the Mendix runtime exposes an embedded entry bundle at `/dist/embedded-index.js`. @@ -46,7 +39,7 @@ Your host application is responsible for the following: The same integration pattern works in React, Vue, plain JavaScript, and other frontend frameworks. -## Configuring the Embedded Navigation Profile +## Configuring the Embedded App To enable the embedded client for your Mendix app, do the following: @@ -55,7 +48,7 @@ To enable the embedded client for your Mendix app, do the following: 3. Click **Add navigation profile**. 4. Select **Embedded**. 5. Configure the **Default home page** for the Embedded profile. -6. Configure the error page for the Embedded profile (optional). +6. Configure an error page for the Embedded profile (optional). 7. Run or deploy the app. After you add the Embedded profile, the Mendix runtime serves the following bundle: @@ -66,39 +59,7 @@ After you add the Embedded profile, the Mendix runtime serves the following bund For example, if your runtime URL is `http://localhost:8081`, the embedded bundle is served from `http://localhost:8081/dist/embedded-index.js`. -The Embedded profile defines the starting page for the embedded app. It also defines which page is shown if the embedded app reaches an error state during startup or navigation. - -If you configure an error page, it is shown when the parameters passed in `render(...)` do not match the expected parameter types of the embedded home page. It is also shown when the selected home page is not accessible for the signed-in user. - -## Configuring the Embedded Home Page - -The Embedded profile uses its own home page. This is the first page shown when the host calls `render(...)`. - -If your embedded home page requires page parameters, pass those values from the host application by using the `parameters` object in the `render(...)` configuration. - -## Passing Parameters to the Embedded Home Page - -You can pass page parameters for the embedded home page in the `parameters` object. - -For example: - -```js -const DEFAULT_REMOTE_URL = "https://your-mendix-runtime.example.com"; - -export async function mountEmbeddedMendix(container) { - const remoteUrl = window.__MENDIX_REMOTE_URL__ ?? DEFAULT_REMOTE_URL; - - const embeddedModule = await import(`${remoteUrl}/dist/embedded-index.js`); - - return embeddedModule.render(container, { - remoteUrl: `${remoteUrl}/`, - minHeight: "620px", - parameters: { - customerId: "12345" - } - }); -} -``` +The Embedded profile defines the starting page for the embedded app, which is the first page shown when the host calls `render(...)`, and it can also define an error page for startup or navigation failures. When the embedded home page requires page parameters, pass those values from the host application by using the `parameters` object in the `render(...)` configuration. The configured error page is shown when the parameters passed in `render(...)` do not match the expected parameter types of the embedded home page or when the selected home page is not accessible for the signed-in user. The parameter names in `parameters` must match the page parameters expected by the embedded home page. From 62255ab4df7334931b0e90abe89bb18110bbfe04 Mon Sep 17 00:00:00 2001 From: Wim Jongeneel Date: Mon, 18 May 2026 14:50:22 +0200 Subject: [PATCH 8/8] Update general navigation profle docs as well --- .../app-explorer/app/navigation/_index.md | 16 +++++++++++++++- .../setting-up-the-navigation-structure.md | 11 ++++++++++- 2 files changed, 25 insertions(+), 2 deletions(-) diff --git a/content/en/docs/refguide/modeling/app-explorer/app/navigation/_index.md b/content/en/docs/refguide/modeling/app-explorer/app/navigation/_index.md index c88078580a6..3fde22ce85e 100644 --- a/content/en/docs/refguide/modeling/app-explorer/app/navigation/_index.md +++ b/content/en/docs/refguide/modeling/app-explorer/app/navigation/_index.md @@ -25,8 +25,9 @@ The core of Mendix's navigation model is founded on the following profiles: * Phone web * Phone web offline * Native mobile (tablet & phone) +* Embedded (Beta) -Users that access the app via a particular device type are automatically redirected to the homepage of the appropriate profile based on the profile type (for details, see the [Redirection to Profiles](#redirection) section below). +Users that access the app via a particular device type are automatically redirected to the homepage of the appropriate browser or mobile profile based on the profile type (for details, see the [Redirection to Profiles](#redirection) section below). The Embedded profile is not selected through device detection. It is used when a host application loads the embedded client. The device type of the currently logged-in user is available in [microflows](/refguide/microflows/) as the `$currentDeviceType` variable. The type of this variable is the [enumeration](/refguide/enumerations/) `System.DeviceType`, which has the values `Phone`, `Tablet`, and `Desktop`. You can use `$currentDeviceType` to perform different actions based on the device type. A typical example is to show different pages based on the device type. @@ -56,6 +57,12 @@ The Mendix app will run in [offline-first](/refguide/offline-first/) mode. This You are required to enable anonymous users in your app's security settings and include anonymous user roles on native login pages. This is because there is no built-in login screen in the native profile; login pages are modeled as regular native pages. {{% /alert %}} +### Embedded + +The Embedded profile lets you use a Mendix web app as a component inside another web application. The host application loads the embedded client and owns browser-level navigation, while the Mendix app renders and navigates inside its mounted region. + +The Embedded profile defines a default home page and can also define an error page. When the configured home page expects page parameters, the host application can pass them through the `parameters` object in `render(...)`. For more information, see [Embedding the Client](/refguide/mendix-client/embedding-the-client/). + ## Redirection to Profiles {#redirection} Mendix Runtime automatically redirects users to the home page of the appropriate device type based on the device they are using. This happens by examining the `User-Agent` string that is sent by the device. The default configuration for this redirection is as follows: @@ -98,6 +105,8 @@ The default home page indicates which [page](/refguide/page/) or [microflow](/re The default home page is visible to all unauthenticated users. {{% /alert %}} +For the Embedded profile, the default home page is the first page shown when the host application calls `render(...)`. + #### Role-Based Home Pages{#role-based} By using role-based home pages, you can show different home pages for different users. If a user logs in, the first role-based home page of which the user role matches the user role of the user is displayed. If no match is found, the default home page is used. @@ -108,6 +117,10 @@ For each role-based home page, you can specify the user role it applies to and t The fallback page is a page or microflow that can be used to customize the application's behavior when trying to access a [microflow](/refguide/microflow/#url) or [page](/refguide/page-properties/#url) URL that does not exist. For more information, see [Setting a Fallback Page](/refguide/setting-up-the-navigation-structure/#fallback) in *Setting Up Navigation*. +#### Error Page + +For Embedded profiles, you can configure an error page. This page is shown when the embedded app cannot open the configured home page during startup or navigation. Examples include page parameter values passed through `render(...)` that do not match the expected parameter types, or a configured home page that is not accessible for the signed-in user. For more information, see [Embedding the Client](/refguide/mendix-client/embedding-the-client/). + ### Authentication {#authentication} If a user, [anonymous](/refguide/anonymous-users/) or authenticated, tries to access a resource to which the user has no access, the configured [sign-in page](/refguide/authentication-widgets/) will be displayed, prompting the user to sign in. @@ -145,4 +158,5 @@ For more details on the settings and when to use them, see the [Offline-First Re ## Read More * [App Explorer](/refguide/app-explorer/) +* [Embedding the Client](/refguide/mendix-client/embedding-the-client/) * [Navigation Tree](/refguide/navigation-tree/) diff --git a/content/en/docs/refguide/modeling/app-explorer/app/navigation/setting-up-the-navigation-structure.md b/content/en/docs/refguide/modeling/app-explorer/app/navigation/setting-up-the-navigation-structure.md index e7b9db9d07f..038b286a2ae 100644 --- a/content/en/docs/refguide/modeling/app-explorer/app/navigation/setting-up-the-navigation-structure.md +++ b/content/en/docs/refguide/modeling/app-explorer/app/navigation/setting-up-the-navigation-structure.md @@ -8,7 +8,7 @@ aliases: --- ## Introduction -Once your app has some pages, create a navigation menu to give your users access to them. The navigation editor allows you define the navigation menu for different type of apps and devices (for example, for responsive, tablet browser, or native mobile apps). It also allows you to define which page is shown as a default home page depending on the user role. +Once your app has some pages, create a navigation menu to give your users access to them. The navigation editor allows you define the navigation menu for different type of apps and devices (for example, for responsive, tablet browser, native mobile, or embedded apps). It also allows you to define which page is shown as a default home page depending on the user role. ## Setting a Default Home Page {#home} @@ -35,6 +35,8 @@ Do the following: For online profiles, you can set a microflow as a default home page. Make sure a [Show Page](/refguide/show-page/) activity is called from the startup microflow for each possible execution flow. Otherwise, the user will see nothing during execution paths where the activity is missing. For the native mobile profile, you can set a nanoflow as a home page, either as a default or as a role-based. For more information, see the [Setting a Nanoflow as a Home Page](#nanoflow-home-page) section below. + +For the Embedded profile, the selected home page is the first page shown when the host application calls `render(...)`. When that page requires parameters, the host application passes them through the `parameters` object in `render(...)`. For more information, see [Embedding the Client](/refguide/mendix-client/embedding-the-client/). {{% /alert %}} Now every time a user signs in to the application, the selected page/microflow is shown/triggered. @@ -74,6 +76,12 @@ If a microflow is used as a fallback, it can have only one String parameter name The fallback page will only be used for URLs that start with a [URL Prefix](/refguide/runtime-tab/#url-prefix). +## Setting an Error Page for an Embedded Profile + +The Embedded profile can use an error page when the configured home page cannot be opened during startup or navigation. This can happen when the values passed in `render(...)` do not match the expected page parameter types or when the signed-in user does not have access to the configured home page. + +To configure an error page, open the Embedded profile in the **Navigation** editor and select the page you want to use. + ## Setting a Nanoflow as a Home Page {#nanoflow-home-page} Instead of using a page, you can set a nanoflow as your app's home page as long as you are using a native profile. The nanoflow you selected will be executed during startup and will show your app's starting page. This is a normal nanoflow call, which means that you can implement custom logic that determines which page to show, creates objects, calls sub-nanoflows, uses JavaScript actions, and more. @@ -134,3 +142,4 @@ To avoid adding the menu widget on every page in your app, you can use a layout. * [Atlas UI](/howto/front-end/atlas-ui/) * [Create Your First Two Overview and Detail Pages](/howto/front-end/create-your-first-two-overview-and-detail-pages/) +* [Embedding the Client](/refguide/mendix-client/embedding-the-client/)