From e45c3d3621da5cd3478391aa4e9b4208184c7e25 Mon Sep 17 00:00:00 2001 From: Wim Jongeneel Date: Wed, 20 May 2026 15:30:19 +0200 Subject: [PATCH] Document URL pattern best practices --- .../microflows/microflow.md | 2 ++ .../dev-best-practices/general-guidelines.md | 23 +++++++++++++++++++ .../modeling/pages/page/page-properties.md | 2 ++ 3 files changed, 27 insertions(+) diff --git a/content/en/docs/refguide/modeling/application-logic/microflows-and-nanoflows/microflows/microflow.md b/content/en/docs/refguide/modeling/application-logic/microflows-and-nanoflows/microflows/microflow.md index bfc9b313dd1..dc90a0d0265 100644 --- a/content/en/docs/refguide/modeling/application-logic/microflows-and-nanoflows/microflows/microflow.md +++ b/content/en/docs/refguide/modeling/application-logic/microflows-and-nanoflows/microflows/microflow.md @@ -52,6 +52,8 @@ In the **Edit Microflow URL** dialog box, the configured URL is shown together w URLs are not supported for microflows that have non-persistable entities or lists as parameters. {{%/alert %}} +For recommendations on structuring URLs and avoiding conflicts, see [Page and Microflow URLs](/refguide/general-best-practices/#page-and-microflow-urls). + ### Common Section {#common} #### Name diff --git a/content/en/docs/refguide/modeling/best-practices/dev-best-practices/general-guidelines.md b/content/en/docs/refguide/modeling/best-practices/dev-best-practices/general-guidelines.md index 81ce54e63d6..9dfc8ea428b 100644 --- a/content/en/docs/refguide/modeling/best-practices/dev-best-practices/general-guidelines.md +++ b/content/en/docs/refguide/modeling/best-practices/dev-best-practices/general-guidelines.md @@ -30,6 +30,29 @@ Applications exceeding these guidelines may still function, depending on your sy App size impacts IDE performance. Choose a development strategy that aligns with your system's capabilities and Mendix's recommended guidelines. {{% /alert %}} +## Page and Microflow URLs {#page-and-microflow-urls} + +When designing page and microflow URLs, prefer clear path segments over compact patterns: + +* Use `/` to divide the URL into meaningful parts +* Prefer putting a parameter in its own segment, for example, `product/{Product/Name}` instead of `product-{Product/Name}` +* Use static segments to make the structure explicit, for example, `category/{Category/Code}/product/{Product/Name}` + +This makes URLs easier to read, easier to maintain, and less likely to conflict with other URLs. + +URL conflicts are checked per path segment. Two URLs are considered conflicting when they have the same number of segments and Studio Pro cannot determine that at least one corresponding segment is always different. + +Common conflict cases include the following: + +* Two parameters in the same position, such as `product/{Product/Name}` and `product/{Product/Code}` +* A static segment that can also be matched by a parameter, such as `product/{Product/Name}` and `product/sale` +* A numeric static segment that overlaps with an `Id` parameter, such as `order/{Order/Id}` and `order/123` +* Mixed segments where neither the static prefix nor the static suffix makes the segment unique, such as `product-{Product/Name}-details` and `product-sale-details` + +If either the prefix or the suffix is unique, the segments do not conflict. + +Using separate segments reduces ambiguity. For example, `product/{Product/Name}` and `product-sale` do not conflict because they have a different number of segments. + ## Model SDK The Mendix Model SDK enforces a strict limit of 20,000 units per working copy. 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..6968f0b3d9b 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,8 @@ 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 %}} +For recommendations on structuring URLs and avoiding conflicts, see [Page and Microflow URLs](/refguide/general-best-practices/#page-and-microflow-urls). + ### Common Section {#common} {{% snippet file="/static/_includes/refguide/common-section-link.md" %}}