Manage Navigation

Navigation Management Skill

This skill covers inspecting and modifying Mendix navigation profiles via MDL: home pages, menu items, login pages, role-based routing, and navigation catalog queries.

When to Use This Skill

Use when the user asks to:

• View or change navigation home pages
• View or modify the navigation menu structure
• Set login or not-found pages
• Configure role-based home page routing
• Discover which pages are navigation entry points
• Set up navigation for a new project

Navigation Concepts

• Navigation Profiles — Every Mendix project has navigation profiles: Responsive, Phone, Tablet, and optionally Native. Each profile has its own home page, menu, and login page. The web kinds are a closed set and create or replace navigation will create one that does not exist yet:

  Online	Offline twin
  Responsive	ResponsiveOffline
  Phone	PhoneOffline
  Tablet	TabletOffline

  An invented name (Mobile, Desktop) is an error, not a new profile: Mendix routes on User-Agent to its own kinds, so a profile the platform does not define can never be reached. Native profiles are a different document type and are not creatable from MDL.

• Offline Profiles — An offline profile makes the app work without a connection (a PWA with a local database that syncs). It is not a different document — same properties as its online twin — but it constrains every page it can reach, see below.

• Home Page — The default page shown after login. Can be a PAGE or MICROFLOW.

• Role-Based Home Pages — Override the default home page per user role (e.g., admins see a dashboard, users see a task list).

• Menu Items — Hierarchical menu tree. Each item has a caption and optionally targets a PAGE or MICROFLOW. Sub-menus nest with menu 'caption' { ... }.

• Menu Documents — A separate document type (Menus$MenuDocument) holding a reusable menu that a menu widget points at, e.g. Atlas_Core's Phone_Menu. Not the same thing as a profile's menu, though both are built from the same items, so the item syntax is identical. Managed with create/describe/drop menu — see below.

• Login Page — Custom login page (optional; Mendix provides a default).

• Not-Found Page — Custom 404 page (optional).

Show Commands (Read-Only)

-- Summary of all navigation profiles (home pages, menu counts)
list navigation;

-- Full MDL description of a profile (round-trippable output)
describe navigation Responsive;
describe navigation;              -- all profiles

-- Menu tree for a specific profile
list navigation menu Responsive;
list navigation menu;             -- all profiles

-- Home page assignments across all profiles and roles
list navigation homes;

CREATE OR MODIFY NAVIGATION (Full Replacement)

This command fully replaces a navigation profile's configuration. All clauses are optional — omitted clauses clear that section. The output from describe navigation can be pasted back directly.

Basic: Set Home and Login Page

mdl 1;
create or modify navigation Responsive
  home page MyModule.Home_Web
  login page Administration.Login;

Role-Based Home Pages

Add for <UserRole> to override the home page for specific user roles. The role is a bare name — user roles are project-level and have no module part:

mdl 1;
create or modify navigation Responsive
  home page MyModule.Home_Web
  home page MyModule.AdminDashboard for Administrator
  home page MyModule.CustomerPortal for Customer
  login page Administration.Login;

Never write a module-qualified role here. for Administration.Administrator is a module role, and Mendix cannot load a project containing one in this position:

StorageLoadException: Role based home page has an invalid value '' for property
UserRole. The text 'Administration.Administrator' is not a valid UserRoleIdentifier.

That is worse than a build error — it happens before checking runs, so there is no error code and no line number, and mx check exits non-zero without the "The app contains: N errors" line. The two role kinds are easy to confuse because they share names: a blank app has a user role Administrator and module roles called Administrator in three modules. List the real ones with list user roles; mxcli check --references refuses the wrong form.

Full Menu Tree

The menu items are the profile's children, in { ... } after its clauses, like a page's widgets — no ; between them. The block replaces the entire menu. Use menu item 'Caption' ( OnClick: … ) for leaf items and menu 'caption' { ... } for sub-menus. OnClick: takes the action expression a button's Action: takes, limited to what a menu item can do: show page M.P, call microflow M.F, call nanoflow M.N, open link 'https://…', create object M.E then show page M.E_New, sign out or nothing — each with the button's with ( … ) settings (ProgressBar, ProgressMessage, Confirmation/ProceedCaption/CancelCaption, Asynchronous and FormValidations for a microflow, DisabledDuringExecution). Save, delete, close page and complete task act on a page's object and are refused on a menu item:

mdl 1;
create or modify navigation Responsive
  home page MyModule.Home_Web
  login page Administration.Login
  {
    menu item 'Home' ( OnClick: show page MyModule.Home_Web )
    menu 'Orders' {
      menu item 'All Orders' ( OnClick: show page Orders.Order_Overview )
      menu item 'New Order' ( OnClick: show page Orders.Order_New )
    }
    menu 'Admin' {
      menu item 'Users' ( OnClick: show page Administration.Account_Overview )
      menu item 'Run Report' ( OnClick: call microflow Reports.ACT_GenerateReport with (ProgressBar: Blocking, ProgressMessage: 'Generating…') )
    }
    menu item 'Reports' ( OnClick: call nanoflow Reports.NAV_ShowReports )
    menu item 'Docs' ( OnClick: open link 'https://docs.mendix.com' )
    menu item 'New order' ( OnClick: create object Orders.Order then show page Orders.Order_New )
  };

Describe prints every stored action this way, so describe → exec writes nothing. What the expression cannot spell — a show page's page title override, an open link's link type other than Web — is flagged with a -- comment; a rewrite keeps it while the item's action is unchanged (same caption, same action), and loses it if the item is renamed or its action changed. An action describe cannot print at all is flagged too, and an item that states no OnClick keeps it.

The old spelling — menu ( menu item 'Home' page M.Home; menu 'Admin' ( … ); ), the action and icon as clauses and ; after each item — still parses and warns (MDL-DEPR121, MDL-DEPR122); mxcli fmt --upgrade rewrites it.

Menu Icons

Give every menu item an icon. It is optional in the grammar and mxcli check warns when it is missing (MDL077), because the navigation sidebar collapses to an icon rail and that is the state most users leave it in: a collapsed item shows its icon, and one without falls back to the first few characters of its caption — rarely enough to tell Orders from Order lines. Nothing else catches it. The model builds, mx check passes, and the menu is simply hard to use.

Both menu item and menu 'caption' { ... } take an Icon: in their property list, in one of three forms — Mendix stores three different icon elements, not three spellings of one value:

menu item 'Home'  ( OnClick: show page M.Home,  Icon: Atlas_Core.Atlas.home )   -- icon collection
menu item 'Close' ( OnClick: show page M.Close, Icon: glyph 57377 )             -- numeric glyph code
menu item 'Logo'  ( OnClick: show page M.Logo,  Icon: image M.Images.logo )     -- image collection
menu 'Admin' ( Icon: Atlas_Core.Atlas.user ) { … }                               -- a sub-menu's icon

The bare form is the icon-collection icon and is what you normally want. Use glyph only to reproduce a legacy icon a project already has — describe navigation emits it for you — and image for a picture from an image collection, which is a different document from an icon collection.

Do not invent a glyph code. It is a bare integer that nothing resolves, so a code the Mendix font does not define passes mxcli check AND mx check at 0 errors and then breaks mxbuild --target=deploy with "An exception occurred while exporting layout '<some layout>'" — a message naming a document that is not the cause. mxcli check now warns (MDL078) against the 247 codes the shipped font defines, but a glyph is still an unchecked number where an icon collection reference is a resolved model reference. Browse the codes with list glyphs (list glyphs like 'star' searches by name, describe glyph 57350 goes the other way), or use Icon: Atlas_Core.Atlas.<name> and list the names with describe icon collection Atlas_Core.Atlas.

The icon-collection form is a qualified name — a model reference, written like every other reference in MDL, not a string:

mdl 1;
create or modify navigation Responsive
  home page MyModule.Home_Web
  {
    menu item 'Home' ( OnClick: show page MyModule.Home_Web, Icon: Atlas_Core.Atlas.home )
    menu 'Orders' ( Icon: Atlas_Core.Atlas."shopping-cart" ) {
      menu item 'All Orders' ( OnClick: show page Orders.Order_Overview,
        Icon: Atlas_Core.Atlas."list-bullets" )
    }
  };

Hyphenated names are double-quoted (Atlas_Core.Atlas."align-center") — a hyphen does not lex as an identifier, so the segment is quoted exactly as a keyword-colliding name would be. Plain names need no quotes, including ones that happen to be MDL keywords (home, user, add). Atlas_Core ships three collections: Atlas (outline), Atlas_Filled, and Atlas_Styling. List what is actually available in your project rather than guessing a name:

list icon collections;
describe icon collection Atlas_Core.Atlas;

Only the icon-collection form is writable. Studio Pro can also attach a glyph icon (a numeric character code) or an image icon (pointing into an image collection). Those are different elements with different fields, so MDL does not write them — and describe navigation reports them as a comment rather than emitting an Icon: that would silently convert one into the other on replay:

menu item 'Close' ( OnClick: show page MyModule.Close )
-- icon System.Images.Close (Forms$ImageIcon) is not reproducible by CREATE NAVIGATION; set it in Studio Pro

Offline Synchronization

An offline profile downloads nothing until its entities are given a sync mode. Without a SYNC block the app builds, routes and installs as a PWA — and shows an empty screen. That is the single most common way an offline profile looks broken while every check passes.

mdl 1;
create or modify navigation PhoneOffline
  home page MyModule.Mobile_Dashboard
  sync (
    sync MyModule.Setting online;
    sync MyModule.Vehicle all;
    sync MyModule.Trip where [Distance > 0];
    sync MyModule.AuditEntry never;
    sync MyModule.Lookup none;
    sync MyModule.Draft none preserve data;
  );

The words are not Studio Pro's captions. Its dialog shows "All Objects" and "By XPath"; neither is a value Mendix stores. all and where are. Copying a caption out of the UI gives a parse error rather than a broken document, which is deliberate.

where implies the constrained mode rather than naming it, so a constraint without a mode and a mode without a constraint are both unspellable.

Use the bracket form. It takes the XPath verbatim — nothing inside is escaped, so quoted literals stay readable:

sync MyModule.Team where [contains(Name, 'abc')];

A quoted where '<xpath>' still parses, but every quote inside it must be doubled — and a stored constraint already carries Mendix's own escaping, so the two compose into runs of six quotes. describe navigation emits the bracket form. This is the general problem tracked as mendixlabs/mxcli#750.

The block replaces the stored list, the way the { ... } menu block replaces the menu. Omitting it leaves the stored configuration alone.

Ask the catalog which entities sync, rather than reading the profile.

select EntityQualifiedName, SyncMode, XPathConstraint
  from CATALOG.OFFLINE_ENTITY_CONFIGS where ProfileName = 'PhoneOffline';

And before changing an entity, ask which profiles download it — an offline change reaches every device that already synced:

list references to MyModule.Order;

The sync row names the profile. Every mode produces one, including the modes that download nothing: a profile with sync X never still names X, so renaming or dropping it leaves the configuration dangling.

Errors when the server rejects an object. Studio Pro's "Throw error when server rejects objects during synchronization" checkbox:

mdl 1;
create or modify navigation PhoneOffline
  home page MyModule.Mobile_Dashboard
  on sync error continue;      -- default is `throw`

It uses the phrase MDL already has for failure handling — a microflow's on error continue — rather than a keyword of its own. Omitting the clause leaves the stored value alone; describe navigation emits it only when it is not the default, so existing scripts stay quiet.

Compatibility mode has no syntax. mxcli reads it, preserves it across a rewrite, and describe navigation flags any entity that has it on — it is never silently dropped.

Clear the Menu

An empty { } menu block removes all menu items:

mdl 1;
create or modify navigation Responsive
  home page MyModule.Home_Web
  {};

Not-Found Page

mdl 1;
create or modify navigation Responsive
  home page MyModule.Home_Web
  not found page MyModule.Custom404;

Microflow as Home Page

Use home microflow instead of home page to run a microflow on login:

mdl 1;
create or modify navigation Responsive
  home microflow MyModule.ACT_ShowHome;

A native profile's flow home is a nanoflow: home nanoflow MyModule.NAV_Home (home nanoflow on a web profile is refused). On a native profile mxcli writes the home pages and the sync ( … ) block only — a { } menu block (the bottom bar), login page, not found page and on sync error are refused, and describe lists the bottom bar as comments.

Round-Trip Workflow

The DESCRIBE output is directly executable. Use this pattern to inspect, modify, and re-apply:

mdl 1;
-- Step 1: Inspect current state
describe navigation Responsive;

-- Step 2: Copy the output, modify as needed, paste back
create or modify navigation Responsive
  home page MyModule.Home_Web
  login page Administration.Login
  {
    menu item 'Home' ( OnClick: show page MyModule.Home_Web )
    menu item 'New Feature' ( OnClick: show page MyModule.NewFeature )
  };

-- Step 3: Verify
describe navigation Responsive;

Catalog Queries

After refresh catalog full, navigation references appear in the REFS table:

refresh catalog full;

-- Find all pages that are navigation entry points
select SourceName, TargetName, RefKind
from CATALOG.REFS
where RefKind in ('home_page', 'menu_item', 'login_page');

-- What references point to a specific page?
list references to MyModule.Home_Web;

-- Impact analysis: what breaks if I change this page?
list impact of MyModule.Home_Web;

-- Full context for a page (includes navigation references)
describe context of MyModule.Home_Web;

Common Patterns

New Project Setup

Set up navigation for a freshly created project:

mdl 1;
-- Create home page
create page MyModule.Home_Web
(
  title: 'Home',
  layout: Atlas_Core.Atlas_Default
)
{
  container ctnMain {
    dynamictext txtWelcome (content: 'Welcome!')
  }
};

-- Configure navigation
create or modify navigation Responsive
  home page MyModule.Home_Web
  {
    menu item 'Home' ( OnClick: show page MyModule.Home_Web )
  };