Skip to main content

MasterDetailLayout

Purpose​

The MasterDetailLayout combines one master View with one or more dependent detail Views. It is suitable when a central record selection or preview should control the content shown in one or more related detail areas.

Behavior​

The layout enables you to specify one View as the master, on which one or more other Views, the details, depend.

In most cases, an Entity's MainView uses a MasterDetailLayout:

  • the PreviewView of the same Entity acts as the master on the left side
  • one or more related Views act as detail areas on the right side

For example, in the xRM Context Company, the MainView uses this pattern. On the left, the PreviewView of the selected company is shown. On the right, dependent Views such as Activities, contacts, or attributes are displayed in tabs.

Thus, a View with a MasterDetailLayout usually does not contain its own ViewTemplates. Instead, it acts as a frame that combines the PreviewView with one or more dependent Views.

Configuration​

At first, after creating the Context, Entity, PreviewView, and all required Consumers, create a View, usually the MainView, and set its property layout to MasterDetailLayout. As a result, property master becomes available.

To define the master View and all detail Views:

  1. Double-click on the View that uses the MasterDetailLayout.
  2. In the Navigator window, right-click the View name and choose Add reference to existing View....
  3. In the dialog, configure the following fields:
    • EntityField
      • #ENTITY: Select this if you want to add a View of the same Entity.
      • If available, select one of the Entity's Consumers if you want to add a View of another Entity that is linked through a Provider.
    • View: Select one of the Views related to the selected EntityField.
    • Assign To
      • Select master when referencing the PreviewView of the same Context.
      • Leave the field empty for all detail Views.

You can also edit the master property later and assign the desired master View there. In MainViews, the master is usually the PreviewView.

All other referenced Views are automatically treated as detail Views. In the Navigator window, they appear on the same level as the master View, but without the [master] prefix.

In the client, the master View usually appears on the left, while the detail Views are shown on the right and grouped in tabs.

Establishing a dependency​

The dependency between master and detail is based on the Provider-Consumer mechanism. The Provider supplies detail data based on a parameter exposed to the Consumer, which is used by the master side to define the data selection.

Technically, this is done as follows:

  • On the Provider side, which is the Entity of the detail View:

    • Optionally create a Parameter whose name reflects the selection criterion defined by the master. This Parameter must be exposed by setting expose = true.

    • Create a Provider whose name reflects the provided data.

    • If a Parameter is used, the conditionProcess of the RecordContainer must evaluate it. A typical example is:

      MyContacts_entity.RecordContainers.db.conditionProcess.js
      var cond = newWhereIfSet("CONTACT.ORGANISATION_ID", "$param.OrgId_param");
      result.string(cond);

  • On the Consumer side, which is the Entity of the master View:

    • Create a Consumer that references the Provider via properties entityName and fieldName.

    • Initialize the exposed Parameter and set its valueProcess. A typical example is:

      XXX_entity.Consumers.XXX.XXXId_param.valueProcess.js
      result.string(vars.get("$field.ORGANISATIONID"));

Once this dependency is defined, all related detail Views become selectable in the Add reference to existing View... dialog of the View using the MasterDetailLayout.

Example usage​

One common example is an Entity's MainView. In the xRM Context Company, the PreviewView of the selected company is shown as the master on the left, while dependent Views such as Activities, contacts, or attributes are displayed as detail areas on the right in tabs.

Implementation hints​

MasterDetailLayout usually acts as a frame for related Views and typically does not contain its own ViewTemplates.

DashletConfigs cannot be added to Views that use MasterDetailLayout.

note

DashletConfigs cannot be added to Views that use a MasterDetailLayout.