Master/Detail

Overview

A common use case in enterprise applications is displaying a list of items with detail available for each item.

If only a small amount of detail is displayed for each list item, you can use the data grid to display each list item as a grid row, with the detail displayed in grid columns.

But if a larger amount of detail is displayed for each item, the Master/Detail approach offers more room in which to display the detail:

• The list of items — called the master list — displays vertically on the left. Each item in the list typically displays only enough information for the user to know which item to select.
• Detail for the selected list item displays on the right, typically using record detail.
• Unlike a data grid, detail only displays for the selected item. But this detail can take as much vertical space as needed, giving you more room in which to display the detail.

The Master/Detail pattern supports 3 master list formats:

• Button master lists
• Data grid master lists
• Tree view master lists

Button master lists

The simplest format for a master list is a vertical list of buttons.

Each item in the list can display either a simple text value or a template. The template approach allows you to display multiple data values for each list item in a custom template.

Data grid master lists

Data grid master lists display their items in data grid rows and columns. Grid master lists are more complex but offer more functionality than button master lists, including:

• The ability to display multiple data values for each list item in data grid columns with a header.
• The ability to select multiple rows in the master list. A checkbox displays in each data row, allowing the user to select that row, and in the header to allow the user to select all rows.
• The ability to sort master list rows. The user can click a grid column header to sort that column, then click it again to reverse the sort direction. A sort arrow displays next to the header for any sorted column, indicating the sort direction.
• The ability to filter master list rows (not shown here). The user can interact with the filter for each grid column to hide all rows that don’t match the filter.

Tree view master lists

Tree view master lists are less common than button or grid master lists, but can be used to implement master detail for a hierarchical master list, i.e. a master list with parent/child relationships between list items.

The user can press the arrow next to parent nodes to expand or collapse their children, but typically “leaf nodes” (nodes at the very bottom of the parent/child relationship) are the only tree view nodes that display detail when clicked.

Detail buttons

In master/detail scenarios, the user selects an item in the master list and the application displays detail for the selected item.

In many cases, the detail section provides additional functionality for the selected item. In the example below, we see Edit and Delete buttons that operate on the selected institution.

The buttons for this functionality are displayed in the detail area to help the user understand that this functionality is scoped to the selected item. We call these buttons detail buttons.

Shortcut buttons

After the users selects an item in the master list, they can then access any detail buttons provided in the detail area (Edit and Delete in our example above). This is a 2-step process.

But it’s even better if we allow the user to access this functionality with only 1 step. By duplicating some or all of the detail buttons within the master list itself, we allow the user to immediately access these functions for any item in the list without having to first select the item. We call these buttons shortcut buttons.

When the user clicks a shortcut button, this initiates the functionality associated with that button, using the clicked list item as the context. Again, this allows the user to immediately access this functionality for any item in the list without having to select the item first.

To simplify the visual complexity in the view, shortcut buttons only display for the selected item in the master list and any list item that the user hovers the mouse over. By only displaying these buttons for selected and hovered items, we allow the user’s eye to focus on what’s important: the data.

Clicking a shortcut button in a list item also selects that item in the list. Seeing the item selected in the master list provides the user with more visual context as they perform the action for that list item.

Using the example above, pressing the Edit shortcut button in the Golden Bank list item would immediately initiate the Edit functionality for that institution. It would also select the Golden Bank item in the master list, providing the user with even more visual confirmation that they’re editing Golden Bank.

Even when shortcut buttons are used, it’s still important to display the full list of detail buttons in the detail area too:

• Shortcut buttons can’t be the only way for the user to initiate this functionality. The user may be on a touch system and unable to hover over list items.
• When the user is looking at detail, they’ll expect quick access to this functionality. If it were only available in the master list, this would force the user to hunt across the screen for this functionality.
• So we always provide access to this functionality in the detail area, even if it’s available as shortcut buttons too. The shortcut buttons are a courtesy.

Shortcut buttons are supported in button master lists and data grid master lists.

Master buttons

We also support master/detail buttons in a third location: above the master list. We call these “master buttons”. We’ll talk more about these master buttons in later sections.

Multiple selection

Master/detail primarily involves selecting one item in the master list and displaying detail for it. But there are cases where the user may benefit from operating on multiple items in the master list at once.

Let’s say the user wants to delete one item from the master list. They first click the item in the master list, then press the Delete button in the detail area. Or they can click the Delete shortcut button in the master list if we’re displaying shortcut buttons.

But what if the user needs to delete several items at once? With single selection, the user must delete each item one at a time. If we instead allow the user to select multiple items in the master list and delete them all at once, we can save the user some time.

Checkboxes are used for toggling selection of items in the master list when multiple selection is enabled. A checkbox displays next to each individual item in the master list, allowing the user to toggle selection of individual items. A checkbox in the header row is used to toggle selection of all items in the list.

Selecting one item to view its detail is the primary interaction for master lists; operating on multiple items at once is a secondary interaction. Because of this, we make it easy for the user to select a single item but also make it possible for the user to select and operate on multiple items. This gives the user the best of both worlds.

Multiple selection is supported in data grid master lists and tree view master lists.

Let’s take a look at some examples of how master/detail works, based on the number of items selected.

No items selected in master list

In the example below, we see a Grid master list that supports multiple selection, with no items selected in the master list:

• The detail displays a “Nothing is selected” message.
• The display block title instructs the user to select a financial institution.
• The add functionality displays as a master button since the user can always add a new item to the list.
• The edit functionality does not display since no items are selected.
• Likewise, the delete functionality does not display since no items are selected.
• We typically pre-select 1 item in a master list, although the user can manually get to the state shown below by unselecting all items in the list.

One item selected in master list

In the example below, we see a Grid master list that supports multiple selection, with 1 item selected in the list:

• Detail displays for the selected item since exactly 1 item is selected in the master list.
• The detail display block title identifies the currently selected item, helping reinforce the relationship between the selected master list item and the detail area.
• The add functionality displays as a master button since the user can always add a new item to the list.
• The edit functionality displays as a master button, shortcut button, and detail button since an item is selected.
• Likewise, the delete functionality displays as a master button, shortcut button, and detail button since an item is selected.

Multiple items selected in master list

In the example below, we see a Grid master list that supports multiple selection, with multiple items selected in the list:

• There are a few options for displaying detail when multiple items are selected:
  • You could display a simple text message like “Multiple items selected” in the detail area.
  • You could display detail for all of the selected items, one after another, if appropriate.
  • In this example we chose to display a vertical list of buttons that illustrate the user’s options here.
• The detail display block title is “3 Institutions Selected”, helping the user understand that multiple items are selected and how many are selected.
• The add functionality could technically be displayed as a master button here since the user can always add a new item to the list, although we’re hiding it in this example since adding an item after selecting multiple items feels like a mistake. You could go either way with that.
• The user can only edit 1 item at a time in this example, so the edit functionality is hidden.
• The user can delete 1 or more items at a time in this example, so the delete functionality displays as a master button and as an option in the detail area.
• Note that shortcut buttons are hidden when multiple items are selected in a grid master list.

Drag and Drop Reordering

The user must be allowed to reorder master list items in some master/detail scenarios.

Some applications use a roundabout way to achieve this, such as displaying “Move Up” and “Move Down” buttons for each master list item. While that approach is valid (and supported), modern user interfaces often use drag and drop to reorder list items. This is a more natural approach that mirrors the real-world actions of moving items around.

Drag and drop can introduce a usability challenge though: if users aren’t expecting drag-and-drop support in a list, they can accidentally drag an item when they were intending to click it. You can handle this challenge in two ways:

1. Always have drag and drop turned on for a particular master list if, if your users know to expect this functionality.
2. Allow the user to explicitly turn drag and drop on and off, using a master toggle button titled “Reorder” displayed above the master list. This requires an extra button in the toolbar but gives the user more control.

The correct approach here depends on your use case and your users’ expectations.

When drag and drop is turned on for a button or grid master list — whether it’s always turned on or explicitly turned on and off by the user — a drag grip displays at the left edge of each master list button.

In the example below, drag-and-drop functionality is explicitly turned on only when the user presses the “Reorder List” toggle button. The “Reorder List” button is not initially toggled on here, so drag and drop is not available yet. (You could just as easily have drag and drop implicitly available without using an external button, if that’s more appropriate to your use case.)

Once the user presses the “Reorder List” toggle button, drag-and-drop functionality is now available. We see a drag grip displayed at the left edge of each master list item, signaling to the user that drag and drop is now available in the list.

Drag and drop reordering is supported in button master lists, data grid master lists, and tree view master lists, with two exceptions.

• Data grid master lists that support multiple selection do not support drag-and-drop reordering. You have to select one behavior or the other.
• Tree view master lists support drag-and-drop reordering, but they do not display a drag grip due to the fact that they only display a simple string value for each node.

Development

Web component development

Component reference

rui-master-list

rui-master-list-option

p-table

p-tree

Implementation

There are four different approaches to implementing a master/detail list. You will need to select the best implementation based on your requirements.

• The Button Layout provides a simple UI that allows selection and reordering, but not multiple selection or sorting.
• The Data Grid Layout uses the PrimeNG Table component allowing selection, reordering and sorting.
• The Data Grid Multiple Selection Layout uses the PrimeNG Table component allowing multiple selection, reordering and sorting.
• The Tree View Layout is best when the list has a hierarchical structure.

Developing a Button Layout

Begin by importing the rui-master-detail module into your application.

// import into app.module
import '@jkhy/responsive-ui-wc/components/rui-master-detail/rui-master-detail-imports';

The button layout uses rui-master-list to implement a master list. Bind value to a string value in your TypeScript that tracks the value for the currently selected item in the list. Add a rui-master-list-value-change event handler to perform an action whenever the selected item value changes.

Nest a rui-master-list-option element within the rui-master-list element for each item in the list. Specify the item’s value with the value property. The content within the rui-master-list-option tag is what gets displayed in the list.

If you need to allow users to reorder the items in the list, bind the isSortable property in rui-master-list to true.

You can provide shortcut button elements to allow users to perform an immediate action for any item in the list with a single click. To do this, specify a comma-delimited list of icon types in each rui-master-list-option’s shortcutButtons property, then handle the rui-master-list-shortcut-click event that fires when a shortcut button is pressed.

See the Master/Detail: Buttons view in the sample application for an example of a master/detail button layout.

Developing a Data Grid Layout

Start by importing the PrimeNG p-table component. In the view, add a p-table component and bind value to your data object and selection to the selected item in your TypeScript. Set the selectionMode to single and tableStyleClass to rui-master-list-grid to pull in the correct styles. Bind onRowSelect and onRowUnselect to back end methods (addSelectedFi and removeSelectedFi) in the TypeScript.

In the body template, you can provide shortcut rui-button elements to allow users to edit or delete an item in the list with a single click. Bind the Edit button to a backing startEditing method. For the delete button, add a rui-question dialog to confirm the action, and if confirmed, remove the item from the list.

Next, build out the views for both displaying the detail information, and if needed editing the details.

To allow users the ability to reorder the master list, add a toggle button in the display block toolbar to toggle the ability to sort. Create a copy of the existing body template row for when isSortable is true, and add the pReorderableRow directive and a new handle with the pReorderableRowHandle directive.

Finally, wrap everything in a fixed layout container and add rui-display-block-toolbars to provide users additional ways to add/edit/delete items in the list.

See the Master/Detail: Grid view in the sample application for an example of a master/detail grid layout.

Developing a Multiple Selection Grid Layout

Start by importing the PrimeNG p-table component. In the view, add a p-table component and bind value to your data object and selection to the selected item in your TypeScript. Set the selectionMode to multiple and tableStyleClass to rui-master-list-grid to pull in the correct styles. Bind onRowSelect and onRowUnselect to back end methods (addSelectedFi and removeSelectedFi) in the TypeScript.

In the body template, you can provide shortcut rui-button elements to allow users to edit or delete an item in the list with a single click. Bind the Edit button to a backing startEditing method. For the delete button, add a rui-question dialog to confirm the action, and if confirmed, remove the item from the list.

Next, build out the views for both displaying the detail information, and if needed editing the details.

To allow users the ability to reorder the master list, add a toggle button in the display block toolbar to toggle the ability to sort. Create a copy of the existing body template row for when isSortable is true, and add the pReorderableRow directive and a new handle with the pReorderableRowHandle directive.

See the Master/Detail: Grid Multiple Selection view in the sample application for an example of a master/detail grid layout.

Developing a Tree View Layout

Start by importing the PrimeNG p-tree component. Create a new function view with a fixed layout. Add a p-tree component and bind value and selection to your data object and selected item. Set selectionMode to single and bind onNodeSelect to the onTreeNodeSelect() backing method.

In the TypeScript, initiate the data object, selected item and selected item name. After pulling in the data and selecting the correct list item, create a onTreeNodeSelect method to update the detail view name when a new node is selected.

See the Master/Detail: Tree View view in the sample application for an example of a master/detail grid layout.

Angular wrapper development

Wrapper reference

jha-master-list

jha-master-list-option

p-table

p-tree

Implementation

There are four different approaches to implementing a master/detail list. You will need to select the best implementation based on your requirements.

• The Button Layout provides a simple UI that allows selection and reordering, but not multiple selection or sorting.
• The Data Grid Layout uses the PrimeNG Table component allowing selection, reordering and sorting.
• The Data Grid Multiple Selection Layout uses the PrimeNG Table component allowing multiple selection, reordering and sorting.
• The Tree View Layout is best when the list has a hierarchical structure.

Developing a Button Layout

Begin by importing the JhaMasterDetailModule module into your application.

// import into app.module
import { JhaMasterDetailModule } from '@jkhy/responsive-ui-angular/jha-master-detail';

@NgModule({
    imports: [
        ...
        JhaMasterDetailModule,
        ...
    ]
})

export class AppModule(){}

The button layout uses jha-master-list to implement a master list. Two-way bind jhaValue to a string value in your TypeScript that tracks the value for the currently selected item in the list. Add a jhaValueChanged event handler if you need to perform an action whenever the selected item value changes.

Nest a jha-master-list-option element within the jha-master-list element for each item in the list. Specify the item’s value with the jhaValue property. The content within the jha-master-list-option tag is what gets displayed in the list.

If you need to allow users to reorder the items in the list, bind the jhaIsSortable property in jha-master-list to true.

You can provide shortcut button elements to allow users to perform an immediate action for any item in the list with a single click. To do this, specify a comma-delimited list of icon types in each jha-master-list-option’s jhaShortcutButtons property, then handle the jhaShortcutButtonClick event that fires when a shortcut button is pressed.

See the Master/Detail: Buttons view in the sample application for an example of a master/detail button layout.

Developing a Data Grid Layout

Start by importing the PrimeNG p-table component. In the view, add a p-table component and bind value to your data object and selection to the selected item in your TypeScript. Set the selectionMode to single and tableStyleClass to jha-master-list-grid to pull in the correct styles. Bind onRowSelect and onRowUnselect to back end methods (addSelectedFi and removeSelectedFi) in the TypeScript.

In the body template, you can provide shortcut jha-button elements to allow users to edit or delete an item in the list with a single click. Bind the Edit button to a backing startEditing method. For the delete button, add a jha-question dialog to confirm the action, and if confirmed, remove the item from the list.

Next, build out the views for both displaying the detail information, and if needed editing the details.

To allow users the ability to reorder the master list, add a toggle button in the display block toolbar to toggle the ability to sort. Create a copy of the existing body template row for when isSortable is true, and add the pReorderableRow directive and a new handle with the pReorderableRowHandle directive.

Finally, wrap everything in a fixed layout container and add jha-display-block-toolbars to provide users additional ways to add/edit/delete items in the list.

See the Master/Detail: Grid view in the sample application for an example of a master/detail grid layout.

Developing a Multiple Selection Grid Layout

Start by importing the PrimeNG p-table component. In the view, add a p-table component and bind value to your data object and selection to the selected item in your TypeScript. Set the selectionMode to multiple and tableStyleClass to jha-master-list-grid to pull in the correct styles. Bind onRowSelect and onRowUnselect to back end methods (addSelectedFi and removeSelectedFi) in the TypeScript.

In the body template, you can provide shortcut jha-button elements to allow users to edit or delete an item in the list with a single click. Bind the Edit button to a backing startEditing method. For the delete button, add a jha-question dialog to confirm the action, and if confirmed, remove the item from the list.

Next, build out the views for both displaying the detail information, and if needed editing the details.

To allow users the ability to reorder the master list, add a toggle button in the display block toolbar to toggle the ability to sort. Create a copy of the existing body template row for when isSortable is true, and add the pReorderableRow directive and a new handle with the pReorderableRowHandle directive.

See the Master/Detail: Grid Multiple Selection view in the sample application for an example of a master/detail grid layout.

Developing a Tree View Layout

Start by importing the PrimeNG p-tree component. Create a new function view with a fixed layout. Add a p-tree component and bind value and selection to your data object and selected item. Set selectionMode to single and bind onNodeSelect to the onTreeNodeSelect() backing method.

In the TypeScript, initiate the data object, selected item and selected item name. After pulling in the data and selecting the correct list item, create a onTreeNodeSelect method to update the detail view name when a new node is selected.

See the Master/Detail: Tree View view in the sample application for an example of a master/detail grid layout.

Design

Figma design

Master/detail supports three different formats: button master lists, data grid master lists, and tree view master lists.

Only one of the master/detail buttons in a list can be selected.

Button and grid master lists can include shortcut buttons that display on hover or selection.

Button and grid master lists can optionally include drag handles for drag and drop.

Grid master lists can optionally support multiple selection using checkboxes at the far left of each master list item’s content.

Adobe XD design

Master/detail supports three different formats: button master lists, data grid master lists, and tree view master lists.

Only one of the master/detail buttons in a list can be selected.

Button and grid master lists can include shortcut buttons that display on hover or selection.

Button and grid master lists can optionally include drag handles for drag and drop.

Grid master lists can optionally support multiple selection using checkboxes at the far left of each master list item’s content.