Use this interaction flow if you want to make only part of an object editable (single sections or items).

There are two variants for editing part of an object:

• Partial edit in place (preferred)
• Partial edit with dialog

You can use both variants in split screen and full screen layouts.

Partial Edit in Place

With this flow, the user edits a specific section of an object in place by clicking a transparent Edit button in the section header. The section then switches to edit mode, and the Edit button is replaced by Save and Cancel buttons.

In-place editing is the preferred method for changing part of an existing object into edit mode.

Data Loss Message

If the user has made changes in edit mode, show a data loss message whenever the user navigates away from the page being edited, or clicks Cancel. The data loss message is required for both split screen and full screen layouts.

If you want to keep unsaved changes, you need to implement draft handling.

Partial Edit with Dialog

With this flow, the user selects one or several existing objects for editing. The values are then edited in a separate dialog. For more information, see Mass Edit.

When the user clicks Save, the dialog closes, and the line items in the table are updated.

Use the partial edit flow with a dialog if the switch from display to edit mode involves an extensive change of layout, such as mass editing. If the dialog contains more than 8 editable fields, consider navigating to a details page instead.

Data Loss Message

No data loss message is required for the partial edit flow with a dialog. The user can leave the edit dialog by clicking Cancel. Any changes are discarded.

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Use the flows described below to create and edit simple objects. All the information for a simple object appears on a single page. The flows use standard message and draft handling. For the delete flow, see Delete Objects.

Create

Full Screen Layout

If your app runs in full screen mode, meaning that one page is shown at a time, the standard create flow is as follows:

1. In a list report, the user chooses Create.
   An empty object page appears with the title New <object type> (here: New Leave Request). The footer toolbar contains the finalizing Create action and Cancel.
2. After entering all the data, the user chooses Create.
   You have the following flow options, depending on your use case:
   1. The standard flow shows the object in display mode and a message toast.
      If required by the use case, you can also keep the object in edit mode.
   2. If your use case involves creating several objects in succession, you can also navigate back to the list report. The message toast is shown on the list report and an indicator highlights the new item.
3. Choosing Cancel opens a confirmation popover and the user can opt to discard the draft. In this case, the system navigates back to the list report.

Flexible Column Layout

If your app runs in the flexible column layout and the user chooses Create on the object page, the display is as follows:

• The first column shows the updated list report with the focus on the newly created item (as for 2b).
• The second column shows the object page in display mode plus the message toast (as for 2a).

If the user confirms Cancel, the second column is closed.

Edit

Full Screen Layout

You can choose between the following edit flows for the entire page:

• The standard flow is to navigate from a list report to the object details. The object is shown in display mode. Choosing Edit in the header toolbar of the object page opens the object in edit mode.
  See also: Start editing from object page
  As an alternative, you can open the object directly in edit mode.
• In a list report, the user selects an object and chooses Edit in the list report toolbar. This opens the selected object in edit mode.
  See also: Start editing from list report

Start editing from object page

1. From the list report, the user navigates to the details of an object.
   The object page features a header toolbar with an Edit button. The title of the page is <object type> (here: Leave Request).
2. The user chooses Edit.
   The object page changes to edit mode, showing a footer toolbar containing the finalizing Save action and Cancel. The title does not change.
3. After updating the data, the user chooses Save.
   You have the following flow options, depending on your use case:

1. The standard flow shows the object in display mode and a message toast.
2. If your use case involves editing several objects in succession, you can also navigate back to the list report. The message toast is shown on the list report and an indicator highlights the updated item.

• Choosing Cancel opens a confirmation popover and the user can opt to discard the changes. The object then switches to display mode. If required by the use case, the system can also navigate back to the list report.

Start editing from list report

1. In a list report, the user selects an object and chooses Edit.
   The object page features a footer toolbar containing the finalizing Save action and Cancel. The title of the page is <object type> (here: Leave Request).
2. After updating the data, the user chooses Save.
   You have the following flow options, depending on your use case:
   1. The standard flow shows the object in display mode and a message toast.
   2. If your use case involves editing several objects in succession, you can also navigate back to the list report. The message toast is shown on the list report and an indicator highlights the updated item.
3. Selecting Cancel opens a confirmation popover, and the user can opt to discard the changes. The object then switches to display mode. If required by the use case, the system can also navigate back to the list report.

Flexible Column Layout

If your app runs in the flexible column layout, and the user chooses Save on the object page, the display is as follows:

• The first column shows the list report with the focus on the updated object.
• The second column shows the object page in display mode plus the message toast.

If the user confirms Cancel, the second column shows the object in display mode.

Related Links

Intro

The smart table creates a responsive table, grid table, tree table, or analytical table based on an OData (Open Data Protocol) service and its annotations. The table toolbar comes with additional built-in features, such as personalization, export to spreadsheet, and variant management.

When to Use

Use the smart table if:

• You use an OData service for your app (OData version 2 only).
• The feature set of the smart table fits for your app. In this case, the smart table is faster to implement.
• You need more than one of the major features of the smart table. Otherwise, you might not benefit from a shorter implementation time. For example, if you just need the export to spreadsheet feature, creating a responsive table directly is usually faster than using the smart table.

Do not use the smart table if:

• You use a different technology to OData version 2. Use the corresponding table control directly.
• You need more flexibility in the content design, such as several different row templates or less complex personalization features. Use the responsive table directly.
• You do not have complex data. Another control like a select, combo box, list, grid list, tree, or smart list might do the job better.
• You have very complex data. Did you check the chart?
• Users need to switch between a chart and table. The smart table is not designed to work inside an existing chart container. In this case, use either the smart chart or the corresponding table directly.
• You need to layout different controls in a table-like grid. Use a flexible grid instead.
• You need to layout different input fields with labels. Use a form, simple form, or smart form.

Components

The smart table consists of a table toolbar (1), an infobar (2), and a table (3).

Table Toolbar

The table toolbar is generated automatically. The following toolbar content is provided by the smart table out-of-the box:

1. Title
2. Item counter
3. Variant management
4. Show Details / Hide Details
5. View Settings
6. Export to Spreadsheet
7. Maximize / Minimize

In addition, you can add app-specific actions.

Title

Displaying a title is optional (property: header).

Item Counter

The item counter is optional and only available if you show a title (property: showRowCount).

Variant Management

Variant management is optional (properties: persistencyKey, useVariantManagement, currentVariantID, association: smartVariant).

Show Details / Hide Details

The Show Details / Hide Details button is mandatory with and only available for the responsive table. Columns with a low priority (low or medium priority on phones) are hidden in the pop-in area (properties: demandPopin, enableAutoColumnWidth, showDetailsButton, annotation: UI.Importance).

You can define which priority levels cause the columns to be hidden (property: detailsButtonSettings). The button only appears if there are columns that belong in the pop-in area. Columns disappear from right to left but columns with the priority “High”, are never hidden. They are shown in the pop-in area if they do not fit on the current screen size

View Settings

View Settings are optional. The button triggers a P13n Dialog (property: useTablePersonalisation). The View Settings dialog can also be opened with the shortcut Ctrl+Comma.

Sort and Filter

Sorting, filtering, and column settings are automatically available for all columns in all tables. For single columns, you can remove the sort and filter settings (annotations: SortRestrictions, FilterRestrictions).

• The current sort state and sort order is displayed as an icon in the column header of the sorted columns.
• The current filter state is displayed as follows:
  • In the responsive table, an infobar is shown if filters have been set in the table personalization settings.
  • For all other tables, filtering is indicated by an icon in the column header of each filtered column.

When amounts with different currencies appear in a single column, you can change the sort behavior to sort these columns first by currency, then by amount (annotation: ApplyMulitUnitBehaviorForSortingAndFiltering). This behavior is applied for all such columns in the smart table. It cannot be defined per column.

Group

Group settings are only available for the responsive table (all columns, one level only) and the analytical table (dimension columns only, multiple levels).

The following text is usually shown on the group header:
[Label of the grouped column]: [Grouping value]

Within the analytical table, the grouped column remains visible by default if it is grouped using the P13n Dialog. The column is hidden if it is grouped using the column header menu.

Column Settings

Column settings are used to show and hide columns. For the grid table, tree table, and analytical table, the column settings automatically enable resizing via the column header and size-to-fit for text-only columns (double-click on column separator line).

Export to Spreadsheet

Export to Spreadsheet is optional. The button triggers either a front-end export using the export to spreadsheet utility, or a back-end export via Gateway (properties: useExportToExcel, exportType). The front-end export allows for additional settings and can also be triggered with the shortcut Ctrl+Shift+E.

Maximize / Minimize

Maximize / Minimize is optional. It allows users to show the table in full screen mode and to exit full screen mode (property: showFullScreenButton).

App-Specific Actions

App-specific actions can only be added using a custom toolbar (aggregation: customToolbar).

Infobar

The infobar is only available for the responsive table. It indicates which filter settings are currently active. If no filters are set, the infobar is hidden (property: useInfoToolbar, value: Auto).

Table

The table is generated automatically. The sections below describe the behavior and different possibilities:

• Table
• Column Visibility
• Column Layout
• Column Headers
• Column Content

Table

The table provides the following features:

• You can use the responsive table, grid table, tree table, or analytical table within the smart table (property: tableType).

• While the grid table, analytical table, and tree table support multi-selection by default within the smart table, the responsive table does not offer any kind of selection. The selection mode can be changed.

Column Visibility

• Columns are created automatically. Items are rendered based on the properties and metadata of the underlying OData service (annotation: LineItem, properties: entitySet, tableBindingPath, initiallyVisibleFields, ignoreFields). A column is generated for each OData entity property.

• You can define which columns are initially visible when the app is first launched. All other columns are initially hidden (annotation: PresentationVariant/ LineItem, property: initiallyVisibleFields).

• For each column that is initially visible, the LineItem annotation includes a DataField record, which allows you to influence the content rendering of the smart table.
  For columns that are initially invisible, the content rendering can also be influenced via the annotation DataFieldDefault.

Column Layout

• A default column width can be calculated for each column based on the data type, the column label, the edit/read-only state, and the annotations: textArrangement, MaxLength for strings, Precision and Scale for numeric data (property: enableAutoColumnWidth).
  The calculated width is between 3 rem and 20 rem. Apps can change this default width if needed (annotation: CSSDefaults).
  If the combined width of all the columns is less than the width of the table, the remaining space stays empty.

• Columns can be resized by dragging the column separator. If the combined width of all columns is less than the width of the table, the remaining space stays empty. The smart table provides column resizing automatically in the following cases:
  • Grid table / tree table / analytical table: Column resizing is automatically enabled with the column settings.
  • Responsive table: Column resizing is automatically enabled with the automatically calculated default column width.

• If the automatically generated content does not fit for your use case, you can override the automatic behavior with your own column template.
  You can also add further columns. This allows you to provide columns with app-specific or inline actions, columns which show calculated values (based on more than one OData entity property), or – for responsive tables – columns that show more than one control.

Column Headers

• You can specify a column header text for each column (annotation: sap:label).
• SAP S/4HANA Only:
  Tooltips are available by default for smart table column headers.
  In smart tables, texts that exceed the column width always truncate (see Column Layout). The tooltip allows users to read the full column header text without resizing.

• The column headers contain the following settings:
  • Sort Ascending, Sort Descending
  • Filter: Opens the P13n Dialog. If this does not fit for your use case, exchange this menu item (property: enableCustomFilter)
  • Group (only analytical table, only on dimension columns)
  • Total (only analytical table, only on measure columns): This setting is not persisted (annotation: sap:aggregation-role, value: measure).
    If a column contains entries with different units of measurement, a Show Details link appears instead of the total. Clicking the link opens a popover showing the subtotals per unit of measurement.
  • Freeze (only available for grid table, tree table, and analytical table): Must be added manually.

Content

The smart table offers the following options for creating columns automatically:

1. You can render the smart table in either read-only or edit mode (with no option to switch), or allow users to switch between the two modes (properties: editable, useSmartToggle).
2. In read-only or edit mode, the smart table renders the controls as listed in the table below, or uses the smart field for both modes. If you use smart fields together with the option to switch between read-only and edit mode, the smart table renders the read-only controls as in the list below, but uses the smart field for edit mode. The smart field limits the rendering options (aggregation: customData, key: useSmartField), but also allows for:
   • Better control of the visibility of a field per row (smart field, annotation: FieldControl)
   • Use of value help for input fields

In cases where the controls are rendered by the smart table, the following controls are used:

In all cases, the smart table automatically takes care of the content alignment and formatting (except for custom columns).

Input fields can be accompanied by a value help dialog (annotation: ValueList). If annotated, triggering the value help button opens a value help dialog. Within this dialog, you can provide a search field (annotation: ValueList, property: SearchSupported).

If no ValueList annotation is provided, you can restrict the number of characters for an input field (annotation: MaxLength).

You can provide additional controls, such as micro charts, rating indicators, progress indicators, and buttons, as custom columns (using an XML view). For custom columns, you must provide any read-only and editable content manually.

If the smart table is used with the responsive table, you can show the status of an item by displaying a highlight indicator on the left of the item (property: highlight).

Behavior and Interaction

The behavior is generally inherited from the underlying table, toolbar, variant management, export to spreadsheet, and P13n dialog (see the corresponding articles for details.) Note that the smart table provides limited options and not all settings of the underlying controls are available.

Empty Tables

If there is no data to show, the smart table renders a default text. This text can be overwritten by the app development team. The default texts are:

• If a table is initially empty:
  No items available.
  Overwrite this whenever a hint can be provided on how to fill the table with data.
  (property: initialNoDataText, value: $NO_FILTERBAR)
• If a table is used together with a filter bar (as in the list report), and is initially empty, use the following text:
  To start, set the relevant filters.
  (property: initialNoDataText, value: $FILTERBAR)
• If a table is used together with a filter bar and the filter does not return results, use the following text:
  No data found. Try adjusting the filter settings.
  (aggregation: noData, changeable at runtime)
• If the user has hidden all of the columns in the personalization settings, the following text is shown:
  Right now, there are no visible columns in the table. Please select the columns you need in the table settings.
  This text cannot be changed.
  

Errors and Warnings

To indicate that the table contains items with errors or warnings, the smart table can show a message strip above the table (aggregation: dataStateIndicator). On the message strip, information about errors or warnings is provided, as well as the possibility to filter down the table to the corresponding rows. When issues are solved or when new issues appear, the message strip is updated accordingly.

For details on displaying errors, warnings, and other messages, see Message Handling.

Responsiveness

The smart table acts exactly like the embedded controls. For details see:

• Toolbar Overview
• Infobar
• Responsive Table via auto pop-in mode
  (sap.ui.comp.smarttable.SmartTable, property: demandPopin, value: true).
  You can use the UI.Importance annotation to influence the priority of each column.
  You can provide a Show Details button to let users show/hide columns with low importance (property: showDetailsButton).
• Grid Table, Tree Table, Analytical Table are not fully responsive. They are available only for desktops and tablets. For smartphones, you need to take an adaptive approach by offering an additional UI.

Examples

Top Tips

• If you are using the responsive table, enable and configure the auto pop-in mode and use the Show Details / Hide Details button.
• For custom columns, follow the guidelines of the respective table. If needed, use responsive paddings for aligning the content.
• Enable only the features that are needed for your use case. Very small tables do not need to be sorted, filtered, grouped, and rarely exported. Don’t just add unnecessary features for consistency purposes.
• If the page has a filter bar, don’t offer filtering for the table.
• If you are using custom columns, make sure that any export and personalization features you are using also work for these columns.

Properties

The following properties are available for sap.ui.comp.smarttable.SmartTable:

• The property: toolbarStyleClass is deprecated. Do not use it.
• The property: useOnlyOneSolidToolbar is deprecated. Do not use it.

Related Links

Intro

The block layout is used to display content in a section-based manner. It features horizontal and vertical subdivisions and full-width banners seen frequently in contemporary web design. Background colors are attached directly to these areas within the layout. Also, special full-width sections of the block layout enable horizontal scrolling through a set of areas.

Usage

Use the block layout if:

• You want to display section-based content. Place elements next to each other to indicate a content relationship.

Do not use the block layout if:

• You want to display properties or features of one content item. Use the object page floorplan instead.
• You want to display KPIs in the dashboard-variant. Use the overview page or a layout using cards instead.

Block layout case examples include landing pages and catalog-like pages.

In landing pages, the block layout may serve as a banner-like presentation of illustrative icons with associated text. By placing pictorial and textual elements side by side in different areas, a content relationship is established. In catalog-like layouts, the block layout serves as a flexible container for diverging content, such as headings, explanatory texts, code snippets, remarks, and examples.

It is also possible to have clickable blocks with their own hover and pressed states.

Layout

The block layout is divided into horizontal sections, which take on the full width of the available screen real estate. Their screen height is determined by their inner content, which prevents vertical scrolling.

If needed, the width of sections can also be set to the following predefined ratios (for the sizes XL, L and M):

• 1 block: 100%
• 2 blocks:
  • 50% and 50% or
  • 75% and 25% or
  • 25% and 75%
• 3 blocks:
  • 3 × 33% or
  • 2 × 25% and 50% or
  • 50% and 2 × 25% or
  • 25% and 50% and 25%
• 4 blocks: 4 × 25%

Block layouts can also contain sections that allow horizontal scrolling. These sections always have a width of 100%.

Components

1 – Section

1a – Section Title

2 – Block

2a – Block Title – can be text or a link.

2b – Block Body – can contain text or other controls.

Types

There are four types of block layouts:

1. Default: This layout does not use any background colors.
2. Dashboard: This layout type uses white blocks with spacing around them, making each block look like a card.
3. Light: Areas use predefined colors found in the SAP Fiori 3 Quartz Light theme. These colors follow a specific order that is defined in the control. If there are more than six areas, the background colors start over beginning with the initial color.
4. Accent: Each row contains a range of colors derived from one accent color, and these colors are used alternately. If required by the control, you can display multiple gray blocks: the different shades of gray will then be displayed alternately, beginning with the initial color.

Light Color Set

Accent Color Sets

Row (Section) Color Sets

For the Accent variant of the block layout, you can use a different color set for each row (sap.ui.layout.BlockLayoutRow, property:rowColorSet). This enables different starting colors for the row coloring, and prevents color coalescence in the responsive behavior of the block layout.

Cell (Block) Colors

There are 10 predefined color sets that you can use as accent variants, each with 6 different shades.

To change the background of a particular block, set the desired color set (sap.ui.layout.BlockLayoutCell, property: backgroundColorSet) and color shade (sap.ui.layout.BlockLayoutCell, property: backgroundColorShade) accordingly.

Images

Images may be placed as background images within one block. The predefined paddings do not apply to blocks with images; images fill out the entire block.
If needed, the title control may be placed on top of the images.

Responsiveness

The block layout offers responsive behavior. There are three breakpoints, which results in four supported sizes: XL, L, M, and S. As with the responsive grid (another generic layout control), these breakpoints apply both to the page and block layout. However, the page layout’s breakpoints react to screen width, whereas the breakpoints of the block layout react to the width of the control itself.

Ratios of areas in different contexts

^*Blocks wrap and are displayed underneath each other

Sections with Horizontal Scrolling

The width of the horizontal scrolling area in different device contexts:

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Use this control to display different currencies in a vertical layout, such as in a table, list, or form. The control ensures that the amount is always aligned to the decimal point.

Usage

Use the currency control if:

• You need to display amounts with different currencies in a vertical layout, such as in a table, list, or form, and it is important that the user is able to compare the amounts.

Do not use the currency control if:

• You need to display amounts with the same currency in a table. Use an object number instead.
• You need to display a number with a unit of measurement that is not a currency. Use an object number instead.
• You need to display an amount in a structure other than a list, table, or form.

Responsiveness

Components

Guidelines

Resources

In addition to the basic display option, the following actions are available for objects:

• Create 
  Objects can be created as follows:
  • From scratch
    Most of the examples in this article show how to create objects from scratch.
  • Copy an existing object
    The source object and copy are of the same object type but are not related.
  • With reference to an existing object
    The object can be of another object type, and both objects are related. For example, the user creates a delivery with a reference to the corresponding sales order.
• Edit
  Objects can be edited at different levels: You can make the complete object editable, or only parts, such as single sections or items.
• Delete

The interaction flows for the “create”, “edit”, and “delete” cases depend on the structure of the object.

Simple vs. Complex Objects

An object can consist of only one page or several nested pages:

Simple Objects (1 Page)

Create

For the create flow, see Simple Objects (Create, Edit).

Edit

For 1-page objects, you can set the entire page to edit mode. If only a few sections are editable, set only these sections to edit mode, or open a dialog for editing. For more information, see Partial Edit.

Tip: If your page contains a table and you need to edit specific fields for many items at once, use the mass edit pattern.   

Delete

For the delete flow, see Delete Objects.

Complex Objects (Nested Pages)

You can choose between 3 interaction flows for handling objects with nested pages:

• Partial flow
• Local flow (only the page a user is working on is locked)
• Global flow (entire object including subpages is locked)

You can only use one of these flows for any given object. Do not mix them.

Use the following criteria to choose the right flow:

You can use the mass edit pattern in all flows. 

For more information, see Partial Edit, Complex Objects – Local Flow and Complex Objects – Global Flow.

Naming Guidelines

Apply the following naming conventions for the triggering button, finalizing action, title in the shell bar, and the placeholder for newly created objects.

For subitems, apply the following naming conventions.

¹⁾ Create: Brand new object that has not yet been created on the database.
²⁾ Add: Existing object that is being added/assigned.

For naming examples, see Creating an object or item in the UI text guidelines.

Resources