Acumatica Modern UI Master-Detail Pattern

Acumatica Modern UI Master-Detail Pattern is one of those Acumatica topics that is both obvious and subtle. The Modern UI is the default since 2025 R2, the Mobile Framework is the engine, the screen editor is the IDE, and the conventions are the difference between a screen that ships in a week and one that ships in a month. This guide is the field-tested walkthrough.

What the Mobile Framework actually is

The Mobile Framework (MF) is a metadata-driven engine that exposes every Modern UI screen as a swagger-compliant API. The front-end uses the API to render the page; the back-end uses the standard Acumatica graph and DAC. The MF is the bridge between the two.

The screen editor

The Modern UI screen editor is the in-browser IDE for screen configuration. You can add fields, configure tabs, define conditional visibility, and set up actions — all without writing code. For the deeper customisation (custom TypeScript controls, complex validation), you drop into the code editor.

import { Control, PXView, controlConfig } from "client-controls";

@controlConfig({ view: "CurrentDocument" })
export class MyCustomControl extends Control {
    // The control renders inside a card on the document form
    // It receives the form data via the view
    // It can call actions via the Base.Actions API
}

For the broader screen editor patterns, see the screen editor vs code editor guide.

Building a screen from scratch

The end-to-end pattern for adding a new screen to the Modern UI:

1. DAC. Define the data model. Standard IBqlTable, dual-field pattern, attributes for UI hints.
2. Graph. The data view, the actions, the event handlers. Standard PXGraph.
3. Mobile Framework. Define the screen layout in the MF editor (SM204510). Map the form, the tabs, the actions.
4. Workspace. Add the screen to a workspace. Set access rights.
5. Test on desktop, tablet, phone. The layout is responsive by default; verify on each form factor.

// DAC
[Serializable]
[PXCacheName("My Entity")]
public class MyEntity : IBqlTable
{
    [PXDBIdentity(IsKey = true)]
    public virtual int? RecordID { get; set; }
    public abstract class recordID : PX.Data.BQL.BqlInt.Field<recordID> { }
    [PXDBString(60)]
    [PXUIField(DisplayName = "Name")]
    public virtual string Name { get; set; }
    public abstract class name : PX.Data.BQL.BqlString.Field<name> { }
}
// Graph
public class MyGraph : PXGraph<MyGraph, MyEntity>
{
    public PXSelect<MyEntity> Records;
}

For the broader customisation pattern, see the customisation definitive guide and the modern UI custom screens guide.

Responsive design conventions

Modern UI screens are responsive by default. The conventions:

• Forms collapse from 2-column to 1-column on narrow viewports.
• Grids scroll horizontally on narrow viewports.
• Buttons reflow to a menu on narrow viewports.
• Long text truncates with ellipsis; hover to see the full value.

/* Default: desktop layout */
.my-form { display: grid; grid-template-columns: 1fr 1fr; }
/* Tablet: single column */
@media (max-width: 64rem) { .my-form { grid-template-columns: 1fr; } }
/* Phone: compact */
@media (max-width: 30rem) { .my-form { font-size: 0.95rem; } }

Toolbar actions in the Modern UI

Toolbar actions are graph actions that the user clicks. The MF maps them to buttons on the screen. The patterns:

[PXUIField(DisplayName = "Approve")]
[PXButton]
public virtual IEnumerable<MyEntity> Approve(MyEntity entity)
{
    entity.Status = "A";
    entity.ApprovedAt = DateTime.UtcNow;
    yield return entity;
}
[PXUIField(DisplayName = "Reject")]
[PXButton]
public virtual IEnumerable<MyEntity> Reject(MyEntity entity)
{
    entity.Status = "R";
    yield return entity;
}

For the broader action and workflow patterns, see the workflow engine guide and the automated actions guide.

Mobile-only features

Some Modern UI features are mobile-only. The patterns:

• Barcode scanning. The mobile scanner uses the device camera; the MF returns the scanned value to the form.
• Geolocation. The mobile app captures the device's GPS coordinates; the form can save them with the record.
• Camera capture. For photos of receipts, delivery proof, or damaged goods.
• Offline mode. The mobile app caches data locally; changes sync when the device reconnects.

@controlConfig({ view: "CurrentRecord" })
export class GeolocationCapture extends Control {
    async onClick() {
        if (!navigator.geolocation) { this.showError("Geolocation not supported"); return; }
        navigator.geolocation.getCurrentPosition(
            (pos) => {
                this.setValue("Latitude", pos.coords.latitude);
                this.setValue("Longitude", pos.coords.longitude);
            },
            (err) => this.showError(err.message)
        );
    }
}

For the mobile app customisation pattern, see the mobile app customisation guide and the offline mode guide.

Modern UI performance

The Modern UI has its own performance story. The factors that matter:

async function loadHeavyControl() {
    const { default: HeavyControl } = await import('./HeavyControl');
    return HeavyControl;
}

For the broader performance playbook, see the performance tuning guide.

Upgrade safety for Modern UI screens

Modern UI screens survive upgrades well — the framework is the upgrade. The risks are:

• Custom TypeScript controls that depend on a specific MF version. Test after every upgrade.
• Custom CSS that targets internal Acumatica classes. Use semantic selectors.
• Custom navigation that depends on the workspace structure. Workspace layouts can change.

For the broader upgrade survival playbook, see the upgrade checklist.

Wrapping up

The Modern UI is the default; the Mobile Framework is the engine; the screen editor is the IDE. Build your screens against the framework, and they work everywhere. Build outside the framework, and they work in one place. The choice is yours, but it is the choice that determines whether your customisation ages well.