Form Patterns
A form pattern is a predefined control-tree template that the D365 F&O framework validates at compile time. Every form design should comply with a pattern. Patterns enforce a consistent visual structure, automatic layout, responsive behaviour, and accessibility across the application.
When a pattern is applied to a form's design node, the Best Practice checker validates that the control hierarchy matches the expected structure — the correct container types, the right nesting order, mandatory controls (such as action panes or grids), and optional regions. If the control tree deviates from the pattern specification, a compile-time warning or error is raised.
Why Form Patterns Matter
| Concern | Benefit |
|---|---|
| Consistency | Every form that follows the same pattern looks and behaves identically, reducing the learning curve for end-users. |
| Automatic layout | The framework manages responsive resizing, column flow, and spacing. Developers do not need to set manual pixel positions. |
| Accessibility | Patterned forms comply with accessibility standards (keyboard navigation, screen-reader landmarks) by default. |
| Upgradeability | When the platform evolves, patterned forms automatically pick up visual and behavioural improvements without code changes. |
| Quality gates | The pattern validator acts as a compile-time guardrail, catching structural mistakes before they reach production. |
How Patterns Are Applied
Two properties on the Design node (AxFormDesign) and on any container control (AxFormControl) control pattern assignment:
| Property | Type | Description |
|---|---|---|
Pattern | String | The name of the applied pattern (e.g., DetailsFormMaster, SimpleList). |
PatternVersion | String | The version of the pattern specification. Used when multiple versions of the same pattern coexist during platform upgrades. |
The Style property on the design node (FormStyle enum) works in tandem with the pattern. The style tells the framework how to render the form chrome (caption bar, navigation, window type), while the pattern dictates the internal control-tree structure.
FormStyle Enum Values
| Value | Name | Description |
|---|---|---|
| 0 | Auto | Framework determines the style automatically. |
| 1 | DetailsFormMaster | Master-detail form. Used with Details Master or Details Transaction patterns. |
| 2 | Dialog | Modal dialog form. |
| 3 | DropDialog | Lightweight dropdown dialog anchored to a button or field. |
| 4 | ListPage | Read-only grid with filters and navigation buttons. |
| 5 | Lookup | Popup selection grid bound to a reference field. |
| 6 | SimpleList | Single editable grid for reference data. |
| 7 | SimpleListDetails | List panel with a details panel for the selected record. |
| 8 | FormPart | A part displayed in the FactBox pane or embedded in another form. |
| 9 | DetailsFormTransaction | Document form with header, lines, and line-details. |
| 10 | TableOfContents | Tree-navigation form for parameter and setup pages. |
| 11 | Dashboard | Dashboard layout (legacy). |
| 12 | EntityPage | Entity page layout. |
| 13 | Sitemap | Site map navigation layout. |
| 14 | Workspace | Tiles, lists, and links aggregated into a functional-area dashboard. |
| 15 | SimpleDetails | A single-record form with fields only (no grid). |
| 16 | TaskSingle | A task-oriented form with a single data source. |
| 17 | TaskDouble | A task-oriented form with header and line data sources. |
| 18 | Wizard | Multi-step guided form. |
| 19 | Report | Report parameter form. |
Form Patterns at a Glance
The table below lists every top-level form pattern available in D365 F&O together with the form style it pairs with and a brief description. Each pattern has a dedicated sub-page with full structural detail, usage guidance, and example forms.
| Pattern | Form Style | Sub-page | Description |
|---|---|---|---|
| Details Master | DetailsFormMaster | Details Master | Master-detail form with header fields, FastTabs, and an optional lines grid. |
| Details Transaction | DetailsFormTransaction | Details Transaction | Document form with header fields, a lines grid, and a line-details panel. |
| Simple List | SimpleList | Simple List | A full-page editable grid for maintaining reference data. |
| Simple List and Details | SimpleListDetails | Simple List and Details | A list panel on the left with a detail panel on the right for the selected record. |
| Simple Details | SimpleDetails | Simple Details | A single-record form showing fields only. Includes variations with toolbar and fields, or FastTabs. |
| List Page | ListPage | List Page | A read-only grid with filters and an action pane used as a navigation hub. |
| Dialog | Dialog | Dialog and Drop Dialog | A modal parameter-entry form. Includes the Drop Dialog variation. |
| Workspace | Workspace | Workspace | A role-based dashboard with tiles, lists, charts, and links. |
| Table of Contents | TableOfContents | Table of Contents | A tree-navigation form used for parameter and configuration pages. |
| Task Single / Task Double | TaskSingle / TaskDouble | Task Pages | Activity-oriented forms for focused data entry. Single (one data source) and Double (header + lines). |
| Wizard | Wizard | Wizard | A multi-step guided process form. |
| Lookup | Lookup | Lookup | A popup selection grid anchored to a field. |
| FactBox | FormPart | FactBox | A read-only info part displayed alongside a parent form. |
Subpatterns (Control Patterns)
Patterns do not only apply at the form level. Container controls (groups, tab pages) within a form can also have a subpattern assigned via the same Pattern and PatternVersion properties inherited from AxFormControl.
Subpatterns define the expected child-control structure inside a container region. For example, a FastTab group inside a Details Master form might use a Fields and Field Groups subpattern to organise its input controls, or a Toolbar and List subpattern to embed an actions strip above a grid.
Common subpatterns include:
| Subpattern | Applies To | Description |
|---|---|---|
| Fields and Field Groups | Group, Tab Page | Arranges fields and field groups in a responsive column layout. The most common subpattern for data-entry regions. |
| Toolbar and List | Group | An action toolbar above a grid or tree. Used inside tab pages that embed secondary lists. |
| Toolbar and Fields | Group | An action toolbar above a set of fields. Used for editable detail sections with their own action buttons. |
| Nested Simple List and Details | Group | Embeds a Simple List and Details layout within a tab page of a parent form. |
| Custom Filters | Group | A filter group with QuickFilter and optional custom filter fields. Used at the top of list regions. |
| Section Tiles | Group | A set of tile buttons used in workspaces and navigation areas. |
| Section Related Links | Group | A list of hyperlinks grouped by category. Common in workspace forms. |
| Section Stacked Chart | Group | Container for a chart control inside a workspace section. |
| Section Tabbed List | Group | A tabbed list region inside a workspace. |
| Section Power BI | Group | A section hosting a Power BI tile or report in a workspace. |
| Filters and Toolbar | Group | A compound subpattern combining a filter bar and action toolbar. |
For a full reference on subpatterns, see Subpatterns.
Pattern Validation
Compile-Time Checking
When a form is compiled, the pattern validator walks the control tree and checks:
- Required controls — are all mandatory containers and controls present?
- Control order — are controls in the correct sequence within their parent?
- Control types — does each node use the expected control type (e.g.,
AxFormActionPaneControlwhere an action pane is required)? - Nesting depth — are containers nested at the correct level?
- Subpattern compliance — do inner containers satisfy their own assigned subpatterns?
Violations appear as Best Practice warnings (BPWarning) or errors (BPError) in the build output. A form can still compile with pattern warnings, but it may render incorrectly or lose responsive behaviour.
Custom Pattern (No Pattern)
If a form's Pattern property is left blank, the form is unpatternered (freeform). This is strongly discouraged for new development:
- No automatic layout — all sizing and positioning must be set manually.
- No responsive behaviour — the form does not adapt to different screen sizes.
- No compile-time structure validation.
- Potential accessibility gaps.
Legacy forms migrated from AX 2012 may still be unpatterned. When customising these forms, apply a pattern if feasible, or at minimum apply subpatterns to individual container controls.
Properties Reference
The following properties from AxFormControl (the base type for all controls, including the design node) relate to pattern assignment. Every control in the form hierarchy inherits these.
| Property | Display Name | Type | Description |
|---|---|---|---|
| AxFormControl (base — all controls) | |||
| Pattern | Pattern | String | The name of the form pattern or subpattern applied to this control. Set on the Design node for the form-level pattern, or on a container control for a subpattern. |
| PatternVersion | PatternVersion | String | The version of the applied pattern specification. |
On the Design node specifically, the Style property (from AxFormDesign) controls the form's visual chrome and works in tandem with the pattern:
| Property | Display Name | Type | Description |
|---|---|---|---|
| AxFormDesign (design node only) | |||
| Style | Style | FormStyle | Specifies the form style. See the FormStyle enum table above for all values. |
| Caption | Caption | String | The heading that appears on the form. Use a label. |
| TitleDataSource | Title Data Source | String | The data source used to build the dynamic form caption. |
| WindowType | Window Type | WindowType_ITxt | The type of window used to display the form. Values: Standard (0), Popup (1), ListPage (2), Workspace (3), ContentPage (4), Slider (5). |