ALTER PAGE / ALTER SNIPPET

The ALTER PAGE and ALTER SNIPPET statements modify an existing page or snippet’s widget tree in-place, without requiring a full CREATE OR REPLACE. This is especially useful for incremental changes: adding a field, changing a button caption, or removing an unused widget.

ALTER operates directly on the raw widget tree, preserving any widget types that MDL does not natively support (pluggable widgets, custom widgets, etc.).

Syntax

ALTER PAGE <Module>.<Name> {
  <operations>
};

ALTER SNIPPET <Module>.<Name> {
  <operations>
};

Operations

SET – Modify Widget Properties

Change one or more properties on a widget identified by name:

-- Single property
ALTER PAGE Module.EditPage {
  SET Caption = 'Save & Close' ON btnSave
};

-- Multiple properties at once
ALTER PAGE Module.EditPage {
  SET (Caption = 'Save & Close', ButtonStyle = Success) ON btnSave
};

Supported SET properties:

SET – Page-Level Properties

Omit the ON clause to set page-level properties:

ALTER PAGE Module.EditPage {
  SET Title = 'Customer Details'
};

SET – Pluggable Widget Properties

Use quoted property names to set properties on pluggable widgets (ComboBox, DataGrid2, etc.):

ALTER PAGE Module.EditPage {
  SET 'showLabel' = false ON cbStatus
};

INSERT – Add Widgets

Insert new widgets before or after an existing widget:

-- Insert after a widget
ALTER PAGE Module.EditPage {
  INSERT AFTER txtEmail {
    TEXTBOX txtPhone (Label: 'Phone', Attribute: Phone)
    TEXTBOX txtFax (Label: 'Fax', Attribute: Fax)
  }
};

-- Insert before a widget
ALTER PAGE Module.EditPage {
  INSERT BEFORE btnSave {
    ACTIONBUTTON btnPreview (Caption: 'Preview', Action: MICROFLOW Module.ACT_Preview)
  }
};

The inserted widgets use the same syntax as in CREATE PAGE. Multiple widgets can be inserted in a single block.

DROP WIDGET – Remove Widgets

Remove one or more widgets by name:

ALTER PAGE Module.EditPage {
  DROP WIDGET txtUnused
};

-- Multiple widgets
ALTER PAGE Module.EditPage {
  DROP WIDGET txtFax, txtPager, btnObsolete
};

Dropping a container widget also removes all of its children.

REPLACE – Replace a Widget

Replace a widget (and its subtree) with new widgets:

ALTER PAGE Module.EditPage {
  REPLACE txtOldField WITH {
    TEXTAREA txtNotes (Label: 'Notes', Attribute: Notes)
  }
};

Page Variables

Add or remove page-level variables:

-- Add a variable
ALTER PAGE Module.EditPage {
  ADD Variables $showAdvanced: Boolean = 'false'
};

-- Remove a variable
ALTER PAGE Module.EditPage {
  DROP Variables $showAdvanced
};

Combining Operations

Multiple operations can be combined in a single ALTER statement. They are applied in order:

ALTER PAGE Module.Customer_Edit {
  -- Change button appearance
  SET (Caption = 'Save & Close', ButtonStyle = Success) ON btnSave;

  -- Remove unused fields
  DROP WIDGET txtFax;

  -- Add new fields after email
  INSERT AFTER txtEmail {
    TEXTBOX txtPhone (Label: 'Phone', Attribute: Phone)
    TEXTBOX txtMobile (Label: 'Mobile', Attribute: Mobile)
  };

  -- Replace old status dropdown with combobox
  REPLACE ddStatus WITH {
    COMBOBOX cbStatus (Label: 'Status', Attribute: Status)
  }
};

Workflow Tips

1. Discover widget names first – Run DESCRIBE PAGE Module.PageName to see the current widget tree with all widget names.

2. Use ALTER for small changes – For adding a field or changing a caption, ALTER is faster and safer than CREATE OR REPLACE, because it preserves widgets that MDL cannot round-trip (pluggable widgets with complex configurations).

3. Use CREATE OR REPLACE for major rewrites – When restructuring the entire page layout, a full replacement is cleaner.

Examples

Add a Field to an Edit Page

-- First, check what's on the page
DESCRIBE PAGE MyModule.Customer_Edit;

-- Add a phone field after email
ALTER PAGE MyModule.Customer_Edit {
  INSERT AFTER txtEmail {
    TEXTBOX txtPhone (Label: 'Phone Number', Attribute: Phone)
  }
};

Change Button Behavior

ALTER PAGE MyModule.Order_Edit {
  SET (Caption = 'Submit Order', ButtonStyle = Success) ON btnSave;
  SET Caption = 'Discard' ON btnCancel
};

Add a DataGrid Column

Since DataGrid columns are part of the widget tree, use INSERT to add columns:

ALTER PAGE MyModule.Customer_Overview {
  INSERT AFTER colEmail {
    COLUMN colPhone (Attribute: Phone, Caption: 'Phone')
  }
};

See Also

• Pages – page overview and CREATE PAGE basics
• Widget Types – widgets available for INSERT and REPLACE
• Snippets – ALTER SNIPPET uses the same operations
• Common Patterns – page layout patterns