List-Details¶

List-Details (formerly Main-detail container) is a layout pattern that shows a list of items and the corresponding details of the selected item. It allows users to stay focused on the main content (list) while accessing and editing related details without losing context.

Usage¶

Use this layout when viewing details from an item in a large list or group on the same page is required.

The content in the list pane such as list, data table or simple navigation is used to control the information shown in the details pane.

Selecting an item from the list pane opens the details pane. The user can select another item from the list pane to switch content of the details pane.

List-details layouts are optimized for wider screens, while also incorporating a responsive behavior to adapt to various screen sizes.

List-details

When to use¶

For navigating through hierarchical data structures, making it easier for users to explore and understand content.
When there's a need to navigate through large amounts of data or items but only focus on one item at a time.
In scenarios where users might need to switch quickly between items without losing context.

Design¶

Elements¶

List-details elements

List pane: Displays content types such as lists, tables or trees.
List actions (optional): These are the functions that a user can perform within the list pane.
Details pane: Displays information from the selected node, such as tables, forms or KPIs.
Details title (optional): It provides context about the information displayed, e.g. name of the selected item
Details actions (optional): Functions that can be performed within the details pane.

Resizing the panes¶

The two sections can be dynamically resizable: when users hover over the dividing area, the cursor turns into a double-sided arrow, allowing for size adjustments.

List-details resize

Edit mode¶

An 'Edit mode' can be optionally enabled in the details pane, allowing content modifications. When active, 'Save' and 'Cancel' actions are displayed in a footer.

The main content area is scrollable independently of the footer. This way, the footer remains visible and accessible even when the content overflows.

List-details edit

Search and actions in list¶

These actions are designed to manipulate data in the list pane.

They are context-specific, meaning they directly affect the item in the list pane. For example, a bulk action to "Update user permissions" to modify settings for multiple users at once, or "Adjust settings for multiple zones" enables uniform changes across different areas in a single step.

Any button type can be used as an action. However, if more than one action is needed, they should be collapsed over a menu, or reconsidered as global actions.

List-details actions

Filtering in the list¶

If filters are needed in the list, a filter button can be placed above the content. Applied filters can be represented with a filter bar.

If the action next to the search bar is used for another purpose, the filter button can be placed next to the applied filters.

List-details filters

Filters in the list pane can overlay the content to show filtering options. When activated, a panel appears, allowing users to select criteria, and then retracts to update the displayed content based on the selected filters.

List-details filters flow

Global search and actions¶

Unlike the actions that are exclusive to the 'List' or 'Details', global actions transcend specific areas and provide functionality that is consistently relevant regardless of the user's current focus. E.g.: A 'Create' button that initiates the process to create a new entry to the list pane.

List-details global actions

Bulk actions¶

When multiple items can be selected, the details pane will display an empty state guiding users to either perform an action or clear the selection.

List-details bulk actions

Initial interaction¶

Consider the initial interaction: It can either feature a preselected item, displaying its details, or be user-initiated, where the details pane relists empty until an item is selected or created.

There can also be situations where the list pane itself is not populated until the user creates or adds an item.

In instances, where no data is immediately available, use an empty state to guide the user.

List-details initial interaction

Responsive behavior¶

In responsive mode, the List-details splits into two screens: first displaying the main content, then the details of a selected node with a 'Back' button.

List-details responsive

Code¶

Usage¶

import { SiListDetailsComponent } from '@siemens/element-ng/list-details';

@Component({
  imports: [SiListDetailsComponent, ...]
})

The <si-list-details> represents the layout used to organize the different elements. Inside it different child template components are used to assign the content to the correct position in the list-details layout and enable the correct responsive styling, the <si-list-pane> and <si-details-pane>.

Inside the <si-list-pane> the following child components can be used: - <si-list-pane-header>: Header of the list pane, typically containing search and actions. - <si-list-pane-body>: Body of the list pane, typically containing the list or table.

Inside the <si-details-pane> the following child components can be used: - <si-details-pane-header>: Header of the details pane, typically containing the title and actions. - <si-details-pane-body>: Body of the details pane, typically containing the details content. - <si-details-pane-footer>: Footer of the details pane, typically containing save and cancel actions.

It is highly advised to use at least the <si-details-pane-header> to show the back button in a responsive (mobile) view.

If the content may exceed the available space, the overflow-auto class should be applied to the body components or a child inside them.

In the standard layout, the card class should be applied to both the <si-list-pane> and <si-details-pane>, though it can also be moved to suite the design needs.

SiListDetailsComponent API Documentation¶

selector

si-list-details

Input Properties¶

Name	Type	Default	Description
detailsActive ¶	`boolean`	`false`	Whether the details are currently active or not, mostly relevant in the responsive scenario when the viewport only shows either the list or the detail.
disableResizing ¶	`boolean`	`false`	Whether the list and detail parts should be resizable by a splitter or not. This is only supported in the 'large' scenario (when `hasLargeSize` is `true` ). Default value is `false` .
listWidth ¶	`number`	`32`	The percentage width of the list view of the overall component width.
minDetailsSize ¶	`number`	`300`	Sets the minimal width of the detail component in pixel.
minListSize ¶	`number`	`300`	Sets the minimal width of the list component in pixel.
stateId ¶	`string`		An optional stateId to uniquely identify a component instance. Required for persistence of ui state.

Output Properties¶

Name	Type	Description
detailsActiveChange ¶	`boolean`	Whether the details are currently active or not, mostly relevant in the responsive scenario when the viewport only shows either the list or the detail.
listWidthChange ¶	`number`	The percentage width of the list view of the overall component width.

Attributes and Methods¶

Name	Type	Default	Description
(readonly) expandBreakpoint ¶	`InputSignal`<`number`>	`BOOTSTRAP_BREAKPOINTS.mdMinimum`	A numeric value defining the minimum width in px, which the component needs to be displayed in its large layout. Whenever smaller than this threshold, the small layout will be used. Default is value is BOOTSTRAP_BREAKPOINTS.mdMinimum.
(readonly) hasLargeSize ¶	`Signal`<`boolean`>	...

SiListPaneComponent API Documentation¶

selector

si-list-pane

No API to document for this.

SiListPaneHeaderComponent API Documentation¶

selector

si-list-pane-header

No API to document for this.

SiListPaneBodyComponent API Documentation¶

selector

si-list-pane-body

No API to document for this.

SiDetailsPaneComponent API Documentation¶

selector

si-details-pane

No API to document for this.

SiDetailsPaneHeaderComponent API Documentation¶

selector

si-details-pane-header

Input Properties¶

Name	Type	Default	Description
backButtonText ¶	`TranslatableString`	$localize`:@@SI_LIST_DETAILS.BACK:Back`	Details back button text. Required for a11y.
backButtonUrl ¶	`string`	`'../'`	The URL to navigate to when the back buttons is clicked. This is only used when the `si-details-pane` is used with a router-outlet.
hideBackButton ¶	`boolean`	`false`	You can hide the back button in the mobile view by setting true. Required in add, edit workflows on mobile sizes. During add or edit, the back button should be hidden. Default value is `false` .
title ¶	`TranslatableString`		Optional title to be displayed.

SiDetailsPaneBodyComponent API Documentation¶

selector

si-details-pane-body

No API to document for this.

SiDetailsPaneFooterComponent API Documentation¶

selector

si-details-pane-footer

No API to document for this.

Types Documentation¶

TranslatableString (`string` & `Translatable`)¶ Type alias Represents a translatable string. This can either be a translation key, e.g. `ACTIONS.EDIT` that will be automatically translated when displayed on the UI or a pre-translated string, e.g. `Edit` . Equivalent to a normal string in usage and functionality.

Translatable ¶ import imported from @siemens/element-translate-ng

ElementDimensions

¶

Interface

Properties
height: `number`¶
width: `number`¶

ResizeObserverService

¶

Class

▶

A service wrapping ResizeObserver . This is a service for those reasons: - only one ResizeObserver should be used for performance reason. - For Angular change detection to work, explicit ngZone calls are necessary - Observable stream

Constructor
() => `{}`¶

Properties
listeners: `Map`<`Element`, `Listener`> = ...¶
resizeObserver?: `ResizeObserver`¶
timerQueue: `Map`<`number`, `QueueEntry`[]> = ...¶
zone: `NgZone` = ...¶

Methods

check size on all observed elements. Only use in testing!
_checkAll: () => void¶

emitSize

(element: Element, entry: ResizeSubscriber, force: boolean = false) => void¶

Parameters
element: `Element`¶
entry: `ResizeSubscriber`¶
force: `boolean` = `false`¶

handleElement

(element: Element) => void¶

Parameters
element: `Element`¶

handleResizeSubscriber

(element: Element, entry: ResizeSubscriber) => void¶

Parameters
element: `Element`¶
entry: `ResizeSubscriber`¶

observe

(element: Element, throttle: number, emitInitial: boolean, emitImmediate: boolean) => Observable<ElementDimensions>¶

Observe the size of an element. Returns an observable with the changes.

Parameters
The element to observe element: `Element`¶
Throttle time in ms. Will emit this time after the resize throttle: `number`¶
Emit the initial size after subscribe? emitInitial?: `boolean`¶
Emit an event immediately after the size changes. Useful e.g. for visibility checks. emitImmediate?: `boolean`¶

processQueue

(queue: QueueEntry[]) => void¶

Parameters
queue: `QueueEntry`[]¶

schedule

(timeout: number, element: Element, subscriber: ResizeSubscriber, unblock: boolean, force: boolean = false) => void¶

Parameters
timeout: `number`¶
element: `Element`¶
subscriber: `ResizeSubscriber`¶
unblock: `boolean`¶
force: `boolean` = `false`¶

subscriberAdded

(entry: Listener, subscriber: ResizeSubscriber, emitInitial: boolean) => void¶

Parameters
entry: `Listener`¶
subscriber: `ResizeSubscriber`¶
emitInitial?: `boolean`¶

subscriberRemoved

(entry: Listener, subscriber: ResizeSubscriber) => void¶

Parameters
entry: `Listener`¶
subscriber: `ResizeSubscriber`¶

unschedule

(entry: ResizeSubscriber) => void¶

Parameters
entry: `ResizeSubscriber`¶

Code (legacy)¶

Usage¶

import { SiMainDetailContainerComponent } from '@siemens/element-ng/main-detail-container';

@Component({
  imports: [SiMainDetailContainerComponent, ...]
})

The <si-main-detail-container> represents the layout container used to organize the different elements. The slot attribute on the child elements is used to assign them to the correct position in the list-details layout.

The slot attribute accepts one of the following values:

mainSearch: Search field for the main list
mainActions: Content actions for the main list
mainData: List/table to show the main data
details: Details pane
detailActions: Content actions for the details pane

SiMainDetailContainerComponent API Documentation¶

selector

si-main-detail-container

Input Properties¶

Name	Type	Default	Description
containerClass ¶	`string`	`'px-6 pt-6 px-md-9'`	CSS class(es) applied to the outermost container. Per default, Bootstrap classes to handle responsive paddings are applied: `px-6 pt-6 px-md-9` .
detailContainerClass ¶	`string`	`'pb-6'`	CSS class(es) applied to the detail container. In combination with `containerClass` , this allows for settings individual padding and margin values on the individual containers.
detailsActive ¶	`boolean`	`false`	Whether the details are currently active or not, mostly relevant in the responsive scenario when the viewport only shows either the main or the detail.
detailsBackButtonText ¶	`TranslatableString`	$localize`:@@SI_MAIN_DETAIL_CONTAINER.BACK:Back`	Details back button text. Required for a11y.
detailsHeading ¶	`string`	`''`	The heading of the detail area.
heading ¶	`string`	`''`	The heading of the main-detail layout component, usually a page heading.
hideBackButton ¶	`boolean`	`false`	You can hide the back button in the mobile view by setting true. Required in add, edit workflows on mobile sizes. During add or edit, the back button should be hidden. Default value is `false` .
mainContainerClass ¶	`string`	`'pb-6'`	CSS class(es) applied to the main container. In combination with `containerClass` , this allows for settings individual padding and margin values on the individual containers.
mainContainerWidth ¶	(`number` \| `"default"`)	`'default'`	The percentage width of the main container from the overall component width. Can be a number or `'default'` , which is 32% when resizableParts is active, otherwise 50%.
minDetailSize ¶	`number`	`300`	Sets the minimal width of the detail container in pixel.
minMainSize ¶	`number`	`300`	Sets the minimal width of the main container in pixel.
resizableParts ¶	`boolean`	`false`	Whether the main and detail parts should be resizable by a splitter or not. This is only supported in the 'large' scenario (when `hasLargeSize` is `true` ). Default value is `false` .
stateId ¶	`string`		An optional stateId to uniquely identify a component instance. Required for persistence of ui state.
truncateHeading ¶	`boolean`	`false`	Whether the heading should be truncated (single line) or not. Default value is `false` .

Output Properties¶

Name	Type	Description
detailsActiveChange ¶	`boolean`	Whether the details are currently active or not, mostly relevant in the responsive scenario when the viewport only shows either the main or the detail.
hasLargeSizeChange ¶	`boolean`	Emits whether the components size is large enough to display main and details views next to each other or not.
mainContainerWidthChange ¶	(`number` \| `"default"`)	The percentage width of the main container from the overall component width. Can be a number or `'default'` , which is 32% when resizableParts is active, otherwise 50%.

Attributes and Methods¶

Name	Type	Default	Description
hasLargeSize ¶	`boolean`		Whether the main-detail layout component has a large size or not, `true` if the container´s width matches or exceeds the `largeLayoutBreakpoint` .
(readonly) largeLayoutBreakpoint ¶	`InputSignal`<`number`>	`BOOTSTRAP_BREAKPOINTS.mdMinimum`	A numeric value defining the minimum width in px, which the container needs to be displayed in its large layout. Whenever smaller than this threshold, the small layout will be used. Default is value is BOOTSTRAP_BREAKPOINTS.mdMinimum.

Except where otherwise noted, content on this site is licensed under MIT License.