Alter Page

ALTER PAGE / ALTER SNIPPET - Modify Existing Pages and Snippets

Overview

ALTER PAGE and ALTER SNIPPET modify an existing page or snippet's widget tree in-place without requiring a full create or modify. Operations work directly on the raw BSON tree, preserving widget types and properties that MDL doesn't explicitly model.

When to Use

Rule of thumb:

• alter page — targeted edits to one page. Combine multiple ops in one block when they belong together.
• update widgets — cross-page bulk updates with WHERE filtering and DRY RUN.
• create or modify page — redefining the full page structure of a page your MDL scripts own.

Who owns the page decides (choose-edit-mode). A page or snippet authored or edited in Studio Pro is changed with alter, however large the change. describe → edit → create or modify is only for pages your MDL scripts created and nobody has changed in Studio Pro since: on a Studio Pro page that round trip has dropped translations and filled an empty English caption from another language, and on a snippet it has dropped the snippet's type.

Syntax

alter page Module.PageName {
  operation1;
  operation2;
  ...
};

alter snippet Module.SnippetName {
  operation1;
  operation2;
  ...
};

This is the generic ALTER — the same four verbs for every document type (alter layout too):

alter page Module.PageName {
  set (Key: value, …) on <target>;      -- no `on`: the page itself
  insert before|after|into <target> { <widgets as in create page> }
  replace <target> with { <widgets> }
  drop <target>, <target>;
};

A <target> on a page is a widget name, a DataGrid 2 column grid column(Attr) (or grid column('Caption')), or a layout region layoutContainer.top. Properties go in parentheses with :, exactly as in create page. The older spellings set Key = value on w, set Key: value (no parentheses) and drop widget w still run, and warn with MDL-DEPR101, MDL-DEPR102 and MDL-DEPR103 — write the form above.

Multiple operations can be combined in a single ALTER statement. They are applied sequentially; later operations see the page state produced by earlier ones, so you can set on a widget you just inserted.

mdl 1;
-- Rename a column, add a sibling, drop an obsolete one — all in one block.
alter page MyMod.Product_Overview {
  set (caption: 'Product Name') on dgProducts column(Name);
  insert after dgProducts column(Lifecycle) {
    column (attribute: Sku, caption: 'SKU')
  };
  drop dgProducts column('Old')
};

For changes that should be applied across many pages (e.g., "add Class='card' to every Container in MyMod"), use UPDATE WIDGETS instead — see bulk-widget-updates.

Operations

List View Specialization Templates

A List View template has no name, so it cannot be reached by a widget ref like every other target. Adding one reuses INSERT INTO with the same template for block create page uses — a template has one spelling everywhere. Removing one has its own form:

mdl 1;
alter page Pages.Vehicle_Overview {
  insert into vehicleListView {
    template for Pages.Motorcycle {
      dynamictext mcLabel (content: 'Motorcycle {1}', contentparams: ({1} = Brand))
    }
  };
  drop template for Pages.SUV in vehicleListView
};

Naming the list view in the drop is required, not optional: one page can hold two list views with a template for the same entity.

Most template edits need none of this. The widgets inside a template are ordinary named widgets, so set (content: '…') on busLabel and insert after busLabel { … } already work and land in the right template. To replace a whole template, drop it and insert the new one in the same block — operations apply in order.

Refused, each naming the problem:

• insert before / insert after a template — templates are not siblings of the widgets in the list view's body, so only insert into makes sense.
• mixing template for … blocks with ordinary widgets in one insert — they go to different places (the Templates array and the default body). Use two inserts.
• a template for an entity that is not the list view's entity or a specialization of it — it could never match an object the list view shows.
• a second template for an entity that already has one.
• drop template for an entity with no template — the error names the ones that are there, because dropping nothing and reporting success is how a typo becomes a silent no-op.

SET - Modify Widget Properties

-- Single property
set (caption: 'New Caption') on widgetName

-- Multiple properties
set (caption: 'Save & Close', buttonstyle: success) on btnSave

-- Page-level property (no ON clause). Page-level property names are
-- case-sensitive and must match the Mendix property exactly.
set (Title: 'New Page Title')

-- Pop-up dimensions (apply when the page is opened in a pop-up)
set (PopupWidth: 800)
set (PopupHeight: 480)
set (PopupResizable: true)
set (Documentation: 'What this page is for.')

-- Retarget a button's on-click action. Any form `create page` accepts works
-- here, including the combined ones.
set (Action: call microflow Module.ACT_Other) on btnSave
set (Action: SAVE CHANGES CLOSE PAGE) on btnSave
set (Action: SHOW PAGE Module.DetailPage) on btnEdit

-- Retarget ONE named action slot of a pluggable widget, by the widget's own
-- property key (the same key `create page` takes: `createFileAction: …`).
set ('createFileAction': call microflow Module.ACT_CreateFile) on fileUploader1
set ('onSelectionChange': show page Module.Detail) on dgOrders

-- Rebind a data-bound widget
set (DataSource: $OrderParam) on dvOrder
set (DataSource: microflow Module.MF_Get) on dvOrder

Prefer set Action over replace when only the action changes. replace rebuilds the widget from what the statement says, so any property you do not restate — ButtonStyle, Class, design properties, tooltip — is dropped. set edits the one property and leaves the rest of the widget alone.

The exception is a pluggable widget replaced by one of the same kind (a combo box by a combo box): there replace keeps every stored property the statement does not change — a translated placeholder, readOnlyStyle, anything MDL has no word for — and writes only what differs from the widget as describe prints it. So a sort can be added to a combo box's options by restating its describe line with sort by appended.

set Action is refused on a widget that has no action (a plain container, say), rather than writing a property the widget type does not define — Studio Pro refuses to open a document with an unknown property while MxBuild tolerates it, so a silent write would build cleanly and then fail to open.

Supported SET properties:

Conditional visibility/editability — set (Visible: <expr>) on widget (and Editable) attach a per-object client expression, stored as written: name attributes as $currentObject/Name. The bracketed set (Visible: [Name != '']), which roots a bare attribute for you, still works and warns MDL-DEPR081. Setting Editable on a non-input widget is rejected. This mirrors CREATE PAGE's visible: — see the create-page skill for enum-value rules.

Pluggable widget properties use quoted names to set values in the widget's Object.Properties[]. Boolean values are stored as "yes"/"no" in BSON.

Column property names are case-insensitive in MDL — set (caption: …) and set (Caption: …) both work. The internal BSON keys are dictated by the widget schema and stay case-sensitive on the storage side.

Warning: Style on DYNAMICTEXT — Setting style directly on a DYNAMICTEXT widget crashes MxBuild with a NullReferenceException. Wrap the DYNAMICTEXT in a CONTAINER and apply styling to the container instead:

-- Wrong: crashes MxBuild
SET (Style: 'color: red;') ON txtHeading

-- Correct: style the container
REPLACE txtHeading WITH {
  CONTAINER ctnHeading (Style: 'color: red;') {
    DYNAMICTEXT txtHeading (Content: 'Heading', RenderMode: H2)
  }
}

Changing a widget's DataSource

SET DataSource retypes a data source in place — including across shapes, e.g. from a microflow to a page parameter:

mdl 1;
ALTER PAGE MyModule.OrderPage {
  SET (DataSource: $Order) ON dvOrder;                       -- page/snippet parameter
  SET (DataSource: microflow MyModule.MF_Get) ON dvOrder;     -- microflow
  SET (DataSource: nanoflow MyModule.NF_Get) ON dvOrder;      -- nanoflow
  SET (DataSource: selection dgOrders) ON dvDetail;           -- listen to widget
};

The parameter must exist on the page (or snippet) being altered — its entity is read from the container's own parameter list, and an unknown name is refused rather than written as an unresolved reference.

association and database sources are not supported by SET. Use REPLACE for those, which rebuilds the widget through the CREATE PAGE path and handles every datasource type; the error message says so.

A database source has no single stored shape — the widget holding it decides which element Mendix writes (a list view, a data grid and a pluggable widget each store a different one), and SET writes the property directly rather than rebuilding the widget, so it has nothing to choose from. This used to be accepted and half-applied: the widget was left with a source that DESCRIBE read back as absent and mxbuild rejected as CE7007, on a page exec had just reported as altered (mendixlabs/mxcli#1032).

A data view is the one case REPLACE does not rescue: it binds to a single object, so Mendix gives it no database form at all and the CREATE PAGE path refuses one too. Point it at a context parameter, a microflow, a nanoflow or selection <widget>, and use a list view or a data grid to show a query. The refusal says which of the two situations you are in.

INSERT - Add Widgets

-- Insert after a widget
insert after txtName {
  textbox txtMiddleName (label: 'Middle Name', attribute: MiddleName)
}

-- Insert before a widget
insert before btnSave {
  actionbutton btnPreview (caption: 'Preview', action: call microflow Module.ACT_Preview)
}

-- Insert INTO a container — append as its last child (works on an EMPTY container)
insert into ctnToolbar {
  actionbutton btnNew (caption: 'New', action: nothing, buttonstyle: primary)
}

Inserted widgets use the same syntax as create page. Multiple widgets can be inserted in a single block.

insert into <container> appends as the last child of the named container — the only way to fill an empty container, and handy for adding to a container/dataview without needing a sibling to anchor to. Widgets inserted into a dataview take that dataview's entity as their context. Supported on simple containers (container, dataview, groupbox, tab page, scroll-container region); for a layout grid, insert relative to a widget inside the target column instead.

Adding a tab: insert into <tabcontainer> { tabpage … } appends a tab page, and insert after|before <tabpage> { tabpage … } places it next to that sibling. A tab page cannot go next to an ordinary widget or inside another tab page, and one insert cannot mix tab pages and widgets. Dropping or reordering tab pages still needs create or modify page.

The context comes from the nearest enclosing data source, whatever kind it is — a database or association source, a microflow/nanoflow source (the entity is the flow's return type), or datasource: selection <list>, which takes the entity of the list it listens to. A bare attribute in the inserted or replaced widget resolves against that entity, exactly as it would in create page. When no enclosing source can be resolved, the binding is written unset rather than guessed at — describe page then prints <unbound>, and mxbuild reports CE0402 "No value specified.", so re-describe the page after an ALTER that moves data-bound widgets.

DROP - Remove Widgets

-- Drop a single widget
drop txtUnused

-- Drop multiple widgets
drop txtOldField, lblOldLabel, container2

Removes widgets and their entire subtree from the page.

REPLACE - Replace Widget Subtree

mdl 1;
-- Replace a data view's footer (it has no name: address it by its data view)
alter page MyModule.Customer_Edit {
  replace dvMain.footer with {
    footer {
      actionbutton btnSave (caption: 'Save', action: save changes, buttonstyle: primary)
      actionbutton btnCancel (caption: 'Cancel', action: cancel changes)
    }
  }
};

Replaces the target widget with one or more new widgets. The new widgets use the same syntax as create page, and may reuse the names of the widgets the replace removes. insert into dvMain.footer { … } appends to a footer and drop dvMain.footer empties it.