From 4b826db90004f821be94283905fc296db102838e Mon Sep 17 00:00:00 2001 From: Jonathan Diehl <1334574+jdiehl@users.noreply.github.com> Date: Fri, 29 May 2026 10:09:50 +0200 Subject: [PATCH 1/2] Explain URL uniqueness requirement for page URLs --- .../modeling/pages/page/page-properties.md | 16 ++++++++++++++++ .../modeling/pages/page/page-properties.md | 16 ++++++++++++++++ 2 files changed, 32 insertions(+) diff --git a/content/en/docs/refguide/modeling/pages/page/page-properties.md b/content/en/docs/refguide/modeling/pages/page/page-properties.md index 3cdec89f35b..57083dcf82b 100644 --- a/content/en/docs/refguide/modeling/pages/page/page-properties.md +++ b/content/en/docs/refguide/modeling/pages/page/page-properties.md @@ -106,6 +106,22 @@ In simple e-commerce applications, the URLs can be configured as follows: Mendix does not recommend configuring page URLs for pages that are displayed as a pop-up. Navigating to such a URL will result in layout issues. {{%/alert %}} +#### URL Uniqueness Requirement {#url-uniqueness} + +Each page URL pattern must be unique across your application. Studio Pro compares URL patterns structurally — the parameter names themselves do not matter. Two pages with URLs like `documents/{ParamA}` and `documents/{ParamB}` are considered identical patterns and will produce a consistency error, even if the parameters refer to different entity types or have different names. + +All page parameters must appear in the URL. This means a page with a parameter cannot have a static URL such as `documents/orders` — the parameter must be part of the URL pattern. + +{{% alert color="info" %}} +This constraint exists because the runtime must determine which page to open based solely on the incoming URL — before loading any data. When a user navigates directly to a URL (for example, from a bookmark or external link), the runtime has no session context available. If two pages shared the same URL pattern, the router would have no way to resolve which page to open without first querying the database. Performing database queries during routing is not practical: it would significantly increase page load latency and produce unreliable results. Standard web routing frameworks apply the same principle — ambiguous route patterns cause a routing conflict. Mendix enforces this at compile time rather than allowing it to fail at runtime. +{{% /alert %}} + +If you need incoming links to work across multiple pages that would otherwise share a URL pattern, the following approaches are available: + +* **Use distinct static URL segments** — Give each page a unique static prefix so each pattern is unambiguous. For example, use `orders/{Order/Id}` and `invoices/{Invoice/Id}` instead of a shared base pattern such as `documents/{Document/Id}`. + +* **Use a microflow URL as a router** — Assign the shared URL pattern to a microflow instead of a page. The microflow receives the parameter, determines which page to open (for example, based on an enumeration or string value), and uses **Show Page** to navigate. For example, a microflow handling `report/{ReportType}` can read the `ReportType` string parameter and open the corresponding page, such as a sales report or an inventory report page. Note that nanoflows are not supported for URL handling. + ### Common Section {#common} {{% snippet file="/static/_includes/refguide/common-section-link.md" %}} diff --git a/content/en/docs/refguide10/modeling/pages/page/page-properties.md b/content/en/docs/refguide10/modeling/pages/page/page-properties.md index 47f1b610315..8469ae76ad3 100644 --- a/content/en/docs/refguide10/modeling/pages/page/page-properties.md +++ b/content/en/docs/refguide10/modeling/pages/page/page-properties.md @@ -87,6 +87,22 @@ In simple e-commerce applications, the URLs can be configured as follows: Mendix does not recommend configuring page URLs for pages that are displayed as a pop-up. Navigating to such a URL will result in layout issues. {{%/alert %}} +#### URL Uniqueness Requirement {#url-uniqueness} + +Each page URL pattern must be unique across your application. Studio Pro compares URL patterns structurally — the parameter names themselves do not matter. Two pages with URLs like `documents/{ParamA}` and `documents/{ParamB}` are considered identical patterns and will produce a consistency error, even if the parameters refer to different entity types or have different names. + +All page parameters must appear in the URL. This means a page with a parameter cannot have a static URL such as `documents/orders` — the parameter must be part of the URL pattern. + +{{% alert color="info" %}} +This constraint exists because the runtime must determine which page to open based solely on the incoming URL — before loading any data. When a user navigates directly to a URL (for example, from a bookmark or external link), the runtime has no session context available. If two pages shared the same URL pattern, the router would have no way to resolve which page to open without first querying the database. Performing database queries during routing is not practical: it would significantly increase page load latency and produce unreliable results. Standard web routing frameworks apply the same principle — ambiguous route patterns cause a routing conflict. Mendix enforces this at compile time rather than allowing it to fail at runtime. +{{% /alert %}} + +If you need incoming links to work across multiple pages that would otherwise share a URL pattern, the following approaches are available: + +* **Use distinct static URL segments** — Give each page a unique static prefix so each pattern is unambiguous. For example, use `orders/{Order/Id}` and `invoices/{Invoice/Id}` instead of a shared base pattern such as `documents/{Document/Id}`. + +* **Use a microflow URL as a router** — Assign the shared URL pattern to a microflow instead of a page. The microflow receives the parameter, determines which page to open (for example, based on an enumeration or string value), and uses **Show Page** to navigate. For example, a microflow handling `report/{ReportType}` can read the `ReportType` string parameter and open the corresponding page, such as a sales report or an inventory report page. Note that nanoflows are not supported for URL handling. + ### Common Section {#common} {{% snippet file="/static/_includes/refguide10/common-section-link.md" %}} From ff9caf4aa313c645cb10ae69078af33ceea2dc33 Mon Sep 17 00:00:00 2001 From: Jonathan Diehl <1334574+jdiehl@users.noreply.github.com> Date: Fri, 29 May 2026 10:20:35 +0200 Subject: [PATCH 2/2] Reduce duplication with general-best-practices URL section --- .../refguide/modeling/pages/page/page-properties.md | 10 +++------- .../refguide10/modeling/pages/page/page-properties.md | 10 +++------- 2 files changed, 6 insertions(+), 14 deletions(-) diff --git a/content/en/docs/refguide/modeling/pages/page/page-properties.md b/content/en/docs/refguide/modeling/pages/page/page-properties.md index 57083dcf82b..06b9049fdc5 100644 --- a/content/en/docs/refguide/modeling/pages/page/page-properties.md +++ b/content/en/docs/refguide/modeling/pages/page/page-properties.md @@ -108,19 +108,15 @@ Mendix does not recommend configuring page URLs for pages that are displayed as #### URL Uniqueness Requirement {#url-uniqueness} -Each page URL pattern must be unique across your application. Studio Pro compares URL patterns structurally — the parameter names themselves do not matter. Two pages with URLs like `documents/{ParamA}` and `documents/{ParamB}` are considered identical patterns and will produce a consistency error, even if the parameters refer to different entity types or have different names. - All page parameters must appear in the URL. This means a page with a parameter cannot have a static URL such as `documents/orders` — the parameter must be part of the URL pattern. +Page URL patterns must also be unambiguous. For the full rules on what constitutes a conflict and how to resolve it using URL structure, see [Page and Microflow URLs](/refguide/general-best-practices/#page-and-microflow-urls). + {{% alert color="info" %}} This constraint exists because the runtime must determine which page to open based solely on the incoming URL — before loading any data. When a user navigates directly to a URL (for example, from a bookmark or external link), the runtime has no session context available. If two pages shared the same URL pattern, the router would have no way to resolve which page to open without first querying the database. Performing database queries during routing is not practical: it would significantly increase page load latency and produce unreliable results. Standard web routing frameworks apply the same principle — ambiguous route patterns cause a routing conflict. Mendix enforces this at compile time rather than allowing it to fail at runtime. {{% /alert %}} -If you need incoming links to work across multiple pages that would otherwise share a URL pattern, the following approaches are available: - -* **Use distinct static URL segments** — Give each page a unique static prefix so each pattern is unambiguous. For example, use `orders/{Order/Id}` and `invoices/{Invoice/Id}` instead of a shared base pattern such as `documents/{Document/Id}`. - -* **Use a microflow URL as a router** — Assign the shared URL pattern to a microflow instead of a page. The microflow receives the parameter, determines which page to open (for example, based on an enumeration or string value), and uses **Show Page** to navigate. For example, a microflow handling `report/{ReportType}` can read the `ReportType` string parameter and open the corresponding page, such as a sales report or an inventory report page. Note that nanoflows are not supported for URL handling. +If you cannot avoid a conflict using URL structure, you can use a microflow URL as a router: assign the URL pattern to a microflow instead of a page. The microflow receives the parameter, determines which page to open (for example, based on an enumeration or string value), and uses **Show Page** to navigate. For example, a microflow handling `report/{ReportType}` can read the `ReportType` string parameter and open the corresponding page, such as a sales report or an inventory report page. Note that nanoflows are not supported for URL handling. ### Common Section {#common} diff --git a/content/en/docs/refguide10/modeling/pages/page/page-properties.md b/content/en/docs/refguide10/modeling/pages/page/page-properties.md index 8469ae76ad3..2cceb0be24d 100644 --- a/content/en/docs/refguide10/modeling/pages/page/page-properties.md +++ b/content/en/docs/refguide10/modeling/pages/page/page-properties.md @@ -89,19 +89,15 @@ Mendix does not recommend configuring page URLs for pages that are displayed as #### URL Uniqueness Requirement {#url-uniqueness} -Each page URL pattern must be unique across your application. Studio Pro compares URL patterns structurally — the parameter names themselves do not matter. Two pages with URLs like `documents/{ParamA}` and `documents/{ParamB}` are considered identical patterns and will produce a consistency error, even if the parameters refer to different entity types or have different names. - All page parameters must appear in the URL. This means a page with a parameter cannot have a static URL such as `documents/orders` — the parameter must be part of the URL pattern. +Page URL patterns must also be unambiguous. For the full rules on what constitutes a conflict and how to resolve it using URL structure, see [Page and Microflow URLs](/refguide/general-best-practices/#page-and-microflow-urls). + {{% alert color="info" %}} This constraint exists because the runtime must determine which page to open based solely on the incoming URL — before loading any data. When a user navigates directly to a URL (for example, from a bookmark or external link), the runtime has no session context available. If two pages shared the same URL pattern, the router would have no way to resolve which page to open without first querying the database. Performing database queries during routing is not practical: it would significantly increase page load latency and produce unreliable results. Standard web routing frameworks apply the same principle — ambiguous route patterns cause a routing conflict. Mendix enforces this at compile time rather than allowing it to fail at runtime. {{% /alert %}} -If you need incoming links to work across multiple pages that would otherwise share a URL pattern, the following approaches are available: - -* **Use distinct static URL segments** — Give each page a unique static prefix so each pattern is unambiguous. For example, use `orders/{Order/Id}` and `invoices/{Invoice/Id}` instead of a shared base pattern such as `documents/{Document/Id}`. - -* **Use a microflow URL as a router** — Assign the shared URL pattern to a microflow instead of a page. The microflow receives the parameter, determines which page to open (for example, based on an enumeration or string value), and uses **Show Page** to navigate. For example, a microflow handling `report/{ReportType}` can read the `ReportType` string parameter and open the corresponding page, such as a sales report or an inventory report page. Note that nanoflows are not supported for URL handling. +If you cannot avoid a conflict using URL structure, you can use a microflow URL as a router: assign the URL pattern to a microflow instead of a page. The microflow receives the parameter, determines which page to open (for example, based on an enumeration or string value), and uses **Show Page** to navigate. For example, a microflow handling `report/{ReportType}` can read the `ReportType` string parameter and open the corresponding page, such as a sales report or an inventory report page. Note that nanoflows are not supported for URL handling. ### Common Section {#common}