Smart Table

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).

The components of a smart table

Table Toolbar

Toolbar with all features provided by the smart table out-of-the-box

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

Title
Item counter
Variant management
Show Details / Hide Details
View Settings
Export to Spreadsheet
Maximize / Minimize

In addition, you can add app-specific actions.

Title

Displaying a title is optional (property: header).

Guidelines

Add a title whenever the title is not indicated in the surrounding area.
If you don’t display a title, ensure that you still provide a table title for screen reader users.

Developer Hint

If there is no title title, support screen reader users as follows: create a simple table in the XML view, use ariaLabelledBy to point to the corresponding text, and add this table to the smart table. Make sure that the table type within the smart table is set accordingly. The smart table will take care of the rest (creating columns, and so on).

Item Counter

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

Guidelines

Show the item counter together with the table title, unless:

You expect this to cause performance problems.
You use a responsive table and use the More button for loading additional items. Use the item counter on the More button instead.

Variant Management

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

Guidelines

Use variant management only if really needed.

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

Details hidden

Details shown

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.

Guidelines

Offer view settings only if they are really needed. Tables with just a few columns and rows do not need to be sorted, filtered, or grouped.

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.

Guidelines

Do not turn off the info bar (property: useInfoBar).
In the default delivery, sort items in a meaningful order. This works only for the grid table, tree table, and analytical table. You can also provide default filter settings (all tables) and grouping (responsive table and analytical table only) (annotation:
PresentationVariant).
If the smart table is used together with a filter bar (property:
smartFilterId), do not offer filtering for the smart table itself.

Developer Hint

The smart table can be linked to a smart filter bar. If linked, the filter bar settings are automatically applied to the smart table (sap.ui.comp.smarttable,SmartTable, property: smartFilterId).

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.

Guidelines

In some cases, the group header text may not be shown automatically as described. This applies to special cases in the analytical table (for example, if the displayed text is not taken directly from the data source), as well as custom columns in both responsive and analytical tables. In such cases, you must set and format the group header text yourself.

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).

Guidelines

If sorting, grouping, and/or filtering are needed, also show the column settings (sap.ui.comp.smarttable.SmartTable, property: useTablePersonalisation).

Developer Hint

Only offer column settings if you need more columns than a tablet screen can display at a time (usually more than five).

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.

Guidelines

Only offer the Export to Spreadsheet option if your end users typically export the data shown in the table to work with it in a spreadsheet application.
- This is usually the case if data is collected from several systems and analyzed in the spreadsheet application.
- This is not usually the case for worklists, attachment lists, tables with only a few items, shopping carts, or data that does not need to be analyzed.
If you offer the Export to Spreadsheet button, use the front-end export.
If your table has columns with non-textual content, provide a textual equivalent for those columns. Non-textual content is not exported.

Warning

With both methods, the file size is limited by the available browser memory. As a result, exporting large tables can lead to memory overflows and crash the export process.

Apply the following size restrictions as a rule-of-thumb:

For the front-end export, do not export more than 2 million table cells on desktop browsers or 100,000 table cells on tablets and phones.
For the back-end export, do not export more than 100,000 table cells.

For larger tables, consider using custom-built, specialized export solutions instead.

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).

Guidelines

Use Maximize / Minimize only if really needed.
Do not use it in list reports, worklists, analytical list pages, and initial pages. We recommend it in object pages with multiple grid tables in one tab.
Do not use it for responsive tables with a More button.
Do not use it if the table is in a dialog or popover.

App-Specific Actions

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

Developer Hint

If additional actions are needed, use a custom toolbar for the table. The smart table can also add integrated functionality, such as a table title, item counter, variant management, view settings, and export to spreadsheet to the custom toolbar (aggregation: customToolbar).
If you are using a custom toolbar in a responsive table, show the bottom border of the toolbar. For all other tables, do not show it (property: style, value: clear).
The property placeToolbarInTable adds the toolbar to the corresponding aggregation of the inner SAPUI5 table. In most cases, set this to “true”, especially when you are using the custom toolbar with the responsive table. Otherwise, the table toolbar cannot stick to the top of the surrounding layout container.

Infobar

Infobar with filter information

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).

Guidelines

For the responsive table, the info bar is mandatory.
For all other tables, do not show the info bar.

Table

Responsive table within a smart 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).

Guidelines

The analytical table, tree table and grid table are not fully responsive. They are available only for desktops and tablets, so you will need to take an adaptive approach by offering an additional UI for smartphones.
For the responsive table, the smart table initially loads 20 items and shows a More button for loading additional items. Change this behavior if:
- You expect fewer than 200 items. Load all items from the start (sap.m.Table, property: growing).
- You expect more than 200 items. Adapt the number of items initially loaded to cater for large screens, and load additional items automatically when the user scrolls down (sap.m.Table, property: growingScrolllToLoad).

Developer Hint

To change the growing behavior, create a responsive table with just the settings for the growing behavior, and hand it over to the smart table. The smart table then takes care of the rest (such as adding columns, and so on).

Developer Hint

The property tableBindingPath defines the path from which the data is fetched.
The property enableAutoBinding fetches the data automatically as soon as the corresponding OData model is initialized and the smart table is created.

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.

Developer Hint

To change the selection mode, add a navigation indicator to single rows, or add a highlight to specific rows, you need to create a table with the corresponding settings. You do not need to define anything else. Hand this table over to the smart table. The smart table then takes care of the rest (such as adding columns, and so on). This method allows you to use the multi-selection plug-in with the grid table, tree table, and analytical table.

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.

Developer Hint

If a column needs to be in the model but should not be shown, you can hide it from both the table and the P13n dialog (property: ignoredFields, annotation: UI.Hidden).

Use this option if:

A column is needed to provide an ID that is used for navigation purposes only. However, you only want to display the corresponding text on the UI, and not the ID.
The values of a column are needed to perform calculations, but only the results are shown on the UI.

You can use the property requestAtLeastFields to request additional (technical) columns with every request, regardless of whether these columns are currently visible. This does not work with the analytical table.

The property ignoreFromPersonalization is only available with the analytical table. It loads additional key fields that are needed for aggregations but are never visible.

Developer Hint

Columns can be removed at runtime. This is useful if the same table is used for similar, but slightly different objects. For one of the objects, specific columns need to be shown, for others they must be hidden, and users must not be able to add them in the personalization settings (function: deactivateColumn).

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).

Guidelines

Keep the number of initially visible columns to a minimum. Avoid pop-in behavior (responsive table) or horizontal scrolling (all other tables) on a tablet screen size in the default delivery (annotation: PresentationVariant/ LineItem).
Also keep the number of additional columns offered in the personalization settings to a minimum. You can use the P13n dialog to let users show/hide the columns. Select the columns offered in the P13n dialog carefully. Do not just show all columns available in the backend tables (annotation: sap:visible, value: false).

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.

Developer Hint

If the same column is defined via LineItem and via DataFieldDefault, LineItem wins.

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.

Guidelines

Choose a column width that avoids truncation for the initial data and (if feasible) for the column header label. If the default column width doesn’t fit, change it.

Developer Hint

For the responsive table, enableAutoColumnWidth also applies the following changes:

The smart table property demandPopin is set to true.
The responsive table property fixedLayout is set to Strict.
The responsive table property contextualWidth is set to Auto.
Column resizing is enabled for all columns (including custom columns).
Labels in the column headers no longer wrap. If there is not enough space, they truncate.

In this case, the properties above must not be managed by the app.

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.

Responsive table with automatically calculated column widths, resizing, and remaining space

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.

Developer Hint

To add or override columns (“custom columns”):

Use an XML view to define the underlying table with just the columns to be added/overridden.
To override columns, provide the column key of the column you want to exchange.
Add this “unfinished” table to the smart table. The smart table adds all the automatically generated columns and additional features.

Make sure that the sortProperty and the filterProperty are set (define p13nData via the aggregation CustomData). If you offer the export to spreadsheet option, ensure that it works as expected.

If you are using a responsive table, also make sure that the responsive behavior for this column works as expected (sap.m.Column, property: importance).

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.

Guidelines

Provide a column header text for each column. (annotation: sap:label).

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.

Guidelines

Offer column totals by default for all columns where totals make sense (annotation: PresentationVariant).

Developer Hint

To add a Freeze option manually, declare the corresponding table inside the smart table in the XML view, and use the corresponding settings for this inner table.

Clicking the column header reveals sort and filter options (responsive table)

Column header menu for a dimension column of an analytical table within a smart table

Column header menu for a measure column of an analytical table within a smart table

Content

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

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).
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

Developer Hint

From a performance perspective, using the smart field is more expensive than using the controls provided by the smart table directly. With this in mind, follow the rules below:

For read-only tables, use the controls provided by the smart table.
For simple editing cases with no need for FieldControl or value help on input fields, use the controls provided by the smart table.
For more complex editing cases, use smart fields.
For switching between read-only and edit modes:
- In read-only mode, use the controls provided by the smart table.
- In edit mode, use either smart fields or the controls provided by the smart table, based on the guidance above.

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

	Read-only	Edit	Annotations / Edm type	Comment
Static text	Text	Input field	Edm.String
Decimal numbers	Text	Input field	Precision, Scale, Edm.Byte, Edm.Decimal, Edm.Double, Edm.Int16, Edm.Int32, Edm.Int64, Edm.SByte, Edm.Single
Status information	Object status or Icon	Input field	Criticality, CriticalityType, CriticalityRepresentationType	Do not use editable status information.
Key identifier	Object identifier (responsive table) Text (all other tables)	Input field for the ID	SemanticKey, Common.EditableFieldFor
Text and ID	Text, object status, or object identifier	Input field for the ID	TextArrangement	Use together with the annotation mentioned above for static text, status information, or key identifier. Sorting, filtering, and grouping only works for the ID, even if the ID is not displayed.
Links with/without quick view	Smart link	Smart link	SemanticObject	Smart links can be customized using the aggregation: `semanticObjectController`
Dates	Text	Date picker	Edm.DateTime, sap:display-format, value: date, IsCalendarDate
Dates and times	Text	Date/time picker	Edm.DateTime, Edm.DateTimeOffset
Times	Text	Time picker	Edm.Time
Fiscal periods	Text	Input field	IsFiscalYear, IsFiscalPeriod, IsFiscalYearPeriod, IsFiscalQuarter, IsFiscalYearQuarter, IsFiscalWeek, IsFiscalYearWeek, IsDayOfFiscalYear
Amounts with currencies	Two text controls	Input field for the amount	sap:semantics, value: currency-code	In edit mode, the currency is shown as static text next to the input field.
Phone numbers	Link	Input field	IsPhoneNumber	Opens the system application for making phone calls.
Email	Link	Input field	IsEmailAddress	Opens the system application for writing emails.
Pictures	Image	Input field	IsImageURL	Only available for the responsive table. In edit mode, the input field contains the URL to the image.
Boolean	Text	Checkbox	Edm.Boolean	For read-only, the displayed text is Yes or No.

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.

Guidelines

For inline actions, use a text-only or an icon-only button. Make sure the icon communicates the function clearly enough. Otherwise, use a text-only button.

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.

Guidelines

For all other cases, provide instructions on how to fill the table with data (aggregation: noData).
The “no data” text can be exchanged at runtime. Use specific texts for different situations.
Avoid displaying a table without any items, especially when the app is initially loaded.

An empty smart table

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.

Table containing warnings

Table containing errors and warnings

Guidelines

To show that an item contains an error,

Highlight the row accordingly.
Add the string (contains errors) and place it at the bottom of the column that identifies the line item (responsive table) or in the Editing Status column (all other tables).

Developer Hint

Binding-related messages are shown automatically.

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.

Guidelines

If used with the responsive table, enable the pop-in behavior (sap.ui.comp.smarttable.SmartTable, property: demandPopin, value: true). Ensure that the most important columns stay in the tabular layout as long as possible (annotation: UI.Importance). The most important columns are those that contain the following information:

The column that identifies the line item.
The column that contains the key attribute.

Developer Hint

To change the layout of the pop-in area (Block, GridSmall, GridLarge), you need to create a responsive table with the corresponding settings (property: popinLayout). You do not need to define anything else. Hand this responsive table over to the smart table. The smart table then takes care of the rest (such as adding columns, and so on).
Do not use the annotation UI.Importance together with the grid table, tree table, or analytical table. It hides columns with low priority on phones or narrow-width screens, without the possibility to show them again.

Examples

Responsive table within a smart table

Grid table within a smart table

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.

Intro

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).

The components of a smart table

Table Toolbar

Toolbar with all features provided by the smart table out-of-the-box

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

Title
Item counter
Variant management
Show Details / Hide Details
View Settings
Export to Spreadsheet
Maximize / Minimize

In addition, you can add app-specific actions.

Title

Displaying a title is optional (property: header).

Guidelines

Add a title whenever the title is not indicated in the surrounding area.
If you don’t display a title, ensure that you still provide a table title for screen reader users.

Developer Hint

Item Counter

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

Guidelines

Show the item counter together with the table title, unless:

You expect this to cause performance problems.
You use a responsive table and use the More button for loading additional items. Use the item counter on the More button instead.

Variant Management

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

Guidelines

Use variant management only if really needed.

Show Details / Hide Details

Details hidden

Details shown

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.

Guidelines

Offer view settings only if they are really needed. Tables with just a few columns and rows do not need to be sorted, filtered, or grouped.

Sort and Filter

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.

Guidelines

Do not turn off the info bar (property: useInfoBar).
In the default delivery, sort items in a meaningful order. This works only for the grid table, tree table, and analytical table. You can also provide default filter settings (all tables) and grouping (responsive table and analytical table only) (annotation:
PresentationVariant).
If the smart table is used together with a filter bar (property:
smartFilterId), do not offer filtering for the smart table itself.

Developer Hint

The smart table can be linked to a smart filter bar. If linked, the filter bar settings are automatically applied to the smart table (sap.ui.comp.smarttable,SmartTable, property: smartFilterId).

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.

Guidelines

Column Settings

Guidelines

If sorting, grouping, and/or filtering are needed, also show the column settings (sap.ui.comp.smarttable.SmartTable, property: useTablePersonalisation).

Developer Hint

Only offer column settings if you need more columns than a tablet screen can display at a time (usually more than five).

Export to Spreadsheet

Guidelines

Only offer the Export to Spreadsheet option if your end users typically export the data shown in the table to work with it in a spreadsheet application.
- This is usually the case if data is collected from several systems and analyzed in the spreadsheet application.
- This is not usually the case for worklists, attachment lists, tables with only a few items, shopping carts, or data that does not need to be analyzed.
If you offer the Export to Spreadsheet button, use the front-end export.
If your table has columns with non-textual content, provide a textual equivalent for those columns. Non-textual content is not exported.

Warning

With both methods, the file size is limited by the available browser memory. As a result, exporting large tables can lead to memory overflows and crash the export process.

Apply the following size restrictions as a rule-of-thumb:

For the front-end export, do not export more than 2 million table cells on desktop browsers or 100,000 table cells on tablets and phones.
For the back-end export, do not export more than 100,000 table cells.

For larger tables, consider using custom-built, specialized export solutions instead.

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).

Guidelines

Use Maximize / Minimize only if really needed.

App-Specific Actions

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

Developer Hint

If additional actions are needed, use a custom toolbar for the table. The smart table can also add integrated functionality, such as a table title, item counter, variant management, view settings, and export to spreadsheet to the custom toolbar (aggregation: customToolbar).
If you are using a custom toolbar in a responsive table, show the bottom border of the toolbar. For all other tables, do not show it (property: style, value: clear).
The property placeToolbarInTable adds the toolbar to the corresponding aggregation of the inner SAPUI5 table. In most cases, set this to “true”, especially when you are using the custom toolbar with the responsive table. Otherwise, the table toolbar cannot stick to the top of the surrounding layout container.

Infobar

Infobar with filter information

Guidelines

For the responsive table, the info bar is mandatory.
For all other tables, do not show the info bar.

Table

Responsive table within a smart 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).

Guidelines

The analytical table, tree table and grid table are not fully responsive. They are available only for desktops and tablets, so you will need to take an adaptive approach by offering an additional UI for smartphones.
For the responsive table, the smart table initially loads 20 items and shows a More button for loading additional items. Change this behavior if:
- You expect fewer than 200 items. Load all items from the start (sap.m.Table, property: growing).
- You expect more than 200 items. Adapt the number of items initially loaded to cater for large screens, and load additional items automatically when the user scrolls down (sap.m.Table, property: growingScrolllToLoad).

Developer Hint

The property tableBindingPath defines the path from which the data is fetched.
The property enableAutoBinding fetches the data automatically as soon as the corresponding OData model is initialized and the smart table is created.

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.

Developer Hint

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.

Developer Hint

If a column needs to be in the model but should not be shown, you can hide it from both the table and the P13n dialog (property: ignoredFields, annotation: UI.Hidden).

Use this option if:

A column is needed to provide an ID that is used for navigation purposes only. However, you only want to display the corresponding text on the UI, and not the ID.
The values of a column are needed to perform calculations, but only the results are shown on the UI.

The property ignoreFromPersonalization is only available with the analytical table. It loads additional key fields that are needed for aggregations but are never visible.

Developer Hint

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).

Guidelines

Keep the number of initially visible columns to a minimum. Avoid pop-in behavior (responsive table) or horizontal scrolling (all other tables) on a tablet screen size in the default delivery (annotation: PresentationVariant/ LineItem).
Also keep the number of additional columns offered in the personalization settings to a minimum. You can use the P13n dialog to let users show/hide the columns. Select the columns offered in the P13n dialog carefully. Do not just show all columns available in the backend tables (annotation: sap:visible, value: false).

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.

Developer Hint

If the same column is defined via LineItem and via DataFieldDefault, LineItem wins.

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.

Guidelines

Choose a column width that avoids truncation for the initial data and (if feasible) for the column header label. If the default column width doesn’t fit, change it.

Developer Hint

For the responsive table, enableAutoColumnWidth also applies the following changes:

The smart table property demandPopin is set to true.
The responsive table property fixedLayout is set to Strict.
The responsive table property contextualWidth is set to Auto.
Column resizing is enabled for all columns (including custom columns).
Labels in the column headers no longer wrap. If there is not enough space, they truncate.

In this case, the properties above must not be managed by the app.

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.

Responsive table with automatically calculated column widths, resizing, and remaining space

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.

Developer Hint

To add or override columns (“custom columns”):

Use an XML view to define the underlying table with just the columns to be added/overridden.
To override columns, provide the column key of the column you want to exchange.
Add this “unfinished” table to the smart table. The smart table adds all the automatically generated columns and additional features.

If you are using a responsive table, also make sure that the responsive behavior for this column works as expected (sap.m.Column, property: importance).

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.

Guidelines

Provide a column header text for each column. (annotation: sap:label).

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.

Guidelines

Offer column totals by default for all columns where totals make sense (annotation: PresentationVariant).

Developer Hint

To add a Freeze option manually, declare the corresponding table inside the smart table in the XML view, and use the corresponding settings for this inner table.

Clicking the column header reveals sort and filter options (responsive table)

Column header menu for a dimension column of an analytical table within a smart table

Column header menu for a measure column of an analytical table within a smart table

Content

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

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).
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

Developer Hint

From a performance perspective, using the smart field is more expensive than using the controls provided by the smart table directly. With this in mind, follow the rules below:

For read-only tables, use the controls provided by the smart table.
For simple editing cases with no need for FieldControl or value help on input fields, use the controls provided by the smart table.
For more complex editing cases, use smart fields.
For switching between read-only and edit modes:
- In read-only mode, use the controls provided by the smart table.
- In edit mode, use either smart fields or the controls provided by the smart table, based on the guidance above.

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

	Read-only	Edit	Annotations / Edm type	Comment
Static text	Text	Input field	Edm.String
Decimal numbers	Text	Input field	Precision, Scale, Edm.Byte, Edm.Decimal, Edm.Double, Edm.Int16, Edm.Int32, Edm.Int64, Edm.SByte, Edm.Single
Status information	Object status or Icon	Input field	Criticality, CriticalityType, CriticalityRepresentationType	Do not use editable status information.
Key identifier	Object identifier (responsive table) Text (all other tables)	Input field for the ID	SemanticKey, Common.EditableFieldFor
Text and ID	Text, object status, or object identifier	Input field for the ID	TextArrangement	Use together with the annotation mentioned above for static text, status information, or key identifier. Sorting, filtering, and grouping only works for the ID, even if the ID is not displayed.
Links with/without quick view	Smart link	Smart link	SemanticObject	Smart links can be customized using the aggregation: `semanticObjectController`
Dates	Text	Date picker	Edm.DateTime, sap:display-format, value: date, IsCalendarDate
Dates and times	Text	Date/time picker	Edm.DateTime, Edm.DateTimeOffset
Times	Text	Time picker	Edm.Time
Fiscal periods	Text	Input field	IsFiscalYear, IsFiscalPeriod, IsFiscalYearPeriod, IsFiscalQuarter, IsFiscalYearQuarter, IsFiscalWeek, IsFiscalYearWeek, IsDayOfFiscalYear
Amounts with currencies	Two text controls	Input field for the amount	sap:semantics, value: currency-code	In edit mode, the currency is shown as static text next to the input field.
Phone numbers	Link	Input field	IsPhoneNumber	Opens the system application for making phone calls.
Email	Link	Input field	IsEmailAddress	Opens the system application for writing emails.
Pictures	Image	Input field	IsImageURL	Only available for the responsive table. In edit mode, the input field contains the URL to the image.
Boolean	Text	Checkbox	Edm.Boolean	For read-only, the displayed text is Yes or No.

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

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

Guidelines

For inline actions, use a text-only or an icon-only button. Make sure the icon communicates the function clearly enough. Otherwise, use a text-only button.

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

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.

Guidelines

For all other cases, provide instructions on how to fill the table with data (aggregation: noData).
The “no data” text can be exchanged at runtime. Use specific texts for different situations.
Avoid displaying a table without any items, especially when the app is initially loaded.

An empty smart table

Errors and Warnings

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

Table containing warnings

Table containing errors and warnings

Guidelines

To show that an item contains an error,

Highlight the row accordingly.
Add the string (contains errors) and place it at the bottom of the column that identifies the line item (responsive table) or in the Editing Status column (all other tables).

Developer Hint

Binding-related messages are shown automatically.

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.

Guidelines

The column that identifies the line item.
The column that contains the key attribute.

Developer Hint

To change the layout of the pop-in area (Block, GridSmall, GridLarge), you need to create a responsive table with the corresponding settings (property: popinLayout). You do not need to define anything else. Hand this responsive table over to the smart table. The smart table then takes care of the rest (such as adding columns, and so on).
Do not use the annotation UI.Importance together with the grid table, tree table, or analytical table. It hides columns with low priority on phones or narrow-width screens, without the possibility to show them again.

Examples

Responsive table within a smart table

Grid table within a smart table

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.

When to Use

Use the smart field if:

You use an OData service for your app (OData version 2 only).
The feature set of the smart field fits your app. In this case, the smart field is faster to implement.
You use the smart table and your app is not performance-critical. The smart field offers more flexibility than the controls provided directly by the smart table, especially for editing.
You use a smart form.

Do not use the smart field if:

You use a different technology to OData version 2. Use the corresponding controls directly.
You need a different control for entering or displaying data, such as multi input, a multi combo box, step input, a radio button, or a title. In this case, use the corresponding control directly.
You need a different dialog for offering value help, such as the select dialog or table select dialog.
You use the smart table and your app is performance-critical. In this case, the controls offered directly by the smart table offer less flexibility but better performance.

Components

The smart field consists of a basic UI element and an optional label. The following UI elements are available:

Edit mode:

One or two input fields (with or without a value help dialog)
Select
Combo box
Text area
Checkbox
Date picker
Date/time picker
Time picker

Display mode:

For details, see the corresponding guideline topics.

User Input Control

The smart field chooses the control automatically based on the data type (Edm type) and annotations of the OData service and additional properties. The following controls are used:

	Read-Only	Edit	Edm Types / Annotations / Properties	Comment
Single-line text	Text	Input field	Edm.String Configuration: controlType, value: input
		Combo box	Edm.String Configuration: controlType, value: dropDownList
		Select	Edm.String Configuration: controlType, value: selection
Multi-line text	Text	Text area	Edm.String MultiLineText
Decimal numbers	Text Object number	One or two input fields (for number and unit)	Edm.Int16, Edm.Int32, Edm.Int64, Edm.SByte, Edm.Byte, Edm.Single, Edm.Float, Edm.Double, Edm.Decimal Precision, Scale
Status information	Object status		Edm.String criticality, criticalityRepresentationType
Text and ID	Text Object identifier Object status	Input field	TextArrangement controlProposal displayBehavior textInEditModeSource, sap:text, fetchValueListReadOnly	The following patterns can be selected via displayBehavior: Text (ID) ID (Text) Text ID
Links (with/without quick view)	Link Smart link		Edm.String IsURL, url semanticObjectController
Dates	Text	Date picker	Edm.DateTime sap:display-format=”Date” IsCalendarDate Configuration: controlType
Dates and times	Text	Date/time picker	Edm.DateTime Edm.DateTimeOffset
Times	Text	Time picker	Edm.Time
Fiscal periods	Text	Input field	IsFiscalYear, IsFiscalPeriod, IsFiscalYearPeriod, IsFiscalQuarter, IsFiscalYearQuarter, IsFiscalWeek, IsFiscalYearWeek, IsDayOfFiscalYear
Amounts with currencies	Text	One or two input fields	ISOCurrency or sap:unit with sap:semantics=”currency-code”
Phone numbers	Text	Input field	IsPhoneNumber
Email	Text	Input field	IsEmailAddress
Boolean	Checkbox	Checkbox	Edm.Boolean
Boolean	Text	Combo box	Edm.Boolean valueList displayBehavior	The text in display mode can be influenced via displayBehavior: Yes/No True/False On/Off

Guidelines

Set a default value whenever appropriate (annotation: text, property: value).
To show a static unit of measurement, use a description (annotation: text).
To display a text and ID in the same place, use the format Text (ID) wherever possible. Use another format only if displaying the text doesn’t make any sense. Be careful when using the text arrangement options in tables: end users will only be able to sort, group, or filter based on the ID, even if the ID isn’t visible.
If you are not using the smart field within a smart form or smart table, label the smart field with a smart label (annotation: label, properties: textLabel, showLabel). The standard label doesn’t know the inner structure of a smart field.
You can set a tooltip (annotation: QuickInfo), but this should usually be avoided. See Using Tooltips.
If data entry is expected in a specific format, set a placeholder (property: Placeholder).

Developer Hint

Performance: Using the TextArrangement annotation to display both the text and ID (in any order) triggers two requests to the back end.

Behavior and Interaction

Context

You can use the smart field in different contexts
(property: controlContext):

Standalone
Within a form (depending on the form layout)
Within a table (depending on the table type)

The context influences:

Labels: In most cases, forms provide the label automatically.
Empty values in display mode: In forms, empty values are shown as a dash. In tables, the field remains blank. In popins, empty values are shown as a dash because the popin is similar to a form in a table.
How units of measurement are displayed

Guidelines

If the width is not handled by the context, set a meaningful width for the smart field, based on the expected data (property: Width).
If you use a “standalone” smart field in a form-like arrangement, use a dash to show an empty value in display mode.

Switching Between Edit and Display Mode

Switching between edit and display mode can be controlled manually (annotation: FieldControl, property: editable) or automatically by the containing smart form or smart table (property: contextEditable).

Smart field as a select with 'required' indicator in edit mode

The same smart field in display mode

Guidelines

Define which fields should be editable (annotations: updateable, creatable, updateable-path, InsertRestrictions, UpdateRestrictions, computed, immutable, fieldControl, fieldControlType).
For fields with a unit of measurement, define whether the unit of measurement is editable or static (annotation: FieldControl, property: uomEditable).
Make sure that the full text is shown in display mode (property: wrapping), unless this is handled differently for the corresponding context (for example, see guidelines for content in the grid table).
When you display the text and ID, the smart field automatically displays both values in display mode, but only the ID in edit mode (annotation: TextArrangement). In most cases, it makes sense to also display both values in edit mode (annotation: sap:text, property: textInEditModeSource, aggregation: Configuration with property: displayBehavior).

Suggestions and Value Help

You can enable suggestions for controls that offer this feature (property: showSuggestions). The list of suggestible values must be provided (annotation: ValueList or ValueListWithFixedValues only for Edm.String, property: entitySet). This list can contain several attributes and is also used for the value help dialog. You can restrict the number of attributes from this list to be shown as suggestions, while all attributes are shown within the value help dialog.

Autocomplete is enabled automatically.

For input fields, the value help dialog is also created automatically. Hide it if it is not needed (property: showValueHelp). The table in the value help dialog can be filled with initial content (annotation: ValueList, property: fetchValues, sap.ui.comp.smartfield.Configuration, property: preventInitialDataFetchInValueHelpDialog)

Both the value help dialog and the suggestion list can be prefiltered (annotation: ValueList, property: valueListParameterIn). The selected items can be used to prefilter other fields (annotation: ValueList, property: ValueListParameterOut). The corresponding filter settings are visible. “Invisible” prefiltering is also supported. To use this option, provide the exact matching filter value (Common.ValueListParameterConstant).

If a value has been entered in the smart field, this value is transferred to the search field of the value help dialog automatically. In the value help dialog, individual values can be valid, deprecated, or revoked. Revoked values are hidden from the value help (annotation: IsConfigurationDeprecationCode).

The following controls are used to offer suggestions or value help:

A fixed value list leads to a combo box or select, depending on the control configuration.
A non-fixed value list leads to an input field with a value help dialog.

Smart field as a combo box

Smart field as an input field with suggestions, auto complete, and a value help button

The automatically generated value help dialog for the same smart field

Recently Used Values

Input fields, combo boxes, and selects can provide up to five recently used values automatically on focus if suggestions or value help are available. This can be turned on or off per field (property: historyEnabled). Recently used values are shown by default for input fields, but not for combo boxes and selects.

Guidelines

Do not show recently used values for a field if:

There are only a small number of options.
The field contains personal sensitive data (annotation: IsPotentiallySensitive).
It is unlikely that the same values will be selected again and again.

Recommended Values

In addition to recently used values, a smart field can show recommended values (annotation: RecommendationState).

The corresponding smart field is highlighted and/or prefilled:

If no recommendation is available or the current user input matches the recommendation, the smart field is shown in the default state.
If a recommendation is available and there is no user input, the smart field is shown in the information state.
If a recommendation is available and it differs from the current user input, the smart field is displayed in the warning state.

The recommended values are shown as soon as the user focuses on the smart field.

Validation

The smart field offers the following validations automatically:

Validation for required fields: This can be done on the client or server side (property: clientSideMandatoryCheck, annotation: Nullable).
Validation for a group of fields: Validation is triggered when the focus moves outside a group of fields, rather than when a single field loses the focus. A group is defined by all smart fields that share the same field group ID (property: fieldGroupIds).
Validation for the maximum length of user input: Validation is triggered when a field loses the focus or the ENTER key is pressed (property: maxLength).
Validation for combo boxes: Checks if the value entered is available in the dropdown list (property: fixedValueListValidationEnabled).

The validation result is indicated by a value state (property: showValueStateMessage).

When the user edits a smart field showing a text and ID, you can allow any kind of input to avoid unnecessary validation issues (annotation: ValueListNoValidation).

Examples:

Allowing the user to enter additional values (which are not in the suggestion list)
Typing a text instead of an ID to filter down the suggestion list
Using the smart field in a draft

Automatic validation

IDs

The smart field offers automatic validation for number-only ID fields (annotations: IsDigitSequence or sap:display-format="NonNegative"):

It checks for non-negative numbers.
It shows values containing only “0” digits as empty.
It does not show leading zeros.

Units

For decimal number fields and for fields that show an amount with a currency, you can add a unit of measure (annotations: unit, sap-unit with sap:semantics="unit-of-measure" or sap:semantics="currency-code", property: uomVisible). In display mode, the unit is added to the corresponding number. In edit mode, the unit is shown either as text or, if editable, as a second input field (properties: uomEditable, uomEnabled).

Smart field showing an amount with a currency in display mode

The same smart field in display mode

Sensitive Data

Sensitive data, such as passwords, can be masked. The text is then replaced with asterisks (annotations: IsPotentiallySensitive, masked).

Capitalizing Text Input

Text input can be capitalized automatically (property: IsUpperCase).

States

Smart fields support the following states (annotation: fieldControl):

Editable or display only (additional annotations: updateable, creatable, updatable-path, InsertRestrictions, UpdateRestrictions, property: editable)
Enabled or disabled
Visible or hidden (additional annotations: property: visible, annotation: sap:visible)
Required: If set, the smart field must contain a value when validated. This is indicated by an asterisk next to the corresponding label (additional annotation: Nullable, property: mandatory).

The following states for a unit of measurement can be set independently of the corresponding field:

If editable, a unit of measurement can be enabled or disabled (property: uomEnabled)
The unit of measurement can be visible or hidden (property: uomVisible)

Developer Hint

In the SAPUI5 SDK API Reference for the smart field, the display only state is referred to as read only.

Dependencies between Smart Fields

If the content of a smart field is changed, you can trigger additional changes to other fields on the UI (annotation: SideEffects).

Content Alignment

You can change the horizontal alignment of the text within any kind of input field (property: textAlign).

Guidelines

Follow the alignment rules for the respective context (responsive table, other tables, form). If you are using the standalone option for the smart field (without a context), apply the rules for the corresponding input fields.

Responsiveness

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

Top Tips

Always label a smart field if it is not inside a table context.
Use suggestions with autocomplete whenever possible and meaningful.
- Do not show suggestions if there are only a few choices.
- Use recently used values as appropriate.
- Reduce the number of attributes shown in the suggestion list to a maximum of 4 or 5.
Make use of validation features.

Properties

The following properties, aggregations, and associations are available for sap.ui.comp.smartfield.SmartField:

The property: expandNavigationProperties is deprecated. Do not use it.
The property: importance hides the field if the smart field is placed in a smart form, depending on the importance setting of the smart form. End users have no possibility to show the corresponding fields again. Do not use this property.
The property: jsontype is deprecated. Do not use it.
The property: name is used in HTML forms that send data to the server via “Submit”.
The property: uomEditState is for internal use only. Do not use it.
The property: proposedControl is deprecated. Do not use it.
The property: textDirection provides support for reading directions in different locales.
The aggregation: controlProposal is deprecated. Do not use it.
The association: ariaLabelledBy can be used for linking additional labels to the smart field.

Usage

Use the dynamic date control if:

You need flexibility between fixed and dynamic dates.
You need dynamic dates that can be saved in the variant management (for example, show values from today regardless of when you open the app).
You are using the smart filter bar.
The user only needs to select one value.

Do not use the dynamic date control if:

Users need to enter a date and a time. In this case, use the date picker or the date/time picker instead.
Selecting ranges is not the user’s primary goal. In this case, use the simple date picker.
You are not using the smart filter bar.
You want to offer dynamic date range selection outside the smart filter bar (for example, in a table toolbar). Use the dynamic date range control instead.

Responsiveness

The dynamic date control is fully responsive. It provides a touch-friendly screen in sizes S and M (cozy mode) and is smaller in size L (compact mode). For more information on cozy and compact modes, see the article on content density.

Value help for dynamic date range – Size S

Value help for dynamic date range – Size L

Components

The two clickable areas of the dynamic date control

The dynamic date consists of two components:
(A) Date input field with suggestions
(B) Value help popover

On all devices, users can either use the input field to type a date, or use the value help button to open the popover.

Dynamic Date Input Field

The user can type data directly into the input field. Upon user input, a list of suggestions appears.

Value Help Popover

The value help popover offers all available values the user can choose from. Depending on the selected time period, the popover shows different controls. It either shows:
(A) An input field
(B) One or two date pickers
(C) A read-only text with the chosen date range
(D) A select control

Value help popover – Input field

Value help popover – Date pickers

Value help popover – Read only

Value help popover – Select control

Values Offered

From
To
Date Range
Today
Today -X / +Y days
Last X days
Next X days
This week
Last week
Last X weeks

Offered Values

Next week
Next X weeks
Month
This month
Last month
Last X months
Next X months
This quarter
Last quarter
Last X quarters
Next quarter

Offered Values

Next X quarters
First quarter
Second quarter
Third quarter
Fourth quarter
This year
Last year
Last X years
Next year
Next X years
Year to date

Behavior & Interaction

Typing data into the date range input field

The user can type keywords or numbers into the date range input field. For example, if the user types a number, the system automatically suggests possible dates. All dynamic dates show the actual dates to help the user select the right value.

List of suggestions shown after typed input

Opening the value help and selecting a time period

Clicking the value help icon opens a popover with additional options for defining the time period. The user can choose from several time periods by clicking the down arrow in the select control. Once a time period has been chosen, the selection box closes.

Opening the value help popover and selecting a time period

Defining a custom time period (X)

If the user selects a custom time period with “X”, such as Last X days, the control shows a simple input field for entering the number. The text in the date input field changes according to the user’s input.

Custom time period with a simple input field

Selecting a date range

If the user selects a time period that requires input of a start and end date, two date pickers appear. These can be opened by clicking the calendar icon. The text in the date range input field changes according to the user’s input.

Selected time period with two date pickers (start date and end date)

Styles

Validation

Use inline validation to give the user feedback, especially for errors and warnings. The possible states are “warning”, “error”, and “success”.

The dynamic date input field in question is highlighted by a frame in the corresponding color. If the focus is inside the field, an explanation is shown. Ensure that this explanation is as specific as possible.

Visible frame that shows an error when the field is out of focus

Error state with meaningful text – The date range input field is in focus

Guidelines

See the Date Picker and Date Range Selection articles for the guidelines. They also apply to the dynamic date control.

List of Options

Only provide values that are relevant for the use case in the list of options.
You can also add your own values, if necessary.
If you use your own values, provide human readable text.

Resources

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

Elements and Controls

Date Picker (guidelines)
Input Field (guidelines)
Select (guidelines)

Implementation

Date Picker (SAPUI5 samples)
Input (SAPUI5 samples)
Select (SAPUI5 samples)
Smart Controls (SAPUI5 samples)

Smart Filter Bar (SAPUI5 API reference)

Smart Link

Intro

Like the quick view, the smart link triggers a popover from a text link. This popover shows additional information, such as simple object details, and offers links to related apps for the user to take action. The user can choose which links are shown in the popover by selecting them in a separate dialog.
The smart link is a smart control that uses metadata annotations to offer user-specific navigation. It analyzes the user’s assigned apps and offers only relevant navigation targets.

When to Use

Use the smart link if:

You want to offer direct navigation to a related app. For example:

Navigate from a product list to the app for changing the pricing
Navigate from a sales order list to the app that shows a customer’s balance

You want to show a popover with contextual information or navigation. For example:

Offer navigation to multiple related apps
Display simple object details

Do not use the smart link if:

You want to display more or complex information about an object. Use the object page or charts instead.
Access to metadata is not possible, and only a direct link to a website, document or application is needed. Use the standard link instead.
You need to structure information in a deeper hierarchy. Use the quick view or a list drilldown instead.

Components

The smart link popover contains the following areas:

The header bar of the smart link popover is only visible on mobile devices (see example image for responsiveness, size S).
The title area contains a title and a subtitle. You can also show the title as a link, which can be used to navigate to the corresponding object or fact sheet. You can use the subtitle to show an object ID, for example.
The content area shows object-related information, such as details about a product or contact information. You can use any UI control, based on what best fits your use case.
The link area offers links to all other apps that are relevant for a user role. The link list includes all semantic objects defined for the app, and can also include additional links defined manually by the application development team. The link area can have two states:

Link area is empty:
If no links have been selected for the app, or if there are more than 10 links, the link area is initially empty. Instead, the user sees a Define Links button, which opens a dialog for selecting the links to be shown.

Links are shown:
As soon as the link area contains links, the button text changes to More Links. This opens the same selection dialog.

Only the header bar is mandatory (for mobile devices). All the other sections are optional. For example, you might choose to show only a content area or a only a link area, depending on your use case.

The areas of the smart link (header bar not shown)

Behavior and Interaction

The smart link and its popover are always triggered by clicking a text element that appears as a link. You can place this text element in any list, table, or other container. You can also set the link label individually. Clicking outside the popover closes it. If only one link is offered, and there is no additional information, the smart link control navigates directly to the target without opening the popover.

If the semantic object annotation is not set, the smart link is rendered as sap.m.Text by default. However, you can also opt to render any other control.

Link Selection Dialog

Clicking the More Links or Define Links button opens the Define Link List dialog. There, the user can select the app links to be displayed in the link area. The links offered in the selection list are modifiable semantic objects suggested by the smart link control. The app team can remove links from the selection list, change the link texts, or manually add links to any website or app.

Exception: Within SAP Fiori elements, the links offered in the Define Link List dialog are generated automatically. App teams cannot adapt the list.

You can switch off the More Links / Define Links option by setting the property enableAvailableActionsPersonalization to “false”. By default, it is set to “true”.

Smart Links in a Smart Table

Within a smart table, the link label of the smart link is set automatically using the semantic object annotation. In other words, you can’t change the description. If there are no navigation targets, the smart link is rendered as sap.m.Text.

Define link list dialog with a list of application links

Responsiveness

The responsiveness of the smart link is based on the responsiveness of the popover that overlays the content.

On desktop devices, clicking anywhere outside the popover closes it.

On mobile devices, the smart link opens a full screen dialog with a Close icon () on the top right.

Size S – On smartphones, the smart link overlays the content

Sizes M/L/XL - Smart link shown in a table on a desktop device

Top Tips

Check the related apps you offer carefully. Only display those that are relevant for the user.
Use meaningful link names in the link area. Do not use the same link name more than once. If necessary, rename the links to suit your context (for example, “Add Product” instead of “Manage Products”).

Intro

When to Use

Use the smart link if:

You want to offer direct navigation to a related app. For example:

Navigate from a product list to the app for changing the pricing
Navigate from a sales order list to the app that shows a customer’s balance

You want to show a popover with contextual information or navigation. For example:

Offer navigation to multiple related apps
Display simple object details

Do not use the smart link if:

You want to display more or complex information about an object. Use the object page or charts instead.
Access to metadata is not possible, and only a direct link to a website, document or application is needed. Use the standard link instead.
You need to structure information in a deeper hierarchy. Use the quick view or a list drilldown instead.

Components

The smart link popover contains the following areas:

The header bar of the smart link popover is only visible on mobile devices (see example image for responsiveness, size S).
The title area contains a title and a subtitle. You can also show the title as a link, which can be used to navigate to the corresponding object or fact sheet. You can use the subtitle to show an object ID, for example.
The content area shows object-related information, such as details about a product or contact information. You can use any UI control, based on what best fits your use case.
The link area offers links to all other apps that are relevant for a user role. The link list includes all semantic objects defined for the app, and can also include additional links defined manually by the application development team. The link area can have two states:

Links are shown:
As soon as the link area contains links, the button text changes to More Links. This opens the same selection dialog.

The areas of the smart link (header bar not shown)

Behavior and Interaction

If the semantic object annotation is not set, the smart link is rendered as sap.m.Text by default. However, you can also opt to render any other control.

Link Selection Dialog

Exception: Within SAP Fiori elements, the links offered in the Define Link List dialog are generated automatically. App teams cannot adapt the list.

You can switch off the More Links / Define Links option by setting the property enableAvailableActionsPersonalization to “false”. By default, it is set to “true”.

Smart Links in a Smart Table

Define link list dialog with a list of application links

Responsiveness

The responsiveness of the smart link is based on the responsiveness of the popover that overlays the content.

On desktop devices, clicking anywhere outside the popover closes it.

On mobile devices, the smart link opens a full screen dialog with a Close icon () on the top right.

Size S – On smartphones, the smart link overlays the content

Sizes M/L/XL - Smart link shown in a table on a desktop device

Top Tips

Check the related apps you offer carefully. Only display those that are relevant for the user.
Use meaningful link names in the link area. Do not use the same link name more than once. If necessary, rename the links to suit your context (for example, “Add Product” instead of “Manage Products”).

Check the related apps you offer carefully. Only display those that are relevant for the user.
Use meaningful link names in the link area. Do not use the same link name more than once. If necessary, rename the links to suit your context (for example, “Add Product” instead of “Manage Products”).

When to Use

Use the smart form if:

You use an OData service for your app (OData version 2 only).
You are using only (or primarily) smart fields inside your form. In this case, the smart form is faster to implement.

Do not use the smart form if:

You use a different technology to OData version 2. Use the form or simple form.
You need several other controls in your form that are not provided by the smart field, such as buttons, progress indicators, or sliders. In this case, use the form or simple form.
You just want to display a few fields within a very strict layout (such as in the object page header facets). In this case, use layout containers for placing the controls.
You want to place several input fields in one column of the responsive table. In this case, use layout containers for placing the controls.

Components

The smart form consists of a toolbar and a form.

Toolbar

The following options are provided:

Expand/collapse button
Title
App-specific actions

Expand/Collapse Button

The expand/collapse button is optional (properties: expandable,
expanded). It shows or hides the form.

Expanded smart form

Collapsed smart form

Guidelines

Do not use the expand/collapse button in object pages.
Even in other places, it is not usually recommended.

Title

The title is optional (property: title).

App-Specific Actions

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

Guidelines

For custom actions, follow the guidelines for object handling.

Developer Hint

The smart form can add its title to the custom toolbar.

Form

The form consists of form groups (sap.ui.comp.smartform.Group) and a layout.

Form Groups

Each form group comes with:

A title
One or several form elements and/or semantic form elements

Form elements (sap.ui.comp.smartform.GroupElement) consist of a label and one or several UI elements. If smart fields are used, the label is automatically provided by the corresponding metadata. If more than one smart field is used, define which label to display (GroupElement, property: elementForLabel).

The semantic form element (sap.ui.comp.smartform.SemanticGroupSlement) provides additional support when more than one control is attached to a single label. In display mode, the corresponding texts are displayed as a single value and therefore use less space. You can define a delimiter, which is shown between the fields.

A semantic form element in edit mode

The same semantic form element in display mode

Guidelines

When using more than one control in a form element, consider the semantic form element. In most cases, it will be the better choice.

Developer Hint

Ideally, use only smart fields.
If this is not possible, use only controls that implement theIFormContent interface . Other controls could damage the visual layout, keyboard support, and screen reader support.

Layout

The layout defines how the form groups and form elements are placed on the screen, depending on the available width (aggregation: layout). There are two layout options: column layout and responsive grid layout.

Guidelines

Always use the column layout.
If using a smart form on an object page, additional guidelines apply.

Behavior and Interaction

Display and Edit Mode

In display mode, the line height for each row is reduced (property: editable). This results in less white space between two lines of text. This setting is passed to all smart fields inside the smart form, which then also switch automatically.

Developer Hint

Controls other than the smart field need to be adapted manually.

Validation

The smart form offers two validation modes: standard and asynchronous (property: validationMode). The standard validation mode works only for smart fields and only with synchronous validation.

Developer Hint

Always use the asynchronous mode: it works for all form elements, not only for smart fields.

Responsiveness

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

Size S

Size M

Size L

Size XL

Example

Smart form in edit mode

The same smart form in display mode

Top Tips

Use smart fields wherever it makes sense.
Use the column layout.
When using one label for several controls, consider the semantic form element.

Properties

The following properties are available for sap.ui.comp.smartform.SmartForm:

The property: checkButton adds a button labeled Check to the toolbar. The button triggers front-end validation on available smart fields. Do not use it. Follow the guidelines for form field validation instead.
The property: editToggable adds an icon-only button to the toolbar, which switches the editable property. Do not use it. Follow the guidelines for object handling instead.
The property: entityType is used for key user adaptations.
The property: flexEnabled is used for key user adaptations.
The property: horizontalLayoutGroupElementMinWidth only works with the horizontal layout, which is deprecated. Do not use it. Use the column layout instead.
The property: ignoredFields is used for key user adaptations.
The property: importance hides all smart fields with lower importance. Do not use it.
The property: useHorizontalLayout only works with the horizontal layout, which is deprecated. Use the column layout instead.

The following properties are available for sap.ui.comp.smartform.Group:

The property: horizontalLayoutGroupElementMinWidth only works with the horizontal layout, which is deprecated. Use the column layout instead.
The property: label is deprecated. Use the aggregation: title instead.
The property: useHorizontalLayout only works with the horizontal layout, which is deprecated. Use the column layout instead.
The aggregation: layout is deprecated. Use the aggregation: layoutData instead.

When to Use

You can use the smart list if you use an OData service for your app (OData version 2 only).

For detailed recommendations on when to use a list or a tree, see the corresponding guideline articles:

Components

The smart list control consists of an overflow toolbar (1) in combination with either the list control (2) or the tree control (3).

Smart list used as a list:

(1) An overflow toolbar on the top
(2) List control below

List components

Smart list used as a tree:

(1) An overflow toolbar on the top
(3) Tree control below

Tree components

Behavior and Interaction

The individual controls mentioned in the Components section behave exactly as they would on their own.

For more information, see the respective guidelines:

Responsiveness

Both smart list variants are responsive. Each embedded control behaves as specified.

The following schematic examples show how list and tree use cases appear on different devices.

Responsive list - Size S

Responsive list - Size M

Responsive list - Size L

Responsive tree - Size S

Responsive tree - Size M

Responsive tree - Size L

For more information, see the respective guidelines:

Top Tips

List or tree? What you should consider

Due to their one-dimensional layout, lists are much easier for users to grasp than trees. First consider if you can use a list to present your data. Only use a tree if your data requires a hierarchy. Make sure that the nodes are clearly labeled and that information is not nested too deeply.

Developer Hint

The listType property controls whether the smart list presents itself as a list or tree. It must be appended by either List or Tree to work.

More guidelines and tips for each component of the smart list

Guidelines and tips for toolbars
Guidelines and tips for lists
Guidelines and tips for trees

When to Use

Use the smart field if:

You use an OData service for your app (OData version 2 only).
The feature set of the smart field fits your app. In this case, the smart field is faster to implement.
You use the smart table and your app is not performance-critical. The smart field offers more flexibility than the controls provided directly by the smart table, especially for editing.
You use a smart form.

Do not use the smart field if:

You use a different technology to OData version 2. Use the corresponding controls directly.
You need a different control for entering or displaying data, such as multi input, a multi combo box, step input, a radio button, or a title. In this case, use the corresponding control directly.
You need a different dialog for offering value help, such as the select dialog or table select dialog.
You use the smart table and your app is performance-critical. In this case, the controls offered directly by the smart table offer less flexibility but better performance.

Components

The smart field consists of a basic UI element and an optional label. The following UI elements are available:

Edit mode:

One or two input fields (with or without a value help dialog)
Select
Combo box
Text area
Checkbox
Date picker
Date/time picker
Time picker

Display mode:

For details, see the corresponding guideline topics.

User Input Control

The smart field chooses the control automatically based on the data type (Edm type) and annotations of the OData service and additional properties. The following controls are used:

	Read-Only	Edit	Edm Types / Annotations / Properties	Comment
Single-line text	Text	Input field	Edm.String Configuration: controlType, value: input
		Combo box	Edm.String Configuration: controlType, value: dropDownList
		Select	Edm.String Configuration: controlType, value: selection
Multi-line text	Text	Text area	Edm.String MultiLineText
Decimal numbers	Text Object number	One or two input fields (for number and unit)	Edm.Int16, Edm.Int32, Edm.Int64, Edm.SByte, Edm.Byte, Edm.Single, Edm.Float, Edm.Double, Edm.Decimal Precision, Scale
Status information	Object status		Edm.String criticality, criticalityRepresentationType
Text and ID	Text Object identifier Object status	Input field	TextArrangement controlProposal displayBehavior textInEditModeSource, sap:text, fetchValueListReadOnly	The following patterns can be selected via displayBehavior: Text (ID) ID (Text) Text ID
Links (with/without quick view)	Link Smart link		Edm.String IsURL, url semanticObjectController
Dates	Text	Date picker	Edm.DateTime sap:display-format=”Date” IsCalendarDate Configuration: controlType
Dates and times	Text	Date/time picker	Edm.DateTime Edm.DateTimeOffset
Times	Text	Time picker	Edm.Time
Fiscal periods	Text	Input field	IsFiscalYear, IsFiscalPeriod, IsFiscalYearPeriod, IsFiscalQuarter, IsFiscalYearQuarter, IsFiscalWeek, IsFiscalYearWeek, IsDayOfFiscalYear
Amounts with currencies	Text	One or two input fields	ISOCurrency or sap:unit with sap:semantics=”currency-code”
Phone numbers	Text	Input field	IsPhoneNumber
Email	Text	Input field	IsEmailAddress
Boolean	Checkbox	Checkbox	Edm.Boolean
Boolean	Text	Combo box	Edm.Boolean valueList displayBehavior	The text in display mode can be influenced via displayBehavior: Yes/No True/False On/Off

Guidelines

Set a default value whenever appropriate (annotation: text, property: value).
To show a static unit of measurement, use a description (annotation: text).
To display a text and ID in the same place, use the format Text (ID) wherever possible. Use another format only if displaying the text doesn’t make any sense. Be careful when using the text arrangement options in tables: end users will only be able to sort, group, or filter based on the ID, even if the ID isn’t visible.
If you are not using the smart field within a smart form or smart table, label the smart field with a smart label (annotation: label, properties: textLabel, showLabel). The standard label doesn’t know the inner structure of a smart field.
You can set a tooltip (annotation: QuickInfo), but this should usually be avoided. See Using Tooltips.
If data entry is expected in a specific format, set a placeholder (property: Placeholder).

Developer Hint

Performance: Using the TextArrangement annotation to display both the text and ID (in any order) triggers two requests to the back end.

Behavior and Interaction

Context

You can use the smart field in different contexts
(property: controlContext):

Standalone
Within a form (depending on the form layout)
Within a table (depending on the table type)

The context influences:

Labels: In most cases, forms provide the label automatically.
Empty values in display mode: In forms, empty values are shown as a dash. In tables, the field remains blank.
How units of measurement are displayed

Guidelines

If the width is not handled by the context, set a meaningful width for the smart field, based on the expected data (property: Width).
If you use a “standalone” smart field in a form-like arrangement, use a dash to show an empty value in display mode.

Switching Between Edit and Display Mode

Smart field as a select with 'required' indicator in edit mode

The same smart field in display mode

Guidelines

Define which fields should be editable (annotations: updateable, creatable, updateable-path, InsertRestrictions, UpdateRestrictions, computed, immutable, fieldControl, fieldControlType).
For fields with a unit of measurement, define whether the unit of measurement is editable or static (annotation: FieldControl, property: uomEditable).
Make sure that the full text is shown in display mode (property: wrapping), unless this is handled differently for the corresponding context (for example, see guidelines for content in the grid table).
When you display the text and ID, the smart field automatically displays both values in display mode, but only the ID in edit mode (annotation: TextArrangement). In most cases, it makes sense to also display both values in edit mode (annotation: sap:text, property: textInEditModeSource, aggregation: Configuration with property: displayBehavior).

Suggestions and Value Help

Autocomplete is enabled automatically.

The following controls are used to offer suggestions or value help:

A fixed value list leads to a combo box or select, depending on the control configuration.
A non-fixed value list leads to an input field with a value help dialog.

Smart field as a combo box

Smart field as an input field with suggestions, auto complete, and a value help button

The automatically generated value help dialog for the same smart field

Recently Used Values

Guidelines

Do not show recently used values for a field if:

There are only a small number of options.
The field contains personal sensitive data (annotation: IsPotentiallySensitive).
It is unlikely that the same values will be selected again and again.

Recommended Values

In addition to recently used values, a smart field can show recommended values (annotation: RecommendationState).

The corresponding smart field is highlighted and/or prefilled:

If no recommendation is available or the current user input matches the recommendation, the smart field is shown in the default state.
If a recommendation is available and there is no user input, the smart field is shown in the information state.
If a recommendation is available and it differs from the current user input, the smart field is displayed in the warning state.

The recommended values are shown as soon as the user focuses on the smart field.

Validation

The smart field offers the following validations automatically:

Validation for required fields: This can be done on the client or server side (property: clientSideMandatoryCheck, annotation: Nullable).
Validation for a group of fields: Validation is triggered when the focus moves outside a group of fields, rather than when a single field loses the focus. A group is defined by all smart fields that share the same field group ID (property: fieldGroupIds).
Validation for the maximum length of user input: Validation is triggered when a field loses the focus or the ENTER key is pressed (property: maxLength).
Validation for combo boxes: Checks if the value entered is available in the dropdown list (property: fixedValueListValidationEnabled).

The validation result is indicated by a value state (property: showValueStateMessage).

When the user edits a smart field showing a text and ID, you can allow any kind of input to avoid unnecessary validation issues (annotation: ValueListNoValidation).

Examples:

Allowing the user to enter additional values (which are not in the suggestion list)
Typing a text instead of an ID to filter down the suggestion list
Using the smart field in a draft

Automatic validation

IDs

The smart field offers automatic validation for number-only ID fields (annotations: IsDigitSequence or sap:display-format="NonNegative"):

It checks for non-negative numbers.
It shows values containing only “0” digits as empty.
It does not show leading zeros.

Units

Smart field showing an amount with a currency in display mode

The same smart field in display mode

Sensitive Data

Sensitive data, such as passwords, can be masked. The text is then replaced with asterisks (annotations: IsPotentiallySensitive, masked).

Capitalizing Text Input

Text input can be capitalized automatically (property: IsUpperCase).

States

Smart fields support the following states (annotation: fieldControl):

Editable or display only (additional annotations: updateable, creatable, updatable-path, InsertRestrictions, UpdateRestrictions, property: editable)
Enabled or disabled
Visible or hidden (additional annotations: property: visible, annotation: sap:visible)
Required: If set, the smart field must contain a value when validated. This is indicated by an asterisk next to the corresponding label (additional annotation: Nullable, property: mandatory).

The following states for a unit of measurement can be set independently of the corresponding field:

If editable, a unit of measurement can be enabled or disabled (property: uomEnabled)
The unit of measurement can be visible or hidden (property: uomVisible)

Developer Hint

In the SAPUI5 SDK API Reference for the smart field, the display only state is referred to as read only.

Dependencies between Smart Fields

If the content of a smart field is changed, you can trigger additional changes to other fields on the UI (annotation: SideEffects).

Content Alignment

You can change the horizontal alignment of the text within any kind of input field (property: textAlign).

Guidelines

Responsiveness

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

Top Tips

Always label a smart field if it is not inside a table context.
Use suggestions with autocomplete whenever possible and meaningful.
- Do not show suggestions if there are only a few choices.
- Use recently used values as appropriate.
- Reduce the number of attributes shown in the suggestion list to a maximum of 4 or 5.
Make use of validation features.

Properties

The following properties, aggregations, and associations are available for sap.ui.comp.smartfield.SmartField:

The property: expandNavigationProperties is experimental. Do not use it.
The property: importance hides the field if the smart field is placed in a smart form, depending on the importance setting of the smart form. End users have no possibility to show the corresponding fields again. Do not use this property.
The property: jsontype is deprecated. Do not use it.
The property: name is used in HTML forms that send data to the server via “Submit”.
The property: uomEditState is for internal use only. Do not use it.
The property: proposedControl is deprecated. Do not use it.
The property: textDirection provides support for reading directions in different locales.
The aggregation: controlProposal is deprecated. Do not use it.
The association: ariaLabelledBy can be used for linking additional labels to the smart field.

Intro

Information

This article is intended as an aid to designers and developers who want to explore the detail configuration options available for the smart filter bar.

The smart filter bar uses annotations to create a filter bar. It’s a wrapper that analyzes a given OData service and renders a filter bar based on the content defined by the service. For example, the OData service determines whether a field is visible on the filter bar, and whether it supports type-ahead and value help. To configure more settings or overwrite the settings from the OData service, the developer can set additional annotations in an external document (metadata.xml).

The developer can use annotation properties in the classes ControlConfiguration and GroupConfiguration to adapt the filter bar for the purposes of the app.

These annotations let you:

Determine the type of control (for example, whether a field is shown as a multi-input field or as a date picker)
Enable the autocomplete suggestions feature
Enable the value help dialog
Overwrite settings from the OData service
Set custom filter groups
Add custom fields
Access all settings for the underlying filter bar

You can also use all the configuration options described here in the smart filter bar for the list report SAP Fiori element.

Warning

Most of the attributes/properties are not dynamic and cannot be changed once the control has been initialized.

Usage

Use the smart filter bar if:

An OData service is available.
You want to develop quickly and efficiently.

Do not use the smart filter bar if:

You need to make extensive changes to the filter bar.

Components

You can use the annotation properties listed below to influence how filters are rendered in the expanded filter bar and in the filter dialog.

Expanded Filter Bar

Properties of the expanded filter bar

1 enableBasicSearch
Defines whether the filter bar includes a basic search. By default, the basic search is not included.

2 FilterRestrictions/NonFilterableProperties
Defines whether a property is available as a filter criterion.

3 FilterRestrictions/RequiredProperties
Defines the filter field as a mandatory filter. Mandatory filters are marked by an asterisk (*).

4 ValueList
Contains annotations that provide information for rendering a value help list that has been set for a property.

5 FilterExpressionType/MultiValue
Defines whether multiple values can be used in a single filter.

6 FilterExpressionType/SingleValue
Restricts the filter to allow only one value entry.

7 LineItem/Label
A short, human-readable text for the filter name.

8 DynamicDateRange
The dynamic date range supports different operators, such as “Today -X / +Y days”. X and Y also support negative values (thus ranges in the past of future can be selected).

8 insertDefaultFilterValue
Inserts a default filter value into the aggregation defaultFilterValues.

9 liveMode
Defines whether the expanded filter bar is shown in live mode (no Go button) or in manual mode. By default, the filter bar is shown in manual mode.

Filter Dialog

Properties of the filter dialog

1 FilterRestrictions/RequiredProperties
Defines the filter field as a mandatory filter. Mandatory filters are marked by an asterisk (*).

2 FieldControlType/Hidden
Defines whether the filter is initially visible on the expanded filter bar.

3 SelectionFields
Defines whether a filter belongs to the basic group. All filters in the basic group are initially visible on the expanded filter bar.

4 FieldGroup
Defines whether a filter field is initially shown on the filter dialog, and which group it belongs to.

5 FilterRestrictions/NonFilterableProperties
Defines whether a property is available as a filter criterion.

6 LineItem/Label
A short, human-readable text for the filter name.

Fiscal Annotations

As an example, the smart filter bar supports fiscal annotations, like i.e. for fiscal period / data / time information. Such annotations guarantee the correct rendering of such values.

Smart filter bar with filters based on fiscal annotations

Recently Used Values

The smart filter bar provides a history of the most recent values entered in smart filter fields.

When the user focuses on a field, the app can display a small number of recently used values. They are shown below the recommended items, which can appear at the same time.
When the dropdown list is opened, all values are shown. When the user starts to type, the recently used values are filtered accordingly.

IN / OUT Parameter

In the smart filter bar, a dropdown or suggestion list can only contain a sub-set of items in case a dependent filter is set (IN parameter). It is also possible that selecting a value in a dropdown or suggestion list fills the current plus additional filter fields (OUT parameter).

Data Types

The smart filter bar analyzes and interprets the metadata provided by the OData service. This allows you to create complex UI entities, and to automatically add fields offered by the OData service to the filter bar as editable input fields. (Note that only fields marked with sap:filterable are added automatically.)

The tables below tell you which input controls are used for the key data types.

General Data Types

DataType	ODataMetadata	Additional Configuration	Edit type	Display type	Notes
*	*		Input	Text
DateTime	–	sap:display-format=”Date”	DatePicker	Text
Decimal	–	Precision=”3″ Scale=”0″	Input	Text
All	–		Input (with VHD)	Text	If a matching ValueList annotation is found, the ValueHelp for the Input is enabled. A ValueHelp Dialog is created automatically, based on the data in the ValueList annotation.
All	–	sap:semantics=”fixed-values” on the ValueList entity	ComboBox	Text	If a matching ValueList annotation is found, and the ValueList entity has the semantics=”fixed-values”, a dropdown list is shown.

Filter Bar-Specific Data Types

Input Type	sap:filter-restriction	display-format	hasValueHelpDialog	controlType	Resulting Control Type
*	*		controlType/filterType is specified		As specified in additional configuration
DateTime	“interval”	“Date”	NA		Date Range Selection
DateTime	“anything other than interval” or empty	“Date”	NA		Date Picker
String	“single-value”		“true” / none		Input Field With Value Help Dialog (with typeAhead according to hasTypeAhead flag)
String	“single-value”		“false”	not specified/input	Input Field (with typeAhead according to hasTypeAhead flag)
String	“single-value”		“false”	dropDownList; hasTypeAhead is not considered here	ComboBox
*	“single-value”				Input Field
String	empty or no filter-restriction		“true” / none		Multi Input Field with Value Help Dialog
String	“multi-value”		“true” / none		If no VL Annotation is found – only show the range selection part
String	“multi-value” / empty		“false”		If no VL Annotation is found – hide the ValueHelpDialog icon
String	“multi-value” / empty		“false”	dropDownList	MultiComboBox
*	“multi-value”				Input Field
*	“interval”		NA		A single Input Field that allows the “-” shortcut notation for intervals

Guidelines

Reduced set of table columns for the tabular suggestion

You have the option to define different columns in the table of the Value Help Dialog and the suggestion list of the Smart Filter Bar.

In the value list annotation, each parameter can be statically annotated as important using the <code>Importance</code> annotation with EnumMember set to High:

<Annotation Term="com.sap.vocabularies.UI.v1.Importance"
EnumMember="com.sap.vocabularies.UI.v1.ImportanceType/High" />

In the suggestion list only the important parameters are displayed as columns, while in the table of the Value Help Dialog all of the parameters are displayed.

The Importance annotation is optional – if omitted all of the parameters are displayed in both table of the Value Help Dialog and the suggestion list of the Smart Filter Bar.

Formatting option for negative numbers

The OData type “NumericText” together with display-format=”NonNegative” interprets and displays all values containing only “0” (e.g. “0”, “000”) as empty.

Resources

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

Elements and Controls

Filter Bar (guidelines)

Implementation

Smart Filter Bar (SAPUI5 samples)
Smart Filter Bar (SAPUI5 API reference)
Smart Filter Bar Annotations (SAPUI5 API reference)
Filter Bar (SAPUI5 samples)
Filter Bar (SAPUI5 API reference)
UI Development Toolkit (SAPUI5 samples)

Smart Field

Information

The smart field is only available for OData version 2.

When to Use

Use the smart field if:

You use an OData service for your app (OData version 2 only).
The feature set of the smart field fits your app. In this case, the smart field is faster to implement.
You use the smart table and your app is not performance-critical. The smart field offers more flexibility than the controls provided directly by the smart table, especially for editing.
You use a smart form.

Do not use the smart field if:

You use a different technology to OData version 2. Use the corresponding controls directly.
You need a different control for entering or displaying data, such as multi input, a multi combo box, step input, a radio button, or a title. In this case, use the corresponding control directly.
You need a different dialog for offering value help, such as the select dialog or table select dialog.
You use the smart table and your app is performance-critical. In this case, the controls offered directly by the smart table offer less flexibility but better performance.

Components

The smart field consists of a basic UI element and an optional label. The following UI elements are available:

Edit mode:

One or two input fields (with or without a value help dialog)
Select
Combo box
Text area
Checkbox
Date picker
Date/time picker
Time picker

Display mode:

For details, see the corresponding guideline topics.

User Input Control

The smart field chooses the control automatically based on the data type (Edm type) and annotations of the OData service and additional properties. The following controls are used:

	Read-Only	Edit	Edm Types / Annotations / Properties	Comment
Single-line text	Text	Input field	Edm.String Configuration: controlType, value: input
		Combo box	Edm.String Configuration: controlType, value: dropDownList
		Select	Edm.String Configuration: controlType, value: selection
Multi-line text	Text	Text area	Edm.String MultiLineText
Decimal numbers	Text Object number	One or two input fields (for number and unit)	Edm.Int16, Edm.Int32, Edm.Int64, Edm.SByte, Edm.Byte, Edm.Single, Edm.Float, Edm.Double, Edm.Decimal Precision, Scale
Status information	Object status		Edm.String criticality, criticalityRepresentationType
Text and ID	Text Object identifier Object status	Input field	TextArrangement controlProposal displayBehavior textInEditModeSource, sap:text, fetchValueListReadOnly	The following patterns can be selected via displayBehavior: Text (ID) ID (Text) Text ID
Links (with/without quick view)	Link Smart link		Edm.String IsURL, url semanticObjectController
Dates	Text	Date picker	Edm.DateTime sap:display-format=”Date” IsCalendarDate Configuration: controlType
Dates and times	Text	Date/time picker	Edm.DateTime Edm.DateTimeOffset
Times	Text	Time picker	Edm.Time
Fiscal periods	Text	Input field	IsFiscalYear, IsFiscalPeriod, IsFiscalYearPeriod, IsFiscalQuarter, IsFiscalYearQuarter, IsFiscalWeek, IsFiscalYearWeek, IsDayOfFiscalYear
Amounts with currencies	Text	One or two input fields	ISOCurrency or sap:unit with sap:semantics=”currency-code”
Phone numbers	Text	Input field	IsPhoneNumber
Email	Text	Input field	IsEmailAddress
Boolean	Checkbox	Checkbox	Edm.Boolean
Boolean	Text	Combo box	Edm.Boolean valueList displayBehavior	The text in display mode can be influenced via displayBehavior: Yes/No True/False On/Off

Guidelines

Set a default value whenever appropriate (annotation: text, property: value).
To show a static unit of measurement, use a description (annotation: text).
To display a text and ID in the same place, use the format Text (ID) wherever possible. Use another format only if displaying the text doesn’t make any sense. Be careful when using the text arrangement options in tables: end users will only be able to sort, group, or filter based on the ID, even if the ID isn’t visible.
If you are not using the smart field within a smart form or smart table, label the smart field with a smart label (annotation: label, properties: textLabel, showLabel). The standard label doesn’t know the inner structure of a smart field.
You can set a tooltip (annotation: QuickInfo), but this should usually be avoided. See Using Tooltips.
If data entry is expected in a specific format, set a placeholder (property: Placeholder).

Developer Hint

Performance: Using the TextArrangement annotation to display both the text and ID (in any order) triggers two requests to the back end.

Behavior and Interaction

Context

You can use the smart field in different contexts
(property: controlContext):

Standalone
Within a form (depending on the form layout)
Within a table (depending on the table type)

The context influences:

Labels: In most cases, forms provide the label automatically.
Empty values in display mode: In forms, empty values are shown as a dash. In tables, the field remains blank.
How units of measurement are displayed

Guidelines

If the width is not handled by the context, set a meaningful width for the smart field, based on the expected data (property: Width).
If you use a “standalone” smart field in a form-like arrangement, use a dash to show an empty value in display mode.

Switching Between Edit and Display Mode

Smart field as a select with 'required' indicator in edit mode

The same smart field in display mode

Guidelines

Define which fields should be editable (annotations: updateable, creatable, updateable-path, InsertRestrictions, UpdateRestrictions, computed, immutable, fieldControl, fieldControlType).
For fields with a unit of measurement, define whether the unit of measurement is editable or static (annotation: FieldControl, property: uomEditable).
Make sure that the full text is shown in display mode (property: wrapping), unless this is handled differently for the corresponding context (for example, see guidelines for content in the grid table).
When you display the text and ID, the smart field automatically displays both values in display mode, but only the ID in edit mode (annotation: TextArrangement). In most cases, it makes sense to also display both values in edit mode (annotation: sap:text, property: textInEditModeSource, aggregation: Configuration with property: displayBehavior).

Suggestions and Value Help

Autocomplete is enabled automatically.

The following controls are used to offer suggestions or value help:

A fixed value list leads to a combo box or select, depending on the control configuration.
A non-fixed value list leads to an input field with a value help dialog.

Smart field as a combo box

Smart field as an input field with suggestions, auto complete and a value help button

The automatically generated value help dialog for the same smart field

Recently Used Values

Guidelines

Do not show recently used values for a field if:

There are only a small number of options.
The field contains personal sensitive data (annotation: IsPotentiallySensitive).
It is unlikely that the same values will be selected again and again.

Recommended Values

In addition to recently used values, a smart field can show recommended values (annotation: RecommendationState).

The corresponding smart field is highlighted and/or prefilled:

If no recommendation is available or the current user input matches the recommendation, the smart field is shown in the default state.
If a recommendation is available and there is no user input, the smart field is shown in the information state.
If a recommendation is available and it differs from the current user input, the smart field is displayed in the warning state.

The recommended values are shown as soon as the user focuses on the smart field.

Validation

The smart field offers the following validations automatically:

Validation for required fields: This can be done on the client or server side (property: clientSideMandatoryCheck, annotation: Nullable).
Validation for a group of fields: Validation is triggered when the focus moves outside a group of fields, rather than when a single field loses the focus. A group is defined by all smart fields that share the same field group ID (property: fieldGroupIds).
Validation for the maximum length of user input: Validation is triggered when a field loses the focus or the ENTER key is pressed (property: maxLength).

The validation result is indicated by a value state (property: showValueStateMessage).

When the user edits a smart field showing a text and ID, you can allow any kind of input to avoid unnecessary validation issues (annotation: ValueListNoValidation).

Examples:

Allowing the user to enter additional values (which are not in the suggestion list)
Typing a text instead of an ID to filter down the suggestion list
Using the smart field in a draft

Automatic validation

IDs

The smart field offers automatic validation for number-only ID fields (annotations: IsDigitSequence or sap:display-format="NonNegative"):

It checks for non-negative numbers.
It shows values containing only “0” digits as empty.
It does not show leading zeros.

Units

Smart field showing an amount with a currency in display mode

The same smart field in display mode

Sensitive Data

Sensitive data, such as passwords, can be masked. The text is then replaced with asterisks (annotations: IsPotentiallySensitive, masked).

Capitalizing Text Input

Text input can be capitalized automatically (property: IsUpperCase).

States

Smart fields support the following states (annotation: fieldControl):

Editable or display only (additional annotations: updateable, creatable, updatable-path, InsertRestrictions, UpdateRestrictions, property: editable)
Enabled or disabled
Visible or hidden (additional annotations: property: visible, annotation: sap:visible)
Required: If set, the smart field must contain a value when validated. This is indicated by an asterisk next to the corresponding label (additional annotation: Nullable, property: mandatory).

The following states for a unit of measurement can be set independently of the corresponding field:

If editable, a unit of measurement can be enabled or disabled (property: uomEnabled)
The unit of measurement can be visible or hidden (property: uomVisible)

Developer Hint

In the SAPUI5 SDK API Reference for the smart field, the display only state is referred to as read only.

Dependencies between Smart Fields

If the content of a smart field is changed, you can trigger additional changes to other fields on the UI (annotation: SideEffects).

Content Alignment

You can change the horizontal alignment of the text within any kind of input field (property: textAlign).

Guidelines

Responsiveness

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

Top Tips

Always label a smart field if it is not inside a table context.
Use suggestions with autocomplete whenever possible and meaningful.
- Do not show suggestions if there are only a few choices.
- Use recently used values as appropriate.
- Reduce the number of attributes shown in the suggestion list to a maximum of 4 or 5.
Make use of validation features.

Properties

The following properties, aggregations, and associations are available for sap.ui.comp.smartfield.SmartField:

The property: expandNavigationProperties is experimental. Do not use it.
The property: jsontype is deprecated. Do not use it.
The property: name is used in HTML forms that send data to the server via “Submit”.
The property: uomEditState is for internal use only. Do not use it.
The property: proposedControl is deprecated. Do not use it.
The property: textDirection provides support for reading directions in different locales.
The aggregation: controlProposal is deprecated. Do not use it.
The association: ariaLabelledBy can be used for linking additional labels to the smart field.

Usage

Use the dynamic date control if:

You need flexibility between fixed and dynamic dates.
You need dynamic dates that can be saved in the variant management (for example, show values from today regardless of when you open the app).
You are using the smart filter bar.
The user only needs to select one value.

Do not use the dynamic date control if:

Users need to enter a date and a time. In this case, use the date picker or the date/time picker instead.
Selecting ranges is not the user’s primary goal. In this case, use the simple date picker.
You are not using the smart filter bar.

Responsiveness

Value help for dynamic date range – Size S

Value help for dynamic date range – Size L

Components

The two clickable areas of the dynamic date control

The dynamic date consists of two components:
(A) Date input field with suggestions
(B) Value help popover

On all devices, users can either use the input field to type a date, or use the value help button to open the popover.

Dynamic Date Input Field

The user can type data directly into the input field. Upon user input, a list of suggestions appears.

Value Help Popover

Value help popover – Input field

Value help popover – Date pickers

Value help popover – Read only

Value help popover – Select control

Values Offered

From
To
Date Range
Today
Today -X / +Y days
Last X days
Next X days
This week
Last week
Last X weeks

Offered Values

Next week
Next X weeks
Month
This month
Last month
Last X months
Next X months
This quarter
Last quarter
Last X quarters
Next quarter

Offered Values

Next X quarters
First quarter
Second quarter
Third quarter
Fourth quarter
This year
Last year
Last X years
Next year
Next X years
Year to date

Behavior & Interaction

Typing data into the date range input field

List of suggestions shown after typed input

Opening the value help and selecting a time period

Opening the value help popover and selecting a time period

Defining a custom time period (X)

Custom time period with a simple input field

Selecting a date range

Selected time period with two date pickers (start date and end date)

Styles

Validation

Use inline validation to give the user feedback, especially for errors and warnings. The possible states are “warning”, “error”, and “success”.

Visible frame that shows an error when the field is out of focus

Error state with meaningful text – The date range input field is in focus

Guidelines

See the Date Picker and Date Range Selection articles for the guidelines. They also apply to the dynamic date control.

List of Options

Only provide values that are relevant for the use case in the list of options.
You can also add your own values, if necessary.
If you use your own values, provide human readable text.

Resources

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

Elements and Controls

Date Picker (guidelines)
Input Field (guidelines)
Select (guidelines)

Implementation

Date Picker (SAPUI5 samples)
Input (SAPUI5 samples)
Select (SAPUI5 samples)
Smart Controls (SAPUI5 samples)

Smart Filter Bar (SAPUI5 API reference)

Smart Table

Intro

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).

The components of a smart table

Table Toolbar

Toolbar with all features provided by the smart table out-of-the-box

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

Title
Item counter
Variant management
Show Details / Hide Details
View Settings
Export to Spreadsheet
Maximize / Minimize

In addition, you can add app-specific actions.

Title

The title is optional (property: header).

Guidelines

Add a title whenever the title is not indicated in the surrounding area.

Developer Hint

If you don’t provide a title, ensure that you support screen reader users: create a simple table in the XML view, use ariaLabelledBy to point to the corresponding text, and add this table to the smart table. Make sure that the table type within the smart table is set accordingly. The smart table will take care of the rest (creating columns, and so on).

Item Counter

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

Guidelines

Show the item counter together with the table title, unless:

You expect this to cause performance problems.
You use a responsive table and use the More button for loading additional items. Use the item counter on the More button instead.

Variant Management

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

Guidelines

Use variant management only if really needed.

Show Details / Hide Details

Show Details / Hide Details is mandatory with and only available for the responsive table. It shows/hides columns with low priority in the pop-in area (properties: demandPopin, showDetailsButton, annotation: UI.Importance). The button only appears if there are corresponding columns in the pop-in area.

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.

Guidelines

Offer view settings only if they are really needed. Tables with just a few columns and rows do not need to be sorted, filtered, or grouped.

Sort and Filter

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.

Guidelines

Do not turn off the info bar (property: useInfoBar).
In the default delivery, sort items in a meaningful order. This works only for the grid table, tree table, and analytical table. You can also provide default filter settings (all tables) and grouping (responsive table and analytical table only) (annotation:
PresentationVariant).
If the smart table is used together with a filter bar (property:
smartFilterId), do not offer filtering for the smart table itself.

Developer Hint

The smart table can be linked to a smart filter bar. If linked, the filter bar settings are automatically applied to the smart table (sap.ui.comp.smarttable,SmartTable, property: smartFilterId).

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.

Guidelines

Column Settings

Guidelines

If sorting, grouping, and/or filtering are needed, also show the column settings (sap.ui.comp.smarttable.SmartTable, property: useTablePersonalisation).

Developer Hint

Only offer column settings if you need more columns than a tablet screen can display at a time (usually more than five).

Export to Spreadsheet

Guidelines

Only offer the Export to Spreadsheet option if your end users typically export the data shown in the table to work with it in a spreadsheet application.
- This is usually the case if data is collected from several systems and analyzed in the spreadsheet application.
- This is not usually the case for worklists, attachment lists, tables with only a few items, shopping carts, or data that does not need to be analyzed.
If you offer the Export to Spreadsheet button, use the front-end export.
If your table has columns with non-textual content, provide a textual equivalent for those columns. Non-textual content is not exported.

Warning

With both methods, the file size is limited by the available browser memory. As a result, exporting large tables can lead to memory overflows and crash the export process.

Apply the following size restrictions as a rule-of-thumb:

For the front-end export, do not export more than 2 million table cells on desktop browsers or 100,000 table cells on tablets and phones.
For the back-end export, do not export more than 100,000 table cells.

For larger tables, consider using custom-built, specialized export solutions instead.

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).

Guidelines

Use Maximize / Minimize only if really needed.
Do not use it in list reports, worklists, analytical list pages, and initial pages.
Do not use it if the table is in a dialog or popover.

App-Specific Actions

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

Developer Hint

If additional actions are needed, use a custom toolbar for the table. The smart table can also add integrated functionality, such as a table title, item counter, variant management, view settings, and export to spreadsheet to the custom toolbar (aggregation: customToolbar).
The property placeToolbarInTable adds the toolbar to the corresponding aggregation of the inner SAPUI5 table. In most cases, set this to “true”, especially when you are using the custom toolbar with the responsive table. Otherwise, the table toolbar cannot stick to the top of the surrounding layout container.

Infobar

Infobar with filter information

Guidelines

For the responsive table, the info bar is mandatory.
For all other tables, do not show the info bar.

Table

A responsive table within a smart 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).

Guidelines

Use the responsive table wherever possible. Use the other table types only if really needed. If you use another table, provide a fallback solution for phones.
For the responsive table, the smart table initially loads 20 items and shows a More button for loading additional items. Change this behavior if:
- You expect fewer than 200 items. Load all items from the start (sap.m.Table, property: growing).
- You expect more than 200 items. Adapt the number of items initially loaded to cater for large screens, and load additional items automatically when the user scrolls down (sap.m.Table, property: growingScrolllToLoad).

Developer Hint

The property tableBindingPath defines the path from which the data is fetched.
The property enableAutoBinding fetches the data automatically as soon as the corresponding OData model is initialized and the smart table is created.

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.

Developer Hint

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 property.

Developer Hint

If a column needs to be in the model but should not be shown, you can hide it from both the table and the P13n dialog (property: ignoredFields, annotation: UI.Hidden).

Use this option if:

A column is needed to provide an ID that is used for navigation purposes only. However, you only want to display the corresponding text on the UI, and not the ID.
The values of a column are needed to perform calculations, but only the results are shown on the UI.

The property ignoreFromPersonalization is only available with the analytical table. It loads additional key fields that are needed for aggregations but are never visible.

Developer Hint

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).

Guidelines

Keep the number of initially visible columns to a minimum. Avoid pop-in behavior (responsive table) or horizontal scrolling (all other tables) on a tablet screen size in the default delivery (annotation: PresentationVariant/ LineItem).
Also keep the number of additional columns offered in the personalization settings to a minimum. You can use the P13n dialog to let users show/hide the columns. Select the columns offered in the P13n dialog carefully. Do not just show all columns available in the backend tables (annotation: sap:visible, value: false).

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.

Developer Hint

If the same column is defined via LineItem and via DataFieldDefault, LineItem wins.

Column Layout

For the grid table, tree table, and analytical table, a default column width is calculated for each column based on the data displayed in it (annotations: MaxLength, Precision, Scale). Apps can change this default width if it does not fit (annotation: CSSDefaults).
By contrast, the responsive table uses the same width for each column. To change this, use a custom column. End users cannot change the column width in the responsive table.

Guidelines

Choose a column width which avoids truncation for the initial data as well as for the column header label. If the default column width does not fit, change it.

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 property), or – for responsive tables – columns that show more than one control.

Developer Hint

To add or override columns (“custom columns”):

Use an XML view to define the underlying table with just the columns to be added/overridden.
To override columns, provide the column key of the column you want to exchange.
Add this “unfinished” table to the smart table. The smart table adds all the automatically generated columns and additional features.

If you are using a responsive table, also make sure that the responsive behavior for this column works as expected (sap.m.Column, property: importance).

Column Headers

You can specify a column header text for each column (annotation: sap:label).

Guidelines

Provide a column header text for each column. (annotation: sap:label).

The column headers contain the following settings:
- Sort
- 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.

Guidelines

Offer column totals by default for all columns where totals make sense (annotation: PresentationVariant).

Developer Hint

To add a Freeze option manually, declare the corresponding table inside the smart table in the XML view, and use the corresponding settings for this inner table.

Clicking the column header reveals sort and filter options (responsive table)

Column header menu for a dimension column of an analytical table within a smart table

Column header menu for a measure column of an analytical table within a smart table

Content

The smart table provides two options for creating columns automatically:

The smart table is rendered in either read-only or edit mode. In this case, the smart table renders the controls as described below. This is the default and recommended way to render content and fits for most use cases (property: editable).
If users need to switch between read-only and edit mode at runtime, the smart table uses smart fields for both modes. This limits the rendering options (aggregation: customData, key: useSmartField, property: smartToggle), 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

For option 1, the following controls are used:

	Read-only	Edit	Annotations / Edm type	Comment
Static text	Text	Input field	Edm.String
Decimal numbers	Text	Input field	Precision, Scale, Edm.Byte, Edm.Decimal, Edm.Double, Edm.Int16, Edm.Int32, Edm.Int64, Edm.SByte, Edm.Single
Status information	Object status or Icon	Input field	CriticalityType, CriticalityRepresentationType
Key identifier	Object identifier (responsive table) Text (all other tables)	Input field for the ID	SemanticKey, Common.EditableFieldFor
Text and ID	Text, object status, or object identifier	Input field for the ID	TextArrangement	Use together with the annotation mentioned above for static text, status information, or key identifier.
Links with/without quick view	Smart link	Smart link	SemanticObject	Smart links can be customized using the aggregation: `semanticObjectController`
Dates	Text	Date picker	sap:display-format, value: date, IsCalendarDate
Dates and times	Text	Date/time picker	Edm.DateTime, Edm.DateTimeOffset
Times	Text	Time picker	Edm.Time
Fiscal periods	Text	Input field	IsFiscalYear, IsFiscalPeriod, IsFiscalYearPeriod, IsFiscalQuarter, IsFiscalYearQuarter, IsFiscalWeek, IsFiscalYearWeek, IsDayOfFiscalYear
Amounts with currencies	Two text controls	Input field for the amount	sap:semantics, value: currency-code	In edit mode, the currency is shown as static text next to the input field.
Phone numbers	Link	Input field	IsPhoneNumber	Opens the system application for making phone calls.
Email	Link	Input field	IsEmailAddress	Opens the system application for writing emails.
Pictures	Image	Input field	IsImageURL	Only available for the responsive table. In edit mode, the input field contains the URL to the image.
Boolean	Text	Checkbox	Edm.Boolean	For read-only, the displayed text is Yes or No.

For option 2, the smart field is used in all cases.

For both options, the smart table automatically takes care of the content alignment and formatting (except for custom columns).

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

Guidelines

For inline actions, use a text-only or an icon-only button. Make sure the icon communicates the function clearly enough. Otherwise, use a text-only button.

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

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.

Guidelines

For all other cases, provide instructions on how to fill the table with data (aggregation: noData).
The “no data” text can be exchanged at runtime. Use specific texts for different situations.
Avoid displaying a table without any items, especially when the app is initially loaded.

An empty smart table

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:
These controls are not intended for use on smartphones. If you use a smart table with this configuration, ensure that you implement a fallback solution for small screens.

Guidelines

The column that identifies the line item.
The column that contains the key attribute.

Examples

Responsive table within a smart table

Grid table within a smart table

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.

Intro

When to Use

Use the smart link if:

You want to offer direct navigation to a related app. For example:

Navigate from a product list to the app for changing the pricing
Navigate from a sales order list to the app that shows a customer’s balance

You want to show a popover with contextual information or navigation. For example:

Offer navigation to multiple related apps
Display simple object details

Do not use the smart link if:

You want to display more or complex information about an object. Use the object page or charts instead.
No metadata is accessible, and only a direct link to a website, document or application is needed. Use the standard link instead.
You need to structure information in a deeper hierarchy. Use the quick view or a list drilldown instead.

Components

The smart link popover contains the following areas:

The header bar of the smart link popover is only visible on mobile devices (see example image for responsiveness, size S).
The title area contains a title and a subtitle. You can also show the title as a link, which can be used to navigate to the corresponding object or fact sheet. You can use the subtitle to show an object ID, for example.
The content area shows object-related information, such as details about a product or contact information. You can use any UI control, based on what best fits your use case.
The link area offers links to all other apps that are relevant for a user role. The link list includes all semantic objects defined for the app, and can also include additional links defined manually by the application development team. The link area can have two states:

Links are shown:
As soon as the link area contains links, the button text changes to More Links. This opens the same selection dialog.

The areas of the smart link (header bar not shown)

Behavior and Interaction

If the semantic object annotation is not set, the smart link is rendered as sap.m.Text by default. However, you can also opt to render any other control.

Link Selection Dialog

Exception: Within SAP Fiori elements, the links offered in the Define Link List dialog are generated automatically. App teams cannot adapt the list.

You can switch off the More Links / Define Links option by setting the property enableAvailableActionsPersonalization to “false”. By default, it is set to “true”.

Smart Links in a Smart Table

Define link list dialog with a list of application links

Responsiveness

The responsiveness of the smart link is based on the responsiveness of the popover that overlays the content.

On desktop devices, clicking anywhere outside the popover closes it.

On mobile devices, the smart link opens a full screen dialog with a Close icon () on the top right.

Size S – On smartphones, the smart link overlays the content

Sizes M/L/XL - Smart link shown in a table on a desktop device

Top Tips

Check the related apps you offer carefully. Only display those that are relevant for the user.
Use meaningful link names in the link area. Do not use the same link name more than once. If necessary, rename the links to suit your context (for example, “Add Product” instead of “Manage Products”).

Check the related apps you offer carefully. Only display those that are relevant for the user.
Use meaningful link names in the link area. Do not use the same link name more than once. If necessary, rename the links to suit your context (for example, “Add Product” instead of “Manage Products”).

Intro

The smart table is a wrapper around existing tables, and can be used together with the responsive table, grid table, analytical table, or tree table.

The smart table creates columns automatically based on the underlying OData service plus corresponding annotations. It also adds some generic functionality, such as a toolbar, complex personalization settings, variant management, and export to spreadsheet.

Everything that can be done using the smart table can also be achieved using the responsive table, grid table, analytical table, or tree table directly, but with more development effort. Therefore, the main purpose of the smart table is to reduce development effort. However, this comes at the expense of decreased flexibility.

Usage

Use the smart table if:

Data is fed into the table through OData services.
You need a simple table with limited flexibility to display its content. In this case, the smart table reduces development effort.
You need a table in which some columns provide flexible content. In this case, use the smart table together with a responsive table, and provide app-specific column definitions for these columns.

Do not use the smart table if:

You create your own UI coding, whereby the data is not fed through OData services. In this case, use the underlying table control directly.
The main use case involves selecting one item from very few items, with no additional details. In this case, a select or combo box might be more suitable.
The main use case involves selecting one item from several items, with only a few details per item. In this case, a list might be more suitable. Pay attention to the layout of the list item to provide a pleasant appearance (see, for example, the master list and the feed list item).
The table is displayed together with a chart inside a chart container. The smart table is not designed to work inside an existing chart container. In this case, use the underlying table control directly.
You need an overview of a large amount of data. In this case, use charts.
You just need it for layout reasons. In this case, use a layout container, such as the grid layout, instead.
You need read-only or editable field value pairs. In this case, use a form instead. Tables are not optimized for form-like input navigation.

Responsiveness

The responsiveness of the smart table depends on the encapsulated table. The table toolbar uses the overflow mechanism for adapting to the screen width.

Using the responsive table

The smart table offers generic responsive behavior (sap.ui.comp.smarttable.SmartTable, property: demandPopin, value: true):

For every 10 rem of screen width, one column stays in the tabular layout. All others are moved to the pop-in area. The columns are moved to the pop-in area from right to left, so the column furthest to the right moves to the pop-in first.
Exception: The first two columns always stay in the tabular layout. This works best if the smart table uses the whole screen width. It might not work well if the smart table uses far less space.

Using the grid table, analytical table, or tree table

The smart table works only on desktop and tablets, but not on smartphones. It supports touch devices, but is not optimized for small screens.
If you use a smart table in this configuration, ensure that you implement a fallback solution for small screens. This fallback solution does not need to support all use cases. You could create a fallback by using a responsive table. However, a completely different solution, such as showing charts in a read-only case, might be more suitable.

Size S with responsive table

Size M with responsive table

Size L with responsive table

Size M with grid table

Size L with grid table

Layout

The title bar contains the title of the smart table, the item count, variant management, and the toolbar itself. All of these elements are optional.
The table area shows the corresponding table (responsive table, grid table, analytical table, or tree table).

Schematic visualization of the smart table

Components

The title bar consists of a toolbar.

This can be the standard toolbar or a custom toolbar. The standard toolbar can contain a title text with or without item count, variant management, view switch (switching the table to edit mode), an entry point for the P13n dialog, and an Export to Spreadsheet action.

If you require additional functionality, you can use an app-specific toolbar. All toolbar options provided by the smart table can also be added to the app-specific toolbar. (Aggregation: customToolbar)

The table area consists of any of the following tables: responsive table, grid table, analytical table, or tree table.

Standard toolbar with everything enabled

Standard toolbar just with title and item count

Behavior and Interaction

The behavior is generally inherited from the underlying table, toolbar, variant management, 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.

Table Level

Table Type

The smart table can encapsulate the responsive table, grid table, analytical table, or tree table. (sap.ui.comp.smarttable.SmartTable, property: tableType)

Automatic Rendering of the Table

The smart table automatically creates columns and renders all items based on the metadata of the underlying OData service (sap.ui.comp.smarttable.SmartTable, property: smartFilterId).

To be more flexible in the table layout, the smart table also offers app-specific column templates for some or all columns. In this case, app developers must provide the definition for the underlying table and for the corresponding (but not necessarily for all) columns in the XML view. For this, the app development team must provide the column keys of the overridden columns via custom data.

Additional columns can also be added. Columns that are defined in this way retain all the options of the underlying table. This is especially useful with the responsive table, which offers complete flexibility in content design. Any columns that are not defined by the app development team are still rendered automatically by the smart table.

No Data

If there is no data to show, the smart table renders default text. This text can be overwritten by the app development team (aggregation: NoData).

Initially Visible Columns

The smart table enables you to define which columns are initially shown. Here, initially means that these columns are shown when the app is first launched. All other columns are initially hidden (annotation: PresentationVariant/ LineItem, property: initiallyVisibleColumns).

Persistency

End users can show additional columns if table personalization is provided. In this case, column settings are persisted. On consecutive startups, the columns are shown with the same settings as last defined by the user (property: persistenceKey).

Removing Columns

The smart table always shows all columns from the OData model. In some cases, columns needs to be in the model but should not be available on the front end at all. Examples of this include:

A column is needed to provide an ID which is used for navigation purposes, but the front end should only display the corresponding text, not the ID.
The values of a column are needed to perform calculations, but only the results should be shown on the UI.

In these cases, you can define which columns should not be available at all on the UI. These columns are not shown and are not available in the P13n dialog. You can also do this for columns that are added manually in the XML view (annotation: sap:visible, value:false).

P13n/personalization dialog

Filter Settings

The “Show Field as Column” option for newly added filters is switched on by default.

Sorting and Filtering

The smart table allows you to add sort and filter settings for each column. These settings enable the corresponding pages in the P13n dialog. For the grid table, analytical table, and tree table, sorting and filtering are also enabled on the column header. (Annotations: sap:sortable and sap:filterable)

Column header menu of the grid table

Smart Table and Smart Filter Bar

The smart table can be linked to a smart filter bar. If linked, filter bar settings are automatically used on the smart table. (sap.ui.comp.smarttable,SmartTable, property:smartFIlterId)

Aggregation

If used with the analytical table, the smart table allows total sums of measure columns to be calculated. The totals are shown in the usual way:

As the last row of the analytical table.
As the last row of each group if the group is expanded.
On the group header of each group if the group is collapsed.

Aggregation settings are not persisted (annotation: sap:aggregation-role, value:measure).

The total can be hidden via the column header menu.

Aggregation entry in column header menu of the grid table

Aggregation of Different Currencies

If used with the analytical table, the smart table also allows you to display totals for amount columns with different currencies.

In this case, a Show Details link is displayed instead of the total. Clicking the link opens a popover showing the subtotals per currency.

Exception: If a group contains only one currency, the total is shown directly.

Totals for a column which contains amounts in different currencies

Column Width

A default column width is calculated for each column based on the data displayed in it. Important: end users cannot change the column width in the responsive table (annotations: MaxLength, Precision, Scale).

Column Header

A column header text can be specified for each column (annotation: sap:label).

Persistence

The smart table allows you to persist sort, group, and filter column settings (such as by hidden columns) as well as variants (sap.ui.comp.smarttable.SmartTable, Property:persistenceyKey).

Content

The smart table provides two options to create columns automatically:

The smart table is rendered in either read-only or edit mode. In this case, the smart table renders the controls as described below. This is the default way of rendering content (property: editable)
If users need to switch between read-only and edit mode at runtime, the smart table allows smart fields to be rendered instead. You should use this if the edit button is added to the toolbar of the smart table (aggregation: customData key: useSmartField, property: smartToggle).

For option 1, the following controls are used:

To show currency amounts, the smart table allows the amount and the currency code to be displayed in a single cell. For read-only mode, the currency control is used. For edit mode, a single input field is used, and the currency itself is shown next to the input field as non-editable text (annotation: sap:semantics, value: currency-code).
To show links that open a quick view, the smart table supports the smart link.
To show static text, the smart table uses an input field in edit mode, and a text in read-only mode.
To show dates, the smart table uses a date picker in edit mode, and a text in read-only mode (annotation: sap:display-format, value:Date).
To show decimal numbers, the smart table uses an input field in edit mode, and a text in read-only mode (Annotations:Precision, Scale).
The smart table also provides an object status and object identifier control. For more information, see object display components.
Pictures and microcharts, as well as rating indicators and progress bars are available.

Amount formatting

Link formatting

Date formatting

Value Help

The smart table supports value help in the following ways (annotation: ValueList):

Input fields can show a value help button. Triggering this button opens a value help dialog. Within this dialog, you can provide a search field (annotation:ValueList, property: SearchSupported).
You can restrict the number of characters for the input field. Use this if no ValueList annotation is provided (annotation:MaxLength).

Toolbar Level

Table Title

The smart table can provide a title for the table within the toolbar (sap.ui.comp.smarttable.SmartTable, Property:header).

Table title

Item Count

Next to the table title, an item count can be shown (sap.ui.comp.smarttable.SmartTable, Property:showRowCount).

Table title with item count

Edit

The table toolbar can contain a button for toggling the table between read-only and edit modes. If smart fields are used, the smart table handles both modes automatically (sap.ui.comp.smarttable.SmartTable, properties:editTogglable, smartToggle, aggregation: customData, key: useSmartField).

If used with the responsive table, the edit button also switches the keyboard behavior accordingly.

Edit button

View Settings

The table toolbar can contain a button for opening the P13n dialog. This dialog provides extensive sort, group, and filter settings. It also allows columns to be shown, hidden, or rearranged (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).

Settings button

Export to Spreadsheet

The table toolbar can contain a button for exporting the table data to a spreadsheet (sap.ui.comp.smarttable.SmartTable, Property:useExportToExcel). The spreadsheet file can be created using back-end functionality (if available) or in the front-end (sap.ui.comp.smarttable.ExportType):

With the back-end export, the following columns are exported: currently visible columns, “technical columns” that are in the data model but not visible to the user, and usually some (but not all) of the columns that are currently hidden. In the spreadsheet file, neither the columns nor the rows are in the same order as in the exporting app. The exported file might also show different column header texts.
When the user triggers the export, the corresponding file is created in the background and offered for download automatically. The export process cannot be canceled. This option is only available if the back-end export is supported in the corresponding back-end system.
With the front-end export (default and recommended), only visible columns are exported. In the exported file, columns are in the same order and have the same header texts as in the exporting app. During the export, the system displays a progress dialog that blocks the UI. The export can be canceled at any time. As soon as the file has been created, it is offered for download automatically. The front-end export is always available.

In both cases, the export works only with simple text-only cell content. Non-text elements, such as icons, images, micro charts, or controls like checkboxes and buttons are not supported. Formatters are not taken into account (for example, for numbers, amounts, dates, and times) .

Warning

With both methods, the file size is limited by the available browser memory. Exporting large tables can therefore lead to memory overflows and browser crashes.

For the front-end export, the recommended maximum table size for using the built-in export functionality is 1 million table cells for desktop browsers or 100,000 table cells on tablets and phones. The limitation for the back-end export is even worse: even on a desktop device, the recommended maximum table size is only around 100,000 table cells.

For larger tables, consider using custom-built, specialized export solutions instead.

'Export to Spreadsheet' button

Exporting to Spreadsheet

Full Screen Mode

Applications can implement a maximize button to run the table in full screen (Property: showFullScreenButton).

Maximize button

Footer Toolbar Level

Use button styles only to help the user and not for decoration. For instance, emphasize the most important action. Use only one emphasized button, and never mix emphasized and semantic buttons.

Guidelines

In general, the guidelines for the underlying table, toolbar, variant management, and P13n dialog also apply to the smart table (see the corresponding articles for details). However, because the smart table does not offer the complete flexibility of the underlying controls, there are certain differences.

Table Type

The responsive table is the standard table for SAP Fiori. Use the responsive table whenever possible. It is the most flexible table in terms of how its content is displayed, it is fully responsive, and it can handle up to 1,000 line items.

If you cannot use the responsive table, consider using the grid table instead. The grid table can handle a large number of line Items. Compared to the responsive table, however, it is more restricted content-wise (only certain controls can be used to show the data, and only one control per cell), and it does not run on smartphones. If you use the grid table, you need to provide a fallback solution for smartphones, for example, by using the responsive table.

The analytical table is similar to the grid table, but adds several grouping levels and offers total sums on measure columns. The analytical table can also handle a large number of line Items. Compared to the responsive table, however, it is more restricted content-wise (only certain controls can be used to show the data, and only one control per cell), and it does not run on smartphones. If you use the analytical table, you need to provide a fallback solution for smartphones, for example, by using the responsive table.

The tree table is the only table for displaying hierarchical data. Like the grid table, it can handle a large number of line items, although it is restricted content-wise (only certain controls can be used to show the data, and only one control per cell), and it does not run on smartphones. If you use the tree table, you need to provide a fallback solution for smartphones, for example, by using the responsive table.

For more information about the different table controls, see the corresponding articles.

Table Title, Item Count, and Variant Management

Always show the item count together with the table title, unless this is expected to cause performance problems.
If used with the responsive table and if more than 200 items are generally expected, do not show the item count. In this case, the smart table displays a More button to load additional rows. Using the item count together with the More button might lead to confusion (sap.ui.comp.smarttable.SmartTable, Property:showRowCount).

Even if variant management is easy to implement, use it only if it is really needed. The variant management saves the whole page, including filter settings and table layouts.

Empty Tables

Try not to display an empty table. If there is no way around this, provide instructions on how to fill the table with data (aggregatrion: noData).

The following default texts are provided automatically:

If the smart table is used standalone (without an attached smart filter bar) and it is initially empty (not yet bound), the default text is:
No items available.
Overwrite this whenever a hint can be provided on how to fill the table with data.
If the smart table is used with a smart filter bar attached, and it is initially empty (not yet bound), the default text is:
No filters set. To start, enter your search and filter settings and run the search.
If a smart table is bound but there is no data to display from the binding, the default text is:
No items found. Check the search and filter settings.
Overwrite this whenever this text is either not precise enough (for example, only search is offered) or misleading (for example, if the data is filled based on a master-detail pattern instead of search and filter settings).

Columns – Best Practices

Keep the number of initially shown columns to a minimum. Avoid the need to scroll horizontally on a tablet screen size in default delivery (annotation: PresentationVariant/ LineItem).

Keep the number of additional (initially hidden) columns to a minimum. You can use the P13n dialog to show/hide the columns. Select the columns offered in the P13n dialog carefully. Do not just show all columns available in the backend tables (annotation: sap:visible, value:false).

For the grid table, analytical table, and tree table, the column widths are calculated automatically if the corresponding OData annotations are provided (annotations: MaxLength, Precision, Scale).

In contrast, the responsive table uses the same width for all columns.

If used with the responsive table, enable the pop-in behavior (sap.ui.comp.smarttable.SmartTable, property: smartFilterId, value: true).

Show the most important column on the left and the least important on the right. This ensures that the most important columns stay in the tabular layout as long as possible. The most important columns are those that contain the following information:

The column that identifies the line item
The column that contains the key attribute

(Annotation: PresentationVariant/ LineItem, Property: initiallyVisibleColumns)

Email column in the pop-in area of the responsive table

Provide a column header text for each column. Do not truncate the column header text in default delivery (annotation: sap:label).

Column header text

Content Alignment and Formatting

The smart table automatically takes care of content alignment and formatting in standard use cases. For this, the OData metadata needs to provide the correct information about the data types, semantics of, and value help for the data.
(Annotations such as: sap:semantics, value: currency-code, edm types, Annotation: sap:display-format, value:Date, Annotation:Precision, Annotation: Scale, Annotation: ValueList, Annotation: ValueList:semantics, value:fixed-values)

Highlight Items

If the smart table is used with the responsive table, you can show the status of an item by displaying a highlight indicator in front of the item (property: highlight). The highlight indicator can be used to show:

A semantic state, such as red or orange for an error or warning
A neutral highlight, such as blue to highlight newly added items

Highlighted items

Actions

To trigger actions on multiple items, use a mutliselection smart table. Do not offer action triggering on multiple items if the table is expected to have fewer than 10 items in most cases.
While the grid table, analytical table, and tree table are multiselectable by default within the smart table, the responsive table is single-selectable. The selection mode can be changed (XMLView).

The following actions can be shown on the standard toolbar of the smart table:

Edit
Toggles the table between edit and read-only mode. This only works if smart fields are used inside the smart table (sap.ui.comp.smarttable.SmartTable, properties:editTogglable, smartToggle, aggregation: customData, key: useSmartField).

View Settings
This button opens the P13n dialog. Note that the P13n dialog is quite complex. Neither the simpler view settings dialog nor the table personalization dialog can be used without the app development team developing the entire view settings handling (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).

Export to Spreadsheet
Only use this option if your end users typically export the data shown in the table in order to work with it in a spreadsheet application. This is usually the case if data is collected from several systems and analyzed in the spreadsheet application. This is not usually the case for worklists, attachment lists, lists with only a few items, shopping carts, or data that does not need to be analyzed. This option is only available if the corresponding back end supports exporting to spreadsheet (sap.ui.comp.smarttable.SmartTable, property: useExportToExcel).

If additional actions are needed, use a custom toolbar for the table. The smart table can also add integrated functionality such as a table title, item count, variant management, edit and view settings, and export to spreadsheet to the custom toolbar (aggregation: customToolbar).

For navigation to line item details:

If used with the responsive table, use the navigation mode of the responsive table.
If used with the grid table, analytical table, or tree table, use a link for the attribute that identifies the row. The user can click this link to trigger the navigation.

Clicking a table row can trigger drill-in navigation to a deeper level of the object, as well as cross-navigation to another SAP Fiori app or even to another system.

Inline Actions

Actions that belong to single items can be placed within the row. They can be displayed as text or icons. Make sure the icon communicates the function clearly enough. Otherwise, use a textual button.

Editable Content

The smart table can be editable or read-only (sap.ui.comp.smarttable.SmartTable, property: editable).

The smart table selects the corresponding editable controls automatically based on the data type, semantic annotations, and value list annotations (annotations such as: sap:semantics, value: currency-code, edm types, Annotation: sap:display-format, value:Date, Annotation:Precision, Annotation: Scale, Annotation: ValueList, Annotation: ValueList:semantics, value:fixed-values).

If an edit mode is needed, the controls are automatically switched from read-only controls (such as text) to editable controls (such as input field or date picker) if smart fields are used inside the smart table (sap.ui.comp.smarttable.SmartTable, Property:editTogglable, smartToggle, aggregation: customData, key: useSmartField). The keyboard behavior is switched accordingly, if this is used together with the responsive table.

Only use this if you need to toggle between both modes. In any other case, show only the mode you need (read-only or edit), but do not offer the switch.

View Settings: Sort, Filter, Group, and Column Settings

If view settings are enabled on the smart table, a settings button is available on the table toolbar. This button opens the P13n dialog. Neither the simpler view settings dialog nor table personalization dialog can be used without extra effort (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).

The P13n dialog always enables the user to show, hide, and rearrange columns. Alternatively, it can contain settings for sorting, grouping, and/or filtering (annotations: sap:sortable, sap:filterable)

If the smart table uses the grid table, analytical table, or tree table, sort, filter, and group settings are also available in the column header menu.

Offer view settings only if they are really needed. For example, these settings do not make sense if the table contains only a few items and just a few columns.

Note that the P13n dialog is quite complex. It is ideal for tables with a vast number of items, but is quite cumbersome for handling just a few hundred items. Therefore, show only the settings (sort, group, filter) you really need. For example, do not offer grouping if it does not support your use case well.

If filtering is a main use case, do not offer filtering in the P13n dialog. Use the filter bar instead (annotation: sap:filterable)

Be persistent: When the app is reopened, the smart table is shown with the same view settings as last defined by the user (sap.ui.comp.smarttable.SmartTable, property: persistenceKey).

Sort

The current sort state is displayed as follows:

Using the responsive table, there is no indication that the table is currently sorted.
Using the grid table, analytical table, or tree table, an icon in the column header of the last sorted column indicates that the table is sorted and the direction in which it is sorted.

In default delivery, sort items in a meaningful order by the row-identifying column (usually the first column in default delivery). For example, use an alphabetical order for text, a numeric order for numbers, and a chronological order for dates (annotations: sap:sortable, PresentationVariant – SortOrder).

Filter

The current filter state is displayed as follows:

Using the responsive table, there is no indication that the table is currently filtered. The filter infobar can be added with additional effort.
Using the grid table, analytical table, or tree table, filtering is displayed by an icon on the column header of each filtered column (annotation: sap:filterable).

Group

Group headers display the current group state and are shown automatically. The following text should be shown on the group header:

[Label of the grouped column]: [Grouping value]
This can be done by the smart table, but only if the raw data from the model can be used. In other cases, app development teams must format the group header text. For example, the raw data carries IDs, while the table displays the corresponding names, which are provided by another data source. In this case, app developers must provide the formatting for the group header texts.

Within the responsive table, the grouped column keeps its visibility to reduce confusion after the group settings have been changed. If visible, it stays in the tabular layout even if grouped.

If used with the analytical table, grouping is not offered on measures. Therefore, you can have aggregations or grouping for a specific column.

Reasonable grouping can be offered by default via the property GroupBy.

Responsive table grouped by sales order ID

Aggregate

If used with the analytical table, aggregation settings can be provided on measure columns. These settings are only available in the column header menu.
To display the current aggregation state, the total sum of the corresponding column is shown at the bottom of the table.
If items are grouped, an intermediate sum is shown per group:

At the bottom of each group if the group is expanded.
In the group header if the group is collapsed.

Aggregations are only available on measures, but not on objects or attributes. If aggregation is enabled for a column, this column cannot be grouped.

Avoid aggregations on the first three columns for the default delivery. When grouping is used together with aggregations, collapsing a group shows the aggregation on the group header. This conflicts with the group name.

Where appropriate, offer reasonable aggregation by default (annotation: sap:aggregation-role, value: measure).

Column Settings

Only offer column settings if you need more columns than a tablet screen can display at a time (usually more than five).

If sorting, grouping, and/or filtering are needed, column settings must also be shown (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).

Add, Remove, Rearrange Columns

Use the P13n dialog to add, remove, and rearrange columns.

When used with the grid table, analytical table, or tree table, columns can also be rearranged by dragging and dropping the column header (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).

Resize Columns

When used with the grid table, analytical table, or tree table, columns can be resized on the column header (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).

Freeze Columns

When used with the grid table, analytical table, or tree table, app developers must manually add the options for freezing columns to the column header menu if necessary. They can do this by declaring the corresponding table inside the smart table in the XML view, and by using the corresponding settings on this inner table.

Selecting Freeze on a column freezes all columns from the first one to the one on which Freeze is selected. The menu entry on this column changes from Freeze to Unfreeze.

Properties

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

The property: ignoreFields defines the columns that are not available on the UI – neither in the initial visible columns nor in the P13n dialog.
The property: requestAtLeastFields can be used for requesting additional technical columns.
The property: ignoreFromPersonalization removes columns from the P13n dialog.
The property: toolbarStyleClass is deprecated. Do not use it.
The property: enableCustomFilter allows the filter menu item in the column header menu to be exchanged.
The property: useOnlyOneSolidToolbar is deprecated. Do not use it.
The property: currentVariantId defines the currently used variant.
The property: enableAutoBinding fetches the data automatically as soon as the corresponding OData model is initialized and the smart table is created.
The property: tableBindingPath defines the path from which the data is fetched.
The property: smartToggle influences the way on which controls are displayed in the smart table if smart fields are used.

The following aggregations are available:

The aggregation: semanticObjectController is used to customize smart links inside the smart table.
The aggregation: noData provides a text in case the table contains no line items. For example, this can be the case if the table is filtered. The text should provide context-specific instructions on how to get data into the table.

Resources

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

Elements and Controls

Responsive Table (guidelines)
Grid Table (guidelines)
Analytical Table (guidelines)
Tree Table (guidelines)
Table Overview (guidelines)
Table Toolbar (guidelines)
Variant Management (guidelines)
P13n-Dialog (guidelines)

Implementation

Smart Table (SAPUI5 samples)
Smart Table (SAPUI5 API reference)
Smart Table (Developer Guide)
P13n-Dialog (SAPUI5 samples)
P13n-Dialog (SAPUI5 API reference)
Toolbar (SAPUI5 samples)

Smart Filter Bar

Intro

Information

This article is intended as an aid to designers and developers who want to explore the detail configuration options available for the smart filter bar.

The developer can use annotation properties in the classes [external_only]ControlConfiguration and GroupConfiguration to adapt the filter bar for the purposes of the app.

These annotations let you:

Determine the type of control (for example, whether a field is shown as a multi-input field or as a date picker)
Enable the autocomplete suggestions feature
Enable the value help dialog
Overwrite settings from the OData service
Set custom filter groups
Add custom fields
Access all settings for the underlying filter bar

You can also use all the configuration options described here in the smart filter bar for the list report SAP Fiori element.

Warning

Most of the attributes/properties are not dynamic and cannot be changed once the control has been initialized.

Usage

Use the smart filter bar if:

An OData service is available.
You want to develop quickly and efficiently.

Do not use the smart filter bar if:

You need to make extensive changes to the filter bar.

Components

You can use the annotation properties listed below to influence how filters are rendered in the expanded filter bar and in the filter dialog.

Expanded Filter Bar

Properties for the expanded filter bar

1 enableBasicSearch
Defines whether the filter bar includes a basic search. By default, the basic search is not included.

2 FilterRestrictions/NonFilterableProperties
Defines whether a property is available as a filter criterion.

3 FilterRestrictions/RequiredProperties
Defines the filter field as a mandatory filter. Mandatory filters are marked by an asterisk (*).

4 ValueList
Contains annotations that provide information for rendering a value help list that has been set for a property.

5 FilterExpressionType/MultiValue
Defines whether multiple values can be used in a single filter.

6 FilterExpressionType/SingleValue
Restricts the filter to allow only one value entry.

7 LineItem/Label
A short, human-readable text for the filter name.

8 FilterExpressionType/SingleInterval
Restricts the filter to a specified interval, such as a date interval

8 insertDefaultFilterValue
Inserts a default filter value into the aggregation defaultFilterValues.

9 liveMode
Defines whether the expanded filter bar is shown in live mode (no Go button) or in manual mode. By default, the filter bar is shown in manual mode.

Filter Dialog

Properties on the filter dialog

1 FilterRestrictions/RequiredProperties
Defines the filter field as a mandatory filter. Mandatory filters are marked by an asterisk (*).

2 FieldControlType/Hidden
Defines whether the filter is initially visible on the expanded filter bar.

3 SelectionFields
Defines whether a filter belongs to the basic group. All filters in the basic group are initially visible on the expanded filter bar.

4 FieldGroup
Defines whether a filter field is initially shown on the filter dialog, and which group it belongs to.

5 FilterRestrictions/NonFilterableProperties
Defines whether a property is available as a filter criterion.

6 LineItem/Label
A short, human-readable text for the filter name.

Fiscal annotations

As an example, the smart filter bar supports fiscal annotations, like i.e. for fiscal period / data / time information. Such annotations guarantee the correct rendering of such values.

Smart filter bar with filters based on fiscal annotations

Recently entered values

The smart filter bar provides a history of recently entered values in the smart filter field. When focusing a field, an app can provide a small amount of recently used values. They are shown below the recommended items, which could appear at the same time. All values are shown if the drop-down is opened. Start typing will work like before, where the recently used values are filtered accordingly.

IN / OUT Parameter

In the smart filter bar, a drop-down or suggestion list can only contain a sub-set of items in case a dependent filter is set (IN parameter). It is also possible that selecting a value in a drop-down or suggestion list fills the current plus additional filter fields (OUT parameter).

Data Types

The tables below tell you which input controls are used for the key data types.

General Data Types

DataType	ODataMetadata	Additional Configuration	Edit type	Display type	Notes
*	*		Input	Text
DateTime	–	sap:display-format=”Date”	DatePicker	Text
Decimal	–	Precision=”3″ Scale=”0″	Input	Text
All	–		Input (with VHD)	Text	If a matching ValueList annotation is found, the ValueHelp for the Input is enabled. A ValueHelp Dialog is created automatically, based on the data in the ValueList annotation.
All	–	sap:semantics=”fixed-values” on the ValueList entity	ComboBox	Text	If a matching ValueList annotation is found, and the ValueList entity has the semantics=”fixed-values”, a dropdown list is shown.

Filter Bar-Specific Data Types

Input Type	sap:filter-restriction	display-format	hasValueHelpDialog	controlType	Resulting Control Type
*	*		controlType/filterType is specified		As specified in additional configuration
DateTime	“interval”	“Date”	NA		Date Range Selection
DateTime	“anything other than interval” or empty	“Date”	NA		Date Picker
String	“single-value”		“true” / none		Input Field With Value Help Dialog (with typeAhead according to hasTypeAhead flag)
String	“single-value”		“false”	not specified/input	Input Field (with typeAhead according to hasTypeAhead flag)
String	“single-value”		“false”	dropDownList; hasTypeAhead is not considered here	ComboBox
*	“single-value”				Input Field
String	empty or no filter-restriction		“true” / none		Multi Input Field with Value Help Dialog
String	“multi-value”		“true” / none		If no VL Annotation is found – only show the range selection part
String	“multi-value” / empty		“false”		If no VL Annotation is found – hide the ValueHelpDialog icon
String	“multi-value” / empty		“false”	dropDownList	MultiComboBox
*	“multi-value”				Input Field
*	“interval”		NA		A single Input Field that allows the “-” shortcut notation for intervals

Guidelines

Reduced set of table columns for the tabular suggestion

You have the option to define different columns in the table of the Value Help Dialog and the suggestion list of the Smart Filter Bar.

In the , each parameter can be statically annotated as important using the <code>Importance</code> annotation with EnumMember set to High:

<Annotation Term="com.sap.vocabularies.UI.v1.Importance"
EnumMember="com.sap.vocabularies.UI.v1.ImportanceType/High" />

In the suggestion list only the important parameters are displayed as columns, while in the table of the Value Help Dialog all of the parameters are displayed.

The Importance annotation is optional – if omitted all of the parameters are displayed in both table of the Value Help Dialog and the suggestion list of the Smart Filter Bar.

Formatting option for negative numbers

A new OData type NumericText improves the display-format=”NonNegative” of numeric fields. All values containing only 0, for example, „0“, „00“, „000“ etc., are interpreted and displayed as empty.

Resources

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

Elements and Controls

Filter Bar (guidelines)

Implementation

Smart Filter Bar (SAPUI5 samples)
Smart Filter Bar (SAPUI5 API reference)
Filter Bar (SAPUI5 samples)
Filter Bar (SAPUI5 API reference)

UI Development Toolkit (SAPUI5 samples)

Dynamic Date

Information

The dynamic date control can only be used in the smart filter bar. If you are not using the smart filter bar, use the date range selection control instead.

Usage

Use the dynamic date control if:

You need flexibility between fixed and dynamic dates.
You need dynamic dates that can be saved in the variant management (for example, show values from today regardless of when you open the app).
You are using the smart filter bar.
The user only needs to select one value.

Do not use the dynamic date control if:

Users need to enter a date and a time. In this case, use the date picker or the date/time picker instead.
Selecting ranges is not the user’s primary goal. In this case, use the simple date picker.
You are not using the smart filter bar.

Responsiveness

Value help for dynamic date range - Size S

Value help for dynamic date range - Size L

Components

The dynamic date consists of two components: the date input field with suggestions, and the value help popover. On all devices, users can either use the input field to type a date, or use the value help button to open the popover.

The two clickable areas of the dynamic date control on all devices

Dynamic Date Input Field

The user can type data directly into the input field. Upon user input, a list of suggestions appears.

Value Help Popover

The value help popover offers all available values the user can choose from. Depending on the selected time period, the popover shows different controls. It either shows an input field (1), one or two date pickers (2), a read-only text with the chosen time period and date range (3), or a select control.

The different options for defining time period values

Values Offered

From
To
Date Range
Today
Today -X / +Y days
Last X days
Next X days
This week
Last week
Last X weeks

Offered Values

Next week
Next X weeks
Month
This month
Last month
Last X months
Next X months
This quarter
Last quarter
Last X quarters
Next quarter

Offered Values

Next X quarters
First quarter
Second quarter
Third quarter
Fourth quarter
This year
Last year
Last X years
Next year
Next X years
Year to date

Behavior & Interaction

Typing data into the date range input field

List of suggestions shown after typed input

Opening the value help and selecting a time period

Opening the value help popover and selecting a time period

Defining a custom time period (X)

Custom time period with a simple input field

Selecting a date range

Selected time period with two date pickers (start date and end date)

Styles

Validation

Use inline validation to give the user feedback, especially for errors and warnings. The possible states are “warning”, “error”, and “success”.

Visible frame that shows an error when the field is out of focus

Error state with meaningful text - the date range input field is in focus

Guidelines

See the Date Picker and Date Range Selection articles for the guidelines. They also apply to the dynamic date control.

List of Options

Only provide values that are relevant for the use case in the list of options.
You can also add your own values, if necessary.
If you use your own values, provide human readable text.

Resources

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

Elements and Controls

Date Picker (guidelines)
Input Field (guidelines)
Select (guidelines)

Implementation

Date Picker (SAPUI5 samples)
Input (SAPUI5 samples)
Select (SAPUI5 samples)
Smart Controls (SAPUI5 samples)

Smart Filter Bar (SAPUI5 API reference)

Smart Table

Warning

Intro

The smart table is a wrapper around existing tables, and can be used together with the responsive table, grid table, analytical table, or tree table.

Usage

Use the smart table if:

Data is fed into the table through OData services.
You need a simple table with limited flexibility to display its content. In this case, the smart table reduces development effort.
You need a table in which some columns provide flexible content. In this case, use the smart table together with a responsive table, and provide app-specific column definitions for these columns.

Do not use the smart table if:

You create your own UI coding, whereby the data is not fed through OData services. In this case, use the underlying table control directly.
The main use case involves selecting one item from very few items, with no additional details. In this case, a select or combo box might be more suitable.
The main use case involves selecting one item from several items, with only a few details per item. In this case, a list might be more suitable. Pay attention to the layout of the list item to provide a pleasant appearance (see, for example, the master list and the feed list item).
The table is displayed together with a chart inside a chart container. The smart table is not designed to work inside an existing chart container. In this case, use the underlying table control directly.
You need an overview of a large amount of data. In this case, use charts.
You just need it for layout reasons. In this case, use a layout container, such as the grid layout, instead.
You need read-only or editable field value pairs. In this case, use a form instead. Tables are not optimized for form-like input navigation.

Responsiveness

The responsiveness of the smart table depends on the encapsulated table. The table toolbar uses the overflow mechanism for adapting to the screen width.

Using the responsive table

The smart table offers generic responsive behavior (sap.ui.comp.smarttable.SmartTable, property: demandPopin, value: true):

For every 10 rem of screen width, one column stays in the tabular layout. All others are moved to the pop-in area. The columns are moved to the pop-in area from right to left, so the column furthest to the right moves to the pop-in first.
Exception: The first two columns always stay in the tabular layout. This works best if the smart table uses the whole screen width. It might not work well if the smart table uses far less space.

Using the grid table, analytical table, or tree table

The smart table works only on desktop and tablets, but not on smartphones. It supports touch devices, but is not optimized for small screens.
If you use a smart table in this configuration, ensure that you implement a fallback solution for small screens. This fallback solution does not need to support all use cases. You could create a fallback by using a responsive table. However, a completely different solution, such as showing charts in a read-only case, might be more suitable.

Size S with responsive table

Size M with responsive table

Size L with responsive table

Size M with grid table

Size L with grid table

Layout

Schematic visualization of the smart table

Components

The title bar consists of a toolbar.

The table area consists of any of the following tables: responsive table, grid table, analytical table, or tree table.

Standard toolbar with everything enabled

Standard toolbar just with title and item count

Behavior and Interaction

Table Level

Table Type

The smart table can encapsulate the responsive table, grid table, analytical table, or tree table. (sap.ui.comp.smarttable.SmartTable, property: tableType)

Automatic Rendering of the Table

The smart table automatically creates columns and renders all items based on the metadata of the underlying OData service (sap.ui.comp.smarttable.SmartTable, property: smartFilterId).

No Data

If there is no data to show, the smart table renders default text. This text can be overwritten by the app development team (aggregation: NoData).

Initially Visible Columns

Persistency

Removing Columns

The smart table always shows all columns from the OData model. In some cases, columns needs to be in the model but should not be available on the front end at all. Examples of this include:

A column is needed to provide an ID which is used for navigation purposes, but the front end should only display the corresponding text, not the ID.
The values of a column are needed to perform calculations, but only the results should be shown on the UI.

P13n/personalization dialog

Filter Settings

The “Show Field as Column” option for newly added filters is switched on by default.

Sorting and Filtering

Column header menu of the grid table

Smart Table and Smart Filter Bar

The smart table can be linked to a smart filter bar. If linked, filter bar settings are automatically used on the smart table. (sap.ui.comp.smarttable,SmartTable, property:smartFIlterId)

Aggregation

If used with the analytical table, the smart table allows total sums of measure columns to be calculated. The totals are shown in the usual way:

As the last row of the analytical table.
As the last row of each group if the group is expanded.
On the group header of each group if the group is collapsed.

Aggregation settings are not persisted (annotation: sap:aggregation-role, value:measure).

The total can be hidden via the column header menu.

Aggregation entry in column header menu of the grid table

Aggregation of Different Currencies

If used with the analytical table, the smart table also allows you to display totals for amount columns with different currencies.

In this case, a Show Details link is displayed instead of the total. Clicking the link opens a popover showing the subtotals per currency.

Exception: If a group contains only one currency, the total is shown directly.

Totals for a column which contains amounts in different currencies

Column Width

Column Header

A column header text can be specified for each column (annotation: sap:label).

Persistence

The smart table allows you to persist sort, group, and filter column settings (such as by hidden columns) as well as variants (sap.ui.comp.smarttable.SmartTable, Property:persistenceyKey).

Content

The smart table provides two options to create columns automatically:

The smart table is rendered in either read-only or edit mode. In this case, the smart table renders the controls as described below. This is the default way of rendering content (property: editable)
If users need to switch between read-only and edit mode at runtime, the smart table allows smart fields to be rendered instead. You should use this if the edit button is added to the toolbar of the smart table (aggregation: customData key: useSmartField, property: smartToggle).

For option 1, the following controls are used:

To show currency amounts, the smart table allows the amount and the currency code to be displayed in a single cell. For read-only mode, the currency control is used. For edit mode, a single input field is used, and the currency itself is shown next to the input field as non-editable text (annotation: sap:semantics, value: currency-code).
To show links that open a quick view, the smart table supports the smart link.
To show static text, the smart table uses an input field in edit mode, and a text in read-only mode.
To show dates, the smart table uses a date picker in edit mode, and a text in read-only mode (annotation: sap:display-format, value:Date).
To show decimal numbers, the smart table uses an input field in edit mode, and a text in read-only mode (Annotations:Precision, Scale).
The smart table also provides an object status and object identifier control. For more information, see object display components.
Pictures and microcharts, as well as rating indicators and progress bars are available.

Amount formatting

Link formatting

Date formatting

Value Help

The smart table supports value help in the following ways (annotation: ValueList):

Input fields can show a value help button. Triggering this button opens a value help dialog. Within this dialog, you can provide a search field (annotation:ValueList, property: SearchSupported).
You can restrict the number of characters for the input field. Use this if no ValueList annotation is provided (annotation:MaxLength).

Toolbar Level

Table Title

The smart table can provide a title for the table within the toolbar (sap.ui.comp.smarttable.SmartTable, Property:header).

Table title

Item Count

Next to the table title, an item count can be shown (sap.ui.comp.smarttable.SmartTable, Property:showRowCount).

Table title with item count

Edit

If used with the responsive table, the edit button also switches the keyboard behavior accordingly.

Edit button

View Settings

Settings button

Export to Spreadsheet

With the back-end export, the following columns are exported: currently visible columns, “technical columns” that are in the data model but not visible to the user, and usually some (but not all) of the columns that are currently hidden. In the spreadsheet file, neither the columns nor the rows are in the same order as in the exporting app. The exported file might also show different column header texts.
When the user triggers the export, the corresponding file is created in the background and offered for download automatically. The export process cannot be canceled. This option is only available if the back-end export is supported in the corresponding back-end system.
With the front-end export (default and recommended), only visible columns are exported. In the exported file, columns are in the same order and have the same header texts as in the exporting app. During the export, the system displays a progress dialog that blocks the UI. The export can be canceled at any time. As soon as the file has been created, it is offered for download automatically. The front-end export is always available.

Warning

With both methods, the file size is limited by the available browser memory. Exporting large tables can therefore lead to memory overflows and browser crashes.

For larger tables, consider using custom-built, specialized export solutions instead.

'Export to Spreadsheet' button

Exporting to Spreadsheet

Full Screen Mode

Applications can implement a maximize button to run the table in full screen (Property: showFullScreenButton).

Maximize button

Footer Toolbar Level

Use button styles only to help the user and not for decoration. For instance, emphasize the most important action. Use only one emphasized button, and never mix emphasized and semantic buttons.

Guidelines

Table Type

For more information about the different table controls, see the corresponding articles.

Table Title, Item Count, and Variant Management

Even if variant management is easy to implement, use it only if it is really needed. The variant management saves the whole page, including filter settings and table layouts.

Empty Tables

Try not to display an empty table. If there is no way around this, provide instructions on how to fill the table with data (aggregatrion: noData).

The following default texts are provided automatically:

If the smart table is used standalone (without an attached smart filter bar) and it is initially empty (not yet bound), the default text is:
No items available.
Overwrite this whenever a hint can be provided on how to fill the table with data.
If the smart table is used with a smart filter bar attached, and it is initially empty (not yet bound), the default text is:
No filters set. To start, enter your search and filter settings and run the search.
If a smart table is bound but there is no data to display from the binding, the default text is:
No items found. Check the search and filter settings.
Overwrite this whenever this text is either not precise enough (for example, only search is offered) or misleading (for example, if the data is filled based on a master-detail pattern instead of search and filter settings).

Columns – Best Practices

Keep the number of initially shown columns to a minimum. Avoid the need to scroll horizontally on a tablet screen size in default delivery (annotation: PresentationVariant/ LineItem).

For the grid table, analytical table, and tree table, the column widths are calculated automatically if the corresponding OData annotations are provided (annotations: MaxLength, Precision, Scale).

In contrast, the responsive table uses the same width for all columns.

If used with the responsive table, enable the pop-in behavior (sap.ui.comp.smarttable.SmartTable, property: smartFilterId, value: true).

The column that identifies the line item
The column that contains the key attribute

(Annotation: PresentationVariant/ LineItem, Property: initiallyVisibleColumns)

Email column in the pop-in area of the responsive table

Provide a column header text for each column. Do not truncate the column header text in default delivery (annotation: sap:label).

Column header text

Content Alignment and Formatting

Highlight Items

A semantic state, such as red or orange for an error or warning
A neutral highlight, such as blue to highlight newly added items

Highlighted items

Actions

The following actions can be shown on the standard toolbar of the smart table:

Edit
Toggles the table between edit and read-only mode. This only works if smart fields are used inside the smart table (sap.ui.comp.smarttable.SmartTable, properties:editTogglable, smartToggle, aggregation: customData, key: useSmartField).

View Settings
This button opens the P13n dialog. Note that the P13n dialog is quite complex. Neither the simpler view settings dialog nor the table personalization dialog can be used without the app development team developing the entire view settings handling (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).

Export to Spreadsheet
Only use this option if your end users typically export the data shown in the table in order to work with it in a spreadsheet application. This is usually the case if data is collected from several systems and analyzed in the spreadsheet application. This is not usually the case for worklists, attachment lists, lists with only a few items, shopping carts, or data that does not need to be analyzed. This option is only available if the corresponding back end supports exporting to spreadsheet (sap.ui.comp.smarttable.SmartTable, property: useExportToExcel).

For navigation to line item details:

If used with the responsive table, use the navigation mode of the responsive table.
If used with the grid table, analytical table, or tree table, use a link for the attribute that identifies the row. The user can click this link to trigger the navigation.

Clicking a table row can trigger drill-in navigation to a deeper level of the object, as well as cross-navigation to another SAP Fiori app or even to another system.

Inline Actions

Actions that belong to single items can be placed within the row. They can be displayed as text or icons. Make sure the icon communicates the function clearly enough. Otherwise, use a textual button.

Editable Content

The smart table can be editable or read-only (sap.ui.comp.smarttable.SmartTable, property: editable).

Only use this if you need to toggle between both modes. In any other case, show only the mode you need (read-only or edit), but do not offer the switch.

View Settings: Sort, Filter, Group, and Column Settings

If the smart table uses the grid table, analytical table, or tree table, sort, filter, and group settings are also available in the column header menu.

Offer view settings only if they are really needed. For example, these settings do not make sense if the table contains only a few items and just a few columns.

If filtering is a main use case, do not offer filtering in the P13n dialog. Use the filter bar instead (annotation: sap:filterable)

Be persistent: When the app is reopened, the smart table is shown with the same view settings as last defined by the user (sap.ui.comp.smarttable.SmartTable, property: persistenceKey).

Sort

The current sort state is displayed as follows:

Using the responsive table, there is no indication that the table is currently sorted.
Using the grid table, analytical table, or tree table, an icon in the column header of the last sorted column indicates that the table is sorted and the direction in which it is sorted.

Filter

The current filter state is displayed as follows:

Using the responsive table, there is no indication that the table is currently filtered. The filter infobar can be added with additional effort.
Using the grid table, analytical table, or tree table, filtering is displayed by an icon on the column header of each filtered column (annotation: sap:filterable).

Group

Group headers display the current group state and are shown automatically. The following text should be shown on the group header:

Within the responsive table, the grouped column keeps its visibility to reduce confusion after the group settings have been changed. If visible, it stays in the tabular layout even if grouped.

If used with the analytical table, grouping is not offered on measures. Therefore, you can have aggregations or grouping for a specific column.

Reasonable grouping can be offered by default via the property GroupBy.

Responsive table grouped by sales order ID

Aggregate

At the bottom of each group if the group is expanded.
In the group header if the group is collapsed.

Aggregations are only available on measures, but not on objects or attributes. If aggregation is enabled for a column, this column cannot be grouped.

Where appropriate, offer reasonable aggregation by default (annotation: sap:aggregation-role, value: measure).

Column Settings

Only offer column settings if you need more columns than a tablet screen can display at a time (usually more than five).

If sorting, grouping, and/or filtering are needed, column settings must also be shown (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).

Add, Remove, Rearrange Columns

Use the P13n dialog to add, remove, and rearrange columns.

Resize Columns

When used with the grid table, analytical table, or tree table, columns can be resized on the column header (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).

Freeze Columns

Selecting Freeze on a column freezes all columns from the first one to the one on which Freeze is selected. The menu entry on this column changes from Freeze to Unfreeze.

Properties

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

The property: ignoreFields defines the columns that are not available on the UI – neither in the initial visible columns nor in the P13n dialog.
The property: requestAtLeastFields can be used for requesting additional technical columns.
The property: ignoreFromPersonalization removes columns from the P13n dialog.
The property: toolbarStyleClass is deprecated. Do not use it.
The property: enableCustomFilter allows the filter menu item in the column header menu to be exchanged.
The property: useOnlyOneSolidToolbar is deprecated. Do not use it.
The property: currentVariantId defines the currently used variant.
The property: enableAutoBinding fetches the data automatically as soon as the corresponding OData model is initialized and the smart table is created.
The property: tableBindingPath defines the path from which the data is fetched.
The property: smartToggle influences the way on which controls are displayed in the smart table if smart fields are used.

The following aggregations are available:

The aggregation: semanticObjectController is used to customize smart links inside the smart table.
The aggregation: noData provides a text in case the table contains no line items. For example, this can be the case if the table is filtered. The text should provide context-specific instructions on how to get data into the table.

Resources

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

Elements and Controls

Responsive Table (guidelines)
Grid Table (guidelines)
Analytical Table (guidelines)
Tree Table (guidelines)
Table Overview (guidelines)
Table Toolbar (guidelines)
Variant Management (guidelines)
P13n-Dialog (guidelines)

Implementation

Smart Table (SAPUI5 samples)
Smart Table (SAPUI5 API reference)
Smart Table (Developer Guide)
P13n-Dialog (SAPUI5 samples)
P13n-Dialog (SAPUI5 API reference)
Toolbar (SAPUI5 samples)

Smart Filter Bar Annotations

Warning

This guideline was written for release 1.52 and is no longer updated. For the latest design guidelines on the filter bar, see Filter Bar.

Background:
As of guideline release 1.54, the SAP Fiori Design Guidelines contain only general guidelines for all implementations. These guidelines also apply for implementations using smart controls. You can still use the smart filter bar, but the exact features will no longer be updated in the design guidelines.

Intro

Information

This article is intended as an aid to designers and developers who want to explore the detail configuration options available for the smart filter bar.

The smart filter bar is a wrapper that analyzes a given OData service and renders a filter bar based on the content defined by the service. For example, the OData service determines whether a field is visible on the filter bar, and whether it supports type-ahead and value help. To configure more settings or overwrite the settings from the OData service, the developer can set additional annotations in an external document (metadata.xml).

Developers can use annotation properties in the classes [external_only]ControlConfiguration and GroupConfiguration to adapt the filter bar for the purposes of the app.

These annotations let you:

Determine the type of control (for example, whether a field is shown as a multi-input field or as a date picker)
Enable the autocomplete suggestions feature
Enable the value help dialog
Overwrite settings from the OData service
Set custom filter groups
Add custom fields
Access all settings for the underlying filter bar

You can also use all the configuration options described here in the smart filter bar for the list report SAP Fiori element.

Warning

Most of the attributes/properties are not dynamic and cannot be changed once the control has been initialized.

Usage

Use the smart filter bar if:

An OData service is available.
You want to develop quickly and efficiently.

Do not use the smart filter bar if:

You need to make extensive changes to the filter bar.

Components

You can use the annotation properties listed below to influence how filters are rendered in the expanded filter bar and in the filter dialog.

Expanded Filter Bar

Smart filter bar - Properties for the expanded filter bar

1 enableBasicSearch

Defines whether the filter bar includes a basic search. By default, the basic search is not included.

2 FilterRestrictions/NonFilterableProperties

Defines whether a property is available as a filter criterion.

3 FilterRestrictions/RequiredProperties

Defines the filter field as a mandatory filter. Mandatory filters are marked by an asterisk (*).

4 ValueList

Contains annotations that provide information for rendering a value help list that has been set for a property.

5 FilterExpressionType/MultiValue

Defines whether multiple values can be used in a single filter.

6 FilterExpressionType/SingleValue

Restricts the filter to allow only one value entry.

7 LineItem/Label

A short, human-readable text for the filter name.

8 FilterExpressionType/SingleInterval

Restricts the filter to a specified interval, such as a date interval.

8 insertDefaultFilterValue

Inserts a default filter value into the aggregation defaultFilterValues.

9 liveMode

Defines whether the expanded filter bar is shown in live mode (no Go button) or in manual mode. By default, the filter bar is shown in manual mode.

Filter Dialog

1 FilterRestrictions/RequiredProperties

Defines the filter field as a mandatory filter. Mandatory filters are marked by an asterisk (*).

2 FieldControlType/Hidden

Defines whether the filter is initially visible on the expanded filter bar.

3 SelectionFields

Defines whether a filter belongs to the basic group. All filters in the basic group are initially visible on the expanded filter bar.

4 FieldGroup

Defines whether a filter field is initially shown on the filter dialog, and which group it belongs to.

5 FilterRestrictions/NonFilterableProperties

Defines whether a property is available as a filter criterion.

6 LineItem/Label

A short, human-readable text for the filter name.

SmartFilterBar Properties on the Filter Dialog

Data Types

The smart filter bar analyzes and interprets the metadata provided by the OData service. This allows you to create complex UI entities, and to automatically add fields offered by the OData service to the filter bar as editable input fields. (Note that only fields marked with sap:filterable are added automatically.)

The tables below tell you which input controls are used for the key data types.

General Data Types

DataType ODataMetadata Additional Configuration Edit type Display type Notes

* * Input Text

DateTime – sap:display-format=”Date” DatePicker Text

Decimal – Precision=”3″ Scale=”0″ Input Text

All – Input (with VHD) Text If a matching ValueList annotation is found, the ValueHelp for the Input is enabled.
A ValueHelp Dialog is created automatically, based on the data in the ValueList annotation.

All –
sap:semantics=”fixed-values” on the ValueList entity
ComboBox Text If a matching ValueList annotation is found, and the ValueList entity has the semantics=”fixed-values”, a dropdown list is shown.

Filter Bar-Specific Data Types

Input Type sap:filter-restriction display-format hasValueHelpDialog controlType Resulting Control Type

* * controlType/filterType is specified As specified in additional configuration

DateTime “interval” “Date” NA Date Range Selection

DateTime “anything other than interval” or empty “Date” NA Date Picker

String “single-value” “true” / none Input Field With Value Help Dialog
(with typeAhead according to hasTypeAhead flag)

String “single-value” “false” not specified/input Input Field
(with typeAhead according to hasTypeAhead flag)

String “single-value” “false” dropDownList; hasTypeAhead is not considered here ComboBox

* “single-value” Input Field

String empty or no filter-restriction “true” / none Multi Input Field with Value Help Dialog

String “multi-value” “true” / none If no VL Annotation is found – only show the range selection part

String “multi-value” / empty “false” If no VL Annotation is found – hide the ValueHelpDialog icon

String “multi-value” / empty “false” dropDownList MultiComboBox

* “multi-value” Input Field

* “interval” NA A single Input Field that allows the “-” shortcut notation for intervals

Properties

FilterBar

Filter Bar Properties

persistencyKey
Data type: string
Key used to access personalization data.

advancedMode
Data type: boolean
The advanced mode overwrites the standard behavior and is used in the value help scenario.
Default value is false.

expandAdvancedArea
Data type: boolean
Defines whether the advanced area is expanded when the filter bar is used within the value help dialog.
Default value is false.

searchEnabled
Data type: boolean
Enables/disables the Search button in advanced mode.
Default value is true.

filterBarExpanded
Data type: boolean
Shows/hides the expanded filter bar.
Default value is true.

considerGroupTitle
Data type: boolean
If this property is set, the label for filters is prefixed with the group title.
Default value is false.

showClearButton
Data type: boolean
Handles visibility of the Clear button on the Filters dialog.
Default value is false.

showRestoreButton
Data type: boolean
Handles visibility of the Restore button on the Filters dialog.
Default value is true.

showGoOnFB
Data type: boolean
Handles visibility of the Go button on the filter bar.
Default value is true.

showRestoreOnFB
Data type: boolean
Handles visibility of the Restore button on the filter bar.
Default value is false.

showClearOnFB
Data type: boolean
Handles visibility of the Clear button on the filter bar.
Default value is false.

showGoButton
Data type: boolean
Handles visibility of the Go button on the filter bar.

deltaVariantMode
Data type: boolean
Stores the delta as compared to the standard variant.
Default value is true.

filterContainerWidth
Data type: string
Sets the width of the filter container.
Default value is 12rem.

useToolbar
Data type: boolean
Determines what design should be used. Default is the design with the toolbar. In mobile scenarios this property is ignored – the design with the toolbar is always used.
Default value is true.

header
Data type: string
Specifies the header text that is shown in the toolbar on the first position. This property is ignored, when useToolbar is set to false.

showFilterConfiguration
Data type: boolean
Handles visibility of the Filters button on the filter bar.
Default value is true.

Smart Filter Bar

Smart Filter Bar Properties

entitySet
Data type: string
The OData entity set whose metadata is used to create the SmartFilterBar. Note: Changing this value after the SmartFilterBar is initialized (initialize event was fired) has no effect.

basicSearchFieldName
Data type: string
Name of the field that has to be the focus of the basic search. This is only relevant for SmartFilterBar in combination with ValueHelpDialog.

enableBasicSearch
Data type: boolean
Enables the basic search field in the SmartFilterBar control. This must only be enabled for entities that support such search behavior.
Default value is false.

liveMode
Data type: boolean
Defines the live mode. The live mode only operates on non-phone scenarios.
Default value is false.

showMessages
Data type: boolean
If set to false, any errors that occur during the search will not be displayed in a message box.
Default value is true.

considerAnalyticalParameters
Data type: boolean
Indicates if the analytical parameters (SelectionVariant) must be taken into consideration.
Default value is false.

Smart Filter Bar Annotations

FilterRestrictions/NonFilterableProperties
Defines whether a Property can be used for filtering data.

FieldGroup
Defines a group for a filter field.

TextArrangement
Describes the arrangement of a code value and its text.

FieldControlType/Hidden
Defines whether the filter is visible.

ValueList
Contains annotations that provide information for rendering a ValueHelpList that has been set for a Property.

Label
A short, human-readable text for the filter name.

LineItem/Label
A short, human-readable text suitable for the filter name.

FilterRestrictions/RequiredProperties
Defines the filter field as mandatory filter.

FilterExpressionType/MultiValue
Defines whether multiple values can be used in a single filter.

FilterExpressionType/SingleValue
Restricts the filter to allow only one value entry.

FilterExpressionType/SingleInterval
Restricts the filter to a specified interval, such as a date interval.

SelectionFields
Defines whether certain fields should be initially visible in the SmartFilterBar control.

Control Configuration

Control Configuration Properties

key
The key property corresponds to the field name from the OData service metadata document.
Default value is string

groupId
The groupId can be used to move a field from one group to another. The groupId corresponds to the EntityName from the OData metadata. It is also possible to move a field from the advanced area to the basic area by specifying the groupId _BASIC.
Default value is string

label
You can use this property to overwrite the label of a filter field in the SmartFilterBar.
Default value is string

visible
Data type: boolean
You can use this flag to hide fields from the OData metadata.
Default value is true

hasValueHelpDialog
Data type: boolean
Specifies whether a value help dialog is available or not.
Default value is true

controlType
Data type: sap.ui.comp.smartfilterbar.ControlType
The SmartFilterBar calculates which kind of control will be used for a filter field, based on multiple OData attributes and annotations. You can use this property to overwrite the OData metadata.
Default value is auto

filterType
Data type: sap.ui.comp.smartfilterbar.FilterType
The filter type specifies whether the filter field is for a single value, multiple values, or an interval. The filter type calculated by the SmartFilterBar is based on the OData metadata. You can use this property to configure the filter type manually.
Default value is auto

index
Data type: int
You can use the zero-based index to specify the initial order of fields (without any variants).
Default value is -1

Control Configuration Properties

hasTypeAhead
Data type: boolean
You can use this property to enable the TypeAhead service. Note that TypeAhead does not work with all controls (for example, it is not supported for the DropDownListbox).
Default value is true

mandatory
Data type: sap.ui.comp.smartfilterbar.MandatoryType
You can use this property to overwrite the mandatory state of a filter field. This property can only be set during initialization. Changes at runtime will be ignored.
Default value is auto

width
Default value is string
The width of the filter field in a CSS compatible format. The width can be set only once during initialization. Changes at runtime will not be reflected. The width is not applied to custom controls.

visibleInAdvancedArea
Data type: boolean
If set to true, this field will be added to the advanced area (aka. Dynamic Selection) by default.
Default value is false

preventInitialDataFetchInValueHelpDialog
Data type: boolean
If value help annotations are available for this filter field, you can prevent the the table in the value help dialog for this field from being filled with the initial data fetch.
Default value is true

displayBehaviour
Data type: sap.ui.comp.smartfilterbar.DisplayBehaviour
The displayBehaviour specifies how to display the content on certain controls. For example: DescriptionOnly for Combobox (DropDown text), Description and ID for MultiInput (token text)
Default value is auto

conditionType
Data type: any
The condition Type class name to use for this filter item. Implementation should derive from sap.ui.comp.config.condition.Type.

Group Configuration

Group Configuration Properties

key
Data type: string
The key property shall correspond to the name EntityTypeName from the OData service $metadata document.

index
Data type: any
Zero-based integer index. The index can be used to specify the order of groups. If no index is specified, the order defined by the OData metadata will be used.
Default value is undefined

label
Data type: any
You can use this property to overwrite the label of a group in the advanced area of the SmartFilterBar.
Default value is undefined

Resources

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

Elements and Controls

Filter Bar/ Smart Filter Bar (guidelines)

Implementation

Smart Filter Bar (SAPUI5 samples)

Smart Filter Bar (SAPUI5 API reference)

UI Development Toolkit (SAPUI5 samples)

Smart Table

Warning
This guideline was written for release 1.52 and is no longer updated. For the latest design guidelines, see the corresponding table articles (Responsive Table, Grid Table, Analytical Table, Tree Table).

Background:
As of guideline release 1.54, the SAP Fiori Design Guidelines contain only general guidelines for all implementations. These guidelines also apply for implementations using smart controls. You can still use the smart table, but the exact features will no longer be updated in the design guidelines.

Intro

The smart table is a wrapper around existing tables, and can be used together with the responsive table, grid table, analytical table, or tree table.

The smart table creates columns automatically based on the underlying OData service plus corresponding annotations. It also adds some generic functionality, such as a toolbar, complex personalization settings, variant management, and export to spreadsheet.

Everything that can be done using the smart table can also be achieved using the responsive table, grid table, analytical table, or tree table directly, but with more development effort. Therefore, the main purpose of the smart table is to reduce development effort. However, this comes at the expense of decreased flexibility.

Usage

Use the smart table if:

Data is fed into the table through OData services.

You need a simple table with limited flexibility to display its content. In this case, the smart table reduces development effort.

You need a table in which some columns provide flexible content. In this case, use the smart table together with a responsive table, and provide app-specific column definitions for these columns.

Do not use the smart table if:

You create your own UI coding, whereby the data is not fed through OData services. In this case, use the underlying table control directly.

The main use case involves selecting one item from very few items, with no additional details. In this case, a select or combo box might be more suitable.

The main use case involves selecting one item from several items, with only a few details per item. In this case, a list might be more suitable. Pay attention to the layout of the list item to provide a pleasant appearance (see, for example, the master list and the feed list item).

The table is displayed together with a chart inside a chart container. The smart table is not designed to work inside an existing chart container. In this case, use the underlying table control directly.

You need an overview of a large amount of data. In this case, use charts.

You just need it for layout reasons. In this case, use a layout container, such as the grid layout, instead.

You need read-only or editable field value pairs. In this case, use a form instead. Tables are not optimized for form-like input navigation.

Responsiveness

The responsiveness of the smart table depends on the encapsulated table. The table toolbar uses the overflow mechanism for adapting to the screen width.

Using the responsive table

The smart table offers generic responsive behavior (sap.ui.comp.smarttable.SmartTable, property: demandPopin, value: true):

For every 10 rem of screen width, one column stays in the tabular layout. All others are moved to the pop-in area. The columns are moved to the pop-in area from right to left, so the column furthest to the right moves to the pop-in first.

Exception: The first two columns always stay in the tabular layout. This works best if the smart table uses the whole screen width. It might not work well if the smart table uses far less space.

Using the grid table, analytical table, or tree table

The smart table works only on desktop and tablets, but not on smartphones. It supports touch devices, but is not optimized for small screens.

If you use a smart table in this configuration, ensure that you implement a fallback solution for small screens. This fallback solution does not need to support all use cases. You could create a fallback by using a responsive table. However, a completely different solution, such as showing charts in a read-only case, might be more suitable.

Size S with responsive table
Size M with responsive table
Size L with responsive table
Size M with grid table
Size L with grid table

Layout

The title bar contains the title of the smart table, the item count, variant management, and the toolbar itself. All of these elements are optional.
The table area shows the corresponding table (responsive table, grid table, analytical table, or tree table).

Schematic visualization of the smart table

Components

The title bar consists of a toolbar.

This can be the standard toolbar or a custom toolbar. The standard toolbar can contain a title text with or without item count, variant management, view switch (switching the table to edit mode), an entry point for the P13n dialog, and an Export to Spreadsheet action.

If you require additional functionality, you can use an app-specific toolbar. All toolbar options provided by the smart table can also be added to the app-specific toolbar. (Aggregation: customToolbar)

The table area consists of any of the following tables: responsive table, grid table, analytical table, or tree table.

Standard toolbar with everything enabled
Standard toolbar just with title and item count

Behavior and Interaction

The behavior is generally inherited from the underlying table, toolbar, variant management, 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.

Table Level

Table Type

The smart table can encapsulate the responsive table, grid table, analytical table, or tree table. (sap.ui.comp.smarttable.SmartTable, property: tableType)

Automatic Rendering of the Table

The smart table automatically creates columns and renders all items based on the metadata of the underlying OData service (sap.ui.comp.smarttable.SmartTable, property: smartFilterId).

To be more flexible in the table layout, the smart table also offers app-specific column templates for some or all columns. In this case, app developers must provide the definition for the underlying table and for the corresponding (but not necessarily for all) columns in the XML view. For this, the app development team must provide the column keys of the overridden columns via custom data.

Additional columns can also be added. Columns that are defined in this way retain all the options of the underlying table. This is especially useful with the responsive table, which offers complete flexibility in content design. Any columns that are not defined by the app development team are still rendered automatically by the smart table.

No Data

If there is no data to show, the smart table renders default text. This text can be overwritten by the app development team (aggregation: NoData).

Initially Visible Columns

The smart table enables you to define which columns are initially shown. Here, initially means that these columns are shown when the app is first launched. All other columns are initially hidden (annotation: PresentationVariant/ LineItem, property: initiallyVisibleColumns).

Persistency

End users can show additional columns if table personalization is provided. In this case, column settings are persisted. On consecutive startups, the columns are shown with the same settings as last defined by the user (property: persistenceKey).

Removing Columns

The smart table always shows all columns from the OData model. In some cases, columns needs to be in the model but should not be available on the front end at all. Examples of this include:

A column is needed to provide an ID which is used for navigation purposes, but the front end should only display the corresponding text, not the ID.

The values of a column are needed to perform calculations, but only the results should be shown on the UI.

In these cases, you can define which columns should not be available at all on the UI. These columns are not shown and are not available in the P13n dialog. You can also do this for columns that are added manually in the XML view (annotation: sap:visible, value:false).

P13n/personalization dialog

Filter Settings

The “Show Field as Column” option for newly added filters is switched on by default.

Sorting and Filtering

The smart table allows you to add sort and filter settings for each column. These settings enable the corresponding pages in the P13n dialog. For the grid table, analytical table, and tree table, sorting and filtering are also enabled on the column header. (Annotations: sap:sortable and sap:filterable)

Column header menu of the grid table

Smart Table and Smart Filter Bar

The smart table can be linked to a smart filter bar. If linked, filter bar settings are automatically used on the smart table. (sap.ui.comp.smarttable,SmartTable, property:smartFIlterId)

Aggregation

If used with the analytical table, the smart table allows total sums of measure columns to be calculated. The totals are shown in the usual way:

As the last row of the analytical table.

As the last row of each group if the group is expanded.

On the group header of each group if the group is collapsed.

Aggregation settings are not persisted (annotation: sap:aggregation-role, value:measure).

The total can be hidden via the column header menu.

Aggregation entry in column header menu of the grid table

Aggregation of Different Currencies

If used with the analytical table, the smart table also allows you to display totals for amount columns with different currencies.

In this case, a Show Details link is displayed instead of the total. Clicking the link opens a popover showing the subtotals per currency.

Exception: If a group contains only one currency, the total is shown directly.

Totals for a column which contains amounts in different currencies

Column Width

A default column width is calculated for each column based on the data displayed in it. Important: end users cannot change the column width in the responsive table (annotations: MaxLength, Precision, Scale).

Column Header

A column header text can be specified for each column (annotation: sap:label).

Persistence

The smart table allows you to persist sort, group, and filter column settings (such as by hidden columns) as well as variants (sap.ui.comp.smarttable.SmartTable, Property:persistenceyKey).

Content

The smart table provides two options to create columns automatically:

The smart table is rendered in either read-only or edit mode. In this case, the smart table renders the controls as described below. This is the default way of rendering content (property: editable)

If users need to switch between read-only and edit mode at runtime, the smart table allows smart fields to be rendered instead. You should use this if the edit button is added to the toolbar of the smart table (aggregation: customData key: useSmartField, property: smartToggle).

For option 1, the following controls are used:

To show currency amounts, the smart table allows the amount and the currency code to be displayed in a single cell. For read-only mode, the currency control is used. For edit mode, a single input field is used, and the currency itself is shown next to the input field as non-editable text (annotation: sap:semantics, value: currency-code).

To show links that open a quick view, the smart table supports the smart link.

To show static text, the smart table uses an input field in edit mode, and a text in read-only mode.

To show dates, the smart table uses a date picker in edit mode, and a text in read-only mode (annotation: sap:display-format, value:Date).

To show decimal numbers, the smart table uses an input field in edit mode, and a text in read-only mode (Annotations:Precision, Scale).

The smart table also provides an object status and object identifier control. For more information, see object display components.

Pictures and microcharts, as well as rating indicators and progress bars are available.

Amount formatting
Link formatting
Date formatting

Value Help

The smart table supports value help in the following ways (annotation: ValueList):

Input fields can show a value help button. Triggering this button opens a value help dialog. Within this dialog, you can provide a search field (annotation:ValueList, property: SearchSupported).

You can restrict the number of characters for the input field. Use this if no ValueList annotation is provided (annotation:MaxLength).

Toolbar Level

Table Title

The smart table can provide a title for the table within the toolbar (sap.ui.comp.smarttable.SmartTable, Property:header).

Table title

Item Count

Next to the table title, an item count can be shown (sap.ui.comp.smarttable.SmartTable, Property:showRowCount).

Table title with item count

Edit

The table toolbar can contain a button for toggling the table between read-only and edit modes. If smart fields are used, the smart table handles both modes automatically (sap.ui.comp.smarttable.SmartTable, properties:editTogglable, smartToggle, aggregation: customData, key: useSmartField).

If used with the responsive table, the edit button also switches the keyboard behavior accordingly.

Edit button

View Settings

The table toolbar can contain a button for opening the P13n dialog. This dialog provides extensive sort, group, and filter settings. It also allows columns to be shown, hidden, or rearranged (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).

Settings button

Export to Spreadsheet

The table toolbar can contain a button for exporting the table data to a spreadsheet (sap.ui.comp.smarttable.SmartTable, Property:useExportToExcel). The spreadsheet file can be created using back-end functionality (if available) or in the front-end (sap.ui.comp.smarttable.ExportType):

With the back-end export, the following columns are exported: currently visible columns, “technical columns” that are in the data model but not visible to the user, and usually some (but not all) of the columns that are currently hidden. In the spreadsheet file, neither the columns nor the rows are in the same order as in the exporting app. The exported file might also show different column header texts.
When the user triggers the export, the corresponding file is created in the background and offered for download automatically. The export process cannot be canceled. This option is only available if the back-end export is supported in the corresponding back-end system.

With the front-end export (default and recommended), only visible columns are exported. In the exported file, columns are in the same order and have the same header texts as in the exporting app. During the export, the system displays a progress dialog that blocks the UI. The export can be canceled at any time. As soon as the file has been created, it is offered for download automatically. The front-end export is always available.

In both cases, the export works only with simple text-only cell content. Non-text elements, such as icons, images, micro charts, or controls like checkboxes and buttons are not supported. Formatters are not taken into account (for example, for numbers, amounts, dates, and times) .

Warning
With both methods, the file size is limited by the available browser memory. Exporting large tables can therefore lead to memory overflows and browser crashes.

For the front-end export, the recommended maximum table size for using the built-in export functionality is 1 million table cells for desktop browsers or 100,000 table cells on tablets and phones. The limitation for the back-end export is even worse: even on a desktop device, the recommended maximum table size is only around 100,000 table cells.

For larger tables, consider using custom-built, specialized export solutions instead.

'Export to Spreadsheet' button
Exporting to Spreadsheet

Full Screen Mode

Applications can implement a maximize button to run the table in full screen (Property: showFullScreenButton).

Maximize button

Footer Toolbar Level

Buttons in the footer toolbar can be set to emphasized to give them a brighter appearance.

Guidelines

In general, the guidelines for the underlying table, toolbar, variant management, and P13n dialog also apply to the smart table (see the corresponding articles for details). However, because the smart table does not offer the complete flexibility of the underlying controls, there are certain differences.

Table Type

The responsive table is the standard table for SAP Fiori. Use the responsive table whenever possible. It is the most flexible table in terms of how its content is displayed, it is fully responsive, and it can handle up to 1,000 line items.

If you cannot use the responsive table, consider using the grid table instead. The grid table can handle a large number of line Items. Compared to the responsive table, however, it is more restricted content-wise (only certain controls can be used to show the data, and only one control per cell), and it does not run on smartphones. If you use the grid table, you need to provide a fallback solution for smartphones, for example, by using the responsive table.

The analytical table is similar to the grid table, but adds several grouping levels and offers total sums on measure columns. The analytical table can also handle a large number of line Items. Compared to the responsive table, however, it is more restricted content-wise (only certain controls can be used to show the data, and only one control per cell), and it does not run on smartphones. If you use the analytical table, you need to provide a fallback solution for smartphones, for example, by using the responsive table.

The tree table is the only table for displaying hierarchical data. Like the grid table, it can handle a large number of line items, although it is restricted content-wise (only certain controls can be used to show the data, and only one control per cell), and it does not run on smartphones. If you use the tree table, you need to provide a fallback solution for smartphones, for example, by using the responsive table.

For more information about the different table controls, see the corresponding articles.

Table Title, Item Count, and Variant Management

Always show the item count together with the table title, unless this is expected to cause performance problems.
If used with the responsive table and if more than 200 items are generally expected, do not show the item count. In this case, the smart table displays a More button to load additional rows. Using the item count together with the More button might lead to confusion (sap.ui.comp.smarttable.SmartTable, Property:showRowCount).

Even if variant management is easy to implement, use it only if it is really needed. The variant management saves the whole page, including filter settings and table layouts.

Empty Tables

Try not to display an empty table. If there is no way around this, provide instructions on how to fill the table with data (aggregatrion: noData).

The following default texts are provided automatically:

If the smart table is used standalone (without an attached smart filter bar) and it is initially empty (not yet bound), the default text is:
No items available.
Overwrite this whenever a hint can be provided on how to fill the table with data.

If the smart table is used with a smart filter bar attached, and it is initially empty (not yet bound), the default text is:
No filters set. To start, enter your search and filter settings and run the search.

If a smart table is bound but there is no data to display from the binding, the default text is:
No items found. Check the search and filter settings.
Overwrite this whenever this text is either not precise enough (for example, only search is offered) or misleading (for example, if the data is filled based on a master-detail pattern instead of search and filter settings).

Columns – Best Practices

Keep the number of initially shown columns to a minimum. Avoid the need to scroll horizontally on a tablet screen size in default delivery (annotation: PresentationVariant/ LineItem).

Keep the number of additional (initially hidden) columns to a minimum. You can use the P13n dialog to show/hide the columns. Select the columns offered in the P13n dialog carefully. Do not just show all columns available in the backend tables (annotation: sap:visible, value:false).

For the grid table, analytical table, and tree table, the column widths are calculated automatically if the corresponding OData annotations are provided (annotations: MaxLength, Precision, Scale).

In contrast, the responsive table uses the same width for all columns.

If used with the responsive table, enable the pop-in behavior (sap.ui.comp.smarttable.SmartTable, property: smartFilterId, value: true).

Show the most important column on the left and the least important on the right. This ensures that the most important columns stay in the tabular layout as long as possible. The most important columns are those that contain the following information:

The column that identifies the line item

The column that contains the key attribute

(Annotation: PresentationVariant/ LineItem, Property: initiallyVisibleColumns)

Email column in the pop-in area of the responsive table

Provide a column header text for each column. Do not truncate the column header text in default delivery (annotation: sap:label).

Column header text

Content Alignment and Formatting

The smart table automatically takes care of content alignment and formatting in standard use cases. For this, the OData metadata needs to provide the correct information about the data types, semantics of, and value help for the data.
(Annotations such as: sap:semantics, value: currency-code, edm types, Annotation: sap:display-format, value:Date, Annotation:Precision, Annotation: Scale, Annotation: ValueList, Annotation: ValueList:semantics, value:fixed-values)

Highlight Items

If the smart table is used with the responsive table, you can show the status of an item by displaying a highlight indicator in front of the item (property: highlight). The highlight indicator can be used to show:

A semantic state, such as red or orange for an error or warning

A neutral highlight, such as blue to highlight newly added items

Highlighted items

Actions

To trigger actions on multiple items, use a mutliselection smart table. Do not offer action triggering on multiple items if the table is expected to have fewer than 10 items in most cases.
While the grid table, analytical table, and tree table are multiselectable by default within the smart table, the responsive table is single-selectable. The selection mode can be changed (XMLView).

The following actions can be shown on the standard toolbar of the smart table:

Edit
Toggles the table between edit and read-only mode. This only works if smart fields are used inside the smart table (sap.ui.comp.smarttable.SmartTable, properties:editTogglable, smartToggle, aggregation: customData, key: useSmartField).

View Settings
This button opens the P13n dialog. Note that the P13n dialog is quite complex. Neither the simpler view settings dialog nor the table personalization dialog can be used without the app development team developing the entire view settings handling (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).

Export to Spreadsheet
Only use this option if your end users typically export the data shown in the table in order to work with it in a spreadsheet application. This is usually the case if data is collected from several systems and analyzed in the spreadsheet application. This is not usually the case for worklists, attachment lists, lists with only a few items, shopping carts, or data that does not need to be analyzed. This option is only available if the corresponding back end supports exporting to spreadsheet (sap.ui.comp.smarttable.SmartTable, property: useExportToExcel).

If additional actions are needed, use a custom toolbar for the table. The smart table can also add integrated functionality such as a table title, item count, variant management, edit and view settings, and export to spreadsheet to the custom toolbar (aggregation: customToolbar).

For navigation to line item details:

If used with the responsive table, use the navigation mode of the responsive table.

If used with the grid table, analytical table, or tree table, use a link for the attribute that identifies the row. The user can click this link to trigger the navigation.

Clicking a table row can trigger drill-in navigation to a deeper level of the object, as well as cross-navigation to another SAP Fiori app or even to another system.

Inline Actions

Actions that belong to single items can be placed within the row. They can be displayed as text or icons. Make sure the icon communicates the function clearly enough. Otherwise, use a textual button.

Editable Content

The smart table can be editable or read-only (sap.ui.comp.smarttable.SmartTable, property: editable).

The smart table selects the corresponding editable controls automatically based on the data type, semantic annotations, and value list annotations (annotations such as: sap:semantics, value: currency-code, edm types, Annotation: sap:display-format, value:Date, Annotation:Precision, Annotation: Scale, Annotation: ValueList, Annotation: ValueList:semantics, value:fixed-values).

If an edit mode is needed, the controls are automatically switched from read-only controls (such as text) to editable controls (such as input field or date picker) if smart fields are used inside the smart table (sap.ui.comp.smarttable.SmartTable, Property:editTogglable, smartToggle, aggregation: customData, key: useSmartField). The keyboard behavior is switched accordingly, if this is used together with the responsive table.

Only use this if you need to toggle between both modes. In any other case, show only the mode you need (read-only or edit), but do not offer the switch.

View Settings: Sort, Filter, Group, and Column Settings

If view settings are enabled on the smart table, a settings button is available on the table toolbar. This button opens the P13n dialog. Neither the simpler view settings dialog nor table personalization dialog can be used without extra effort (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).

The P13n dialog always enables the user to show, hide, and rearrange columns. Alternatively, it can contain settings for sorting, grouping, and/or filtering (annotations: sap:sortable, sap:filterable)

If the smart table uses the grid table, analytical table, or tree table, sort, filter, and group settings are also available in the column header menu.

Offer view settings only if they are really needed. For example, these settings do not make sense if the table contains only a few items and just a few columns.

Note that the P13n dialog is quite complex. It is ideal for tables with a vast number of items, but is quite cumbersome for handling just a few hundred items. Therefore, show only the settings (sort, group, filter) you really need. For example, do not offer grouping if it does not support your use case well.

If filtering is a main use case, do not offer filtering in the P13n dialog. Use the filter bar instead (annotation: sap:filterable)

Be persistent: When the app is reopened, the smart table is shown with the same view settings as last defined by the user (sap.ui.comp.smarttable.SmartTable, property: persistenceKey).

Sort

The current sort state is displayed as follows:

Using the responsive table, there is no indication that the table is currently sorted.

Using the grid table, analytical table, or tree table, an icon in the column header of the last sorted column indicates that the table is sorted and the direction in which it is sorted.

In default delivery, sort items in a meaningful order by the row-identifying column (usually the first column in default delivery). For example, use an alphabetical order for text, a numeric order for numbers, and a chronological order for dates (annotations: sap:sortable, PresentationVariant – SortOrder).

Filter

The current filter state is displayed as follows:

Using the responsive table, there is no indication that the table is currently filtered. The filter info bar can be added with additional effort.

Using the grid table, analytical table, or tree table, filtering is displayed by an icon on the column header of each filtered column (annotation: sap:filterable).

Group

Group headers display the current group state and are shown automatically. The following text should be shown on the group header:

[Label of the grouped column]: [Grouping value]
This can be done by the smart table, but only if the raw data from the model can be used. In other cases, app development teams must format the group header text. For example, the raw data carries IDs, while the table displays the corresponding names, which are provided by another data source. In this case, app developers must provide the formatting for the group header texts.

Within the responsive table, the grouped column keeps its visibility to reduce confusion after the group settings have been changed. If visible, it stays in the tabular layout even if grouped.

If used with the analytical table, grouping is not offered on measures. Therefore, you can have aggregations or grouping for a specific column.

Reasonable grouping can be offered by default via the property GroupBy.

Responsive table grouped by country

Aggregate

If used with the analytical table, aggregation settings can be provided on measure columns. These settings are only available in the column header menu.
To display the current aggregation state, the total sum of the corresponding column is shown at the bottom of the table.
If items are grouped, an intermediate sum is shown per group:

At the bottom of each group if the group is expanded.

In the group header if the group is collapsed.

Aggregations are only available on measures, but not on objects or attributes. If aggregation is enabled for a column, this column cannot be grouped.

Avoid aggregations on the first three columns for the default delivery. When grouping is used together with aggregations, collapsing a group shows the aggregation on the group header. This conflicts with the group name.

Where appropriate, offer reasonable aggregation by default (annotation: sap:aggregation-role, value: measure).

Column Settings

Only offer column settings if you need more columns than a tablet screen can display at a time (usually more than five).

If sorting, grouping, and/or filtering are needed, column settings must also be shown (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).

Add, Remove, Rearrange Columns

Use the P13n dialog to add, remove, and rearrange columns.

When used with the grid table, analytical table, or tree table, columns can also be rearranged by dragging and dropping the column header (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).

Resize Columns

When used with the grid table, analytical table, or tree table, columns can be resized on the column header (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).

Freeze Columns

When used with the grid table, analytical table, or tree table, app developers must manually add the options for freezing columns to the column header menu if necessary. They can do this by declaring the corresponding table inside the smart table in the XML view, and by using the corresponding settings on this inner table.

Selecting Freeze on a column freezes all columns from the first one to the one on which Freeze is selected. The menu entry on this column changes from Freeze to Unfreeze.

Properties

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

The property: ignoreFields defines the columns that are not available on the UI – neither in the initial visible columns nor in the P13n dialog.

The property: requestAtLeastFields can be used for requesting additional technical columns.

The property: ignoreFromPersonalization removes columns from the P13n dialog.

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

The property: enableCustomFilter allows the filter menu item in the column header menu to be exchanged.

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

The property: currentVariantId defines the currently used variant.

The property: enableAutoBinding fetches the data automatically as soon as the corresponding OData model is initialized and the smart table is created.

The property: tableBindingPath defines the path from which the data is fetched.

The property: smartToggle influences the way on which controls are displayed in the smart table if smart fields are used.

The following aggregations are available:

The aggregation: semanticObjectController is used to customize smart links inside the smart table.

The aggregation: noData provides a text in case the table contains no line items. For example, this can be the case if the table is filtered. The text should provide context-specific instructions on how to get data into the table.

Resources

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

Elements and Controls

Responsive Table (guidelines)

Grid Table (guidelines)

Analytical Table (guidelines)

Tree Table (guidelines)

Table Overview (guidelines)

Table Toolbar (guidelines)

Variant Management (guidelines)

P13n-Dialog (guidelines)

Implementation

Smart Table (SAPUI5 samples)

Smart Table (SAPUI5 API reference)

Smart Table (Developer Guide)

P13n-Dialog (SAPUI5 samples)

P13n-Dialog (SAPUI5 API reference)

Toolbar (SAPUI5 samples)

Smart Link

Warning
This guideline was written for release 1.52 and is no longer updated. For the latest design guidelines, see Link and Popover.

Background:
As of guideline release 1.54, the SAP Fiori Design Guidelines contain only general guidelines for all implementations. These guidelines also apply for implementations using smart controls. You can still use the smart link, but the exact features will no longer be updated in the design guidelines.

Intro

Like the quick view, the smart link triggers a popover from a text link. This popover shows additional information, such as simple object details, and offers links to related apps for the user to take action. The user can choose which links are shown in the popover by selecting them in a separate dialog.
The smart link is a smart control that uses metadata annotations to offer user-specific navigation. It analyzes the user’s assigned apps and offers only relevant navigation targets.

Usage

Use the smart link to offer direct navigation to related apps. For example:

Navigate from a product list to the app to change the pricing

Navigate from a sales order list to the app to see a customer’s balance

Use the smart link if:

You want to offer related apps for navigation.

You want to display simple object details.

Do not use the smart link if:

You want to display more or complex information about an object. Use the object page or charts instead.

No metadata is accessible, and only a direct link to a website, document or application is needed. Use the standard link instead.

You need to structure information in a deeper hierarchy. Use the quick view or a list drilldown instead.

Responsiveness

The responsiveness of the smart link is based on the responsiveness of the popover and overlays the content.

On a desktop device, clicking anywhere in the background closes the popover.

On mobile devices, the smart link opens a dialog that overlays the entire content. Because the content underneath the popover is no longer directly visible to the end user, the dialog has a header and shows the object type. The dialog can be closed by clicking the close icon () in the header.

Size S – On smartphones, the smart link overlays the content

Sizs M/ L - Smart link shown in a table on a desktop device

Layout

The smart link contains the following areas:

The header bar of the smart link popover indicates the type of object and is only shown on mobile devices.

The title area contains a title and a subtitle. The title can also be shown as a link, which can be used to navigate to the corresponding object or fact sheet. The subtitle can be used to show the ID of the object, for example.

The content area shows object-related information, such as details about a product or contact information. You can use any UI control, based on what best fits your use case.

The link area offers links to all other apps that are relevant for a user role. The link list includes all semantic objects defined for the app, and can also include additional links defined manually by the application development team. The link area can have two states:

Link area is empty:
If no links have been selected for the app, or if there are more than 10 links, the link area is initially empty. Instead, the user sees a Define Links button, which opens a dialog for selecting the links to be shown.

Links are shown:
As soon the link area contains links, the button text changes to More. This opens the same selection dialog.

Only the header bar is mandatory (for mobile devices). All the other sections are optional. Depending on the use case, the application could offer only a content area, or a only a link area, for example.

The areas of the smart link (header bar not shown)

Behavior and Interaction

The smart link and its popover are always triggered by clicking a text element that appears as a link. This text element can be placed in any list, table, or other container. The link label can be set individually. Clicking the background closes the popover. If only one link is offered, and there is no additional information, the smart link control navigates directly to the target without opening the popover.

If the semantic object annotation is not set, the smart link is rendered as sap.m.Text by default. However, app developers can also decide to render any other control.

Link Selection Dialog

Clicking the More or Define Links button opens the Define Link List dialog. There, the user can select the app links to be displayed in the link area. The links offered in the selection list are modifiable semantic objects suggested by the smart link control. Application development teams can remove links from the selection list and change the link texts. They can also manually add links to any website or app.

Exception: Within an SAP Fiori element, the links offered in the Define Link List dialog are generated automatically. Application teams cannot adapt the list.

You can switch off the More/Define Links option by setting the property enableAvailableActionsPersonalization to “false”. By default it is set to “true”.

Smart Links in a Smart Table

Within a smart table, the link label of the smart link is set automatically using the semantic object annotation. In other words, the description cannot be changed. If there are no navigation targets, the smart link is rendered as sap.m.Text.

Link selection dialog with a list of application links

Guidelines

Please check the related apps you offer carefully. Only display the ones that are relevant to the user.

Use meaningful link names in the link area. Do not use the same link name more than once. If necessary, rename the links to suit your context (for example, “Add Product” instead of “Manage Products”).

Resources

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

Elements and Controls

Quickview (guidelines)

Popover (guidelines)

Implementation

Smart Link (SAPUI5 samples)

Smart Link (SAPUI5 API reference)

Smart Table

The smart table is a wrapper around existing tables, and can be used together with the responsive table, grid table, analytical table, or tree table.

The smart table creates columns automatically based on the underlying OData service plus corresponding annotations. It also adds some generic functionality, such as a toolbar, complex personalization settings, variant management, and export to spreadsheet.

Everything that can be done using the smart table can also be achieved using the responsive table, grid table, analytical table, or tree table directly, but with more development effort. Therefore, the main purpose of the smart table is to reduce development effort. However, this comes at the expense of decreased flexibility.

Usage

Use the smart table if:

Data is fed into the table through OData services.

You need a simple table with limited flexibility to display its content. In this case, the smart table reduces development effort.

You need a table in which some columns provide flexible content. In this case, use the smart table together with a responsive table, and provide app-specific column definitions for these columns.

Do not use the smart table if:

You create your own UI coding, whereby the data is not fed through OData services. In this case, use the underlying table control directly.

The main use case involves selecting one item from very few items, with no additional details. In this case, a select or combo box might be more suitable.

The main use case involves selecting one item from several items, with only a few details per item. In this case, a list might be more suitable. Pay attention to the layout of the list item to provide a pleasant appearance (see, for example, the master list and the feed list item).

The table is displayed together with a chart inside a chart container. The smart table is not designed to work inside an existing chart container. In this case, use the underlying table control directly.

You need an overview of a large amount of data. In this case, use charts.

You just need it for layout reasons. In this case, use a layout container, such as the grid layout, instead.

You need read-only or editable field value pairs. In this case, use a form instead. Tables are not optimized for form-like input navigation.

Responsiveness

The responsiveness of the smart table depends on the encapsulated table. The table toolbar uses the overflow mechanism for adapting to the screen width.

Using the responsive table

The smart table offers generic responsive behavior (sap.ui.comp.smarttable.SmartTable, property: demandPopin, value: true):

For every 10 rem of screen width, one column stays in the tabular layout. All others are moved to the pop-in area. The columns are moved to the pop-in area from right to left, so the column furthest to the right moves to the pop-in first.

Exception: The first two columns always stay in the tabular layout. This works best if the smart table uses the whole screen width. It might not work well if the smart table uses far less space.

Using the grid table, analytical table, or tree table

The smart table works only on desktop and tablets, but not on smartphones. It supports touch devices, but is not optimized for small screens.

If you use a smart table in this configuration, ensure that you implement a fallback solution for small screens. This fallback solution does not need to support all use cases. You could create a fallback by using a responsive table. However, a completely different solution, such as showing charts in a read-only case, might be more suitable.

Size S with responsive table
Size M with responsive table
Size L with responsive table
Size M with grid table
Size L with grid table

Layout

The title bar contains the title of the smart table, the item count, variant management, and the toolbar itself. All of these elements are optional.
The table area shows the corresponding table (responsive table, grid table, analytical table, or tree table).

Schematic visualization of the smart table

Components

The title bar consists of a toolbar.

This can be the standard toolbar or a custom toolbar. The standard toolbar can contain a title text with or without item count, variant management, view switch (switching the table to edit mode), an entry point for the P13n dialog, and an Export to Spreadsheet action.

If you require additional functionality, you can use an app-specific toolbar. All toolbar options provided by the smart table can also be added to the app-specific toolbar. (Aggregation: customToolbar)

The table area consists of any of the following tables: responsive table, grid table, analytical table, or tree table.

Standard toolbar with everything enabled
Standard toolbar just with title and item count

Behavior and Interaction

The behavior is generally inherited from the underlying table, toolbar, variant management, 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.

Table Level

Table Type

The smart table can encapsulate the responsive table, grid table, analytical table, or tree table. (sap.ui.comp.smarttable.SmartTable, property: tableType)

Automatic Rendering of the Table

The smart table automatically creates columns and renders all items based on the metadata of the underlying OData service (sap.ui.comp.smarttable.SmartTable, property: smartFilterId).

To be more flexible in the table layout, the smart table also offers app-specific column templates for some or all columns. In this case, app developers must provide the definition for the underlying table and for the corresponding (but not necessarily for all) columns in the XML view. For this, the app development team must provide the column keys of the overridden columns via custom data.

Additional columns can also be added. Columns that are defined in this way retain all the options of the underlying table. This is especially useful with the responsive table, which offers complete flexibility in content design. Any columns that are not defined by the app development team are still rendered automatically by the smart table.

No Data

If there is no data to show, the smart table renders default text. This text can be overwritten by the app development team (aggregation: NoData).

Initially Visible Columns

The smart table enables you to define which columns are initially shown. Here, initially means that these columns are shown when the app is first launched. All other columns are initially hidden (annotation: PresentationVariant/ LineItem, property: initiallyVisibleColumns).

Persistency

End users can show additional columns if table personalization is provided. In this case, column settings are persisted. On consecutive startups, the columns are shown with the same settings as last defined by the user (property: persistenceKey).

Removing Columns

The smart table always shows all columns from the OData model. In some cases, columns needs to be in the model but should not be available on the front end at all. Examples of this include:

A column is needed to provide an ID which is used for navigation purposes, but the front end should only display the corresponding text, not the ID.

The values of a column are needed to perform calculations, but only the results should be shown on the UI.

In these cases, you can define which columns should not be available at all on the UI. These columns are not shown and are not available in the P13n dialog. You can also do this for columns that are added manually in the XML view (annotation: sap:visible, value:false).

P13n/personalization dialog

Filter Settings

The “Show Field as Column” option for newly added filters is switched on by default.

Sorting and Filtering

The smart table allows you to add sort and filter settings for each column. These settings enable the corresponding pages in the P13n dialog. For the grid table, analytical table, and tree table, sorting and filtering are also enabled on the column header. (Annotations: sap:sortable and sap:filterable)

Column header menu of the grid table

Smart Table and Smart Filter Bar

The smart table can be linked to a smart filter bar. If linked, filter bar settings are automatically used on the smart table. (sap.ui.comp.smarttable,SmartTable, property:smartFIlterId)

Aggregation

If used with the analytical table, the smart table allows total sums of measure columns to be calculated. The totals are shown in the usual way:

As the last row of the analytical table.

As the last row of each group if the group is expanded.

On the group header of each group if the group is collapsed.

Aggregation settings are not persisted (annotation: sap:aggregation-role, value:measure).

The total can be hidden via the column header menu.

Aggregation entry in column header menu of the grid table

Aggregation of Different Currencies

If used with the analytical table, the smart table also allows you to display totals for amount columns with different currencies.

In this case, a Show Details link is displayed instead of the total. Clicking the link opens a popover showing the subtotals per currency.

Exception: If a group contains only one currency, the total is shown directly.

Totals for a column which contains amounts in different currencies

Column Width

A default column width is calculated for each column based on the data displayed in it. Important: end users cannot change the column width in the responsive table (annotations: MaxLength, Precision, Scale).

Column Header

A column header text can be specified for each column (annotation: sap:label).

Persistence

The smart table allows you to persist sort, group, and filter column settings (such as by hidden columns) as well as variants (sap.ui.comp.smarttable.SmartTable, Property:persistenceyKey).

Content

The smart table provides two options to create columns automatically:

The smart table is rendered in either read-only or edit mode. In this case, the smart table renders the controls as described below. This is the default way of rendering content (property: editable)

If users need to switch between read-only and edit mode at runtime, the smart table allows smart fields to be rendered instead. You should use this if the edit button is added to the toolbar of the smart table (aggregation: customData key: useSmartField, property: smartToggle).

For option 1, the following controls are used:

To show currency amounts, the smart table allows the amount and the currency code to be displayed in a single cell. For read-only mode, the currency control is used. For edit mode, a single input field is used, and the currency itself is shown next to the input field as non-editable text (annotation: sap:semantics, value: currency-code).

To show links that open a quick view, the smart table supports the smart link.

To show static text, the smart table uses an input field in edit mode, and a text in read-only mode.

To show dates, the smart table uses a date picker in edit mode, and a text in read-only mode (annotation: sap:display-format, value:Date).

To show decimal numbers, the smart table uses an input field in edit mode, and a text in read-only mode (Annotations:Precision, Scale).

The smart table also provides an object status and object identifier control. For more information, see object display components.

Pictures and microcharts, as well as rating indicators and progress bars are available.

Amount formatting
Link formatting
Date formatting

Value Help

The smart table supports value help in the following ways (annotation: ValueList):

Input fields can show a value help button. Triggering this button opens a value help dialog. Within this dialog, you can provide a search field (annotation:ValueList, property: SearchSupported).

You can restrict the number of characters for the input field. Use this if no ValueList annotation is provided (annotation:MaxLength).

Toolbar Level

Table Title

The smart table can provide a title for the table within the toolbar (sap.ui.comp.smarttable.SmartTable, Property:header).

Table title

Item Count

Next to the table title, an item count can be shown (sap.ui.comp.smarttable.SmartTable, Property:showRowCount).

Table title with item count

Edit

The table toolbar can contain a button for toggling the table between read-only and edit modes. If smart fields are used, the smart table handles both modes automatically (sap.ui.comp.smarttable.SmartTable, properties:editTogglable, smartToggle, aggregation: customData, key: useSmartField).

If used with the responsive table, the edit button also switches the keyboard behavior accordingly.

Edit button

View Settings

The table toolbar can contain a button for opening the P13n dialog. This dialog provides extensive sort, group, and filter settings. It also allows columns to be shown, hidden, or rearranged (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).

Settings button

Export to Spreadsheet

The table toolbar can contain a button for exporting the table data to a spreadsheet (sap.ui.comp.smarttable.SmartTable, Property:useExportToExcel). The spreadsheet file can be created using back-end functionality (if available) or in the front-end (sap.ui.comp.smarttable.ExportType):

With the back-end export, the following columns are exported: currently visible columns, “technical columns” that are in the data model but not visible to the user, and usually some (but not all) of the columns that are currently hidden. In the spreadsheet file, neither the columns nor the rows are in the same order as in the exporting app. The exported file might also show different column header texts.
When the user triggers the export, the corresponding file is created in the background and offered for download automatically. The export process cannot be canceled. This option is only available if the back-end export is supported in the corresponding back-end system.

With the front-end export (default and recommended), only visible columns are exported. In the exported file, columns are in the same order and have the same header texts as in the exporting app. During the export, the system displays a progress dialog that blocks the UI. The export can be canceled at any time. As soon as the file has been created, it is offered for download automatically. The front-end export is always available.

In both cases, the export works only with simple text-only cell content. Non-text elements, such as icons, images, micro charts, or controls like checkboxes and buttons are not supported. Formatters are not taken into account (for example, for numbers, amounts, dates, and times) .

Warning
With both methods, the file size is limited by the available browser memory. Exporting large tables can therefore lead to memory overflows and browser crashes.

For the front-end export, the recommended maximum table size for using the built-in export functionality is 1 million table cells for desktop browsers or 100,000 table cells on tablets and phones. The limitation for the back-end export is even worse: even on a desktop device, the recommended maximum table size is only around 100,000 table cells.

For larger tables, consider using custom-built, specialized export solutions instead.

'Export to Spreadsheet' button
Exporting to Spreadsheet

Full Screen Mode

Applications can implement a maximize button to run the table in full screen (Property: showFullScreenButton).

Maximize button

Footer Toolbar Level

Buttons in the footer toolbar can be set to emphasized to give them a brighter appearance.

Guidelines

In general, the guidelines for the underlying table, toolbar, variant management, and P13n dialog also apply to the smart table (see the corresponding articles for details). However, because the smart table does not offer the complete flexibility of the underlying controls, there are certain differences.

Table Type

The responsive table is the standard table for SAP Fiori. Use the responsive table whenever possible. It is the most flexible table in terms of how its content is displayed, it is fully responsive, and it can handle up to 1,000 line items.

If you cannot use the responsive table, consider using the grid table instead. The grid table can handle a large number of line Items. Compared to the responsive table, however, it is more restricted content-wise (only certain controls can be used to show the data, and only one control per cell), and it does not run on smartphones. If you use the grid table, you need to provide a fallback solution for smartphones, for example, by using the responsive table.

The analytical table is similar to the grid table, but adds several grouping levels and offers total sums on measure columns. The analytical table can also handle a large number of line Items. Compared to the responsive table, however, it is more restricted content-wise (only certain controls can be used to show the data, and only one control per cell), and it does not run on smartphones. If you use the analytical table, you need to provide a fallback solution for smartphones, for example, by using the responsive table.

The tree table is the only table for displaying hierarchical data. Like the grid table, it can handle a large number of line items, although it is restricted content-wise (only certain controls can be used to show the data, and only one control per cell), and it does not run on smartphones. If you use the tree table, you need to provide a fallback solution for smartphones, for example, by using the responsive table.

For more information about the different table controls, see the corresponding articles.

Table Title, Item Count, and Variant Management

Always show the item count together with the table title, unless this is expected to cause performance problems.
If used with the responsive table and if more than 200 items are generally expected, do not show the item count. In this case, the smart table displays a More button to load additional rows. Using the item count together with the More button might lead to confusion (sap.ui.comp.smarttable.SmartTable, Property:showRowCount).

Even if variant management is easy to implement, use it only if it is really needed. The variant management saves the whole page, including filter settings and table layouts.

Empty Tables

Try not to display an empty table. If there is no way around this, provide instructions on how to fill the table with data (aggregatrion: noData).

The following default texts are provided automatically:

If the smart table is used standalone (without an attached smart filter bar) and it is initially empty (not yet bound), the default text is:
No items available.
Overwrite this whenever a hint can be provided on how to fill the table with data.

If the smart table is used with a smart filter bar attached, and it is initially empty (not yet bound), the default text is:
No filters set. To start, enter your search and filter settings and run the search.

If a smart table is bound but there is no data to display from the binding, the default text is:
No items found. Check the search and filter settings.
Overwrite this whenever this text is either not precise enough (for example, only search is offered) or misleading (for example, if the data is filled based on a master-detail pattern instead of search and filter settings).

Columns – Best Practices

Keep the number of initially shown columns to a minimum. Avoid the need to scroll horizontally on a tablet screen size in default delivery (annotation: PresentationVariant/ LineItem).

Keep the number of additional (initially hidden) columns to a minimum. You can use the P13n dialog to show/hide the columns. Select the columns offered in the P13n dialog carefully. Do not just show all columns available in the backend tables (annotation: sap:visible, value:false).

For the grid table, analytical table, and tree table, the column widths are calculated automatically if the corresponding OData annotations are provided (annotations: MaxLength, Precision, Scale).

In contrast, the responsive table uses the same width for all columns.

If used with the responsive table, enable the pop-in behavior (sap.ui.comp.smarttable.SmartTable, property: smartFilterId, value: true).

Show the most important column on the left and the least important on the right. This ensures that the most important columns stay in the tabular layout as long as possible. The most important columns are those that contain the following information:

The column that identifies the line item

The column that contains the key attribute

(Annotation: PresentationVariant/ LineItem, Property: initiallyVisibleColumns)

Email column in the pop-in area of the responsive table

Provide a column header text for each column. Do not truncate the column header text in default delivery (annotation: sap:label).

Column header text

Content Alignment and Formatting

The smart table automatically takes care of content alignment and formatting in standard use cases. For this, the OData metadata needs to provide the correct information about the data types, semantics of, and value help for the data.
(Annotations such as: sap:semantics, value: currency-code, edm types, Annotation: sap:display-format, value:Date, Annotation:Precision, Annotation: Scale, Annotation: ValueList, Annotation: ValueList:semantics, value:fixed-values)

Highlight Items

If the smart table is used with the responsive table, you can show the status of an item by displaying a highlight indicator in front of the item (property: highlight). The highlight indicator can be used to show:

A semantic state, such as red or orange for an error or warning

A neutral highlight, such as blue to highlight newly added items

Highlighted items

Actions

To trigger actions on multiple items, use a mutliselection smart table. Do not offer action triggering on multiple items if the table is expected to have fewer than 10 items in most cases.
While the grid table, analytical table, and tree table are multiselectable by default within the smart table, the responsive table is single-selectable. The selection mode can be changed (XMLView).

The following actions can be shown on the standard toolbar of the smart table:

Edit
Toggles the table between edit and read-only mode. This only works if smart fields are used inside the smart table (sap.ui.comp.smarttable.SmartTable, properties:editTogglable, smartToggle, aggregation: customData, key: useSmartField).

View Settings
This button opens the P13n dialog. Note that the P13n dialog is quite complex. Neither the simpler view settings dialog nor the table personalization dialog can be used without the app development team developing the entire view settings handling (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).

Export to Spreadsheet
Only use this option if your end users typically export the data shown in the table in order to work with it in a spreadsheet application. This is usually the case if data is collected from several systems and analyzed in the spreadsheet application. This is not usually the case for worklists, attachment lists, lists with only a few items, shopping carts, or data that does not need to be analyzed. This option is only available if the corresponding back end supports exporting to spreadsheet (sap.ui.comp.smarttable.SmartTable, property: useExportToExcel).

If additional actions are needed, use a custom toolbar for the table. The smart table can also add integrated functionality such as a table title, item count, variant management, edit and view settings, and export to spreadsheet to the custom toolbar (aggregation: customToolbar).

For navigation to line item details:

If used with the responsive table, use the navigation mode of the responsive table.

If used with the grid table, analytical table, or tree table, use a link for the attribute that identifies the row. The user can click this link to trigger the navigation.

Clicking a table row can trigger drill-in navigation to a deeper level of the object, as well as cross-navigation to another SAP Fiori app or even to another system.

Inline Actions

Actions that belong to single items can be placed within the row. They can be displayed as text or icons. Make sure the icon communicates the function clearly enough. Otherwise, use a textual button.

Editable Content

The smart table can be editable or read-only (sap.ui.comp.smarttable.SmartTable, property: editable).

The smart table selects the corresponding editable controls automatically based on the data type, semantic annotations, and value list annotations (annotations such as: sap:semantics, value: currency-code, edm types, Annotation: sap:display-format, value:Date, Annotation:Precision, Annotation: Scale, Annotation: ValueList, Annotation: ValueList:semantics, value:fixed-values).

If an edit mode is needed, the controls are automatically switched from read-only controls (such as text) to editable controls (such as input field or date picker) if smart fields are used inside the smart table (sap.ui.comp.smarttable.SmartTable, Property:editTogglable, smartToggle, aggregation: customData, key: useSmartField). The keyboard behavior is switched accordingly, if this is used together with the responsive table.

Only use this if you need to toggle between both modes. In any other case, show only the mode you need (read-only or edit), but do not offer the switch.

View Settings: Sort, Filter, Group, and Column Settings

If view settings are enabled on the smart table, a settings button is available on the table toolbar. This button opens the P13n dialog. Neither the simpler view settings dialog nor table personalization dialog can be used without extra effort (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).

The P13n dialog always enables the user to show, hide, and rearrange columns. Alternatively, it can contain settings for sorting, grouping, and/or filtering (annotations: sap:sortable, sap:filterable)

If the smart table uses the grid table, analytical table, or tree table, sort, filter, and group settings are also available in the column header menu.

Offer view settings only if they are really needed. For example, these settings do not make sense if the table contains only a few items and just a few columns.

Note that the P13n dialog is quite complex. It is ideal for tables with a vast number of items, but is quite cumbersome for handling just a few hundred items. Therefore, show only the settings (sort, group, filter) you really need. For example, do not offer grouping if it does not support your use case well.

If filtering is a main use case, do not offer filtering in the P13n dialog. Use the filter bar instead (annotation: sap:filterable)

Be persistent: When the app is reopened, the smart table is shown with the same view settings as last defined by the user (sap.ui.comp.smarttable.SmartTable, property: persistenceKey).

Sort

The current sort state is displayed as follows:

Using the responsive table, there is no indication that the table is currently sorted.

Using the grid table, analytical table, or tree table, an icon in the column header of the last sorted column indicates that the table is sorted and the direction in which it is sorted.

In default delivery, sort items in a meaningful order by the row-identifying column (usually the first column in default delivery). For example, use an alphabetical order for text, a numeric order for numbers, and a chronological order for dates (annotations: sap:sortable, PresentationVariant – SortOrder).

Filter

The current filter state is displayed as follows:

Using the responsive table, there is no indication that the table is currently filtered. The filter info bar can be added with additional effort.

Using the grid table, analytical table, or tree table, filtering is displayed by an icon on the column header of each filtered column (annotation: sap:filterable).

Group

Group headers display the current group state and are shown automatically. The following text should be shown on the group header:

[Label of the grouped column]: [Grouping value]
This can be done by the smart table, but only if the raw data from the model can be used. In other cases, app development teams must format the group header text. For example, the raw data carries IDs, while the table displays the corresponding names, which are provided by another data source. In this case, app developers must provide the formatting for the group header texts.

Within the responsive table, the grouped column keeps its visibility to reduce confusion after the group settings have been changed. If visible, it stays in the tabular layout even if grouped.

If used with the analytical table, grouping is not offered on measures. Therefore, you can have aggregations or grouping for a specific column.

Reasonable grouping can be offered by default via the property GroupBy.

Responsive table grouped by country

Aggregate

If used with the analytical table, aggregation settings can be provided on measure columns. These settings are only available in the column header menu.
To display the current aggregation state, the total sum of the corresponding column is shown at the bottom of the table.
If items are grouped, an intermediate sum is shown per group:

At the bottom of each group if the group is expanded.

In the group header if the group is collapsed.

Aggregations are only available on measures, but not on objects or attributes. If aggregation is enabled for a column, this column cannot be grouped.

Avoid aggregations on the first three columns for the default delivery. When grouping is used together with aggregations, collapsing a group shows the aggregation on the group header. This conflicts with the group name.

Where appropriate, offer reasonable aggregation by default (annotation: sap:aggregation-role, value: measure).

Column Settings

Only offer column settings if you need more columns than a tablet screen can display at a time (usually more than five).

If sorting, grouping, and/or filtering are needed, column settings must also be shown (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).

Add, Remove, Rearrange Columns

Use the P13n dialog to add, remove, and rearrange columns.

When used with the grid table, analytical table, or tree table, columns can also be rearranged by dragging and dropping the column header (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).

Resize Columns

When used with the grid table, analytical table, or tree table, columns can be resized on the column header (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).

Freeze Columns

When used with the grid table, analytical table, or tree table, app developers must manually add the options for freezing columns to the column header menu if necessary. They can do this by declaring the corresponding table inside the smart table in the XML view, and by using the corresponding settings on this inner table.

Selecting Freeze on a column freezes all columns from the first one to the one on which Freeze is selected. The menu entry on this column changes from Freeze to Unfreeze.

Properties

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

The property: ignoreFields defines the columns that are not available on the UI – neither in the initial visible columns nor in the P13n dialog.

The property: requestAtLeastFields can be used for requesting additional technical columns.

The property: ignoreFromPersonalization removes columns from the P13n dialog.

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

The property: enableCustomFilter allows the filter menu item in the column header menu to be exchanged.

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

The property: currentVariantId defines the currently used variant.

The property: enableAutoBinding fetches the data automatically as soon as the corresponding OData model is initialized and the smart table is created.

The property: tableBindingPath defines the path from which the data is fetched.

The property: smartToggle influences the way on which controls are displayed in the smart table if smart fields are used.

The following aggregations are available:

The aggregation: semanticObjectController is used to customize smart links inside the smart table.

The aggregation: noData provides a text in case the table contains no line items. For example, this can be the case if the table is filtered. The text should provide context-specific instructions on how to get data into the table.

Resources

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

Elements and Controls

Responsive Table (guidelines)

Grid Table (guidelines)

Analytical Table (guidelines)

Tree Table (guidelines)

Table Overview (guidelines)

Table Toolbar (guidelines)

Variant Management (guidelines)

P13n-Dialog (guidelines)

Implementation

Smart Table (SAPUI5 samples)

Smart Table (SAPUI5 API reference)

Smart Table (Developer Guide)

P13n-Dialog (SAPUI5 samples)

P13n-Dialog (SAPUI5 API reference)

Toolbar (SAPUI5 samples)

Smart Link

Like the quick view, the smart link triggers a popover from a text link. This popover shows additional information, such as simple object details, and offers links to related apps for the user to take action. The user can choose which links are shown in the popover by selecting them in a separate dialog.
The smart link is a smart control that uses metadata annotations to offer user-specific navigation. It analyzes the user’s assigned apps and offers only relevant navigation targets.

Usage

Use the smart link to offer direct navigation to related apps. For example:

Navigate from a product list to the app to change the pricing

Navigate from a sales order list to the app to see a customer’s balance

Use the smart link if:

You want to offer related apps for navigation.

You want to display simple object details.

Do not use the smart link if:

You want to display more or complex information about an object. Use the object page or charts instead.

No metadata is accessible, and only a direct link to a website, document or application is needed. Use the standard link instead.

You need to structure information in a deeper hierarchy. Use the quick view or a list drilldown instead.

Responsiveness

The responsiveness of the smart link is based on the responsiveness of the popover and overlays the content.

On a desktop device, clicking anywhere in the background closes the popover.

On mobile devices, the smart link opens a dialog that overlays the entire content. Because the content underneath the popover is no longer directly visible to the end user, the dialog has a header and shows the object type. The dialog can be closed by clicking the close icon () in the header.

Size S – On smartphones, the smart link overlays the content

Sizs M/ L - Smart link shown in a table on a desktop device

Layout

The smart link contains the following areas:

The header bar of the smart link popover indicates the type of object and is only shown on mobile devices.

The title area contains a title and a subtitle. The title can also be shown as a link, which can be used to navigate to the corresponding object or fact sheet. The subtitle can be used to show the ID of the object, for example.

The content area shows object-related information, such as details about a product or contact information. You can use any UI control, based on what best fits your use case.

The link area offers links to all other apps that are relevant for a user role. The link list includes all semantic objects defined for the app, and can also include additional links defined manually by the application development team. The link area can have two states:

Link area is empty:
If no links have been selected for the app, or if there are more than 10 links, the link area is initially empty. Instead, the user sees a Define Links button, which opens a dialog for selecting the links to be shown.

Links are shown:
As soon the link area contains links, the button text changes to More. This opens the same selection dialog.

Only the header bar is mandatory (for mobile devices). All the other sections are optional. Depending on the use case, the application could offer only a content area, or a only a link area, for example.

The areas of the smart link (header bar not shown)

Behavior and Interaction

The smart link and its popover are always triggered by clicking or tapping a text element that appears as a link. This text element can be placed in any list, table, or other container. The link label can be set individually. Clicking or tapping the background closes the popover. If only one link is offered, and there is no additional information, the smart link control navigates directly to the target without opening the popover.

If the semantic object annotation is not set, the smart link is rendered as sap.m.Text by default. However, app developers can also decide to render any other control.

Link Selection Dialog

Clicking the More or Define Links button opens the Define Link List dialog. There, the user can select the app links to be displayed in the link area. The links offered in the selection list are modifiable semantic objects suggested by the smart link control. Application development teams can remove links from the selection list and change the link texts. They can also manually add links to any website or app.

Exception: Within an SAP Fiori element, the links offered in the Define Link List dialog are generated automatically. Application teams cannot adapt the list.

You can switch off the More/Define Links option by setting the property enableAvailableActionsPersonalization to “false”. By default it is set to “true”.

Smart Links in a Smart Table

Within a smart table, the link label of the smart link is set automatically using the semantic object annotation. In other words, the description cannot be changed. If there are no navigation targets, the smart link is rendered as sap.m.Text.

Link selection dialog with a list of application links

Guidelines

Please check the related apps you offer carefully. Only display the ones that are relevant to the user.

Use meaningful link names in the link area. Do not use the same link name more than once. If necessary, rename the links to suit your context (for example, “Add Product” instead of “Manage Products”).

Resources

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

Elements and Controls

Quickview (guidelines)

Popover (guidelines)

Implementation

Smart Link (SAPUI5 samples)

Smart Link (SAPUI5 API reference)

Smart Table

The smart table is a wrapper around existing tables, and can be used together with the responsive table, grid table, analytical table, or tree table.

The smart table creates columns automatically based on the underlying OData service plus corresponding annotations. It also adds some generic functionality, such as a toolbar, complex personalization settings, variant management, and export to spreadsheet.

Everything that can be done using the smart table can also be achieved using the responsive table, grid table, analytical table, or tree table directly, but with more development effort. Therefore, the main purpose of the smart table is to reduce development effort. However, this comes at the expense of decreased flexibility.

Usage

Use the smart table if:

Data is fed into the table through OData services.

You need a simple table with limited flexibility to display its content. In this case, the smart table reduces development effort.

You need a table in which some columns provide flexible content. In this case, use the smart table together with a responsive table, and provide app-specific column definitions for these columns.

Do not use the smart table if:

You create your own UI coding, whereby the data is not fed through OData services. In this case, use the underlying table control directly.

The main use case involves selecting one item from very few items, with no additional details. In this case, a select or combo box might be more suitable.

The main use case involves selecting one item from several items, with only a few details per item. In this case, a list might be more suitable. Pay attention to the layout of the list item to provide a pleasant appearance (see, for example, the master list and the feed list item).

The table is displayed together with a chart inside a chart container. The smart table is not designed to work inside an existing chart container. In this case, use the underlying table control directly.

You need an overview of a large amount of data. In this case, use charts.

You just need it for layout reasons. In this case, use a layout container, such as the grid layout, instead.

You need read-only or editable field value pairs. In this case, use a form instead. Tables are not optimized for form-like input navigation.

Responsiveness

The responsiveness of the smart table depends on the encapsulated table. The table toolbar uses the overflow mechanism for adapting to the screen width.

Using the responsive table

The smart table offers a generic responsive behavior (sap.ui.comp.smarttable.SmartTable, property: smartFilterId, value: true):

For every 10 rem of screen width, one column stays in the tabular layout. All others are moved to the pop-in area. The columns are moved to the pop-in area from right to left, so the column furthest to the right moves to the pop-in first.

Exception: The first two columns always stay in the tabular layout. This works best if the smart table uses the whole screen width. It might not work well if the smart table uses far less space.

Using the grid table, analytical table, or tree table

The smart table works only on desktop and tablets, but not on smartphones. It supports touch devices, but is not optimized for small screens.

If you use a smart table in this configuration, ensure that you implement a fallback solution for small screens. This fallback solution does not need to support all use cases. You could create a fallback by using a responsive table. However, a completely different solution, such as showing charts in a read-only case, might be more suitable.

Size S with responsive table
Size M with responsive table
Size L with responsive table
Size M with grid table
Size L with grid table

Layout

The title bar contains the title of the smart table, the item count, variant management, and the toolbar itself. All of these elements are optional.
The table area shows the corresponding table (responsive table, grid table, analytical table, or tree table).

Schematic visualization of the smart table

Components

The title bar consists of a toolbar.

This can be the standard toolbar or a custom toolbar. The standard toolbar can contain a title text with or without item count, variant management, view switch (switching the table to edit mode), an entry point for the P13n dialog, and an Export to Spreadsheet action.

If you require additional functionality, you can use an app-specific toolbar. All toolbar options provided by the smart table can also be added to the app-specific toolbar. (Aggregation: customToolbar)

The table area consists of any of the following tables: responsive table, grid table, analytical table, or tree table.

Standard toolbar with everything enabled
Standard toolbar just with title and item count

Behavior and Interaction

The behavior is generally inherited from the underlying table, toolbar, variant management, 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.

Table Level

Table Type

The smart table can encapsulate the responsive table, grid table, analytical table, or tree table. (sap.ui.comp.smarttable.SmartTable, property: tableType)

Automatic Rendering of the Table

The smart table automatically creates columns and renders all items based on the metadata of the underlying OData service (sap.ui.comp.smarttable.SmartTable, property: smartFilterId).

To be more flexible in the table layout, the smart table also offers app-specific column templates for some or all columns. In this case, app developers must provide the definition for the underlying table and for the corresponding (but not necessarily for all) columns in the XML view. For this, the app development team must provide the column keys of the overridden columns via custom data.

Additional columns can also be added. Columns that are defined in this way retain all the options of the underlying table. This is especially useful with the responsive table, which offers complete flexibility in content design. Any columns that are not defined by the app development team are still rendered automatically by the smart table.

No Data

If there is no data to show, the smart table renders default text. This text can be overwritten by the app development team (aggregation: NoData).

Initially Visible Columns

The smart table enables you to define which columns are initially shown. Here, initially means that these columns are shown when the app is first launched. All other columns are initially hidden (annotation: PresentationVariant/ LineItem, property: initiallyVisibleColumns).

Persistency

End users can show additional columns if table personalization is provided. In this case, column settings are persisted. On consecutive startups, the columns are shown with the same settings as last defined by the user (property: persistenceKey).

Removing Columns

The smart table always shows all columns from the OData model. In some cases, columns needs to be in the model but should not be available on the front end at all. Examples of this include:

A column is needed to provide an ID which is used for navigation purposes, but the front end should only display the corresponding text, not the ID.

The values of a column are needed to perform calculations, but only the results should be shown on the UI.

In these cases, you can define which columns should not be available at all on the UI. These columns are not shown and are not available in the P13n dialog. You can also do this for columns that are added manually in the XML view (annotation: sap:visible, value:false).

P13n/personalization dialog

Filter Settings

The “Show Field as Column” option for newly added filters is switched on by default.

Sorting and Filtering

The smart table allows you to add sort and filter settings for each column. These settings enable the corresponding pages in the P13n dialog. For the grid table, analytical table, and tree table, sorting and filtering are also enabled on the column header. (Annotations: sap:sortable and sap:filterable)

Column header menu of the grid table

Smart Table and Smart Filter Bar

The smart table can be linked to a smart filter bar. If linked, filter bar settings are automatically used on the smart table. (sap.ui.comp.smarttable,SmartTable, property:smartFIlterId)

Aggregation

If used with the analytical table, the smart table allows total sums of measure columns to be calculated. The totals are shown in the usual way:

As the last row of the analytical table.

As the last row of each group if the group is expanded.

On the group header of each group if the group is collapsed.

Aggregation settings are not persisted (annotation: sap:aggregation-role, value:measure).

The total can be hidden via the column header menu.

Aggregation entry in column header menu of the grid table

Aggregation of Different Currencies

If used with the analytical table, the smart table also allows you to display totals for amount columns with different currencies.

In this case, a Show Details link is displayed instead of the total. Clicking the link opens a popover showing the subtotals per currency.

Exception: If a group contains only one currency, the total is shown directly.

Totals for a column which contains amounts in different currencies

Column Width

A default column width is calculated for each column based on the data displayed in it. Important: end users cannot change the column width in the responsive table (annotations: MaxLength, Precision, Scale).

Column Header

A column header text can be specified for each column (annotation: sap:label).

Persistence

The smart table allows you to persist sort, group, and filter column settings (such as by hidden columns) as well as variants (sap.ui.comp.smarttable.SmartTable, Property:persistenceyKey).

Content

The smart table provides two options to create columns automatically:

The smart table is rendered in either read-only or edit mode. In this case, the smart table renders the controls as described below. This is the default way of rendering content (property: editable)

If users need to switch between read-only and edit mode at runtime, the smart table allows smart fields to be rendered instead. You should use this if the edit button is added to the toolbar of the smart table (aggregation: customData key: useSmartField, property: smartToggle).

For option 1, the following controls are used:

To show currency amounts, the smart table allows the amount and the currency code to be displayed in a single cell. For read-only mode, the currency control is used. For edit mode, a single input field is used, and the currency itself is shown next to the input field as non-editable text (annotation: sap:semantics, value: currency-code).

To show links that open a quick view, the smart table supports the smart link.

To show static text, the smart table uses an input field in edit mode, and a text in read-only mode.

To show dates, the smart table uses a date picker in edit mode, and a text in read-only mode (annotation: sap:display-format, value:Date).

To show decimal numbers, the smart table uses an input field in edit mode, and a text in read-only mode (Annotations:Precision, Scale).

The smart table also provides an object status and object identifier control. For more information, see object display components.

Pictures and microcharts, as well as rating indicators and progress bars are available.

Amount formatting
Link formatting
Date formatting

Value Help

The smart table supports value help in the following ways (annotation: ValueList):

Input fields can show a value help button. Triggering this button opens a value help dialog. Within this dialog, you can provide a search field (annotation:ValueList, property: SearchSupported).

You can restrict the number of characters for the input field. Use this if no ValueList annotation is provided (annotation:MaxLength).

Toolbar Level

Table Title

The smart table can provide a title for the table within the toolbar (sap.ui.comp.smarttable.SmartTable, Property:header).

Table title

Item Count

Next to the table title, an item count can be shown (sap.ui.comp.smarttable.SmartTable, Property:showRowCount).

Table title with item count

Edit

The table toolbar can contain a button for toggling the table between read-only and edit modes. If smart fields are used, the smart table handles both modes automatically (sap.ui.comp.smarttable.SmartTable, properties:editTogglable, smartToggle, aggregation: customData, key: useSmartField).

If used with the responsive table, the edit button also switches the keyboard behavior accordingly.

Edit button

View Settings

The table toolbar can contain a button for opening the P13n dialog. This dialog provides extensive sort, group, and filter settings. It also allows columns to be shown, hidden, or rearranged (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).

Settings button

Export to Spreadsheet

If the back end supports the export of data to spreadsheet, the table toolbar can contain a corresponding button. When this button is triggered, the corresponding file is created and the download starts automatically (sap.ui.comp.smarttable.SmartTable, Property:useExportToExcel).

Export to Spreadsheet button

Full Screen Mode

Applications can implement a maximize button to run the table in full screen (Property: showFullScreenButton).

Maximize button

Footer Toolbar Level

Buttons in the footer toolbar can be set to emphasized to give them a brighter appearance.

Guidelines

In general, the guidelines for the underlying table, toolbar, variant management, and P13n dialog also apply to the smart table (see the corresponding articles for details). However, because the smart table does not offer the complete flexibility of the underlying controls, there are certain differences.

Table Type

The responsive table is the standard table for SAP Fiori. Use the responsive table whenever possible. It is the most flexible table in terms of how its content is displayed, it is fully responsive, and it can handle up to 1,000 line items.

If you cannot use the responsive table, consider using the grid table instead. The grid table can handle a large number of line Items. Compared to the responsive table, however, it is more restricted content-wise (only certain controls can be used to show the data, and only one control per cell), and it does not run on smartphones. If you use the grid table, you need to provide a fallback solution for smartphones, for example, by using the responsive table.

The analytical table is similar to the grid table, but adds several grouping levels and offers total sums on measure columns. The analytical table can also handle a large number of line Items. Compared to the responsive table, however, it is more restricted content-wise (only certain controls can be used to show the data, and only one control per cell), and it does not run on smartphones. If you use the analytical table, you need to provide a fallback solution for smartphones, for example, by using the responsive table.

The tree table is the only table for displaying hierarchical data. Like the grid table, it can handle a large number of line items, although it is restricted content-wise (only certain controls can be used to show the data, and only one control per cell), and it does not run on smartphones. If you use the tree table, you need to provide a fallback solution for smartphones, for example, by using the responsive table.

For more information about the different table controls, see the corresponding articles.

Table Title, Item Count, and Variant Management

Always show the item count together with the table title, unless this is expected to cause performance problems.
If used with the responsive table and if more than 200 items are generally expected, do not show the item count. In this case, the smart table displays a More button to load additional rows. Using the item count together with the More button might lead to confusion (sap.ui.comp.smarttable.SmartTable, Property:showRowCount).

Even if variant management is easy to implement, use it only if it is really needed. The variant management saves the whole page, including filter settings and table layouts.

Empty Tables

Try not to display an empty table. If there is no way around this, provide instructions on how to fill the table with data (aggregatrion: noData).

Columns – Best Practices

Keep the number of initially shown columns to a minimum. Avoid the need to scroll horizontally on a tablet screen size in default delivery (annotation: PresentationVariant/ LineItem).

Keep the number of additional (initially hidden) columns to a minimum. You can use the P13n dialog to show/hide the columns. Select the columns offered in the P13n dialog carefully. Do not just show all columns available in the backend tables (annotation: sap:visible, value:false).

For the grid table, analytical table, and tree table, the column widths are calculated automatically if the corresponding OData annotations are provided (annotations: MaxLength, Precision, Scale).

In contrast, the responsive table uses the same width for all columns.

If used with the responsive table, enable the pop-in behavior (sap.ui.comp.smarttable.SmartTable, property: smartFilterId, value: true).

Show the most important column on the left and the least important on the right. This ensures that the most important columns stay in the tabular layout as long as possible. The most important columns are those that contain the following information:

The column that identifies the line item

The column that contains the key attribute

(Annotation: PresentationVariant/ LineItem, Property: initiallyVisibleColumns)

Email column in the pop-in area of the responsive table

Provide a column header text for each column. Do not truncate the column header text in default delivery (annotation: sap:label).

Column header text

Content Alignment and Formatting

The smart table automatically takes care of content alignment and formatting in standard use cases. For this, the OData metadata needs to provide the correct information about the data types, semantics of, and value help for the data.
(Annotations such as: sap:semantics, value: currency-code, edm types, Annotation: sap:display-format, value:Date, Annotation:Precision, Annotation: Scale, Annotation: ValueList, Annotation: ValueList:semantics, value:fixed-values)

Highlight Items

If the smart table is used with the responsive table, you can show the status of an item by displaying a highlight indicator in front of the item (property: highlight). The highlight indicator can be used to show:

A semantic state, such as red or orange for an error or warning

A neutral highlight, such as blue to highlight newly added items

Highlighted items

Actions

To trigger actions on multiple items, use a mutliselection smart table. Do not offer action triggering on multiple items if the table is expected to have fewer than 10 items in most cases.
While the grid table, analytical table, and tree table are multiselectable by default within the smart table, the responsive table is single-selectable. The selection mode can be changed (XMLView).

The following actions can be shown on the standard toolbar of the smart table:

Edit
Toggles the table between edit and read-only mode. This only works if smart fields are used inside the smart table (sap.ui.comp.smarttable.SmartTable, properties:editTogglable, smartToggle, aggregation: customData, key: useSmartField).

View Settings
This button opens the P13n dialog. Note that the P13n dialog is quite complex. Neither the simpler view settings dialog nor the table personalization dialog can be used without the app development team developing the entire view settings handling (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).

Export to Spreadsheet
Only use this option if your end users typically export the data shown in the table in order to work with it in a spreadsheet application. This is usually the case if data is collected from several systems and analyzed in the spreadsheet application. This is not usually the case for worklists, attachment lists, lists with only a few items, shopping carts, or data that does not need to be analyzed. This option is only available if the corresponding back end supports exporting to spreadsheet (sap.ui.comp.smarttable.SmartTable, property: useExportToExcel).

If additional actions are needed, use a custom toolbar for the table. The smart table can also add integrated functionality such as a table title, item count, variant management, edit and view settings, and export to spreadsheet to the custom toolbar (aggregation: customToolbar).

For navigation to line item details:

If used with the responsive table, use the navigation mode of the responsive table.

If used with the grid table, analytical table, or tree table, use a link for the attribute that identifies the row. The user can click this link to trigger the navigation.

Clicking a table row can trigger drill-in navigation to a deeper level of the object, as well as cross-navigation to another SAP Fiori app or even to another system.

Inline Actions

Actions that belong to single items can be placed within the row. They can be displayed as text or icons. Make sure the icon communicates the function clearly enough. Otherwise, use a textual button.

Editable Content

The smart table can be editable or read-only (sap.ui.comp.smarttable.SmartTable, property: editable).

The smart table selects the corresponding editable controls automatically based on the data type, semantic annotations, and value list annotations (annotations such as: sap:semantics, value: currency-code, edm types, Annotation: sap:display-format, value:Date, Annotation:Precision, Annotation: Scale, Annotation: ValueList, Annotation: ValueList:semantics, value:fixed-values).

If an edit mode is needed, the controls are automatically switched from read-only controls (such as text) to editable controls (such as input field or date picker) if smart fields are used inside the smart table (sap.ui.comp.smarttable.SmartTable, Property:editTogglable, smartToggle, aggregation: customData, key: useSmartField). The keyboard behavior is switched accordingly, if this is used together with the responsive table.

Only use this if you need to toggle between both modes. In any other case, show only the mode you need (read-only or edit), but do not offer the switch.

View Settings: Sort, Filter, Group, and Column Settings

If view settings are enabled on the smart table, a settings button is available on the table toolbar. This button opens the P13n dialog. Neither the simpler view settings dialog nor table personalization dialog can be used without extra effort (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).

The P13n dialog always enables the user to show, hide, and rearrange columns. Alternatively, it can contain settings for sorting, grouping, and/or filtering (annotations: sap:sortable, sap:filterable)

If the smart table uses the grid table, analytical table, or tree table, sort, filter, and group settings are also available in the column header menu.

Offer view settings only if they are really needed. For example, these settings do not make sense if the table contains only a few items and just a few columns.

Note that the P13n dialog is quite complex. It is ideal for tables with a vast number of items, but is quite cumbersome for handling just a few hundred items. Therefore, show only the settings (sort, group, filter) you really need. For example, do not offer grouping if it does not support your use case well.

If filtering is a main use case, do not offer filtering in the P13n dialog. Use the filter bar instead (annotation: sap:filterable)

Be persistent: When the app is reopened, the smart table is shown with the same view settings as last defined by the user (sap.ui.comp.smarttable.SmartTable, property: persistenceKey).

Sort

The current sort state is displayed as follows:

Using the responsive table, there is no indication that the table is currently sorted.

Using the grid table, analytical table, or tree table, an icon in the column header of the last sorted column indicates that the table is sorted and the direction in which it is sorted.

In default delivery, sort items in a meaningful order by the row-identifying column (usually the first column in default delivery). For example, use an alphabetical order for text, a numeric order for numbers, and a chronological order for dates (annotations: sap:sortable, PresentationVariant – SortOrder).

Filter

The current filter state is displayed as follows:

Using the responsive table, there is no indication that the table is currently filtered. The filter info bar can be added with additional effort.

Using the grid table, analytical table, or tree table, filtering is displayed by an icon on the column header of each filtered column (annotation: sap:filterable).

Group

Group headers display the current group state and are shown automatically. The following text should be shown on the group header:

[Label of the grouped column]: [Grouping value]
This can be done by the smart table, but only if the raw data from the model can be used. In other cases, app development teams must format the group header text. For example, the raw data carries IDs, while the table displays the corresponding names, which are provided by another data source. In this case, app developers must provide the formatting for the group header texts.

Within the responsive table, the grouped column keeps its visibility to reduce confusion after the group settings have been changed. If visible, it stays in the tabular layout even if grouped.

If used with the analytical table, grouping is not offered on measures. Therefore, you can have aggregations or grouping for a specific column.

Reasonable grouping can be offered by default via the property GroupBy.

Responsive table grouped by country

Aggregate

If used with the analytical table, aggregation settings can be provided on measure columns. These settings are only available in the column header menu.
To display the current aggregation state, the total sum of the corresponding column is shown at the bottom of the table.
If items are grouped, an intermediate sum is shown per group:

At the bottom of each group if the group is expanded.

In the group header if the group is collapsed.

Aggregations are only available on measures, but not on objects or attributes. If aggregation is enabled for a column, this column cannot be grouped.

Avoid aggregations on the first three columns for the default delivery. When grouping is used together with aggregations, collapsing a group shows the aggregation on the group header. This conflicts with the group name.

Where appropriate, offer reasonable aggregation by default (annotation: sap:aggregation-role, value: measure).

Column Settings

Only offer column settings if you need more columns than a tablet screen can display at a time (usually more than five).

If sorting, grouping, and/or filtering are needed, column settings must also be shown (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).

Add, Remove, Rearrange Columns

Use the P13n dialog to add, remove, and rearrange columns.

When used with the grid table, analytical table, or tree table, columns can also be rearranged by dragging and dropping the column header (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).

Resize Columns

When used with the grid table, analytical table, or tree table, columns can be resized on the column header (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).

Freeze Columns

When used with the grid table, analytical table, or tree table, app developers must manually add the options for freezing columns to the column header menu if necessary. They can do this by declaring the corresponding table inside the smart table in the XML view, and by using the corresponding settings on this inner table.

Selecting Freeze on a column freezes all columns from the first one to the one on which Freeze is selected. The menu entry on this column changes from Freeze to Unfreeze.

Properties

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

The property: ignoreFields defines the columns that are not available on the UI – neither in the initial visible columns nor in the P13n dialog.

The property: requestAtLeastFields can be used for requesting additional technical columns.

The property: ignoreFromPersonalization removes columns from the P13n dialog.

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

The property: enableCustomFilter allows the filter menu item in the column header menu to be exchanged.

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

The property: currentVariantId defines the currently used variant.

The property: enableAutoBinding fetches the data automatically as soon as the corresponding OData model is initialized and the smart table is created.

The property: tableBindingPath defines the path from which the data is fetched.

The property: smartToggle influences the way on which controls are displayed in the smart table if smart fields are used.

The following aggregations are available:

The aggregation: semanticObjectController is used to customize smart links inside the smart table.

The aggregation: noData provides a text in case the table contains no line items. For example, this can be the case if the table is filtered. The text should provide context-specific instructions on how to get data into the table.

Resources

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

Elements and Controls

Responsive Table (guidelines)

Grid Table (guidelines)

Analytical Table (guidelines)

Tree Table (guidelines)

Table Overview (guidelines)

Table Toolbar (guidelines)

Variant Management (guidelines)

P13n-Dialog (guidelines)

Implementation

Smart Table (SAPUI5 samples)

Smart Table (SAPUI5 API reference)

Smart Table (Developer Guide)

P13n-Dialog (SAPUI5 samples)

P13n-Dialog (SAPUI5 API reference)

Toolbar (SAPUI5 samples)

Dynamic Date

The dynamic date is a smart control that is currently only available in the smart filter bar. When the user enters a value in the date field, it suggests corresponding fixed and dynamic dates. It also offers a value help feature that lets users choose between different time periods and define them further. The list of values offered must be defined by the app.

Information
The dynamic date control can only be used in the smart filter bar. If you are not using the smart filter bar, use the date range selection control instead.

Usage

Use the dynamic date control if:

You need flexibility between fixed and dynamic dates.

You need dynamic dates that can be saved in the variant management (for example, show values from today regardless of when you open the app).

You are using the smart filter bar.

The user only needs to select one value.

Do not use the dynamic date control if:

Users need to enter a date and a time. In this case, use the date picker or the date/time picker instead.

Selecting ranges is not the user’s primary goal. In this case, use the simple date picker.

You are not using the smart filter bar.

Responsiveness

The dynamic date control is fully responsive. It provides a touch-friendly screen in sizes S and M (cozy mode) and is smaller in size L (compact mode). For more information on cozy and compact modes, see the article on content density.

Value help for dynamic date range - Size S
Value help for dynamic date range - Size L

Components

The dynamic date consists of two components: the date input field with suggestions, and the value help popover. On all devices, users can either use the input field to type a date, or use the value help button to open the popover.

The two clickable areas of the dynamic date control on all devices

Dynamic Date Input Field

The user can type data directly into the input field. Upon user input, a list of suggestions appears.

Value Help Popover

The value help popover offers all available values the user can choose from. Depending on the selected time period, the popover shows different controls. It either shows an input field (1), one or two date pickers (2), a read-only text with the chosen time period and date range (3), or a select control.

The different options for defining time period values

Values Offered

From

To

Date Range

Today

Last X days

Next X days

This week

Last week

Last X weeks

Next week

Offered Values

Next X weeks

Month

This month

Last month

Last X months

Next X months

This quarter

Last quarter

Last X quarters

Next quarter

Offered Values

Next X quarters

First quarter

Second quarter

Third quarter

Fourth quarter

This year

Last year

Last X years

Next year

Next X years

Year to date

Behavior & Interaction

Typing data into the date range input field

The user can type keywords or numbers into the date range input field. For example, if the user types a number, the system automatically suggests possible dates. All dynamic dates show the actual dates to help the user select the right value.

List of suggestions shown after typed input

Opening the value help and selecting a time period

Clicking the value help icon opens a popover with additional options for defining the time period. The user can choose from several time periods by clicking the down arrow in the select control. Once a time period has been chosen, the selection box closes.

Opening the value help popover and selecting a time period

Defining a custom time period (X)

If the user selects a custom time period with “X”, such as Last X days, the control shows a simple input field for entering the number. The text in the date input field changes according to the user’s input.

Custom time period with a simple input field

Selecting a date range

If the user selects a time period that requires input of a start and end date, two date pickers appear. These can be opened by clicking on the calendar icon. The text in the date range input field changes according to the user’s input.

Selected time period with two date pickers (start date and end date)

Styles

Validation

Use inline validation to give the user feedback, especially for errors and warnings. The possible states are “warning”, “error”, and “success”.

The dynamic date input field in question is highlighted by a frame in the corresponding color. If the focus is inside the field, an explanation is shown. Ensure that this explanation is as specific as possible.

Visible frame that shows an error when the field is out of focus
Error state with meaningful text - the date range input field is in focus

Guidelines

See the Date Picker and Date Range Selection articles for the guidelines. They also apply to the dynamic date control.

List of Options

Only provide values that are relevant for the use case in the list of options.

You can also add your own values, if necessary.

If you use your own values, provide human readable text.

Resources

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

Elements and Controls

Date Picker (guidelines)

Input Field (guidelines)

Select (guidelines)

Implementation

Date Picker (SAPUI5 samples)

Input (SAPUI5 samples)

Select (SAPUI5 samples)

Smart Controls (SAPUI5 samples)

Smart Filter Bar (SAPUI5 API reference)

Smart Filter Bar Annotations

Information
This article is intended as an aid to designers and developers who want to explore the detail configuration options available for the smart filter bar.

The smart filter bar is a wrapper that analyzes a given OData service and renders a filter bar based on the content defined by the service. For example, the OData service determines whether a field is visible on the filter bar, and whether it supports type-ahead and value help. To configure more settings or overwrite the settings from the OData service, the developer can set additional annotations in an external document (metadata.xml).

Developers can use annotation properties in the classes [external_only]ControlConfiguration and GroupConfiguration to adapt the filter bar for the purposes of the app.

These annotations let you:

Determine the type of control (for example, whether a field is shown as a multi-input field or as a date picker)

Enable the autocomplete suggestions feature

Enable the value help dialog

Overwrite settings from the OData service

Set custom filter groups

Add custom fields

Access all settings for the underlying filter bar

You can also use all the configuration options described here in the smart filter bar for the list report SAP Fiori element.

Warning
Most of the attributes/properties are not dynamic and cannot be changed once the control has been initialized.

Usage

Use the smart filter bar if:

An OData service is available.

You want to develop quickly and efficiently.

Do not use the smart filter bar if:

You need to make extensive changes to the filter bar.

Components

You can use the annotation properties listed below to influence how filters are rendered in the expanded filter bar and in the filter dialog.

Expanded Filter Bar

Smart filter bar - Properties for the expanded filter bar

1 enableBasicSearch

Defines whether the filter bar includes a basic search. By default, the basic search is not included.

2 FilterRestrictions/NonFilterableProperties

Defines whether a property is available as a filter criterion.

3 FilterRestrictions/RequiredProperties

Defines the filter field as a mandatory filter. Mandatory filters are marked by an asterisk (*).

4 ValueList

Contains annotations that provide information for rendering a value help list that has been set for a property.

5 FilterExpressionType/MultiValue

Defines whether multiple values can be used in a single filter.

6 FilterExpressionType/SingleValue

Restricts the filter to allow only one value entry.

7 LineItem/Label

A short, human-readable text for the filter name.

8 FilterExpressionType/SingleInterval

Restricts the filter to a specified interval, such as a date interval.

8 insertDefaultFilterValue

Inserts a default filter value into the aggregation defaultFilterValues.

9 liveMode

Defines whether the expanded filter bar is shown in live mode (no Go button) or in manual mode. By default, the filter bar is shown in manual mode.

Filter Dialog

1 FilterRestrictions/RequiredProperties

Defines the filter field as a mandatory filter. Mandatory filters are marked by an asterisk (*).

2 FieldControlType/Hidden

Defines whether the filter is initially visible on the expanded filter bar.

3 SelectionFields

Defines whether a filter belongs to the basic group. All filters in the basic group are initially visible on the expanded filter bar.

4 FieldGroup

Defines whether a filter field is initially shown on the filter dialog, and which group it belongs to.

5 FilterRestrictions/NonFilterableProperties

Defines whether a property is available as a filter criterion.

6 LineItem/Label

A short, human-readable text for the filter name.

SmartFilterBar Properties on the Filter Dialog

Data Types

The smart filter bar analyzes and interprets the metadata provided by the OData service. This allows you to create complex UI entities, and to automatically add fields offered by the OData service to the filter bar as editable input fields. (Note that only fields marked with sap:filterable are added automatically.)

The tables below tell you which input controls are used for the key data types.

General Data Types

DataType ODataMetadata Additional Configuration Edit type Display type Notes

* * Input Text

DateTime – sap:display-format=”Date” DatePicker Text

Decimal – Precision=”3″ Scale=”0″ Input Text

All – Input (with VHD) Text If a matching ValueList annotation is found, the ValueHelp for the Input is enabled.
A ValueHelp Dialog is created automatically, based on the data in the ValueList annotation.

All –
sap:semantics=”fixed-values” on the ValueList entity
ComboBox Text If a matching ValueList annotation is found, and the ValueList entity has the semantics=”fixed-values”, a dropdown list is shown.

Filter Bar-Specific Data Types

Input Type sap:filter-restriction display-format hasValueHelpDialog controlType Resulting Control Type

* * controlType/filterType is specified As specified in additional configuration

DateTime “interval” “Date” NA Date Range Selection

DateTime “anything other than interval” or empty “Date” NA Date Picker

String “single-value” “true” / none Input Field With Value Help Dialog
(with typeAhead according to hasTypeAhead flag)

String “single-value” “false” not specified/input Input Field
(with typeAhead according to hasTypeAhead flag)

String “single-value” “false” dropDownList; hasTypeAhead is not considered here ComboBox

* “single-value” Input Field

String empty or no filter-restriction “true” / none Multi Input Field with Value Help Dialog

String “multi-value” “true” / none If no VL Annotation is found – only show the range selection part

String “multi-value” / empty “false” If no VL Annotation is found – hide the ValueHelpDialog icon

String “multi-value” / empty “false” dropDownList MultiComboBox

* “multi-value” Input Field

* “interval” NA A single Input Field that allows the “-” shortcut notation for intervals

Properties

FilterBar

Filter Bar Properties

persistencyKey
Data type: string
Key used to access personalization data.

advancedMode
Data type: boolean
The advanced mode overwrites the standard behavior and is used in the value help scenario.
Default value is false.

expandAdvancedArea
Data type: boolean
Defines whether the advanced area is expanded when the filter bar is used within the value help dialog.
Default value is false.

searchEnabled
Data type: boolean
Enables/disables the Search button in advanced mode.
Default value is true.

filterBarExpanded
Data type: boolean
Shows/hides the expanded filter bar.
Default value is true.

considerGroupTitle
Data type: boolean
If this property is set, the label for filters is prefixed with the group title.
Default value is false.

showClearButton
Data type: boolean
Handles visibility of the Clear button on the Filters dialog.
Default value is false.

showRestoreButton
Data type: boolean
Handles visibility of the Restore button on the Filters dialog.
Default value is true.

showGoOnFB
Data type: boolean
Handles visibility of the Go button on the filter bar.
Default value is true.

showRestoreOnFB
Data type: boolean
Handles visibility of the Restore button on the filter bar.
Default value is false.

showClearOnFB
Data type: boolean
Handles visibility of the Clear button on the filter bar.
Default value is false.

showGoButton
Data type: boolean
Handles visibility of the Go button on the filter bar.

deltaVariantMode
Data type: boolean
Stores the delta as compared to the standard variant.
Default value is true.

filterContainerWidth
Data type: string
Sets the width of the filter container.
Default value is 12rem.

useToolbar
Data type: boolean
Determines what design should be used. Default is the design with the toolbar. In mobile scenarios this property is ignored – the design with the toolbar is always used.
Default value is true.

header
Data type: string
Specifies the header text that is shown in the toolbar on the first position. This property is ignored, when useToolbar is set to false.

showFilterConfiguration
Data type: boolean
Handles visibility of the Filters button on the filter bar.
Default value is true.

Smart Filter Bar

Smart Filter Bar Properties

entitySet
Data type: string
The OData entity set whose metadata is used to create the SmartFilterBar. Note: Changing this value after the SmartFilterBar is initialized (initialize event was fired) has no effect.

basicSearchFieldName
Data type: string
Name of the field that has to be the focus of the basic search. This is only relevant for SmartFilterBar in combination with ValueHelpDialog.

enableBasicSearch
Data type: boolean
Enables the basic search field in the SmartFilterBar control. This must only be enabled for entities that support such search behavior.
Default value is false.

liveMode
Data type: boolean
Defines the live mode. The live mode only operates on non-phone scenarios.
Default value is false.

showMessages
Data type: boolean
If set to false, any errors that occur during the search will not be displayed in a message box.
Default value is true.

considerAnalyticalParameters
Data type: boolean
Indicates if the analytical parameters (SelectionVariant) must be taken into consideration.
Default value is false.

Smart Filter Bar Annotations

FilterRestrictions/NonFilterableProperties
Defines whether a Property can be used for filtering data.

FieldGroup
Defines a group for a filter field.

TextArrangement
Describes the arrangement of a code value and its text.

FieldControlType/Hidden
Defines whether the filter is visible.

ValueList
Contains annotations that provide information for rendering a ValueHelpList that has been set for a Property.

Label
A short, human-readable text for the filter name.

LineItem/Label
A short, human-readable text suitable for the filter name.

FilterRestrictions/RequiredProperties
Defines the filter field as mandatory filter.

FilterExpressionType/MultiValue
Defines whether multiple values can be used in a single filter.

FilterExpressionType/SingleValue
Restricts the filter to allow only one value entry.

FilterExpressionType/SingleInterval
Restricts the filter to a specified interval, such as a date interval.

SelectionFields
Defines whether certain fields should be initially visible in the SmartFilterBar control.

Control Configuration

Control Configuration Properties

key
The key property corresponds to the field name from the OData service metadata document.
Default value is string

groupId
The groupId can be used to move a field from one group to another. The groupId corresponds to the EntityName from the OData metadata. It is also possible to move a field from the advanced area to the basic area by specifying the groupId _BASIC.
Default value is string

label
You can use this property to overwrite the label of a filter field in the SmartFilterBar.
Default value is string

visible
Data type: boolean
You can use this flag to hide fields from the OData metadata.
Default value is true

hasValueHelpDialog
Data type: boolean
Specifies whether a value help dialog is available or not.
Default value is true

controlType
Data type: sap.ui.comp.smartfilterbar.ControlType
The SmartFilterBar calculates which kind of control will be used for a filter field, based on multiple OData attributes and annotations. You can use this property to overwrite the OData metadata.
Default value is auto

filterType
Data type: sap.ui.comp.smartfilterbar.FilterType
The filter type specifies whether the filter field is for a single value, multiple values, or an interval. The filter type calculated by the SmartFilterBar is based on the OData metadata. You can use this property to configure the filter type manually.
Default value is auto

index
Data type: int
You can use the zero-based index to specify the initial order of fields (without any variants).
Default value is -1

Control Configuration Properties

hasTypeAhead
Data type: boolean
You can use this property to enable the TypeAhead service. Note that TypeAhead does not work with all controls (for example, it is not supported for the DropDownListbox).
Default value is true

mandatory
Data type: sap.ui.comp.smartfilterbar.MandatoryType
You can use this property to overwrite the mandatory state of a filter field. This property can only be set during initialization. Changes at runtime will be ignored.
Default value is auto

width
Default value is string
The width of the filter field in a CSS compatible format. The width can be set only once during initialization. Changes at runtime will not be reflected. The width is not applied to custom controls.

visibleInAdvancedArea
Data type: boolean
If set to true, this field will be added to the advanced area (aka. Dynamic Selection) by default.
Default value is false

preventInitialDataFetchInValueHelpDialog
Data type: boolean
If value help annotations are available for this filter field, you can prevent the the table in the value help dialog for this field from being filled with the initial data fetch.
Default value is true

displayBehaviour
Data type: sap.ui.comp.smartfilterbar.DisplayBehaviour
The displayBehaviour specifies how to display the content on certain controls. For example: DescriptionOnly for Combobox (DropDown text), Description and ID for MultiInput (token text)
Default value is auto

conditionType
Data type: any
The condition Type class name to use for this filter item. Implementation should derive from sap.ui.comp.config.condition.Type.

Group Configuration

Group Configuration Properties

key
Data type: string
The key property shall correspond to the name EntityTypeName from the OData service $metadata document.

index
Data type: any
Zero-based integer index. The index can be used to specify the order of groups. If no index is specified, the order defined by the OData metadata will be used.
Default value is undefined

label
Data type: any
You can use this property to overwrite the label of a group in the advanced area of the SmartFilterBar.
Default value is undefined

Resources

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

Elements and Controls

Filter Bar/ Smart Filter Bar (guidelines)

Implementation

Smart Filter Bar (SAPUI5 samples)

Smart Filter Bar (SAPUI5 API reference)

UI Development Toolkit (SAPUI5 samples)

Smart Table

The smart table is a wrapper around existing tables, and can be used together with the responsive table, grid table, analytical table, or tree table.

The smart table creates columns automatically based on the underlying OData service plus corresponding annotations. It also adds some generic functionality, such as a toolbar, complex personalization settings, variant management, and export to spreadsheet.

Everything that can be done using the smart table can also be achieved using the responsive table, grid table, analytical table, or tree table directly, but with more development effort. Therefore, the main purpose of the smart table is to reduce development effort. However, this comes at the expense of decreased flexibility.

Usage

Use the smart table if:

Data is fed into the table through OData services.

You need a simple table with limited flexibility to display its content. In this case, the smart table reduces development effort.

You need a table in which some columns provide flexible content. In this case, use the smart table together with a responsive table, and provide app-specific column definitions for these columns.

Do not use the smart table if:

You create your own UI coding, whereby the data is not fed through OData services. In this case, use the underlying table control directly.

The main use case involves selecting one item from very few items, with no additional details. In this case, a select or combo box might be more suitable.

The main use case involves selecting one item from several items, with only a few details per item. In this case, a list might be more suitable. Pay attention to the layout of the list item to provide a pleasant appearance (see, for example, the master list and the feed list item).

The table is displayed together with a chart inside a chart container. The smart table is not designed to work inside an existing chart container. In this case, use the underlying table control directly.

You need an overview of a large amount of data. In this case, use charts.

You just need it for layout reasons. In this case, use a layout container, such as the grid layout, instead.

You need read-only or editable field value pairs. In this case, use a form instead. Tables are not optimized for form-like input navigation.

Responsiveness

The responsiveness of the smart table depends on the encapsulated table. The table toolbar uses the overflow mechanism for adapting to the screen width.

Using the responsive table

The smart table offers a generic responsive behavior (sap.ui.comp.smarttable.SmartTable, property: smartFilterId, value: true):

For every 10 rem of screen width, one column stays in the tabular layout. All others are moved to the pop-in area. The columns are moved to the pop-in area from right to left, so the column furthest to the right moves to the pop-in first.

Exception: The first two columns always stay in the tabular layout. This works best if the smart table uses the whole screen width. It might not work well if the smart table uses far less space.

Using the grid table, analytical table, or tree table

The smart table works only on desktop and tablets, but not on smartphones. It supports touch devices, but is not optimized for small screens.

If you use a smart table in this configuration, ensure that you implement a fallback solution for small screens. This fallback solution does not need to support all use cases. You could create a fallback by using a responsive table. However, a completely different solution, such as showing charts in a read-only case, might be more suitable.

Size S with responsive table
Size M with responsive table
Size L with responsive table
Size M with grid table
Size L with grid table

Layout

The title bar contains the title of the smart table, the item count, variant management, and the toolbar itself. All of these elements are optional.
The table area shows the corresponding table (responsive table, grid table, analytical table, or tree table).

Schematic visualization of the smart table

Components

The title bar consists of a toolbar.

This can be the standard toolbar or a custom toolbar. The standard toolbar can contain a title text with or without item count, variant management, view switch (switching the table to edit mode), an entry point for the P13n dialog, and an Export to Spreadsheet action.

If you require additional functionality, you can use an app-specific toolbar. All toolbar options provided by the smart table can also be added to the app-specific toolbar. (Aggregation: customToolbar)

The table area consists of any of the following tables: responsive table, grid table, analytical table, or tree table.

Standard toolbar with everything enabled
Standard toolbar just with title and item count

Behavior and Interaction

The behavior is generally inherited from the underlying table, toolbar, variant management, 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.

Table Level

Table Type

The smart table can encapsulate the responsive table, grid table, analytical table, or tree table. (sap.ui.comp.smarttable.SmartTable, property: tableType)

Automatic Rendering of the Table

The smart table automatically creates columns and renders all items based on the metadata of the underlying OData service (sap.ui.comp.smarttable.SmartTable, property: smartFilterId).

To be more flexible in the table layout, the smart table also offers app-specific column templates for some or all columns. In this case, app developers must provide the definition for the underlying table and for the corresponding (but not necessarily for all) columns in the XML view. For this, the app development team must provide the column keys of the overridden columns via custom data.

Additional columns can also be added. Columns that are defined in this way retain all the options of the underlying table. This is especially useful with the responsive table, which offers complete flexibility in content design. Any columns that are not defined by the app development team are still rendered automatically by the smart table.

No Data

If there is no data to show, the smart table renders default text. This text can be overwritten by the app development team (aggregation: NoData).

Initially Visible Columns

The smart table enables you to define which columns are initially shown. Here, initially means that these columns are shown when the app is first launched. All other columns are initially hidden (annotation: PresentationVariant/ LineItem, property: initiallyVisibleColumns).

Persistency

End users can show additional columns if table personalization is provided. In this case, column settings are persisted. On consecutive startups, the columns are shown with the same settings as last defined by the user (property: persistenceKey).

Removing Columns

The smart table always shows all columns from the OData model. In some cases, columns needs to be in the model but should not be available on the front end at all. Examples of this include:

A column is needed to provide an ID which is used for navigation purposes, but the front end should only display the corresponding text, not the ID.

The values of a column are needed to perform calculations, but only the results should be shown on the UI.

In these cases, you can define which columns should not be available at all on the UI. These columns are not shown and are not available in the P13n dialog. You can also do this for columns that are added manually in the XML view (annotation: sap:visible, value:false).

P13n/personalization dialog

Filter Settings

The “Show Field as Column” option for newly added filters is switched on by default.

Sorting and Filtering

The smart table allows you to add sort and filter settings for each column. These settings enable the corresponding pages in the P13n dialog. For the grid table, analytical table, and tree table, sorting and filtering are also enabled on the column header. (Annotations: sap:sortable and sap:filterable)

Column header menu of the grid table

Smart Table and Smart Filter Bar

The smart table can be linked to a smart filter bar. If linked, filter bar settings are automatically used on the smart table. (sap.ui.comp.smarttable,SmartTable, property:smartFIlterId)

Aggregation

If used with the analytical table, the smart table allows total sums of measure columns to be calculated. The totals are shown in the usual way:

As the last row of the analytical table.

As the last row of each group if the group is expanded.

On the group header of each group if the group is collapsed.

Aggregation settings are not persisted (annotation: sap:aggregation-role, value:measure).

The total count be hidden via the column header menu.

Aggregation entry in column header menu of the grid table

Column Width

A default column width is calculated for each column based on the data displayed in it. Important: end users cannot change the column width in the responsive table (annotations: MaxLength, Precision, Scale).

Column Header

A column header text can be specified for each column (annotation: sap:label).

Persistence

The smart table allows you to persist sort, group, and filter column settings (such as by hidden columns) as well as variants (sap.ui.comp.smarttable.SmartTable, Property:persistenceyKey).

Content

The smart table provides two options to create columns automatically:

The smart table is rendered in either read-only or edit mode. In this case, the smart table renders the controls as described below. This is the default way of rendering content (property: editable)

If users need to switch between read-only and edit mode at runtime, the smart table allows smart fields to be rendered instead. You should use this if the edit button is added to the toolbar of the smart table (aggregation: customData key: useSmartField, property: smartToggle).

For option 1, the following controls are used:

To show currency amounts, the smart table allows the amount and the currency code to be displayed in a single cell. For read-only mode, the currency control is used. For edit mode, a single input field is used, and the currency itself is shown next to the input field as non-editable text (annotation: sap:semantics, value: currency-code).

To show links that open a quick view, the smart table supports the smart link.

To show static text, the smart table uses an input field in edit mode, and a text in read-only mode.

To show dates, the smart table uses a date picker in edit mode, and a text in read-only mode (annotation: sap:display-format, value:Date).

To show decimal numbers, the smart table uses an input field in edit mode, and a text in read-only mode (Annotations:Precision, Scale).

The smart table also provides an object status and object identifier control. For more information, see object display components.

Pictures and microcharts, as well as rating indicators and progress bars are available.

Amount formatting
Link formatting
Date formatting

Value Help

The smart table supports value help in the following ways (annotation: ValueList):

Input fields can show a value help button. Triggering this button opens a value help dialog. Within this dialog, you can provide a search field (annotation:ValueList, property: SearchSupported).

You can restrict the number of characters for the input field. Use this if no ValueList annotation is provided (annotation:MaxLength).

Toolbar Level

Table Title

The smart table can provide a title for the table within the toolbar (sap.ui.comp.smarttable.SmartTable, Property:header).

Table title

Item Count

Next to the table title, an item count can be shown (sap.ui.comp.smarttable.SmartTable, Property:showRowCount).

Table title with item count

Edit

The table toolbar can contain a button for toggling the table between read-only and edit modes. If smart fields are used, the smart table handles both modes automatically (sap.ui.comp.smarttable.SmartTable, properties:editTogglable, smartToggle, aggregation: customData, key: useSmartField).

If used with the responsive table, the edit button also switches the keyboard behavior accordingly.

Edit button

View Settings

The table toolbar can contain a button for opening the P13n dialog. This dialog provides extensive sort, group, and filter settings. It also allows columns to be shown, hidden, or rearranged (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).

Settings button

Export to Spreadsheet

If the back end supports the export of data to spreadsheet, the table toolbar can contain a corresponding button. When this button is triggered, the corresponding file is created and the download starts automatically (sap.ui.comp.smarttable.SmartTable, Property:useExportToExcel).

Export to Spreadsheet button

Full Screen Mode

Applications can implement a maximize button to run the table in full screen (Property: showFullScreenButton).

Maximize button

Footer Toolbar Level

Buttons in the footer toolbar can be set to emphasized to give them a brighter appearance.

Guidelines

In general, the guidelines for the underlying table, toolbar, variant management, and P13n dialog also apply to the smart table (see the corresponding articles for details). However, because the smart table does not offer the complete flexibility of the underlying controls, there are certain differences.

Table Type

The responsive table is the standard table for SAP Fiori. Use the responsive table whenever possible. It is the most flexible table in terms of how its content is displayed, it is fully responsive, and it can handle up to 1,000 line items.

If you cannot use the responsive table, consider using the grid table instead. The grid table can handle a large number of line Items. Compared to the responsive table, however, it is more restricted content-wise (only certain controls can be used to show the data, and only one control per cell), and it does not run on smartphones. If you use the grid table, you need to provide a fallback solution for smartphones, for example, by using the responsive table.

The analytical table is similar to the grid table, but adds several grouping levels and offers total sums on measure columns. The analytical table can also handle a large number of line Items. Compared to the responsive table, however, it is more restricted content-wise (only certain controls can be used to show the data, and only one control per cell), and it does not run on smartphones. If you use the analytical table, you need to provide a fallback solution for smartphones, for example, by using the responsive table.

The tree table is the only table for displaying hierarchical data. Like the grid table, it can handle a large number of line items, although it is restricted content-wise (only certain controls can be used to show the data, and only one control per cell), and it does not run on smartphones. If you use the tree table, you need to provide a fallback solution for smartphones, for example, by using the responsive table.

For more information about the different table controls, see the corresponding articles.

Table Title, Item Count, and Variant Management

Always show the item count together with the table title, unless this is expected to cause performance problems.
If used with the responsive table and if more than 200 items are generally expected, do not show the item count. In this case, the smart table displays a More button to load additional rows. Using the item count together with the More button might lead to confusion (sap.ui.comp.smarttable.SmartTable, Property:showRowCount).

Even if variant management is easy to implement, use it only if it is really needed. The variant management saves the whole page, including filter settings and table layouts.

Empty Tables

Try not to display an empty table. If there is no way around this, provide instructions on how to fill the table with data (aggregatrion: noData).

Columns – Best Practices

Keep the number of initially shown columns to a minimum. Avoid the need to scroll horizontally on a tablet screen size in default delivery (annotation: PresentationVariant/ LineItem).

Keep the number of additional (initially hidden) columns to a minimum. You can use the P13n dialog to show/hide the columns. Select the columns offered in the P13n dialog carefully. Do not just show all columns available in the backend tables (annotation: sap:visible, value:false).

For the grid table, analytical table, and tree table, the column widths are calculated automatically if the corresponding OData annotations are provided (annotations: MaxLength, Precision, Scale).

In contrast, the responsive table uses the same width for all columns.

If used with the responsive table, enable the pop-in behavior (sap.ui.comp.smarttable.SmartTable, property: smartFilterId, value: true).

Show the most important column on the left and the least important on the right. This ensures that the most important columns stay in the tabular layout as long as possible. The most important columns are those that contain the following information:

The column that identifies the line item

The column that contains the key attribute

(Annotation: PresentationVariant/ LineItem, Property: initiallyVisibleColumns)

Email column in the pop-in area of the responsive table

Provide a column header text for each column. Do not truncate the column header text in default delivery (annotation: sap:label).

Column header text

Content Alignment and Formatting

The smart table automatically takes care of content alignment and formatting in standard use cases. For this, the OData metadata needs to provide the correct information about the data types, semantics of, and value help for the data.
(Annotations such as: sap:semantics, value: currency-code, edm types, Annotation: sap:display-format, value:Date, Annotation:Precision, Annotation: Scale, Annotation: ValueList, Annotation: ValueList:semantics, value:fixed-values)

Highlight Items

If the smart table is used with the responsive table, you can show the status of an item by displaying a highlight indicator in front of the item (property: highlight). The highlight indicator can be used to show:

A semantic state, such as red or orange for an error or warning

A neutral highlight, such as blue to highlight newly added items

Highlighted items

Actions

To trigger actions on multiple items, use a mutliselection smart table. Do not offer action triggering on multiple items if the table is expected to have fewer than 10 items in most cases.
While the grid table, analytical table, and tree table are multiselectable by default within the smart table, the responsive table is single-selectable. The selection mode can be changed (XMLView).

The following actions can be shown on the standard toolbar of the smart table:

Edit
Toggles the table between edit and read-only mode. This only works if smart fields are used inside the smart table (sap.ui.comp.smarttable.SmartTable, properties:editTogglable, smartToggle, aggregation: customData, key: useSmartField).

View Settings
This button opens the P13n dialog. Note that the P13n dialog is quite complex. Neither the simpler view settings dialog nor the table personalization dialog can be used without the app development team developing the entire view settings handling (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).

Export to Spreadsheet
Only use this option if your end users typically export the data shown in the table in order to work with it in a spreadsheet application. This is usually the case if data is collected from several systems and analyzed in the spreadsheet application. This is not usually the case for worklists, attachment lists, lists with only a few items, shopping carts, or data that does not need to be analyzed. This option is only available if the corresponding back end supports exporting to spreadsheet (sap.ui.comp.smarttable.SmartTable, property: useExportToExcel).

If additional actions are needed, use a custom toolbar for the table. The smart table can also add integrated functionality such as a table title, item count, variant management, edit and view settings, and export to spreadsheet to the custom toolbar (aggregation: customToolbar).

For navigation to line item details:

If used with the responsive table, use the navigation mode of the responsive table.

If used with the grid table, analytical table, or tree table, use a link for the attribute that identifies the row. The user can click this link to trigger the navigation.

Clicking a table row can trigger drill-in navigation to a deeper level of the object, as well as cross-navigation to another SAP Fiori app or even to another system.

Inline Actions

Actions that belong to single items can be placed within the row. They can be displayed as text or icons. Make sure the icon communicates the function clearly enough. Otherwise, use a textual button.

Editable Content

The smart table can be editable or read-only (sap.ui.comp.smarttable.SmartTable, property: editable).

The smart table selects the corresponding editable controls automatically based on the data type, semantic annotations, and value list annotations (annotations such as: sap:semantics, value: currency-code, edm types, Annotation: sap:display-format, value:Date, Annotation:Precision, Annotation: Scale, Annotation: ValueList, Annotation: ValueList:semantics, value:fixed-values).

If an edit mode is needed, the controls are automatically switched from read-only controls (such as text) to editable controls (such as input field or date picker) if smart fields are used inside the smart table (sap.ui.comp.smarttable.SmartTable, Property:editTogglable, smartToggle, aggregation: customData, key: useSmartField). The keyboard behavior is switched accordingly, if this is used together with the responsive table.

Only use this if you need to toggle between both modes. In any other case, show only the mode you need (read-only or edit), but do not offer the switch.

View Settings: Sort, Filter, Group, and Column Settings

If view settings are enabled on the smart table, a settings button is available on the table toolbar. This button opens the P13n dialog. Neither the simpler view settings dialog nor table personalization dialog can be used without extra effort (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).

The P13n dialog always enables the user to show, hide, and rearrange columns. Alternatively, it can contain settings for sorting, grouping, and/or filtering (annotations: sap:sortable, sap:filterable)

If the smart table uses the grid table, analytical table, or tree table, sort, filter, and group settings are also available in the column header menu.

Offer view settings only if they are really needed. For example, these settings do not make sense if the table contains only a few items and just a few columns.

Note that the P13n dialog is quite complex. It is ideal for tables with a vast number of items, but is quite cumbersome for handling just a few hundred items. Therefore, show only the settings (sort, group, filter) you really need. For example, do not offer grouping if it does not support your use case well.

If filtering is a main use case, do not offer filtering in the P13n dialog. Use the filter bar instead (annotation: sap:filterable)

Be persistent: When the app is reopened, the smart table is shown with the same view settings as last defined by the user (sap.ui.comp.smarttable.SmartTable, property: persistenceKey).

Sort

The current sort state is displayed as follows:

Using the responsive table, there is no indication that the table is currently sorted.

Using the grid table, analytical table, or tree table, an icon in the column header of the last sorted column indicates that the table is sorted and the direction in which it is sorted.

In default delivery, sort items in a meaningful order by the row-identifying column (usually the first column in default delivery). For example, use an alphabetical order for text, a numeric order for numbers, and a chronological order for dates (annotations: sap:sortable, PresentationVariant – SortOrder).

Filter

The current filter state is displayed as follows:

Using the responsive table, there is no indication that the table is currently filtered. The filter info bar can be added with additional effort.

Using the grid table, analytical table, or tree table, filtering is displayed by an icon on the column header of each filtered column (annotation: sap:filterable).

Group

Group headers display the current group state and are shown automatically. The following text should be shown on the group header:

[Label of the grouped column]: [Grouping value]
This can be done by the smart table, but only if the raw data from the model can be used. In other cases, app development teams must format the group header text. For example, the raw data carries IDs, while the table displays the corresponding names, which are provided by another data source. In this case, app developers must provide the formatting for the group header texts.

Within the responsive table, the grouped column keeps its visibility to reduce confusion after the group settings have been changed. If visible, it stays in the tabular layout even if grouped.

If used with the analytical table, grouping is not offered on measures. Therefore, you can have aggregations or grouping for a specific column.

Reasonable grouping can be offered by default via the property GroupBy.

Responsive table grouped by country

Aggregate

If used with the analytical table, aggregation settings can be provided on measure columns. These settings are only available in the column header menu.
To display the current aggregation state, the total sum of the corresponding column is shown at the bottom of the table.
If items are grouped, an intermediate sum is shown per group:

At the bottom of each group if the group is expanded.

In the group header if the group is collapsed.

Aggregations are only available on measures, but not on objects or attributes. If aggregation is enabled for a column, this column cannot be grouped.

Avoid aggregations on the first three columns for the default delivery. When grouping is used together with aggregations, collapsing a group shows the aggregation on the group header. This conflicts with the group name.

Where appropriate, offer reasonable aggregation by default (annotation: sap:aggregation-role, value: measure).

Column Settings

Only offer column settings if you need more columns than a tablet screen can display at a time (usually more than five).

If sorting, grouping, and/or filtering are needed, column settings must also be shown (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).

Add, Remove, Rearrange Columns

Use the P13n dialog to add, remove, and rearrange columns.

When used with the grid table, analytical table, or tree table, columns can also be rearranged by dragging and dropping the column header (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).

Resize Columns

When used with the grid table, analytical table, or tree table, columns can be resized on the column header (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).

Freeze Columns

When used with the grid table, analytical table, or tree table, app developers must manually add the options for freezing columns to the column header menu if necessary. They can do this by declaring the corresponding table inside the smart table in the XML view, and by using the corresponding settings on this inner table.

Selecting Freeze on a column freezes all columns from the first one to the one on which Freeze is selected. The menu entry on this column changes from Freeze to Unfreeze.

Properties

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

The property: ignoreFields defines the columns that are not available on the UI – neither in the initial visible columns nor in the P13n dialog.

The property: requestAtLeastFields can be used for requesting additional technical columns.

The property: ignoreFromPersonalization removes columns from the P13n dialog.

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

The property: enableCustomFilter allows the filter menu item in the column header menu to be exchanged.

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

The property: currentVariantId defines the currently used variant.

The property: enableAutoBinding fetches the data automatically as soon as the corresponding OData model is initialized and the smart table is created.

The property: tableBindingPath defines the path from which the data is fetched.

The property: smartToggle influences the way on which controls are displayed in the smart table if smart fields are used.

The following aggregations are available:

The aggregation: semanticObjectController is used to customize smart links inside the smart table.

The aggregation: noData provides a text in case the table contains no line items. For example, this can be the case if the table is filtered. The text should provide context-specific instructions on how to get data into the table.

Resources

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

Elements and Controls

Responsive Table (guidelines)

Grid Table (guidelines)

Analytical Table (guidelines)

Tree Table (guidelines)

Table Overview (guidelines)

Table Toolbar (guidelines)

Variant Management (guidelines)

P13n-Dialog (guidelines)

Implementation

Smart Table (SAPUI5 samples)

Smart Table (SAPUI5 API reference)

Smart Table (Developer Guide)

P13n-Dialog (SAPUI5 samples)

P13n-Dialog (SAPUI5 API reference)

Toolbar (SAPUI5 samples)

Smart Link

Like the quick view, the smart link triggers a popover from a text link. This popover shows additional information, such as simple object details, and offers links to related apps for the user to take action. The user can choose which links are shown in the popover by selecting them in a separate dialog.
The smart link is a smart control that uses metadata annotations to offer user-specific navigation. It analyzes the user’s assigned apps and offers only relevant navigation targets.

Usage

Use the smart link to offer direct navigation to related apps. For example:

Navigate from a product list to the app to change the pricing

Navigate from a sales order list to the app to see a customer’s balance

Use the smart link if:

You want to offer related apps for navigation.

You want to display simple object details.

Do not use the smart link if:

You want to display more or complex information about an object. Use the object page or charts instead.

No metadata is accessible, and only a direct link to a website, document or application is needed. Use the standard link instead.

You need to structure information in a deeper hierarchy. Use the quick view or a list drilldown instead.

Responsiveness

The responsiveness of the smart link is based on the responsiveness of the popover and overlays the content.

On a desktop device, clicking anywhere in the background closes the popover.

On mobile devices, the smart link opens a dialog that overlays the entire content. Because the content underneath the popover is no longer directly visible to the end user, the dialog has a header and shows the object type. The dialog can be closed by clicking the close icon () in the header.

Size S – On smartphones, the smart link overlays the content

Sizs M/ L - Smart link shown in a table on a desktop device

Layout

The smart link contains the following areas:

The header bar of the smart link popover indicates the type of object and is only shown on mobile devices.

The title area contains a title and a subtitle. The title can also be shown as a link, which can be used to navigate to the corresponding object or fact sheet. The subtitle can be used to show the ID of the object, for example.

The content area shows object-related information, such as details about a product or contact information. You can use any UI control, based on what best fits your use case.

The link area offers links to all other apps that are relevant for a user role. The link list includes all semantic objects defined for the app, and can also include additional links defined manually by the application development team. The link area can have two states:

Link area is empty:
If no links have been selected for the app, or if there are more than 10 links, the link area is initially empty. Instead, the user sees a Define Links button, which opens a dialog for selecting the links to be shown.

Links are shown:
As soon the link area contains links, the button text changes to More. This opens the same selection dialog.

Only the header bar is mandatory (for mobile devices). All the other sections are optional. Depending on the use case, the application could offer only a content area, or a only a link area, for example.

The areas of the smart link (header bar not shown)

Behavior and Interaction

The smart link and its popover are always triggered by clicking or tapping a text element that appears as a link. This text element can be placed in any list, table, or other container. The link label can be set individually. Clicking or tapping the background closes the popover. If only one link is offered, and there is no additional information, the smart link control navigates directly to the target without opening the popover.

If the semantic object annotation is not set, the smart link is rendered as sap.m.Text by default. However, app developers can also decide to render any other control.

Link Selection Dialog

Clicking the More or Define Links button opens the Define Link List dialog. There, the user can select the app links to be displayed in the link area. The links offered in the selection list are modifiable semantic objects suggested by the smart link control. Application development teams can remove links from the selection list and change the link texts. They can also manually add links to any website or app.

Exception: Within an SAP Fiori element, the links offered in the Define Link List dialog are generated automatically. Application teams cannot adapt the list.

You can switch off the More/Define Links option by setting the property enableAvailableActionsPersonalization to “false”. By default it is set to “true”.

Smart Links in a Smart Table

Within a smart table, the link label of the smart link is set automatically using the semantic object annotation. In other words, the description cannot be changed. If there are no navigation targets, the smart link is rendered as sap.m.Text.

Link selection dialog with a list of application links

Guidelines

Please check the related apps you offer carefully. Only display the ones that are relevant to the user.

Use meaningful link names in the link area. Do not use the same link name more than once. If necessary, rename the links to suit your context (for example, “Add Product” instead of “Manage Products”).

Resources

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

Elements and Controls

Quickview (guidelines)

Popover (guidelines)

Implementation

Smart Link (SAPUI5 samples)

Smart Link (SAPUI5 API reference)

Smart Table

The smart table is a wrapper around existing tables, and can be used together with the responsive table, grid table, analytical table, or tree table.

The smart table creates columns automatically based on the underlying OData service plus corresponding annotations. It also adds some generic functionality, such as a toolbar, complex personalization settings, variant management, and export to spreadsheet.

Everything that can be done using the smart table can also be achieved using the responsive table, grid table, analytical table, or tree table directly, but with more development effort. Therefore, the main purpose of the smart table is to reduce development effort. However, this comes at the expense of decreased flexibility.

Usage

Use the smart table if:

Data is fed into the table through OData services.

You need a simple table with limited flexibility to display its content. In this case, the smart table reduces development effort.

You need a table in which some columns provide flexible content. In this case, use the smart table together with a responsive table, and provide app-specific column definitions for these columns.

Do not use the smart table if:

You create your own UI coding, whereby the data is not fed through OData services. In this case, use the underlying table control directly.

The main use case involves selecting one item from very few items, with no additional details. In this case, a select or combo box might be more suitable.

The main use case involves selecting one item from several items, with only a few details per item. In this case, a list might be more suitable. Pay attention to the layout of the list item to provide a pleasant appearance (see, for example, the master list and the feed list item).

The table is displayed together with a chart inside a chart container. The smart table is not designed to work inside an existing chart container. In this case, use the underlying table control directly.

You need an overview of a large amount of data. In this case, use charts.

You just need it for layout reasons. In this case, use a layout container, such as the grid layout, instead.

You need read-only or editable field value pairs. In this case, use a form instead. Tables are not optimized for form-like input navigation.

Responsiveness

The responsiveness of the smart table depends on the encapsulated table. The table toolbar uses the overflow mechanism for adapting to the screen width.

Using the responsive table

The smart table offers a generic responsive behavior (sap.ui.comp.smarttable.SmartTable, property: smartFilterId, value: true):

For every 10 rem of screen width, one column stays in the tabular layout. All others are moved to the pop-in area. The columns are moved to the pop-in area from right to left, so the column furthest to the right moves to the pop-in first.

Exception: The first two columns always stay in the tabular layout. This works best if the smart table uses the whole screen width. It might not work well if the smart table uses far less space.

Using the grid table, analytical table, or tree table

The smart table works only on desktop and tablets, but not on smartphones. It supports touch devices, but is not optimized for small screens.

If you use a smart table in this configuration, ensure that you implement a fallback solution for small screens. This fallback solution does not need to support all use cases. You could create a fallback by using a responsive table. However, a completely different solution, such as showing charts in a read-only case, might be more suitable.

Size S with responsive table
Size M with responsive table
Size L with responsive table

Size M with grid table
Size L with grid table

Layout

The title bar contains the title of the smart table, the item count, variant management, and the toolbar itself. All of these elements are optional.
The table area shows the corresponding table (responsive table, grid table, analytical table, or tree table).

Schematic visualization of the smart table

Components

The title bar consists of a toolbar.

This can be the standard toolbar or a custom toolbar. The standard toolbar can contain a title text with or without item count, variant management, view switch (switching the table to edit mode), an entry point for the P13n dialog, and an Export to Spreadsheet action.

If you require additional functionality, you can use an app-specific toolbar. All toolbar options provided by the smart table can also be added to the app-specific toolbar. (Aggregation: customToolbar)

The table area consists of any of the following tables: responsive table, grid table, analytical table, or tree table.

Standard toolbar with everything enabled
Standard toolbar just with title and item count

Behavior and Interaction

The behavior is generally inherited from the underlying table, toolbar, variant management, 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.

Table Level

Table Type

The smart table can encapsulate the responsive table, grid table, analytical table, or tree table. (sap.ui.comp.smarttable.SmartTable, property: tableType)

Automatic Rendering of the Table

The smart table automatically creates columns and renders all items based on the metadata of the underlying OData service (sap.ui.comp.smarttable.SmartTable, property: smartFilterId).

To be more flexible in the table layout, the smart table also offers app-specific column templates for some or all columns. In this case, app developers must provide the definition for the underlying table and for the corresponding (but not necessarily for all) columns in the XML view. For this, the app development team must provide the column keys of the overridden columns via custom data.

Additional columns can also be added. Columns that are defined in this way retain all the options of the underlying table. This is especially useful with the responsive table, which offers complete flexibility in content design. Any columns that are not defined by the app development team are still rendered automatically by the smart table.

No Data

If there is no data to show, the smart table renders default text. This text can be overwritten by the app development team (aggregation: NoData).

Initially Visible Columns

The smart table enables you to define which columns are initially shown. Here, initially means that these columns are shown when the app is first launched. All other columns are initially hidden (annotation: PresentationVariant/ LineItem, property: initiallyVisibleColumns).

Persistency

End users can show additional columns if table personalization is provided. In this case, column settings are persisted. On consecutive startups, the columns are shown with the same settings as last defined by the user (property: persistenceKey).

Removing Columns

The smart table always shows all columns from the OData model. In some cases, columns needs to be in the model but should not be available on the front end at all. Examples of this include:

A column is needed to provide an ID which is used for navigation purposes, but the front end should only display the corresponding text, not the ID.

The values of a column are needed to perform calculations, but only the results should be shown on the UI.

In these cases, you can define which columns should not be available at all on the UI. These columns are not shown and are not available in the P13n dialog. You can also do this for columns that are added manually in the XML view (annotation: sap:visible, value:false).

P13n/personalization dialog

Filter Settings

The “Show Field as Column” option for newly added filters is switched on by default.

Sorting and Filtering

The smart table allows you to add sort and filter settings for each column. These settings enable the corresponding pages in the P13n dialog. For the grid table, analytical table, and tree table, sorting and filtering are also enabled on the column header. (Annotations: sap:sortable and sap:filterable)

Column header menu of the grid table

Smart Table and Smart Filter Bar

The smart table can be linked to a smart filter bar. If linked, filter bar settings are automatically used on the smart table. (sap.ui.comp.smarttable,SmartTable, property:smartFIlterId)

Aggregation

If used with the analytical table, the smart table allows total sums of measure columns to be calculated. The totals are shown in the usual way:

As the last row of the analytical table.

As the last row of each group if the group is expanded.

On the group header of each group if the group is collapsed.

Aggregation settings are not persisted (annotation: sap:aggregation-role, value:measure).

The total count be hidden via the column header menu.

Aggregation entry in column header menu of the grid table

Column Width

A default column width is calculated for each column based on the data displayed in it. Important: end users cannot change the column width in the responsive table (annotations: MaxLength, Precision, Scale).

Column Header

A column header text can be specified for each column (annotation: sap:label).

Persistence

The smart table allows you to persist sort, group, and filter column settings (such as by hidden columns) as well as variants (sap.ui.comp.smarttable.SmartTable, Property:persistenceyKey).

Content

The smart table provides two options to create columns automatically:

The smart table is rendered in either read-only or edit mode. In this case, the smart table renders the controls as described below. This is the default way of rendering content (property: editable)

If users need to switch between read-only and edit mode at runtime, the smart table allows smart fields to be rendered instead. You should use this if the edit button is added to the toolbar of the smart table (aggregation: customData key: useSmartField, property: smartToggle).

For option 1, the following controls are used:

To show currency amounts, the smart table allows the amount and the currency code to be displayed in a single cell. For read-only mode, the currency control is used. For edit mode, a single input field is used, and the currency itself is shown next to the input field as non-editable text (annotation: sap:semantics, value: currency-code).

To show links that open a quick view, the smart table supports the smart link.

To show static text, the smart table uses an input field in edit mode, and a text in read-only mode.

To show dates, the smart table uses a date picker in edit mode, and a text in read-only mode (annotation: sap:display-format, value:Date).

To show decimal numbers, the smart table uses an input field in edit mode, and a text in read-only mode (Annotations:Precision, Scale).

The smart table also provides an object status and object identifier control. For more information, see object display components.

Pictures and microcharts, as well as rating indicators and progress bars are available.

Amount formatting
Link formatting
Date formatting

Value Help

The smart table supports value help in the following ways (annotation: ValueList):

Input fields can show a value help button. Triggering this button opens a value help dialog. Within this dialog, you can provide a search field (annotation:ValueList, property: SearchSupported).

You can restrict the number of characters for the input field. Use this if no ValueList annotation is provided (annotation:MaxLength).

Toolbar Level

Table Title

The smart table can provide a title for the table within the toolbar (sap.ui.comp.smarttable.SmartTable, Property:header).

Table title

Item Count

Next to the table title, an item count can be shown (sap.ui.comp.smarttable.SmartTable, Property:showRowCount).

Table title with item count

Edit

The table toolbar can contain a button for toggling the table between read-only and edit modes. If smart fields are used, the smart table handles both modes automatically (sap.ui.comp.smarttable.SmartTable, properties:editTogglable, smartToggle, aggregation: customData, key: useSmartField).

If used with the responsive table, the edit button also switches the keyboard behavior accordingly.

Edit button

View Settings

The table toolbar can contain a button for opening the P13n dialog. This dialog provides extensive sort, group, and filter settings. It also allows columns to be shown, hidden, or rearranged (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).

Settings button

Export to Spreadsheet

If the back end supports the export of data to spreadsheet, the table toolbar can contain a corresponding button. When this button is triggered, the corresponding file is created and the download starts automatically (sap.ui.comp.smarttable.SmartTable, Property:useExportToExcel).

Export to Spreadsheet button

Full Screen Mode

Applications can implement a maximize button to run the table in full screen (Property: showFullScreenButton).

Maximize button

Footer Toolbar Level

Buttons in the footer toolbar can be set to emphasized to give them a brighter appearance.

Guidelines

In general, the guidelines for the underlying table, toolbar, variant management, and P13n dialog also apply to the smart table (see the corresponding articles for details). However, because the smart table does not offer the complete flexibility of the underlying controls, there are certain differences.

Table Type

The responsive table is the standard table for SAP Fiori. Use the responsive table whenever possible. It is the most flexible table in terms of how its content is displayed, it is fully responsive, and it can handle up to 1,000 line items.

If you cannot use the responsive table, consider using the grid table instead. The grid table can handle a large number of line Items. Compared to the responsive table, however, it is more restricted content-wise (only certain controls can be used to show the data, and only one control per cell), and it does not run on smartphones. If you use the grid table, you need to provide a fallback solution for smartphones, for example, by using the responsive table.

The analytical table is similar to the grid table, but adds several grouping levels and offers total sums on measure columns. The analytical table can also handle a large number of line Items. Compared to the responsive table, however, it is more restricted content-wise (only certain controls can be used to show the data, and only one control per cell), and it does not run on smartphones. If you use the analytical table, you need to provide a fallback solution for smartphones, for example, by using the responsive table.

The tree table is the only table for displaying hierarchical data. Like the grid table, it can handle a large number of line items, although it is restricted content-wise (only certain controls can be used to show the data, and only one control per cell), and it does not run on smartphones. If you use the tree table, you need to provide a fallback solution for smartphones, for example, by using the responsive table.

For more information about the different table controls, see the corresponding articles.

Table Title, Item Count, and Variant Management

Always show the item count together with the table title, unless this is expected to cause performance problems.
If used with the responsive table and if more than 200 items are generally expected, do not show the item count. In this case, the smart table displays a More button to load additional rows. Using the item count together with the More button might lead to confusion (sap.ui.comp.smarttable.SmartTable, Property:showRowCount).

Even if variant management is easy to implement, use it only if it is really needed. The variant management saves the whole page, including filter settings and table layouts.

Empty Tables

Try not to display an empty table. If there is no way around this, provide instructions on how to fill the table with data (aggregatrion: noData).

Columns – Best Practices

Keep the number of initially shown columns to a minimum. Avoid the need to scroll horizontally on a tablet screen size in default delivery (annotation: PresentationVariant/ LineItem).

Keep the number of additional (initially hidden) columns to a minimum. You can use the P13n dialog to show/hide the columns. Select the columns offered in the P13n dialog carefully. Do not just show all columns available in the backend tables (annotation: sap:visible, value:false).

For the grid table, analytical table, and tree table, the column widths are calculated automatically if the corresponding OData annotations are provided (annotations: MaxLength, Precision, Scale).

In contrast, the responsive table uses the same width for all columns.

If used with the responsive table, enable the pop-in behavior (sap.ui.comp.smarttable.SmartTable, property: smartFilterId, value: true).

Show the most important column on the left and the least important on the right. This ensures that the most important columns stay in the tabular layout as long as possible. The most important columns are those that contain the following information:

The column that identifies the line item

The column that contains the key attribute

(Annotation: PresentationVariant/ LineItem, Property: initiallyVisibleColumns)

Email column in the pop-in area of the responsive table

Provide a column header text for each column. Do not truncate the column header text in default delivery (annotation: sap:label).

Column header text

Content Alignment and Formatting

The smart table automatically takes care of content alignment and formatting in standard use cases. For this, the OData metadata needs to provide the correct information about the data types, semantics of, and value help for the data.
(Annotations such as: sap:semantics, value: currency-code, edm types, Annotation: sap:display-format, value:Date, Annotation:Precision, Annotation: Scale, Annotation: ValueList, Annotation: ValueList:semantics, value:fixed-values)

Actions

To trigger actions on multiple items, use a mutliselection smart table. Do not offer action triggering on multiple items if the table is expected to have fewer than 10 items in most cases.
While the grid table, analytical table, and tree table are multiselectable by default within the smart table, the responsive table is single-selectable. The selection mode can be changed (XMLView).

The following actions can be shown on the standard toolbar of the smart table:

Edit
Toggles the table between edit and read-only mode. This only works if smart fields are used inside the smart table (sap.ui.comp.smarttable.SmartTable, properties:editTogglable, smartToggle, aggregation: customData, key: useSmartField).

View Settings
This button opens the P13n dialog. Note that the P13n dialog is quite complex. Neither the simpler view settings dialog nor the table personalization dialog can be used without the app development team developing the entire view settings handling (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).

Export to Spreadsheet
Only use this option if your end users typically export the data shown in the table in order to work with it in a spreadsheet application. This is usually the case if data is collected from several systems and analyzed in the spreadsheet application. This is not usually the case for worklists, attachment lists, lists with only a few items, shopping carts, or data that does not need to be analyzed. This option is only available if the corresponding back end supports exporting to spreadsheet (sap.ui.comp.smarttable.SmartTable, property: useExportToExcel).

If additional actions are needed, use a custom toolbar for the table. The smart table can also add integrated functionality such as a table title, item count, variant management, edit and view settings, and export to spreadsheet to the custom toolbar (aggregation: customToolbar).

For navigation to line item details:

If used with the responsive table, use the navigation mode of the responsive table.

If used with the grid table, analytical table, or tree table, use a link for the attribute that identifies the row. The user can click this link to trigger the navigation.

Clicking a table row can trigger drill-in navigation to a deeper level of the object, as well as cross-navigation to another SAP Fiori app or even to another system.

Inline Actions

Actions that belong to single items can be placed within the row. They can be displayed as text or icons. Make sure the icon communicates the function clearly enough. Otherwise, use a textual button.

Editable Content

The smart table can be editable or read-only (sap.ui.comp.smarttable.SmartTable, property: editable).

The smart table selects the corresponding editable controls automatically based on the data type, semantic annotations, and value list annotations (annotations such as: sap:semantics, value: currency-code, edm types, Annotation: sap:display-format, value:Date, Annotation:Precision, Annotation: Scale, Annotation: ValueList, Annotation: ValueList:semantics, value:fixed-values).

If an edit mode is needed, the controls are automatically switched from read-only controls (such as text) to editable controls (such as input field or date picker) if smart fields are used inside the smart table (sap.ui.comp.smarttable.SmartTable, Property:editTogglable, smartToggle, aggregation: customData, key: useSmartField). The keyboard behavior is switched accordingly, if this is used together with the responsive table.

Only use this if you need to toggle between both modes. In any other case, show only the mode you need (read-only or edit), but do not offer the switch.

View Settings: Sort, Filter, Group, and Column Settings

If view settings are enabled on the smart table, a settings button is available on the table toolbar. This button opens the P13n dialog. Neither the simpler view settings dialog nor table personalization dialog can be used without extra effort (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).

The P13n dialog always enables the user to show, hide, and rearrange columns. Alternatively, it can contain settings for sorting, grouping, and/or filtering (annotations: sap:sortable, sap:filterable)

If the smart table uses the grid table, analytical table, or tree table, sort, filter, and group settings are also available in the column header menu.

Offer view settings only if they are really needed. For example, these settings do not make sense if the table contains only a few items and just a few columns.

Note that the P13n dialog is quite complex. It is ideal for tables with a vast number of items, but is quite cumbersome for handling just a few hundred items. Therefore, show only the settings (sort, group, filter) you really need. For example, do not offer grouping if it does not support your use case well.

If filtering is a main use case, do not offer filtering in the P13n dialog. Use the filter bar instead (annotation: sap:filterable)

Be persistent: When the app is reopened, the smart table is shown with the same view settings as last defined by the user (sap.ui.comp.smarttable.SmartTable, property: persistenceKey).

Sort

The current sort state is displayed as follows:

Using the responsive table, there is no indication that the table is currently sorted.

Using the grid table, analytical table, or tree table, an icon in the column header of the last sorted column indicates that the table is sorted and the direction in which it is sorted.

In default delivery, sort items in a meaningful order by the row-identifying column (usually the first column in default delivery). For example, use an alphabetical order for text, a numeric order for numbers, and a chronological order for dates (annotations: sap:sortable, PresentationVariant – SortOrder).

Filter

The current filter state is displayed as follows:

Using the responsive table, there is no indication that the table is currently filtered. The filter info bar can be added with additional effort.

Using the grid table, analytical table, or tree table, filtering is displayed by an icon on the column header of each filtered column (annotation: sap:filterable).

Group

Group headers display the current group state and are shown automatically. The following text should be shown on the group header:

[Label of the grouped column]: [Grouping value]
This can be done by the smart table, but only if the raw data from the model can be used. In other cases, app development teams must format the group header text. For example, the raw data carries IDs, while the table displays the corresponding names, which are provided by another data source. In this case, app developers must provide the formatting for the group header texts.

Within the responsive table, the grouped column keeps its visibility to reduce confusion after the group settings have been changed. If visible, it stays in the tabular layout even if grouped.

If used with the analytical table, grouping is not offered on measures. Therefore, you can have aggregations or grouping for a specific column.

Reasonable grouping can be offered by default via the property GroupBy.

Responsive table grouped by country

Aggregate

If used with the analytical table, aggregation settings can be provided on measure columns. These settings are only available in the column header menu.
To display the current aggregation state, the total sum of the corresponding column is shown at the bottom of the table.
If items are grouped, an intermediate sum is shown per group:

At the bottom of each group if the group is expanded.

In the group header if the group is collapsed.

Aggregations are only available on measures, but not on objects or attributes. If aggregation is enabled for a column, this column cannot be grouped.

Avoid aggregations on the first three columns for the default delivery. When grouping is used together with aggregations, collapsing a group shows the aggregation on the group header. This conflicts with the group name.

Where appropriate, offer reasonable aggregation by default (annotation: sap:aggregation-role, value: measure).

Column Settings

Only offer column settings if you need more columns than a tablet screen can display at a time (usually more than five).

If sorting, grouping, and/or filtering are needed, column settings must also be shown (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).

Add, Remove, Rearrange Columns

Use the P13n dialog to add, remove, and rearrange columns.

When used with the grid table, analytical table, or tree table, columns can also be rearranged by dragging and dropping the column header (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).

Resize Columns

When used with the grid table, analytical table, or tree table, columns can be resized on the column header (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).

Freeze Columns

When used with the grid table, analytical table, or tree table, app developers must manually add the options for freezing columns to the column header menu if necessary. They can do this by declaring the corresponding table inside the smart table in the XML view, and by using the corresponding settings on this inner table.

Selecting Freeze on a column freezes all columns from the first one to the one on which Freeze is selected. The menu entry on this column changes from Freeze to Unfreeze.

Properties

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

The property: ignoreFields defines the columns that are not available on the UI – neither in the initial visible columns nor in the P13n dialog.

The property: requestAtLeastFields can be used for requesting additional technical columns.

The property: ignoreFromPersonalization removes columns from the P13n dialog.

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

The property: enableCustomFilter allows the filter menu item in the column header menu to be exchanged.

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

The property: currentVariantId defines the currently used variant.

The property: enableAutoBinding fetches the data automatically as soon as the corresponding OData model is initialized and the smart table is created.

The property: tableBindingPath defines the path from which the data is fetched.

The property: smartToggle influences the way on which controls are displayed in the smart table if smart fields are used.

The following aggregations are available:

The aggregation: semanticObjectController is used to customize smart links inside the smart table.

The aggregation: noData provides a text in case the table contains no line items. For example, this can be the case if the table is filtered. The text should provide context-specific instructions on how to get data into the table.

Resources

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

Elements and Controls

Responsive Table (guidelines)

Grid Table (guidelines)

Analytical Table (guidelines)

Tree Table (guidelines)

Table Overview (guidelines)

Table Toolbar (guidelines)

Variant Management (guidelines)

P13n-Dialog (guidelines)

Implementation

Smart Table (SAPUI5 samples)

Smart Table (SAPUI5 API reference)

Smart Table (Developer Guide)

P13n-Dialog (SAPUI5 samples)

P13n-Dialog (SAPUI5 API reference)

Toolbar (SAPUI5 samples)

Smart Table

The smart table is a wrapper around existing tables, and can be used together with the responsive table, grid table, analytical table, or tree table.

The smart table creates columns automatically based on the underlying OData service plus corresponding annotations. It also adds some generic functionality, such as a toolbar, complex personalization settings, variant management, and export to spreadsheet.

Everything that can be done using the smart table can also be achieved using the responsive table, grid table, analytical table, or tree table directly, but with more development effort. Therefore, the main purpose of the smart table is to reduce development effort. However, this comes at the expense of decreased flexibility.

Usage

Use the smart table if:

Data is fed into the table through OData services.

You need a simple table with limited flexibility to display its content. In this case, the smart table reduces development effort.

You need a table in which some columns provide flexible content. In this case, use the smart table together with a responsive table, and provide app-specific column definitions for these columns.

Do not use the smart table if:

You create your own UI coding, whereby the data is not fed through OData services. In this case, use the underlying table control directly.

The main use case involves selecting one item from very few items, with no additional details. In this case, a select or combo box might be more suitable.

The main use case involves selecting one item from several items, with only a few details per item. In this case, a list might be more suitable. Pay attention to the layout of the list item to provide a pleasant appearance (see, for example, the master list and the feed list item).

The table is displayed together with a chart inside a chart container. The smart table is not designed to work inside an existing chart container. In this case, use the underlying table control directly.

You need an overview of a large amount of data. In this case, use charts.

You just need it for layout reasons. In this case, use a layout container, such as the grid layout, instead.

You need read-only or editable field value pairs. In this case, use a form instead. Tables are not optimized for form-like input navigation.

Responsiveness

The responsiveness of the smart table depends on the encapsulated table. The table toolbar uses the overflow mechanism for adapting to the screen width.

Using the responsive table

The smart table offers a generic responsive behavior (sap.ui.comp.smarttable.SmartTable, property: smartFilterId, value: true):

For every 10 rem of screen width, one column stays in the tabular layout. All others are moved to the pop-in area. The columns are moved to the pop-in area from right to left, so the column furthest to the right moves to the pop-in first.

Exception: The first two columns always stay in the tabular layout. This works best if the smart table uses the whole screen width. It might not work well if the smart table uses far less space.

Using the grid table, analytical table, or tree table

The smart table works only on desktop and tablets, but not on smartphones. It supports touch devices, but is not optimized for small screens.

If you use a smart table in this configuration, ensure that you implement a fallback solution for small screens. This fallback solution does not need to support all use cases. You could create a fallback by using a responsive table. However, a completely different solution, such as showing charts in a read-only case, might be more suitable.

Size S with responsive table
Size M with responsive table
Size L with responsive table

Size M with grid table
Size L with grid table

Layout

The title bar contains the title of the smart table, the item count, variant management, and the toolbar itself. All of these elements are optional.
The table area shows the corresponding table (responsive table, grid table, analytical table, or tree table).

Schematic visualization of the smart table

Components

The title bar consists of a toolbar.

This can be the standard toolbar or a custom toolbar. The standard toolbar can contain a title text with or without item count, variant management, view switch (switching the table to edit mode), an entry point for the P13n dialog, and an Export to Spreadsheet action.

If you require additional functionality, you can use an app-specific toolbar. All toolbar options provided by the smart table can also be added to the app-specific toolbar. (Aggregation: customToolbar)

The table area consists of any of the following tables: responsive table, grid table, analytical table, or tree table.

Standard toolbar with everything enabled
Standard toolbar just with title and item count

Behavior and Interaction

The behavior is generally inherited from the underlying table, toolbar, variant management, 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.

Table Level

Table Type

The smart table can encapsulate the responsive table, grid table, analytical table, or tree table. (sap.ui.comp.smarttable.SmartTable, property: tableType)

Automatic Rendering of the Table

The smart table automatically creates columns and renders all items based on the metadata of the underlying OData service (sap.ui.comp.smarttable.SmartTable, property: smartFilterId).

To be more flexible in the table layout, the smart table also offers app-specific column templates for some or all columns. In this case, app developers must provide the definition for the underlying table and for the corresponding (but not necessarily for all) columns in the XML view. For this, the app development team must provide the column keys of the overridden columns via custom data.

Additional columns can also be added. Columns that are defined in this way retain all the options of the underlying table. This is especially useful with the responsive table, which offers complete flexibility in content design. Any columns that are not defined by the app development team are still rendered automatically by the smart table.

No Data

If there is no data to show, the smart table renders default text. This text can be overwritten by the app development team (aggregation: NoData).

Initially Visible Columns

The smart table enables you to define which columns are initially shown. Here, initially means that these columns are shown when the app is first launched. All other columns are initially hidden (annotation: PresentationVariant/ LineItem, property: initiallyVisibleColumns).

Persistency

End users can show additional columns if table personalization is provided. In this case, column settings are persisted. On consecutive startups, the columns are shown with the same settings as last defined by the user (property: persistenceKey).

Removing Columns

The smart table always shows all columns from the OData model. In some cases, columns needs to be in the model but should not be available on the front end at all. Examples of this include:

A column is needed to provide an ID which is used for navigation purposes, but the front end should only display the corresponding text, not the ID.

The values of a column are needed to perform calculations, but only the results should be shown on the UI.

In these cases, you can define which columns should not be available at all on the UI. These columns are not shown and are not available in the P13n dialog. You can also do this for columns that are added manually in the XML view (annotation: sap:visible, value:false).

P13n/personalization dialog

Filter Settings

The “Show Field as Column” option for newly added filters is switched on by default.

Sorting and Filtering

The smart table allows you to add sort and filter settings for each column. These settings enable the corresponding pages in the P13n dialog. For the grid table, analytical table, and tree table, sorting and filtering are also enabled on the column header. (Annotations: sap:sortable and sap:filterable)

Column header menu of the grid table

Smart Table and Smart Filter Bar

The smart table can be linked to a smart filter bar. If linked, filter bar settings are automatically used on the smart table. (sap.ui.comp.smarttable,SmartTable, property:smartFIlterId)

Aggregation

If used with the analytical table, the smart table allows total sums of measure columns to be calculated. The totals are shown in the usual way:

As the last row of the analytical table.

As the last row of each group if the group is expanded.

On the group header of each group if the group is collapsed.

Aggregation settings are not persisted (annotation: sap:aggregation-role, value:measure).

The total count be hidden via the column header menu.

Aggregation entry in column header menu of the grid table

Column Width

A default column width is calculated for each column based on the data displayed in it. Important: end users cannot change the column width in the responsive table (annotations: MaxLength, Precision, Scale).

Column Header

A column header text can be specified for each column (annotation: sap:label).

Persistence

The smart table allows you to persist sort, group, and filter column settings (such as by hidden columns) as well as variants (sap.ui.comp.smarttable.SmartTable, Property:persistenceyKey).

Content

The smart table provides two options to create columns automatically:

The smart table is rendered in either read-only or edit mode. In this case, the smart table renders the controls as described below. This is the default way of rendering content (property: editable)

If users need to switch between read-only and edit mode at runtime, the smart table allows smart fields to be rendered instead. You should use this if the edit button is added to the toolbar of the smart table (aggregation: customData key: useSmartField).

For option 1, the following controls are used:

To show currency amounts, the smart table allows the amount and the currency code to be displayed in a single cell. For read-only mode, the currency control is used. For edit mode, a single input field is used, and the currency itself is shown next to the input field as non-editable text (annotation: sap:semantics, value: currency-code).

To show links that open a quick view, the smart table supports the smart link.

To show static text, the smart table uses an input field in edit mode, and a text in read-only mode.

To show dates, the smart table uses a date picker in edit mode, and a text in read-only mode (annotation: sap:display-format, value:Date).

To show decimal numbers, the smart table uses an input field in edit mode, and a text in read-only mode (Annotations:Precision, Scale).

The smart table also provides an object status and object identifier control. For more information, see object display components.

Pictures and microcharts, as well as rating indicators and progress bars are available.

Amount formatting
Link formatting
Date formatting

Value Help

The smart table supports value help in the following ways (annotation: ValueList):

Input fields can show a value help button. Triggering this button opens a value help dialog. Within this dialog, you can provide a search field (annotation:ValueList, property: SearchSupported).

You can restrict the number of characters for the input field. Use this if no ValueList annotation is provided (annotation:MaxLength).

Toolbar Level

Table Title

The smart table can provide a title for the table within the toolbar (sap.ui.comp.smarttable.SmartTable, Property:header).

Table title

Item Count

Next to the table title, an item count can be shown (sap.ui.comp.smarttable.SmartTable, Property:showRowCount).

Table title with item count

Edit

The table toolbar can contain a button for toggling the table between read-only and edit modes. If smart fields are used, the smart table handles both modes automatically (sap.ui.comp.smarttable.SmartTable, Property:editTogglable, aggregation: customData, key: useSmartField).

Edit button

View Settings

The table toolbar can contain a button for opening the P13n dialog. This dialog provides extensive sort, group, and filter settings. It also allows columns to be shown, hidden, or rearranged (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).

Settings button

Export to Spreadsheet

If the back end supports the export of data to spreadsheet, the table toolbar can contain a corresponding button. When this button is triggered, the corresponding file is created and the download starts automatically (sap.ui.comp.smarttable.SmartTable, Property:useExportToExcel).

Export to Spreadsheet button

Full Screen Mode

Applications can implement a maximize button to run the table in full screen (Property: showFullScreenButton).

Maximize button

Footer Toolbar Level

Buttons in the footer toolbar can be set to emphasized to give them a brighter appearance.

Guidelines

In general, the guidelines for the underlying table, toolbar, variant management, and P13n dialog also apply to the smart table (see the corresponding articles for details). However, because the smart table does not offer the complete flexibility of the underlying controls, there are certain differences.

Table Type

The responsive table is the standard table for SAP Fiori. Use the responsive table whenever possible. It is the most flexible table in terms of how its content is displayed, it is fully responsive, and it can handle up to 1,000 line items.

If you cannot use the responsive table, consider using the grid table instead. The grid table can handle a large number of line Items. Compared to the responsive table, however, it is more restricted content-wise (only certain controls can be used to show the data, and only one control per cell), and it does not run on smartphones. If you use the grid table, you need to provide a fallback solution for smartphones, for example, by using the responsive table.

The analytical table is similar to the grid table, but adds several grouping levels and offers total sums on measure columns. The analytical table can also handle a large number of line Items. Compared to the responsive table, however, it is more restricted content-wise (only certain controls can be used to show the data, and only one control per cell), and it does not run on smartphones. If you use the analytical table, you need to provide a fallback solution for smartphones, for example, by using the responsive table.

The tree table is the only table for displaying hierarchical data. Like the grid table, it can handle a large number of line items, although it is restricted content-wise (only certain controls can be used to show the data, and only one control per cell), and it does not run on smartphones. If you use the tree table, you need to provide a fallback solution for smartphones, for example, by using the responsive table.

For more information about the different table controls, see the corresponding articles.

Table Title, Item Count, and Variant Management

Always show the item count together with the table title, unless this is expected to cause performance problems.
If used with the responsive table and if more than 200 items are generally expected, do not show the item count. In this case, the smart table displays a More button to load additional rows. Using the item count together with the More button might lead to confusion (sap.ui.comp.smarttable.SmartTable, Property:showRowCount).

Even if variant management is easy to implement, use it only if it is really needed. The variant management saves the whole page, including filter settings and table layouts.

Empty Tables

Try not to display an empty table. If there is no way around this, provide instructions on how to fill the table with data (aggregatrion: noData).

Columns – Best Practices

Keep the number of initially shown columns to a minimum. Avoid the need to scroll horizontally on a tablet screen size in default delivery (annotation: PresentationVariant/ LineItem).

Keep the number of additional (initially hidden) columns to a minimum. You can use the P13n dialog to show/hide the columns. Select the columns offered in the P13n dialog carefully. Do not just show all columns available in the backend tables (annotation: sap:visible, value:false).

For the grid table, analytical table, and tree table, the column widths are calculated automatically if the corresponding OData annotations are provided (annotations: MaxLength, Precision, Scale).

In contrast, the responsive table uses the same width for all columns.

If used with the responsive table, enable the pop-in behavior (sap.ui.comp.smarttable.SmartTable, property: smartFilterId, value: true).

Show the most important column on the left and the least important on the right. This ensures that the most important columns stay in the tabular layout as long as possible. The most important columns are those that contain the following information:

The column that identifies the line item

The column that contains the key attribute

(Annotation: PresentationVariant/ LineItem, Property: initiallyVisibleColumns)

Email column in the pop-in area of the responsive table

Provide a column header text for each column. Do not truncate the column header text in default delivery (annotation: sap:label).

Column header text

Content Alignment and Formatting

The smart table automatically takes care of content alignment and formatting in standard use cases. For this, the OData metadata needs to provide the correct information about the data types, semantics of, and value help for the data.
(Annotations such as: sap:semantics, value: currency-code, edm types, Annotation: sap:display-format, value:Date, Annotation:Precision, Annotation: Scale, Annotation: ValueList, Annotation: ValueList:semantics, value:fixed-values)

Actions

To trigger actions on multiple items, use a mutliselection smart table. Do not offer action triggering on multiple items if the table is expected to have fewer than 10 items in most cases.
While the grid table, analytical table, and tree table are multiselectable by default within the smart table, the responsive table is single-selectable. The selection mode can be changed (XMLView).

The following actions can be shown on the standard toolbar of the smart table:

Edit
Toggles the table between edit and read-only mode. This only works if smart fields are used inside the smart table (sap.ui.comp.smarttable.SmartTable, Property:editTogglable, aggregation: customData, key: useSmartField).

View Settings
This button opens the P13n dialog. Note that the P13n dialog is quite complex. Neither the simpler view settings dialog nor the table personalization dialog can be used without the app development team developing the entire view settings handling (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).

Export to Spreadsheet
Only use this option if your end users typically export the data shown in the table in order to work with it in a spreadsheet application. This is usually the case if data is collected from several systems and analyzed in the spreadsheet application. This is not usually the case for worklists, attachment lists, lists with only a few items, shopping carts, or data that does not need to be analyzed. This option is only available if the corresponding back end supports exporting to spreadsheet (sap.ui.comp.smarttable.SmartTable, property: useExportToExcel).

If additional actions are needed, use a custom toolbar for the table. The smart table can also add integrated functionality such as a table title, item count, variant management, edit and view settings, and export to spreadsheet to the custom toolbar (aggregation: customToolbar).

For navigation to line item details:

If used with the responsive table, use the navigation mode of the responsive table.

If used with the grid table, analytical table, or tree table, use a link for the attribute that identifies the row. The user can click this link to trigger the navigation.

Clicking a table row can trigger drill-in navigation to a deeper level of the object, as well as cross-navigation to another SAP Fiori app or even to another system.

Inline Actions

Actions that belong to single items can be placed within the row. They can be displayed as text or icons. Make sure the icon communicates the function clearly enough. Otherwise, use a textual button.

Editable Content

The smart table can be editable or read-only (sap.ui.comp.smarttable.SmartTable, property: editable).

The smart table selects the corresponding editable controls automatically based on the data type, semantic annotations, and value list annotations (annotations such as: sap:semantics, value: currency-code, edm types, Annotation: sap:display-format, value:Date, Annotation:Precision, Annotation: Scale, Annotation: ValueList, Annotation: ValueList:semantics, value:fixed-values).

If an edit mode is needed, the controls are automatically switched from read-only controls (such as text) to editable controls (such as input field or date picker) if smart fields are used inside the smart table (sap.ui.comp.smarttable.SmartTable, Property:editTogglablea, aggregation: customData, key: useSmartField).

Only use this if you need to toggle between both modes. In any other case, show only the mode you need (read-only or edit), but do not offer the switch.

View Settings: Sort, Filter, Group, and Column Settings

If view settings are enabled on the smart table, a settings button is available on the table toolbar. This button opens the P13n dialog. Neither the simpler view settings dialog nor table personalization dialog can be used without extra effort (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).

The P13n dialog always enables the user to show, hide, and rearrange columns. Alternatively, it can contain settings for sorting, grouping, and/or filtering (annotations: sap:sortable, sap:filterable)

If the smart table uses the grid table, analytical table, or tree table, sort, filter, and group settings are also available in the column header menu.

Offer view settings only if they are really needed. For example, these settings do not make sense if the table contains only a few items and just a few columns.

Note that the P13n dialog is quite complex. It is ideal for tables with a vast number of items, but is quite cumbersome for handling just a few hundred items. Therefore, show only the settings (sort, group, filter) you really need. For example, do not offer grouping if it does not support your use case well.

If filtering is a main use case, do not offer filtering in the P13n dialog. Use the filter bar instead (annotation: sap:filterable)

Be persistent: When the app is reopened, the smart table is shown with the same view settings as last defined by the user (sap.ui.comp.smarttable.SmartTable, property: persistenceKey).

Sort

The current sort state is displayed as follows:

Using the responsive table, there is no indication that the table is currently sorted.

Using the grid table, analytical table, or tree table, an icon in the column header of the last sorted column indicates that the table is sorted and the direction in which it is sorted.

In default delivery, sort items in a meaningful order by the row-identifying column (usually the first column in default delivery). For example, use an alphabetical order for text, a numeric order for numbers, and a chronological order for dates (annotations: sap:sortable, PresentationVariant – SortOrder).

Filter

The current filter state is displayed as follows:

Using the responsive table, there is no indication that the table is currently filtered. The filter info bar can be added with additional effort.

Using the grid table, analytical table, or tree table, filtering is displayed by an icon on the column header of each filtered column (annotation: sap:filterable).

Group

Group headers display the current group state and are shown automatically. The following text should be shown on the group header:

[Label of the grouped column]: [Grouping value]
This can be done by the smart table, but only if the raw data from the model can be used. In other cases, app development teams must format the group header text. For example, the raw data carries IDs, while the table displays the corresponding names, which are provided by another data source. In this case, app developers must provide the formatting for the group header texts.

Within the responsive table, the grouped column keeps its visibility to reduce confusion after the group settings have been changed. If visible, it stays in the tabular layout even if grouped.

If used with the analytical table, grouping is not offered on measures. Therefore, you can have aggregations or grouping for a specific column.

Reasonable grouping can be offered by default via the property GroupBy.

Responsive table grouped by country

Aggregate

If used with the analytical table, aggregation settings can be provided on measure columns. These settings are only available in the column header menu.
To display the current aggregation state, the total sum of the corresponding column is shown at the bottom of the table.
If items are grouped, an intermediate sum is shown per group:

At the bottom of each group if the group is expanded.

In the group header if the group is collapsed.

Aggregations are only available on measures, but not on objects or attributes. If aggregation is enabled for a column, this column cannot be grouped.

Avoid aggregations on the first three columns for the default delivery. When grouping is used together with aggregations, collapsing a group shows the aggregation on the group header. This conflicts with the group name.

Where appropriate, offer reasonable aggregation by default (annotation: sap:aggregation-role, value: measure).

Column Settings

Only offer column settings if you need more columns than a tablet screen can display at a time (usually more than five).

If sorting, grouping, and/or filtering are needed, column settings must also be shown (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).

Add, Remove, Rearrange Columns

Use the P13n dialog to add, remove, and rearrange columns.

When used with the grid table, analytical table, or tree table, columns can also be rearranged by dragging and dropping the column header (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).

Resize Columns

When used with the grid table, analytical table, or tree table, columns can be resized on the column header (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).

Freeze Columns

When used with the grid table, analytical table, or tree table, app developers must manually add the options for freezing columns to the column header menu if necessary. They can do this by declaring the corresponding table inside the smart table in the XML view, and by using the corresponding settings on this inner table.

Selecting Freeze on a column freezes all columns from the first one to the one on which Freeze is selected. The menu entry on this column changes from Freeze to Unfreeze.

Properties

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

The property: ignoreFields defines the columns that are not available on the UI – neither in the initial visible columns nor in the P13n dialog.

The property: requestAtLeastFields can be used for requesting additional technical columns.

The property: ignoreFromPersonalization removes columns from the P13n dialog.

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

The property: enableCustomFilter allows the filter menu item in the column header menu to be exchanged.

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

The property: currentVariantId defines the currently used variant.

The property: enableAutoBinding fetches the data automatically as soon as the corresponding OData model is initialized and the smart table is created.

The property: tableBindingPath defines the path from which the data is fetched.

The following aggregations are available:

The aggregation: semanticObjectController is used to customize smart links inside the smart table.

The aggregation: noData provides a text in case the table contains no line items. For example, this can be the case if the table is filtered. The text should provide context-specific instructions on how to get data into the table.

Resources

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

Elements and Controls

Responsive Table (guidelines)

Grid Table (guidelines)

Analytical Table (guidelines)

Tree Table (guidelines)

Table Overview (guidelines)

Table Toolbar (guidelines)

Variant Management (guidelines)

P13n-Dialog (guidelines)

Implementation

Smart Table (SAPUI5 samples)

Smart Table (SAPUI5 API reference)

Smart Table (Developer Guide)

P13n-Dialog (SAPUI5 samples)

P13n-Dialog (SAPUI5 API reference)

Toolbar (SAPUI5 samples)

Smart Table

The smart table is a wrapper around existing tables, and can be used together with the responsive table, grid table, analytical table, or tree table.

The smart table creates columns automatically based on the underlying OData service plus corresponding annotations. It also adds some generic functionality, such as a toolbar, complex personalization settings, variant management, and export to spreadsheet.

Everything that can be done using the smart table can also be achieved using the responsive table, grid table, analytical table, or tree table directly, but with more development effort. Therefore, the main purpose of the smart table is to reduce development effort. However, this comes at the expense of decreased flexibility.

Usage

Use the smart table if:

Data is fed into the table through OData services.

You need a simple table with limited flexibility to display its content. In this case, the smart table reduces development effort.

You need a table in which some columns provide flexible content. In this case, use the smart table together with a responsive table, and provide app-specific column definitions for these columns.

Do not use the smart table if:

You create your own UI coding, whereby the data is not fed through OData services. In this case, use the underlying table control directly.

The main use case involves selecting one item from very few items, with no additional details. In this case, a select or combo box might be more suitable.

The main use case involves selecting one item from several items, with only a few details per item. In this case, a list might be more suitable. Pay attention to the layout of the list item to provide a pleasant appearance (see, for example, the master list and the feed list item).

The table is displayed together with a chart inside a chart container. The smart table is not designed to work inside an existing chart container. In this case, use the underlying table control directly.

You need an overview of a large amount of data. In this case, use charts.

You just need it for layout reasons. In this case, use a layout container, such as the grid layout, instead.

You need read-only or editable field value pairs. In this case, use a form instead. Tables are not optimized for form-like input navigation.

Responsiveness

The responsiveness of the smart table depends on the encapsulated table. The table toolbar uses the overflow mechanism for adapting to the screen width.

Using the responsive table

The smart table offers a generic responsive behavior (sap.ui.comp.smarttable.SmartTable, property: smartFilterId, value: true):

For every 10 rem of screen width, one column stays in the tabular layout. All others are moved to the pop-in area. The columns are moved to the pop-in area from right to left, so the column furthest to the right moves to the pop-in first.

Exception: The first two columns always stay in the tabular layout. This works best if the smart table uses the whole screen width. It might not work well if the smart table uses far less space.

Using the grid table, analytical table, or tree table

The smart table works only on desktop and tablets, but not on smartphones. It supports touch devices, but is not optimized for small screens.

If you use a smart table in this configuration, ensure that you implement a fallback solution for small screens. This fallback solution does not need to support all use cases. You could create a fallback by using a responsive table. However, a completely different solution, such as showing charts in a read-only case, might be more suitable.

Size S with responsive table
Size M with responsive table
Size L with responsive table

Size M with grid table
Size L with grid table

Layout

The title bar contains the title of the smart table, the item count, variant management, and the toolbar itself. All of these elements are optional.
The table area shows the corresponding table (responsive table, grid table, analytical table, or tree table).

Schematic visualization of the smart table

Components

The title bar consists of a toolbar.

This can be the standard toolbar or a custom toolbar. The standard toolbar can contain a title text with or without item count, variant management, view switch (switching the table to edit mode), an entry point for the P13n dialog, and an Export to Spreadsheet action.

If you require additional functionality, you can use an app-specific toolbar. All toolbar options provided by the smart table can also be added to the app-specific toolbar. (Aggregation: customToolbar)

The table area consists of any of the following tables: responsive table, grid table, analytical table, or tree table.

Standard toolbar with everything enabled
Standard toolbar just with title and item count

Behavior and Interaction

The behavior is generally inherited from the underlying table, toolbar, variant management, 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.

Table Level

Table Type

The smart table can encapsulate the responsive table, grid table, analytical table, or tree table. (sap.ui.comp.smarttable.SmartTable, property: tableType)

Automatic Rendering of the Table

The smart table automatically creates columns and renders all items based on the metadata of the underlying OData service (sap.ui.comp.smarttable.SmartTable, property: smartFilterId).

To be more flexible in the table layout, the smart table also offers app-specific column templates for some or all columns. In this case, app developers must provide the definition for the underlying table and for the corresponding (but not necessarily for all) columns in the XML view. For this, the app development team must provide the column keys of the overridden columns via custom data.

Additional columns can also be added. Columns that are defined in this way retain all the options of the underlying table. This is especially useful with the responsive table, which offers complete flexibility in content design. Any columns that are not defined by the app development team are still rendered automatically by the smart table.

No Data

If there is no data to show, the smart table renders default text. This text can be overwritten by the app development team (aggregation: NoData).

Initially Visible Columns

The smart table enables you to define which columns are initially shown. Here, initially means that these columns are shown when the app is first launched. All other columns are initially hidden (annotation: PresentationVariant/ LineItem, property: initiallyVisibleColumns).

Persistency

End users can show additional columns if table personalization is provided. In this case, column settings are persisted. On consecutive startups, the columns are shown with the same settings as last defined by the user (property: persistenceKey).

Removing Columns

The smart table always shows all columns from the OData model. In some cases, columns needs to be in the model but should not be available on the front end at all. Examples of this include:

A column is needed to provide an ID which is used for navigation purposes, but the front end should only display the corresponding text, not the ID.

The values of a column are needed to perform calculations, but only the results should be shown on the UI.

In these cases, you can define which columns should not be available at all on the UI. These columns are not shown and are not available in the P13n dialog. You can also do this for columns that are added manually in the XML view (annotation: sap:visible, value:false).

P13n/personalization dialog

Filter Settings

The “Show Field as Column” option for newly added filters is switched on by default.

Sorting and Filtering

The smart table allows you to add sort and filter settings for each column. These settings enable the corresponding pages in the P13n dialog. For the grid table, analytical table, and tree table, sorting and filtering are also enabled on the column header. (Annotations: sap:sortable and sap:filterable)

Column header menu of the grid table

Smart Table and Smart Filter Bar

The smart table can be linked to a smart filter bar. If linked, filter bar settings are automatically used on the smart table. (sap.ui.comp.smarttable,SmartTable, property:smartFIlterId)

Aggregation

If used with the analytical table, the smart table allows total sums of measure columns to be calculated. The totals are shown in the usual way:

As the last row of the analytical table.

As the last row of each group if the group is expanded.

On the group header of each group if the group is collapsed.

Aggregation settings are not persisted (annotation: sap:aggregation-role, value:measure).

The total count be hidden via the column header menu.

Aggregation entry in column header menu of the grid table

Column Width

A default column width is calculated for each column based on the data displayed in it. Important: end users cannot change the column width in the responsive table (annotations: MaxLength, Precision, Scale).

Column Header

A column header text can be specified for each column (annotation: sap:label).

Persistence

The smart table allows you to persist sort, group, and filter column settings (such as by hidden columns) as well as variants (sap.ui.comp.smarttable.SmartTable, Property:persistenceyKey).

Content

The smart table provides two options to create columns automatically:

The smart table is rendered in either read-only or edit mode. In this case, the smart table renders the controls as described below. This is the default way of rendering content (property: editable)

If users need to switch between read-only and edit mode at runtime, the smart table allows smart fields to be rendered instead. You should use this if the edit button is added to the toolbar of the smart table (aggregation: customData key: useSmartField).

For option 1, the following controls are used:

To show currency amounts, the smart table allows the amount and the currency code to be displayed in a single cell. For read-only mode, the currency control is used. For edit mode, a single input field is used, and the currency itself is shown next to the input field as non-editable text (annotation: sap:semantics, value: currency-code).

To show links that open a quick view, the smart table supports the smart link.

To show static text, the smart table uses an input field in edit mode, and a text in read-only mode.

To show dates, the smart table uses a date picker in edit mode, and a text in read-only mode (annotation: sap:display-format, value:Date).

To show decimal numbers, the smart table uses an input field in edit mode, and a text in read-only mode (Annotations:Precision, Scale).

The smart table also provides an object status and object identifier control. For more information, see object display components.

Pictures and microcharts, as well as rating indicators and progress bars are available.

Amount formatting
Link formatting
Date formatting

Value Help

The smart table supports value help in the following ways (annotation: ValueList):

Input fields can show a value help button. Triggering this button opens a value help dialog. Within this dialog, you can provide a search field (annotation:ValueList, property: SearchSupported).

You can restrict the number of characters for the input field. Use this if no ValueList annotation is provided (annotation:MaxLength).

Toolbar Level

Table Title

The smart table can provide a title for the table within the toolbar (sap.ui.comp.smarttable.SmartTable, Property:header).

Table title

Item Count

Next to the table title, an item count can be shown (sap.ui.comp.smarttable.SmartTable, Property:showRowCount).

Table title with item count

Edit

The table toolbar can contain a button for toggling the table between read-only and edit modes. If smart fields are used, the smart table handles both modes automatically (sap.ui.comp.smarttable.SmartTable, Property:editTogglable, aggregation: customData, key: useSmartField).

Edit button

View Settings

The table toolbar can contain a button for opening the P13n dialog. This dialog provides extensive sort, group, and filter settings. It also allows columns to be shown, hidden, or rearranged (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).

Settings button

Export to Spreadsheet

If the back end supports the export of data to spreadsheet, the table toolbar can contain a corresponding button. When this button is triggered, the corresponding file is created and the download starts automatically (sap.ui.comp.smarttable.SmartTable, Property:useExportToExcel).

Export to Spreadsheet button

Full Screen Mode

Applications can implement a maximize button to run the table in full screen (Property: showFullScreenButton).

Maximize button

Footer Toolbar Level

Buttons in the footer toolbar can be set to emphasized to give them a brighter appearance.

Guidelines

In general, the guidelines for the underlying table, toolbar, variant management, and P13n dialog also apply to the smart table (see the corresponding articles for details). However, because the smart table does not offer the complete flexibility of the underlying controls, there are certain differences.

Table Type

The responsive table is the standard table for SAP Fiori. Use the responsive table whenever possible. It is the most flexible table in terms of how its content is displayed, it is fully responsive, and it can handle up to 1,000 line items.

If you cannot use the responsive table, consider using the grid table instead. The grid table can handle a large number of line Items. Compared to the responsive table, however, it is more restricted content-wise (only certain controls can be used to show the data, and only one control per cell), and it does not run on smartphones. If you use the grid table, you need to provide a fallback solution for smartphones, for example, by using the responsive table.

The analytical table is similar to the grid table, but adds several grouping levels and offers total sums on measure columns. The analytical table can also handle a large number of line Items. Compared to the responsive table, however, it is more restricted content-wise (only certain controls can be used to show the data, and only one control per cell), and it does not run on smartphones. If you use the analytical table, you need to provide a fallback solution for smartphones, for example, by using the responsive table.

The tree table is the only table for displaying hierarchical data. Like the grid table, it can handle a large number of line items, although it is restricted content-wise (only certain controls can be used to show the data, and only one control per cell), and it does not run on smartphones. If you use the tree table, you need to provide a fallback solution for smartphones, for example, by using the responsive table.

For more information about the different table controls, see the corresponding articles.

Table Title, Item Count, and Variant Management

Always show the item count together with the table title, unless this is expected to cause performance problems.
If used with the responsive table and if more than 200 items are generally expected, do not show the item count. In this case, the smart table displays a More button to load additional rows. Using the item count together with the More button might lead to confusion (sap.ui.comp.smarttable.SmartTable, Property:showRowCount).

Even if variant management is easy to implement, use it only if it is really needed. The variant management saves the whole page, including filter settings and table layouts.

Empty Tables

Try not to display an empty table. If there is no way around this, provide instructions on how to fill the table with data (aggregatrion: noData).

Columns – Best Practices

Keep the number of initially shown columns to a minimum. Avoid the need to scroll horizontally on a tablet screen size in default delivery (annotation: PresentationVariant/ LineItem).

Keep the number of additional (initially hidden) columns to a minimum. You can use the P13n dialog to show/hide the columns. Select the columns offered in the P13n dialog carefully. Do not just show all columns available in the backend tables (annotation: sap:visible, value:false).

For the grid table, analytical table, and tree table, the column widths are calculated automatically if the corresponding OData annotations are provided (annotations: MaxLength, Precision, Scale).

In contrast, the responsive table uses the same width for all columns.

If used with the responsive table, enable the pop-in behavior (sap.ui.comp.smarttable.SmartTable, property: smartFilterId, value: true).

Show the most important column on the left and the least important on the right. This ensures that the most important columns stay in the tabular layout as long as possible. The most important columns are those that contain the following information:

The column that identifies the line item

The column that contains the key attribute

(Annotation: PresentationVariant/ LineItem, Property: initiallyVisibleColumns)

Email column in the pop-in area of the responsive table

Provide a column header text for each column. Do not truncate the column header text in default delivery (annotation: sap:label).

Column header text

Content Alignment and Formatting

The smart table automatically takes care of content alignment and formatting in standard use cases. For this, the OData metadata needs to provide the correct information about the data types, semantics of, and value help for the data.
(Annotations such as: sap:semantics, value: currency-code, edm types, Annotation: sap:display-format, value:Date, Annotation:Precision, Annotation: Scale, Annotation: ValueList, Annotation: ValueList:semantics, value:fixed-values)

Actions

To trigger actions on multiple items, use a mutliselection smart table. Do not offer action triggering on multiple items if the table is expected to have fewer than 10 items in most cases.
While the grid table, analytical table, and tree table are multiselectable by default within the smart table, the responsive table is single-selectable. The selection mode can be changed (XMLView).

The following actions can be shown on the standard toolbar of the smart table:

Edit
Toggles the table between edit and read-only mode. This only works if smart fields are used inside the smart table (sap.ui.comp.smarttable.SmartTable, Property:editTogglable, aggregation: customData, key: useSmartField).

View Settings
This button opens the P13n dialog. Note that the P13n dialog is quite complex. Neither the simpler view settings dialog nor the table personalization dialog can be used without the app development team developing the entire view settings handling (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).

Export to Spreadsheet
Only use this option if your end users typically export the data shown in the table in order to work with it in a spreadsheet application. This is usually the case if data is collected from several systems and analyzed in the spreadsheet application. This is not usually the case for worklists, attachment lists, lists with only a few items, shopping carts, or data that does not need to be analyzed. This option is only available if the corresponding back end supports exporting to spreadsheet (sap.ui.comp.smarttable.SmartTable, property: useExportToExcel).

If additional actions are needed, use a custom toolbar for the table. The smart table can also add integrated functionality such as a table title, item count, variant management, edit and view settings, and export to spreadsheet to the custom toolbar (aggregation: customToolbar).

For navigation to line item details:

If used with the responsive table, use the navigation mode of the responsive table.

If used with the grid table, analytical table, or tree table, use a link for the attribute that identifies the row. The user can click this link to trigger the navigation.

Clicking a table row can trigger drill-in navigation to a deeper level of the object, as well as cross-navigation to another SAP Fiori app or even to another system.

Inline Actions

Actions that belong to single items can be placed within the row. They can be displayed as text or icons. Make sure the icon communicates the function clearly enough. Otherwise, use a textual button.

Editable Content

The smart table can be editable or read-only (sap.ui.comp.smarttable.SmartTable, property: editable).

The smart table selects the corresponding editable controls automatically based on the data type, semantic annotations, and value list annotations (annotations such as: sap:semantics, value: currency-code, edm types, Annotation: sap:display-format, value:Date, Annotation:Precision, Annotation: Scale, Annotation: ValueList, Annotation: ValueList:semantics, value:fixed-values).

If an edit mode is needed, the controls are automatically switched from read-only controls (such as text) to editable controls (such as input field or date picker) if smart fields are used inside the smart table (sap.ui.comp.smarttable.SmartTable, Property:editTogglablea, aggregation: customData, key: useSmartField).

Only use this if you need to toggle between both modes. In any other case, show only the mode you need (read-only or edit), but do not offer the switch.

View Settings: Sort, Filter, Group, and Column Settings

If view settings are enabled on the smart table, a settings button is available on the table toolbar. This button opens the P13n dialog. Neither the simpler view settings dialog nor table personalization dialog can be used without extra effort (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).

The P13n dialog always enables the user to show, hide, and rearrange columns. Alternatively, it can contain settings for sorting, grouping, and/or filtering (annotations: sap:sortable, sap:filterable)

If the smart table uses the grid table, analytical table, or tree table, sort, filter, and group settings are also available in the column header menu.

Offer view settings only if they are really needed. For example, these settings do not make sense if the table contains only a few items and just a few columns.

Note that the P13n dialog is quite complex. It is ideal for tables with a vast number of items, but is quite cumbersome for handling just a few hundred items. Therefore, show only the settings (sort, group, filter) you really need. For example, do not offer grouping if it does not support your use case well.

If filtering is a main use case, do not offer filtering in the P13n dialog. Use the filter bar instead (annotation: sap:filterable)

Be persistent: When the app is reopened, the smart table is shown with the same view settings as last defined by the user (sap.ui.comp.smarttable.SmartTable, property: persistenceKey).

Sort

The current sort state is displayed as follows:

Using the responsive table, there is no indication that the table is currently sorted.

Using the grid table, analytical table, or tree table, an icon in the column header of the last sorted column indicates that the table is sorted and the direction in which it is sorted.

In default delivery, sort items in a meaningful order by the row-identifying column (usually the first column in default delivery). For example, use an alphabetical order for text, a numeric order for numbers, and a chronological order for dates (annotations: sap:sortable, PresentationVariant – SortOrder).

Filter

The current filter state is displayed as follows:

Using the responsive table, there is no indication that the table is currently filtered. The filter info bar can be added with additional effort.

Using the grid table, analytical table, or tree table, filtering is displayed by an icon on the column header of each filtered column (annotation: sap:filterable).

Group

To display the current group state, group headers are shown automatically. The following text should be shown on the group header:
[Label of the grouped column]: [Grouping value]
This can be done by the smart table, but only if the raw data from the model can be used. In other cases, app development teams must format the group header text. For example, the raw data carries IDs, while the table displays the corresponding names, which are provided by another data source. In this case, app developers must provide the formatting for the group header texts.

Within the responsive table, the grouped column keeps its visibility to reduce confusion after the group settings have been changed. If visible, it stays in the tabular layout even if grouped.

If used with the analytical table, grouping is not offered on measures. Therefore, you can have aggregations or grouping on a specific column.

If appropriate, offer reasonable grouping by default.

Responsive table grouped by country

Aggregate

If used with the analytical table, aggregation settings can be provided on measure columns. These settings are only available in the column header menu.
To display the current aggregation state, the total sum of the corresponding column is shown at the bottom of the table.
If items are grouped, an intermediate sum is shown per group:

At the bottom of each group if the group is expanded.

In the group header if the group is collapsed.

Aggregations are only available on measures, but not on objects or attributes. If aggregation is enabled for a column, this column cannot be grouped.

Avoid aggregations on the first three columns for the default delivery. When grouping is used together with aggregations, collapsing a group shows the aggregation on the group header. This conflicts with the group name.

Where appropriate, offer reasonable aggregation by default (annotation: sap:aggregation-role, value: measure).

Column Settings

Only offer column settings if you need more columns than a tablet screen can display at a time (usually more than five).

If sorting, grouping, and/or filtering are needed, column settings must also be shown (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).

Add, Remove, Rearrange Columns

Use the P13n dialog to add, remove, and rearrange columns.

When used with the grid table, analytical table, or tree table, columns can also be rearranged by dragging and dropping the column header (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).

Resize Columns

When used with the grid table, analytical table, or tree table, columns can be resized on the column header (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).

Freeze Columns

When used with the grid table, analytical table, or tree table, app developers must manually add the options for freezing columns to the column header menu if necessary. They can do this by declaring the corresponding table inside the smart table in the XML view, and by using the corresponding settings on this inner table.

Selecting Freeze on a column freezes all columns from the first one to the one on which Freeze is selected. The menu entry on this column changes from Freeze to Unfreeze.

Properties

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

The property: ignoreFields defines the columns that are not available on the UI – neither in the initial visible columns nor in the P13n dialog.

The property: requestAtLeastFields can be used for requesting additional technical columns.

The property: ignoreFromPersonalization removes columns from the P13n dialog.

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

The property: enableCustomFilter allows the filter menu item in the column header menu to be exchanged.

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

The property: currentVariantId defines the currently used variant.

The property: enableAutoBinding fetches the data automatically as soon as the corresponding OData model is initialized and the smart table is created.

The property: tableBindingPath defines the path from which the data is fetched.

The following aggregations are available:

The aggregation: semanticObjectController is used to customize smart links inside the smart table.

The aggregation: noData provides a text in case the table contains no line items. For example, this can be the case if the table is filtered. The text should provide context-specific instructions on how to get data into the table.

Resources

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

Elements and Controls

Responsive Table (guidelines)

Grid Table (guidelines)

Analytical Table (guidelines)

Tree Table (guidelines)

Table Overview (guidelines)

Table Toolbar (guidelines)

Variant Management (guidelines)

P13n-Dialog (guidelines)

Implementation

Smart Table (SAPUI5 samples)

Smart Table (SAPUI5 API reference)

Smart Table (Developer Guide)

P13n-Dialog (SAPUI5 samples)

P13n-Dialog (SAPUI5 API reference)

Toolbar (SAPUI5 samples)

Smart Table

The smart table is a wrapper around existing tables, and can be used together with the responsive table, grid table, analytical table, or tree table.

The smart table creates columns automatically based on the underlying OData service plus corresponding annotations. It also adds some generic functionality, such as a toolbar, complex personalization settings, variant management, and export to spreadsheet.

Everything that can be done using the smart table can also be achieved using the responsive table, grid table, analytical table, or tree table directly, but with more development effort. Therefore, the main purpose of the smart table is to reduce development effort. However, this comes at the expense of decreased flexibility.

Usage

Use the smart table if:

Data is fed into the table through OData services.

You need a simple table with limited flexibility to display its content. In this case, the smart table reduces development effort.

You need a table in which some columns provide flexible content. In this case, use the smart table together with a responsive table, and provide app-specific column definitions for these columns.

Do not use the smart table if:

You create your own UI coding, whereby the data is not fed through OData services. In this case, use the underlying table control directly.

The main use case involves selecting one item from very few items, with no additional details. In this case, a select or combo box might be more suitable.

The main use case involves selecting one item from several items, with only a few details per item. In this case, a list might be more suitable. Pay attention to the layout of the list item to provide a pleasant appearance (see, for example, the master list and the feed list item).

The table is displayed together with a chart inside a chart container. The smart table is not designed to work inside an existing chart container. In this case, use the underlying table control directly.

You need an overview of a large amount of data. In this case, use charts.

You just need it for layout reasons. In this case, use a layout container, such as the grid layout, instead.

You need read-only or editable field value pairs. In this case, use a form instead. Tables are not optimized for form-like input navigation.

Responsiveness

The responsiveness of the smart table depends on the encapsulated table. The table toolbar uses the overflow mechanism for adapting to the screen width.

Using the responsive table

The smart table offers a generic responsive behavior (sap.ui.comp.smarttable.SmartTable, property: smartFilterId, value: true):

For every 10 rem of screen width, one column stays in the tabular layout. All others are moved to the pop-in area. The columns are moved to the pop-in area from right to left, so the column furthest to the right moves to the pop-in first.

Exception: The first two columns always stay in the tabular layout. This works best if the smart table uses the whole screen width. It might not work well if the smart table uses far less space.

Using the grid table, analytical table, or tree table

The smart table works only on desktop and tablets, but not on smartphones. It supports touch devices, but is not optimized for small screens.

If you use a smart table in this configuration, ensure that you implement a fallback solution for small screens. This fallback solution does not need to support all use cases. You could create a fallback by using a responsive table. However, a completely different solution, such as showing charts in a read-only case, might be more suitable.

Size S with responsive table
Size M with responsive table

Size M with grid table
Size L with grid table

Layout

The title bar contains the title of the smart table, the item count, variant management, and the toolbar itself. All of these elements are optional.
The table area shows the corresponding table (responsive table, grid table, analytical table, or tree table).

Schematic visualization of the smart table

Components

The title bar consists of a toolbar.

This can be the standard toolbar or a custom toolbar. The standard toolbar can contain a title text with or without item count, variant management, view switch (switching the table to edit mode), an entry point for the P13n dialog, and an Export to Spreadsheet action.

If you require additional functionality, you can use an app-specific toolbar. All toolbar options provided by the smart table can also be added to the app-specific toolbar. (Aggregation: customToolbar)

The table area consists of any of the following tables: responsive table, grid table, analytical table, or tree table.

Standard toolbar with everything enabled
Standard toolbar just with title and item count

Behavior and Interaction

The behavior is generally inherited from the underlying table, toolbar, variant management, 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.

Table Level

Table Type

The smart table can encapsulate the responsive table, grid table, analytical table, or tree table. (sap.ui.comp.smarttable.SmartTable, property: tableType)

Automatic Rendering of the Table

The smart table automatically creates columns and renders all items based on the metadata of the underlying OData service (sap.ui.comp.smarttable.SmartTable, property: smartFilterId).

To be more flexible in the table layout, the smart table also offers app-specific column templates for some or all columns. In this case, app developers must provide the definition for the underlying table and for the corresponding (but not necessarily for all) columns in the XML view. For this, the app development team must provide the column keys of the overridden columns via custom data.

Additional columns can also be added. Columns that are defined in this way retain all the options of the underlying table. This is especially useful with the responsive table, which offers complete flexibility in content design. Any columns that are not defined by the app development team are still rendered automatically by the smart table.

No Data

If there is no data to show, the smart table renders default text. This text can be overwritten by the app development team (aggregation: NoData).

Initially Visible Columns

The smart table enables you to define which columns are initially shown. Here, initially means that these columns are shown when the app is first launched. All other columns are initially hidden (annotation: PresentationVariant/ LineItem, property: initiallyVisibleColumns).

Persistency

End users can show additional columns if table personalization is provided. In this case, column settings are persisted. On consecutive startups, the columns are shown with the same settings as last defined by the user (property: persistenceKey).

Removing Columns

The smart table always shows all columns from the OData model. In some cases, columns needs to be in the model but should not be available on the front end at all. Examples of this include:

A column is needed to provide an ID which is used for navigation purposes, but the front end should only display the corresponding text, not the ID.

The values of a column are needed to perform calculations, but only the results should be shown on the UI.

In these cases, you can define which columns should not be available at all on the UI. These columns are not shown and are not available in the P13n dialog. You can also do this for columns that are added manually in the XML view (annotation: sap:visible, value:false).

P13n dialog

Filter Settings

The “Show Field as Column” option for newly added filters is switched on by default.

Sorting and Filtering

The smart table allows you to add sort and filter settings for each column. These settings enable the corresponding pages in the P13n dialog. For the grid table, analytical table, and tree table, sorting and filtering are also enabled on the column header. (Annotations: sap:sortable and sap:filterable)

Column header menu of the grid table

Smart Table and Smart Filter Bar

The smart table can be linked to a smart filter bar. If linked, filter bar settings are automatically used on the smart table. (sap.ui.comp.smarttable,SmartTable, property:smartFIlterId)

Aggregation

If used with the analytical table, the smart table allows total sums of measure columns to be calculated. The totals are shown in the usual way:

As the last row of the analytical table.

As the last row of each group if the group is expanded.

On the group header of each group if the group is collapsed.

Aggregation settings are not persisted (annotation: sap:aggregation-role, value:measure).

The total count be hidden via the column header menu.

Aggregation entry in column header menu of the grid table

Column Width

A default column width is calculated for each column based on the data displayed in it. Important: end users cannot change the column width in the responsive table (annotations: MaxLength, Precision, Scale).

Column Header

A column header text can be specified for each column (annotation: sap:label).

Persistence

The smart table allows you to persist sort, group, and filter column settings (such as by hidden columns) as well as variants (sap.ui.comp.smarttable.SmartTable, Property:persistenceyKey).

Content

The smart table provides two options to create columns automatically:

The smart table is rendered in either read-only or edit mode. In this case, the smart table renders the controls as described below. This is the default way of rendering content (property: editable)

If users need to switch between read-only and edit mode at runtime, the smart table allows smart fields to be rendered instead. You should use this if the edit button is added to the toolbar of the smart table (aggregation: customData key: useSmartField).

For option 1, the following controls are used:

To show currency amounts, the smart table allows the amount and the currency code to be displayed in a single cell. For read-only mode, the currency control is used. For edit mode, a single input field is used, and the currency itself is shown next to the input field as non-editable text (annotation: sap:semantics, value: currency-code).

To show links that open a quick view, the smart table supports the smart link.

To show static text, the smart table uses an input field in edit mode, and a text in read-only mode.

To show dates, the smart table uses a date picker in edit mode, and a text in read-only mode (annotation: sap:display-format, value:Date).

To show decimal numbers, the smart table uses an input field in edit mode, and a text in read-only mode (Annotations:Precision, Scale).

The smart table also provides an object status and object identifier control. For more information, see object display components.

Pictures and microcharts, as well as rating indicators and progress bars are available.

Amount formatting
Link formatting
Date formatting

Value Help

The smart table supports value help in the following ways (annotation: ValueList):

Input fields can show a value help button. Triggering this button opens a value help dialog. Within this dialog, you can provide a search field (annotation:ValueList, property: SearchSupported).

You can restrict the number of characters for the input field. Use this if no ValueList annotation is provided (annotation:MaxLength).

Toolbar Level

Table Title

The smart table can provide a title for the table within the toolbar (sap.ui.comp.smarttable.SmartTable, Property:header).

Table title

Item Count

Next to the table title, an item count can be shown (sap.ui.comp.smarttable.SmartTable, Property:showRowCount).

Table title with item count

Edit

The table toolbar can contain a button for toggling the table between read-only and edit modes. If smart fields are used, the smart table handles both modes automatically (sap.ui.comp.smarttable.SmartTable, Property:editTogglable, aggregation: customData, key: useSmartField).

Edit button

View Settings

The table toolbar can contain a button for opening the P13n dialog. This dialog provides extensive sort, group, and filter settings. It also allows columns to be shown, hidden, or rearranged (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).

Settings button

Export to Spreadsheet

If the back end supports the export of data to spreadsheet, the table toolbar can contain a corresponding button. When this button is triggered, the corresponding file is created and the download starts automatically (sap.ui.comp.smarttable.SmartTable, Property:useExportToExcel).

Export to Spreadsheet button

Full Screen Mode

Applications can implement a maximize button to run the table in full screen (Property: showFullScreenButton).

Maximize button

Footer Toolbar Level

Buttons in the footer toolbar can be set to emphasized to give them a brighter appearance.

Guidelines

In general, the guidelines for the underlying table, toolbar, variant management, and P13n dialog also apply to the smart table (see the corresponding articles for details). However, because the smart table does not offer the complete flexibility of the underlying controls, there are certain differences.

Table Type

The responsive table is the standard table for SAP Fiori. Use the responsive table whenever possible. It is the most flexible table in terms of how its content is displayed, it is fully responsive, and it can handle up to 1,000 line items.

If you cannot use the responsive table, consider using the grid table instead. The grid table can handle a large number of line Items. Compared to the responsive table, however, it is more restricted content-wise (only certain controls can be used to show the data, and only one control per cell), and it does not run on smartphones. If you use the grid table, you need to provide a fallback solution for smartphones, for example, by using the responsive table.

The analytical table is similar to the grid table, but adds several grouping levels and offers total sums on measure columns. The analytical table can also handle a large number of line Items. Compared to the responsive table, however, it is more restricted content-wise (only certain controls can be used to show the data, and only one control per cell), and it does not run on smartphones. If you use the analytical table, you need to provide a fallback solution for smartphones, for example, by using the responsive table.

The tree table is the only table for displaying hierarchical data. Like the grid table, it can handle a large number of line items, although it is restricted content-wise (only certain controls can be used to show the data, and only one control per cell), and it does not run on smartphones. If you use the tree table, you need to provide a fallback solution for smartphones, for example, by using the responsive table.

For more information about the different table controls, see the corresponding articles.

Table Title, Item Count, and Variant Management

Always show the item count together with the table title, unless this is expected to cause performance problems.
If used with the responsive table and if more than 200 items are generally expected, do not show the item count. In this case, the smart table displays a More button to load additional rows. Using the item count together with the More button might lead to confusion (sap.ui.comp.smarttable.SmartTable, Property:showRowCount).

Even if variant management is easy to implement, use it only if it is really needed. The variant management saves the whole page, including filter settings and table layouts.

Empty Tables

Try not to display an empty table. If there is no way around this, provide instructions on how to fill the table with data (aggregatrion: noData).

Columns – Best Practices

Keep the number of initially shown columns to a minimum. Avoid the need to scroll horizontally on a tablet screen size in default delivery (annotation: PresentationVariant/ LineItem).

Keep the number of additional (initially hidden) columns to a minimum. You can use the P13n dialog to show/hide the columns. Select the columns offered in the P13n dialog carefully. Do not just show all columns available in the backend tables (annotation: sap:visible, value:false).

For the grid table, analytical table, and tree table, the column widths are calculated automatically if the corresponding OData annotations are provided (annotations: MaxLength, Precision, Scale).

In contrast, the responsive table uses the same width for all columns.

If used with the responsive table, enable the pop-in behavior
(sap.ui.comp.smarttable.SmartTable, property: smartFilterId, value: true).

Show the most important column on the left and the least important on the right. This ensures that the most important columns stay in the tabular layout as long as possible. The most important columns are those that contain the following information:

The column that identifies the line item

The column that contains the key attribute

(Annotation: PresentationVariant/ LineItem, Property: initiallyVisibleColumns)

Email column in the pop-in area of the responsive table

Provide a column header text for each column. Do not truncate the column header text in default delivery (annotation: sap:label).

Column header text

Content Alignment and Formatting

The smart table automatically takes care of content alignment and formatting in standard use cases. For this, the OData metadata needs to provide the correct information about the data types, semantics of, and value help for the data.
(Annotations such as: sap:semantics, value: currency-code, edm types, Annotation: sap:display-format, value:Date, Annotation:Precision, Annotation: Scale, Annotation: ValueList, Annotation: ValueList:semantics, value:fixed-values)

Actions

To trigger actions on multiple items, use a mutliselection smart table. Do not offer action triggering on multiple items if the table is expected to have fewer than 10 items in most cases.
While the grid table, analytical table, and tree table are multiselectable by default within the smart table, the responsive table is single-selectable. The selection mode can be changed (XMLView).

The following actions can be shown on the standard toolbar of the smart table:

Edit
Toggles the table between edit and read-only mode. This only works if smart fields are used inside the smart table (sap.ui.comp.smarttable.SmartTable, Property:editTogglable, aggregation: customData, key: useSmartField).

View Settings
This button opens the P13n dialog. Note that the P13n dialog is quite complex. Neither the simpler view settings dialog nor the table personalization dialog can be used without the app development team developing the entire view settings handling (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).

Export to Spreadsheet
Only use this option if your end users typically export the data shown in the table in order to work with it in a spreadsheet application. This is usually the case if data is collected from several systems and analyzed in the spreadsheet application. This is not usually the case for worklists, attachment lists, lists with only a few items, shopping carts, or data that does not need to be analyzed. This option is only available if the corresponding back end supports exporting to spreadsheet (sap.ui.comp.smarttable.SmartTable, property: useExportToExcel).

If additional actions are needed, use a custom toolbar for the table. The smart table can also add integrated functionality such as a table title, item count, variant management, edit and view settings, and export to spreadsheet to the custom toolbar (aggregation: customToolbar).

For navigation to line item details:

If used with the responsive table, use the navigation mode of the responsive table.

If used with the grid table, analytical table, or tree table, use a link for the attribute that identifies the row. The user can click this link to trigger the navigation.

Clicking a table row can trigger drill-in navigation to a deeper level of the object, as well as cross-navigation to another SAP Fiori app or even to another system.

Inline Actions

Actions that belong to single items can be placed within the row. They can be displayed as text or icons. Make sure the icon communicates the function clearly enough. Otherwise, use a textual button.

Editable Content

The smart table can be editable or read-only (sap.ui.comp.smarttable.SmartTable, property: editable).

The smart table selects the corresponding editable controls automatically based on the data type, semantic annotations, and value list annotations (annotations such as: sap:semantics, value: currency-code, edm types, Annotation: sap:display-format, value:Date, Annotation:Precision, Annotation: Scale, Annotation: ValueList, Annotation: ValueList:semantics, value:fixed-values).

If an edit mode is needed, the controls are automatically switched from read-only controls (such as text) to editable controls (such as input field or date picker) if smart fields are used inside the smart table (sap.ui.comp.smarttable.SmartTable, Property:editTogglablea, aggregation: customData, key: useSmartField).

Only use this if you need to toggle between both modes. In any other case, show only the mode you need (read-only or edit), but do not offer the switch.

View Settings: Sort, Filter, Group, and Column Settings

If view settings are enabled on the smart table, a settings button is available on the table toolbar. This button opens the P13n dialog. Neither the simpler view settings dialog nor table personalization dialog can be used without extra effort (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).

The P13n dialog always enables the user to show, hide, and rearrange columns. Alternatively, it can contain settings for sorting, grouping, and/or filtering (annotations: sap:sortable, sap:filterable)

If the smart table uses the grid table, analytical table, or tree table, sort, filter, and group settings are also available in the column header menu.

Offer view settings only if they are really needed. For example, these settings do not make sense if the table contains only a few items and just a few columns.

Note that the P13n dialog is quite complex. It is ideal for tables with a vast number of items, but is quite cumbersome for handling just a few hundred items. Therefore, show only the settings (sort, group, filter) you really need. For example, do not offer grouping if it does not support your use case well.

If filtering is a main use case, do not offer filtering in the P13n dialog. Use the filter bar instead (annotation: sap:filterable)

Be persistent: When the app is reopened, the smart table is shown with the same view settings as last defined by the user (sap.ui.comp.smarttable.SmartTable, property: persistenceKey).

Sort

The current sort state is displayed as follows:

Using the responsive table, there is no indication that the table is currently sorted.

Using the grid table, analytical table, or tree table, an icon in the column header of the last sorted column indicates that the table is sorted and the direction in which it is sorted.

In default delivery, sort items in a meaningful order by the row-identifying column (usually the first column in default delivery). For example, use an alphabetical order for text, a numeric order for numbers, and a chronological order for dates (annotations: sap:sortable, PresentationVariant – SortOrder).

Filter

The current filter state is displayed as follows:

Using the responsive table, there is no indication that the table is currently filtered. The filter info bar can be added with additional effort.

Using the grid table, analytical table, or tree table, filtering is displayed by an icon on the column header of each filtered column (annotation: sap:filterable).

Group

To display the current group state, group headers are shown automatically. The following text should be shown on the group header:
[Label of the grouped column]: [Grouping value]
This can be done by the smart table, but only if the raw data from the model can be used. In other cases, app development teams must format the group header text. For example, the raw data carries IDs, while the table displays the corresponding names, which are provided by another data source. In this case, app developers must provide the formatting for the group header texts.

Within the responsive table, the grouped column keeps its visibility to reduce confusion after the group settings have been changed. If visible, it stays in the tabular layout even if grouped.

If used with the analytical table, grouping is not offered on measures. Therefore, you can have aggregations or grouping on a specific column.

If appropriate, offer reasonable grouping by default.

Responsive table grouped by country

Aggregate

If used with the analytical table, aggregation settings can be provided on measure columns. These settings are only available in the column header menu.
To display the current aggregation state, the total sum of the corresponding column is shown at the bottom of the table.
If items are grouped, an intermediate sum is shown per group:

At the bottom of each group if the group is expanded.

In the group header if the group is collapsed.

Aggregations are only available on measures, but not on objects or attributes. If aggregation is enabled for a column, this column cannot be grouped.

Avoid aggregations on the first three columns for the default delivery. When grouping is used together with aggregations, collapsing a group shows the aggregation on the group header. This conflicts with the group name.

Where appropriate, offer reasonable aggregation by default (annotation: sap:aggregation-role, value: measure).

Column Settings

Only offer column settings if you need more columns than a tablet screen can display at a time (usually more than five).

If sorting, grouping, and/or filtering are needed, column settings must also be shown (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).

Add, Remove, Rearrange Columns

Use the P13n dialog to add, remove, and rearrange columns.

When used with the grid table, analytical table, or tree table, columns can also be rearranged by dragging and dropping the column header (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).

Resize Columns

When used with the grid table, analytical table, or tree table, columns can be resized on the column header (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).

Freeze Columns

When used with the grid table, analytical table, or tree table, app developers must manually add the options for freezing columns to the column header menu if necessary. They can do this by declaring the corresponding table inside the smart table in the XML view, and by using the corresponding settings on this inner table.

Selecting Freeze on a column freezes all columns from the first one to the one on which Freeze is selected. The menu entry on this column changes from Freeze to Unfreeze.

Properties

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

The property: ignoreFields defines the columns that are not available on the UI – neither in the initial visible columns nor in the P13n dialog.

The property: requestAtLeastFields can be used for requesting additional technical columns.

The property: ignoreFromPersonalization removes columns from the P13n dialog.

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

The property: enableCustomFilter allows the filter menu item in the column header menu to be exchanged.

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

The property: currentVariantId defines the currently used variant.

The property: enableAutoBinding fetches the data automatically as soon as the corresponding OData model is initialized and the smart table is created.

The property: tableBindingPath defines the path from which the data is fetched.

The following aggregations are available:

The aggregation: semanticObjectController is used to customize smart links inside the smart table.

The aggregation: noData provides a text in case the table contains no line items. For example, this can be the case if the table is filtered. The text should provide context-specific instructions on how to get data into the table.

Resources

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

Elements and Controls

Responsive Table (guidelines)

Grid Table (guidelines)

Analytical Table (guidelines)

Tree Table (guidelines)

Table Overview (guidelines)

Table Toolbar (guidelines)

Variant Management (guidelines)

P13n-Dialog (guidelines)

Implementation

Smart Table (SAPUI5 samples)

Smart Table (SAPUI5 API reference)

Smart Table (Developer Guide)

P13n-Dialog (SAPUI5 samples)

P13n-Dialog (SAPUI5 API reference)

Toolbar (SAPUI5 samples)

Smart Table

The smart table is a wrapper around existing tables, and can be used together with the responsive table, grid table, analytical table, or tree table.

The smart table creates columns automatically based on the underlying OData service plus corresponding annotations. It also adds some generic functionality, such as a toolbar, complex personalization settings, variant management, and export to spreadsheet.

Everything that can be done using the smart table can also be achieved using the responsive table, grid table, analytical table, or tree table directly, but with more development effort. Therefore, the main purpose of the smart table is to reduce development effort. However, this comes at the expense of decreased flexibility.

Usage

Use the smart table if:

Data is fed into the table through OData services.

You need a simple table with limited flexibility to display its content. In this case, the smart table reduces development effort.

You need a table in which some columns provide flexible content. In this case, use the smart table together with a responsive table, and provide app-specific column definitions for these columns.

Do not use the smart table if:

You create your own UI coding, whereby the data is not fed through OData services. In this case, use the underlying table control directly.

The main use case involves selecting one item from very few items, with no additional details. In this case, a select or combo box might be more suitable.

The main use case involves selecting one item from several items, with only a few details per item. In this case, a list might be more suitable. Pay attention to the layout of the list item to provide a pleasant appearance (see, for example, the master list and the feed list item).

The table is displayed together with a chart inside a chart container. The smart table is not designed to work inside an existing chart container. In this case, use the underlying table control directly.

You need an overview of a large amount of data. In this case, use charts.

You just need it for layout reasons. In this case, use a layout container, such as the grid layout, instead.

You need read-only or editable field value pairs. In this case, use a form instead. Tables are not optimized for form-like input navigation.

Responsiveness

The responsiveness of the smart table depends on the encapsulated table. The table toolbar uses the overflow mechanism for adapting to the screen width.

Using the responsive table

The smart table offers a generic responsive behavior (sap.ui.comp.smarttable.SmartTable, property: smartFilterId, value: true):

For every 10 rem of screen width, one column stays in the tabular layout. All others are moved to the pop-in area. The columns are moved to the pop-in area from right to left, so the column furthest to the right moves to the pop-in first.

Exception: The first two columns always stay in the tabular layout. This works best if the smart table uses the whole screen width. It might not work well if the smart table uses far less space.

Using the grid table, analytical table, or tree table

The smart table works only on desktop and tablets, but not on smartphones. It supports touch devices, but is not optimized for small screens.

If you use a smart table in this configuration, ensure that you implement a fallback solution for small screens. This fallback solution does not need to support all use cases. You could create a fallback by using a responsive table. However, a completely different solution, such as showing charts in a read-only case, might be more suitable.

Size S with responsive table
Size M with responsive table

Size M with grid table
Size L with grid table

Layout

The title bar contains the title of the smart table, the item count, variant management, and the toolbar itself. All of these elements are optional.
The table area shows the corresponding table (responsive table, grid table, analytical table, or tree table).

Schematic visualization of the smart table

Components

The title bar consists of a toolbar.

This can be the standard toolbar or a custom toolbar. The standard toolbar can contain a title text with or without item count, variant management, view switch (switching the table to edit mode), an entry point for the P13n dialog, and an Export to Spreadsheet action.

If you require additional functionality, you can use an app-specific toolbar. All toolbar options provided by the smart table can also be added to the app-specific toolbar. (Aggregation: customToolbar)

The table area consists of any of the following tables: responsive table, grid table, analytical table, or tree table.

Standard toolbar with everything enabled
Standard toolbar just with title and item count

Behavior and Interaction

The behavior is generally inherited from the underlying table, toolbar, variant management, 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.

Table Level

Table Type

The smart table can encapsulate the responsive table, grid table, analytical table, or tree table. (sap.ui.comp.smarttable.SmartTable, property: tableType)

Automatic Rendering of the Table

The smart table automatically creates columns and renders all items based on the metadata of the underlying OData service (sap.ui.comp.smarttable.SmartTable, property: smartFilterId).

To be more flexible in the table layout, the smart table also offers app-specific column templates for some or all columns. In this case, app developers must provide the definition for the underlying table and for the corresponding (but not necessarily for all) columns in the XML view. For this, the app development team must provide the column keys of the overridden columns via custom data.

Additional columns can also be added. Columns that are defined in this way retain all the options of the underlying table. This is especially useful with the responsive table, which offers complete flexibility in content design. Any columns that are not defined by the app development team are still rendered automatically by the smart table.

No Data

If there is no data to show, the smart table renders default text. This text can be overwritten by the app development team (aggregation: NoData).

Initially Visible Columns

The smart table enables you to define which columns are initially shown. Here, initially means that these columns are shown when the app is first launched. All other columns are initially hidden (annotation: PresentationVariant/ LineItem, property: initiallyVisibleColumns).

Persistency

End users can show additional columns if table personalization is provided. In this case, column settings are persisted. On consecutive startups, the columns are shown with the same settings as last defined by the user (property: persistenceKey).

Removing Columns

The smart table always shows all columns from the OData model. In some cases, columns needs to be in the model but should not be available on the front end at all. Examples of this include:

A column is needed to provide an ID which is used for navigation purposes, but the front end should only display the corresponding text, not the ID.

The values of a column are needed to perform calculations, but only the results should be shown on the UI.

In these cases, you can define which columns should not be available at all on the UI. These columns are not shown and are not available in the P13n dialog. You can also do this for columns that are added manually in the XML view (annotation: sap:visible, value:false).

P13n dialog

Sorting and Filtering

The smart table allows you to add sort and filter settings for each column. These settings enable the corresponding pages in the P13n dialog. For the grid table, analytical table, and tree table, sorting and filtering are also enabled on the column header. (Annotations: sap:sortable and sap:filterable)

Column header menu of the grid table

Smart Table and Smart Filter Bar

The smart table can be linked to a smart filter bar. If linked, filter bar settings are automatically used on the smart table. (sap.ui.comp.smarttable,SmartTable, property:smartFIlterId)

Aggregation

If used with the analytical table, the smart table allows total sums of measure columns to be calculated. The totals are shown in the usual way:

As the last row of the analytical table.

As the last row of each group if the group is expanded.

On the group header of each group if the group is collapsed.

Aggregation settings are not persisted (annotation: sap:aggregation-role, value:measure).

Aggregation entry in column header menu of the grid table

Column Width

A default column width is calculated for each column based on the data displayed in it. Important: end users cannot change the column width in the responsive table (annotations: MaxLength, Precision, Scale).

Column Header

A column header text can be specified for each column (annotation: sap:label).

Persistence

The smart table allows you to persist sort, group, and filter column settings (such as by hidden columns) as well as variants (sap.ui.comp.smarttable.SmartTable, Property:persistenceyKey).

Content

The smart table provides two options to create columns automatically:

The smart table is rendered in either read-only or edit mode. In this case, the smart table renders the controls as described below. This is the default way of rendering content (property: editable)

If users need to switch between read-only and edit mode at runtime, the smart table allows smart fields to be rendered instead. You should use this if the edit button is added to the toolbar of the smart table (aggregation: customData key: useSmartField).

For option 1, the following controls are used:

To show currency amounts, the smart table allows the amount and the currency code to be displayed in a single cell. For read-only mode, the currency control is used. For edit mode, a single input field is used, and the currency itself is shown next to the input field as non-editable text (annotation: sap:semantics, value: currency-code).

To show links that open a quick view, the smart table supports the smart link.

To show static text, the smart table uses an input field in edit mode, and a text in read-only mode.

To show dates, the smart table uses a date picker in edit mode, and a text in read-only mode (annotation: sap:display-format, value:Date).

To show decimal numbers, the smart table uses an input field in edit mode, and a text in read-only mode (annotations:Precision, Scale).

Amount formatting
Link formatting
Date formatting

Value Help

The smart table supports value help in the following ways (annotation: ValueList):

Input fields can show a value help button. Triggering this button opens a value help dialog. Within this dialog, you can provide a search field (annotation:ValueList, property: SearchSupported).

You can restrict the number of characters for the input field. Use this if no ValueList annotation is provided (annotation:MaxLength).

Toolbar Level

Table Title

The smart table can provide a title for the table within the toolbar (sap.ui.comp.smarttable.SmartTable, Property:header).

Table title

Item Count

Next to the table title, an item count can be shown (sap.ui.comp.smarttable.SmartTable, Property:showRowCount).

Table title with item count

Variant Management

The table title can provide variant management for the table (sap.ui.comp.smarttable.SmartTable, Property:useVariantManagement).

Table title with item count and variant management

Edit

The table toolbar can contain a button for toggling the table between read-only and edit modes. If smart fields are used, the smart table handles both modes automatically (sap.ui.comp.smarttable.SmartTable, Property:editTogglable, aggregation: customData, key: useSmartField).

Edit button

View Settings

The table toolbar can contain a button for opening the P13n dialog. This dialog provides extensive sort, group, and filter settings. It also allows columns to be shown, hidden, or rearranged (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).

Settings button

Export to Spreadsheet

If the back end supports the export of data to spreadsheet, the table toolbar can contain a corresponding button. When this button is triggered, the corresponding file is created and the download starts automatically (sap.ui.comp.smarttable.SmartTable, Property:useExportToExcel).

Export to Spreadsheet button

Applications can implement a maximize button to run the table in full screen (Property: showFullScreenButton).

Maximize button

Guidelines

In general, the guidelines for the underlying table, toolbar, variant management, and P13n dialog also apply to the smart table (see the corresponding articles for details). However, because the smart table does not offer the complete flexibility of the underlying controls, there are certain differences.

Table Type

The responsive table is the standard table for SAP Fiori. Use the responsive table whenever possible. It is the most flexible table in terms of how its content is displayed, it is fully responsive, and it can handle up to 1,000 line items.

If you cannot use the responsive table, consider using the grid table instead. The grid table can handle a large number of line Items. Compared to the responsive table, however, it is more restricted content-wise (only certain controls can be used to show the data, and only one control per cell), and it does not run on smartphones. If you use the grid table, you need to provide a fallback solution for smartphones, for example, by using the responsive table.

The analytical table is similar to the grid table, but adds several grouping levels and offers total sums on measure columns. The analytical table can also handle a large number of line Items. Compared to the responsive table, however, it is more restricted content-wise (only certain controls can be used to show the data, and only one control per cell), and it does not run on smartphones. If you use the analytical table, you need to provide a fallback solution for smartphones, for example, by using the responsive table.

The tree table is the only table for displaying hierarchical data. Like the grid table, it can handle a large number of line items, although it is restricted content-wise (only certain controls can be used to show the data, and only one control per cell), and it does not run on smartphones. If you use the tree table, you need to provide a fallback solution for smartphones, for example, by using the responsive table.

For more information about the different table controls, see the corresponding articles.

Table Title, Item Count, and Variant Management

Always show the item count together with the table title, unless this is expected to cause performance problems.
If used with the responsive table and if more than 200 items are generally expected, do not show the item count. In this case, the smart table displays a More button to load additional rows. Using the item count together with the More button might lead to confusion (sap.ui.comp.smarttable.SmartTable, Property:showRowCount).

Even if variant management is easy to implement, use it only if it is really needed. For example, if the smart table is used together with the filter bar and the filter bar already implements variant management, an additional variant management on the table is only needed in special cases.
Note that the smart filter bar cannot persist both the smart table settings and the filter settings (sap.ui.comp.smarttable.SmartTable, Property:useVariantManagement).

Empty Tables

Try not to display an empty table. If there is no way around this, provide instructions on how to fill the table with data (aggregatrion: noData).

Columns – Best Practices

Keep the number of initially shown columns to a minimum. Avoid the need to scroll horizontally on a tablet screen size in default delivery (annotation: PresentationVariant/ LineItem).

Keep the number of additional (initially hidden) columns to a minimum. You can use the P13n dialog to show/hide the columns. Select the columns offered in the P13n dialog carefully. Do not just show all columns available in the backend tables (annotation: sap:visible, value:false).

For the grid table, analytical table, and tree table, the column widths are calculated automatically if the corresponding OData annotations are provided (annotations: MaxLength, Precision, Scale).

In contrast, the responsive table uses the same width for all columns.

If used with the responsive table, enable the pop-in behavior
(sap.ui.comp.smarttable.SmartTable, property: smartFilterId, value: true).

Show the most important column on the left and the least important on the right. This ensures that the most important columns stay in the tabular layout as long as possible. The most important columns are those that contain the following information:

The column that identifies the line item

The column that contains the key attribute

(Annotation: PresentationVariant/ LineItem, Property: initiallyVisibleColumns)

Email column in the pop-in area of the responsive table

Provide a column header text for each column. Do not truncate the column header text in default delivery (annotation: sap:label).

Column header text

Content Alignment and Formatting

The smart table automatically takes care of content alignment and formatting in standard use cases. For this, the OData metadata needs to provide the correct information about the data types, semantics of, and value help for the data.
(Annotations such as: sap:semantics, value: currency-code, edm types, Annotation: sap:display-format, value:Date, Annotation:Precision, Annotation: Scale, Annotation: ValueList, Annotation: ValueList:semantics, value:fixed-values)

Actions

To trigger actions on multiple items, use a mutliselection smart table. Do not offer action triggering on multiple items if the table is expected to have fewer than 10 items in most cases.
While the grid table, analytical table, and tree table are multiselectable by default within the smart table, the responsive table is single-selectable. The selection mode can be changed (XMLView).

The following actions can be shown on the standard toolbar of the smart table:

Edit
Toggles the table between edit and read-only mode. This only works if smart fields are used inside the smart table (sap.ui.comp.smarttable.SmartTable, Property:editTogglable, aggregation: customData, key: useSmartField).

View Settings
This button opens the P13n dialog. Note that the P13n dialog is quite complex. Neither the simpler view settings dialog nor the table personalization dialog can be used without the app development team developing the entire view settings handling (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).

Export to Spreadsheet
Only use this option if your end users typically export the data shown in the table in order to work with it in a spreadsheet application. This is usually the case if data is collected from several systems and analyzed in the spreadsheet application. This is not usually the case for worklists, attachment lists, lists with only a few items, shopping carts, or data that does not need to be analyzed. This option is only available if the corresponding back end supports exporting to spreadsheet (sap.ui.comp.smarttable.SmartTable, property: useExportToExcel).

If additional actions are needed, use a custom toolbar for the table. The smart table can also add integrated functionality such as a table title, item count, variant management, edit and view settings, and export to spreadsheet to the custom toolbar (aggregation: customToolbar).

For navigation to line item details:

If used with the responsive table, use the navigation mode of the responsive table.

If used with the grid table, analytical table, or tree table, use a link for the attribute that identifies the row. The user can click this link to trigger the navigation.

Editable Content

The smart table can be editable or read-only (sap.ui.comp.smarttable.SmartTable, property: editable).

The smart table selects the corresponding editable controls automatically based on the data type, semantic annotations, and value list annotations (annotations such as: sap:semantics, value: currency-code, edm types, Annotation: sap:display-format, value:Date, Annotation:Precision, Annotation: Scale, Annotation: ValueList, Annotation: ValueList:semantics, value:fixed-values).

If an edit mode is needed, the controls are automatically switched from read-only controls (such as text) to editable controls (such as input field or date picker) if smart fields are used inside the smart table (sap.ui.comp.smarttable.SmartTable, Property:editTogglablea, aggregation: customData, key: useSmartField).

Only use this if you need to toggle between both modes. In any other case, show only the mode you need (read-only or edit), but do not offer the switch.

View Settings: Sort, Filter, Group, and Column Settings

If view settings are enabled on the smart table, a settings button is available on the table toolbar. This button opens the P13n dialog. Neither the simpler view settings dialog nor table personalization dialog can be used without extra effort (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).

The P13n dialog always enables the user to show, hide, and rearrange columns. Alternatively, it can contain settings for sorting, grouping, and/or filtering (annotations: sap:sortable, sap:filterable)

If the smart table uses the grid table, analytical table, or tree table, sort, filter, and group settings are also available in the column header menu.

Offer view settings only if they are really needed. For example, these settings do not make sense if the table contains only a few items and just a few columns.

Note that the P13n dialog is quite complex. It is ideal for tables with a vast number of items, but is quite cumbersome for handling just a few hundred items. Therefore, show only the settings (sort, group, filter) you really need. For example, do not offer grouping if it does not support your use case well.

If filtering is a main use case, do not offer filtering in the P13n dialog. Use the filter bar instead (annotation: sap:filterable)

Be persistent: When the app is reopened, the smart table is shown with the same view settings as last defined by the user (sap.ui.comp.smarttable.SmartTable, property: persistenceKey).

Sort

The current sort state is displayed as follows:

Using the responsive table, there is no indication that the table is currently sorted.

Using the grid table, analytical table, or tree table, an icon in the column header of the last sorted column indicates that the table is sorted and the direction in which it is sorted.

In default delivery, sort items in a meaningful order by the row-identifying column (usually the first column in default delivery). For example, use an alphabetical order for text, a numeric order for numbers, and a chronological order for dates (annotations: sap:sortable, PresentationVariant – SortOrder).

Filter

The current filter state is displayed as follows:

Using the responsive table, there is no indication that the table is currently filtered. The filter info bar can be added with additional effort.

Using the grid table, analytical table, or tree table, filtering is displayed by an icon on the column header of each filtered column (annotation: sap:filterable).

Group

To display the current group state, group headers are shown automatically. The following text should be shown on the group header:
[Label of the grouped column]: [Grouping value]
This can be done by the smart table, but only if the raw data from the model can be used. In other cases, app development teams must format the group header text. For example, the raw data carries IDs, while the table displays the corresponding names, which are provided by another data source. In this case, app developers must provide the formatting for the group header texts.

Within the responsive table, the grouped column keeps its visibility to reduce confusion after the group settings have been changed. If visible, it stays in the tabular layout even if grouped.

If used with the analytical table, grouping is not offered on measures. Therefore, you can have aggregations or grouping on a specific column.

If appropriate, offer reasonable grouping by default.

Responsive table grouped by country

Aggregate

If used with the analytical table, aggregation settings can be provided on measure columns. These settings are only available in the column header menu.
To display the current aggregation state, the total sum of the corresponding column is shown at the bottom of the table.
If items are grouped, an intermediate sum is shown per group:

At the bottom of each group if the group is expanded.

In the group header if the group is collapsed.

Aggregations are only available on measures, but not on objects or attributes. If aggregation is enabled for a column, this column cannot be grouped.

Avoid aggregations on the first three columns for the default delivery. When grouping is used together with aggregations, collapsing a group shows the aggregation on the group header. This conflicts with the group name.

Where appropriate, offer reasonable aggregation by default (annotation: sap:aggregation-role, value: measure).

Column Settings

Only offer column settings if you need more columns than a tablet screen can display at a time (usually more than five).

If sorting, grouping, and/or filtering are needed, column settings must also be shown (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).

Add, Remove, Rearrange Columns

Use the P13n dialog to add, remove, and rearrange columns.

When used with the grid table, analytical table, or tree table, columns can also be rearranged by dragging and dropping the column header (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).

Resize Columns

When used with the grid table, analytical table, or tree table, columns can be resized on the column header (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).

Freeze Columns

When used with the grid table, analytical table, or tree table, app developers must manually add the options for freezing columns to the column header menu if necessary. They can do this by declaring the corresponding table inside the smart table in the XML view, and by using the corresponding settings on this inner table.

Selecting Freeze on a column freezes all columns from the first one to the one on which Freeze is selected. The menu entry on this column changes from Freeze to Unfreeze.

Properties

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

The property: ignoreFields defines the columns that are not available on the UI – neither in the initial visible columns nor in the P13n dialog.

The property: requestAtLeastFields can be used for requesting additional technical columns.

The property: ignoreFromPersonalization removes columns from the P13n dialog.

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

The property: enableCustomFilter allows the filter menu item in the column header menu to be exchanged.

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

The property: currentVariantId defines the currently used variant.

The property: enableAutoBinding fetches the data automatically as soon as the corresponding OData model is initialized and the smart table is created.

The property: tableBindingPath defines the path from which the data is fetched.

The following aggregations are available:

The aggregation: semanticObjectController is used to customize smart links inside the smart table.

The aggregation: noData provides a text in case the table contains no line items. For example, this can be the case if the table is filtered. The text should provide context-specific instructions on how to get data into the table.

Resources

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

Elements and Controls

Responsive Table (guidelines)

Grid Table (guidelines)

Analytical Table (guidelines)

Tree Table (guidelines)

Table Overview (guidelines)

Table Toolbar (guidelines)

Variant Management (guidelines)

P13n-Dialog (guidelines)

Implementation

Smart Table (SAPUI5 samples)

Smart Table (SAPUI5 API reference)

Smart Table (Developer Guide)

P13n-Dialog (SAPUI5 samples)

P13n-Dialog (SAPUI5 API reference)

Toolbar (SAPUI5 samples)

Smart Link

Similar to the quick view, the smart link triggers a popover from a text link. This popover offers links to related apps for the user to take action, and shows the user additional information such as simple object details.
The smart link is a smart control. It uses metadata annotations to offer the user specific navigation. It analyzes the user’s assigned apps and offers only relevant navigation targets.

Usage

Use the smart link to offer direct navigation to related apps. For example to navigate from a product list to the relevant app to change the pricing, or from a sales order list to the app to see a customer’s balance.

Use the smart link if:

You want to offer related apps for navigation.

You want to offer simple object details.

Do not use the smart link if:

You want to display more or complex information about an object. Use the object page or charts instead.

There is no metadata accessible, and only a direct link to a website, document or application is needed. Use the standard link instead.

You need to structure information in a deeper hierarchy. Use the quick view or a list drill down instead.

You want to display contact details. Use the quick view instead.

You need to show related information (such as an image). Use the popover or quick view instead.

Responsiveness

The responsiveness of the smart link is based on the responsiveness of the popover and overlays the content.

Clicking the background closes the popover on desktop and smartphones.

Size S - On smartphones, the smart link overlays the content
Size M - Smart link on a tablet device
Size L - Smart link in a table on a desktop device

Layout

The smart link contains the following areas:

The header bar of the smart link popover describes the type of information offered.

The title area provides space for a label and a main link. By default, the title and the link description of the link that triggers the popover are the same. However, both can be edited (for example, the title could display the company’s name while the link description is a customer ID).

In the content area, the application can show any control depending on the use case.

The Related Apps area offers links to all relevant applications of a user role. The title Related Apps cannot be changed.

The four different areas cannot be rearranged. The header bar is mandatory, while all other sections are optional. Depending on the use case, the application could only offer a Related Apps section, for example. The offered content in the popover must contain a link; otherwise the popover will not open. We do not recommend offering only one link within the popover – please use the standard link control to offer direct navigation instead.

The four areas of the smart link

Behavior and Interaction

The smart link and its popover are always triggered by clicking or tapping a text element that appears as a link. This text element can be placed in any list, table, or other container. The link label can be individually set. Clicking or tapping the background closes the popover.

If the semantic object annotation is not set, the smart link is rendered as sap.m.Text by default. However, app developers can also decide to render any other control.

Smart Link Interaction

The Related App Area

The title Related Apps cannot be changed. In breakout scenarios and custom applications, the links offered in this section can be freely chosen. The smart link control will suggest semantic objects that are modifiable. It’s possible to link to any website or app.

The Smart Link in a Smart Table

Within a smart table, the link label of the smart link is automatically set depending on the semantic object annotation. This means that the description cannot be changed in a smart table. Inside the smart table, the smart link is rendered as sap.m.Text if there are no navigation targets.

Guidelines

If you only need to offer one link to navigate, please use the standard link instead as this supports direct navigation without opening a popover.

Please check the related apps you offer carefully. Only display the ones that are relevant to the user.

Resources

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

Elements and Controls

Quickview (guidelines)

Popover (guidelines)

Implementation

Smart Link (SAPUI5 samples)

Smart Link (SAPUI5 API reference)

Smart Link

Similar to the quick view, the smart link triggers a popover from a text link. This popover offers links to related apps for the user to take action, and shows the user additional information such as simple object details.
The smart link is a smart control. It uses metadata annotations to offer the user specific navigation. It analyzes the user’s assigned apps and offers only relevant navigation targets.

Usage

Use the smart link to offer direct navigation to related apps. For example to navigate from a product list to the app to change the pricing, or from a sales order list to the app to see a customer’s balance.

Use the smart link if:

You want to offer related apps for navigation.

You want to offer simple object details.

Do not use the smart link if:

You want to display more or complex information about an object. Use the object page or charts instead.

There is no metadata accessible, and only a direct link to a website, document or application is needed. Use the standard link instead.

You need to structure information in a deeper hierarchy. Use the quick view or a list drilldown instead.

Responsiveness

The responsiveness of the smart link is based on the responsiveness of the popover and overlays the content.

Clicking the background closes the popover on desktop and smartphones.

On mobile devices, the smart link opens a dialog that overlays the entire content. Since the content beneath the popover is no longer directly visible to the end user, the dialog has a header that shows the object type. Users close the dialog by clicking the close icon () in the header.

The responsiveness of the smart link is based on the responsiveness of the popover and overlays the content.

A click into the background closes the popover on desktop.

On mobile devices, the smart link opens a dialog that overlays the entire content. Because there the content underneath the popover is no longer directly visible to the end user, the dialog acquires a header and shows the object type. The dialog can be closed by clicking the close icon () in the header.

Size S – On smartphones, the smart link overlays the content

Sizs M/ L - Smart link shown in a table on a desktop device

Layout

The smart link contains the following areas:

The header bar of the smart link popover tells the user the type of information offered and is only shown on mobile devices.

The title area contains a title and a subtitle. The title can also be shown as a link, which can be used to navigate to the corresponding object or factsheet. The subtitle can be used to show the ID of the object for example.

The content area shows object related information. That could be for example more details about a product or/ and contact information. The application can show any control depending on the use case.

The link area offers links to all relevant applications of a user role. Applications should take care of the amount of link that will be shown here. All semantic objects are shown here.

The header bar is mandatory (for mobile devices), while the other sections are optional. Depending on the use case, the application can offer only a content or a link section, for example.

The areas of the smart link (header bar not shown)

Behavior and Interaction

The smart link and its popover are always triggered by clicking or tapping a text element that appears as a link. This text element can be placed in any list, table, or other container. The link label can be individually set. Clicking or tapping the background closes the popover. If only one link is offered with no additional information, the smart link navigates directly to the target without opening the popover.

If the semantic object annotation is not set, the smart link is rendered as sap.m.Text by default. However app developers can also decide to render any other control.

The Related App Area

In breakout scenarios and custom applications, the links offered in this section can be freely chosen. The smart link control will suggest semantic objects that are modifiable. It’s possible to link to any website or app.

The Smart Link in a Smart Table

Within a smart table, the link label of the smart link is automatically set depending on the semantic object annotation. This means that the description cannot be changed in a smart table. Inside the smart table, the smart link is rendered as sap.m.Text if there are no navigation targets.

Guidelines

Please check the related apps you offer carefully. Only display the ones that are relevant to the user.

Use comprehensible link names in the link area. Do not use the same link name more than once in the link area. Rename the links if needed (for example, “Add Product” if the link navigates to the app “Manage Products”).

Resources

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

Elements and Controls

Quickview (guidelines)

Popover (guidelines)

Implementation

Smart Link (SAPUI5 samples)

Smart Link (SAPUI5 API reference)

Smart Filter Bar Annotations

Information
This article is intended as an aid to designers and developers who want to explore the detail configuration options available for the smart filter bar.

The smart filter bar is a wrapper that analyzes a given OData service and renders a filter bar based on the content defined by the service. For example, the OData service determines whether a field is visible on the filter bar, and whether it supports type-ahead and value help. To configure more settings or overwrite the settings from the OData service, the developer can set additional annotations in an external document (metadata.xml).

Developers can use annotation properties in the classes [external_only]ControlConfiguration and GroupConfiguration to adapt the filter bar for the purposes of the app.

These annotations let you:

Determine the type of control (for example, whether a field is shown as a multi-input field or as a date picker)

Enable the autocomplete suggestions feature

Enable the value help dialog

Overwrite settings from the OData service

Set custom filter groups

Add custom fields

Access all settings for the underlying filter bar

You can also use all the configuration options described here in the smart filter bar for the list report (SAP Fiori Elements).

Warning
Most of the attributes/properties are not dynamic and cannot be changed once the control has been initialized.

Usage

Use the smart filter bar if:

An OData service is available.

You want to develop quickly and efficiently.

Do not use the smart filter bar if:

You need to make extensive changes to the filter bar.

Components

You can use the annotation properties listed below to influence how filters are rendered in the expanded filter bar and in the filter dialog.

Expanded Filter Bar

Smart filter bar - Properties for the expanded filter bar

1 enableBasicSearch

Defines whether the filter bar includes a basic search. By default, the basic search is not included.

2 FilterRestrictions/NonFilterableProperties

Defines whether a property is available as a filter criterion.

3 FilterRestrictions/RequiredProperties

Defines the filter field as a mandatory filter. Mandatory filters are marked by an asterisk (*).

4 ValueList

Contains annotations that provide information for rendering a value help list that has been set for a property.

5 FilterExpressionType/MultiValue

Defines whether multiple values can be used in a single filter.

6 FilterExpressionType/SingleValue

Restricts the filter to allow only one value entry.

7 LineItem/Label

A short, human-readable text for the filter name.

8 FilterExpressionType/SingleInterval

Restricts the filter to a specified interval, such as a date interval.

8 insertDefaultFilterValue

Inserts a default filter value into the aggregation defaultFilterValues.

9 liveMode

Defines whether the expanded filter bar is shown in live mode (no Go button) or in manual mode. By default, the filter bar is shown in manual mode.

Filter Dialog

1 FilterRestrictions/RequiredProperties

Defines the filter field as a mandatory filter. Mandatory filters are marked by an asterisk (*).

2 FieldControlType/Hidden

Defines whether the filter is initially visible on the expanded filter bar.

3 SelectionFields

Defines whether a filter belongs to the basic group. All filters in the basic group are initially visible on the expanded filter bar.

4 FieldGroup

Defines whether a filter field is initially shown on the filter dialog, and which group it belongs to.

5 FilterRestrictions/NonFilterableProperties

Defines whether a property is available as a filter criterion.

6 LineItem/Label

A short, human-readable text for the filter name.

SmartFilterBar Properties on the Filter Dialog

Data Types

The smart filter bar analyzes and interprets the metadata provided by the OData service. This allows you to create complex UI entities, and to automatically add fields offered by the OData service to the filter bar as editable input fields. (Note that only fields marked with sap:filterable are added automatically.)

The tables below tell you which input controls are used for the key data types.

General Data Types

DataType ODataMetadata Additional Configuration Edit type Display type Notes

* * Input Text

DateTime – sap:display-format=”Date” DatePicker Text

Decimal – Precision=”3″ Scale=”0″ Input Text

All – Input (with VHD) Text If a matching ValueList annotation is found, the ValueHelp for the Input is enabled.
A ValueHelp Dialog is created automatically, based on the data in the ValueList annotation.

All –
sap:semantics=”fixed-values” on the ValueList entity
ComboBox Text If a matching ValueList annotation is found, and the ValueList entity has the semantics=”fixed-values”, a dropdown list is shown.

Filter Bar-Specific Data Types

Input Type sap:filter-restriction display-format hasValueHelpDialog controlType Resulting Control Type

* * controlType/filterType is specified As specified in additional configuration

DateTime “interval” “Date” NA Date Range Selection

DateTime “anything other than interval” or empty “Date” NA Date Picker

String “single-value” “true” / none Input Field With Value Help Dialog
(with typeAhead according to hasTypeAhead flag)

String “single-value” “false” not specified/input Input Field
(with typeAhead according to hasTypeAhead flag)

String “single-value” “false” dropDownList; hasTypeAhead is not considered here ComboBox

* “single-value” Input Field

String empty or no filter-restriction “true” / none Multi Input Field with Value Help Dialog

String “multi-value” “true” / none If no VL Annotation is found – only show the range selection part

String “multi-value” / empty “false” If no VL Annotation is found – hide the ValueHelpDialog icon

String “multi-value” / empty “false” dropDownList MultiComboBox

* “multi-value” Input Field

* “interval” NA A single Input Field that allows the “-” shortcut notation for intervals

Properties

FilterBar

Filter Bar Properties

persistencyKey
Data type: string
Key used to access personalization data.

advancedMode
Data type: boolean
The advanced mode overwrites the standard behavior and is used in the value help scenario.
Default value is false.

expandAdvancedArea
Data type: boolean
Defines whether the advanced area is expanded when the filter bar is used within the value help dialog.
Default value is false.

searchEnabled
Data type: boolean
Enables/disables the Search button in advanced mode.
Default value is true.

filterBarExpanded
Data type: boolean
Shows/hides the expanded filter bar.
Default value is true.

considerGroupTitle
Data type: boolean
If this property is set, the label for filters is prefixed with the group title.
Default value is false.

showClearButton
Data type: boolean
Handles visibility of the Clear button on the Filters dialog.
Default value is false.

showRestoreButton
Data type: boolean
Handles visibility of the Restore button on the Filters dialog.
Default value is true.

showGoOnFB
Data type: boolean
Handles visibility of the Go button on the filter bar.
Default value is true.

showRestoreOnFB
Data type: boolean
Handles visibility of the Restore button on the filter bar.
Default value is false.

showClearOnFB
Data type: boolean
Handles visibility of the Clear button on the filter bar.
Default value is false.

showGoButton
Data type: boolean
Handles visibility of the Go button on the filter bar.

deltaVariantMode
Data type: boolean
Stores the delta as compared to the standard variant.
Default value is true.

filterContainerWidth
Data type: string
Sets the width of the filter container.
Default value is 12rem.

useToolbar
Data type: boolean
Determines what design should be used. Default is the design with the toolbar. In mobile scenarios this property is ignored – the design with the toolbar is always used.
Default value is true.

header
Data type: string
Specifies the header text that is shown in the toolbar on the first position. This property is ignored, when useToolbar is set to false.

showFilterConfiguration
Data type: boolean
Handles visibility of the Filters button on the filter bar.
Default value is true.

Smart Filter Bar

Smart Filter Bar Properties

entitySet
Data type: string
The OData entity set whose metadata is used to create the SmartFilterBar. Note: Changing this value after the SmartFilterBar is initialized (initialize event was fired) has no effect.

basicSearchFieldName
Data type: string
Name of the field that has to be the focus of the basic search. This is only relevant for SmartFilterBar in combination with ValueHelpDialog.

enableBasicSearch
Data type: boolean
Enables the basic search field in the SmartFilterBar control. This must only be enabled for entities that support such search behavior.
Default value is false.

liveMode
Data type: boolean
Defines the live mode. The live mode only operates on non-phone scenarios.
Default value is false.

showMessages
Data type: boolean
If set to false, any errors that occur during the search will not be displayed in a message box.
Default value is true.

considerAnalyticalParameters
Data type: boolean
Indicates if the analytical parameters (SelectionVariant) must be taken into consideration.
Default value is false.

Smart Filter Bar Annotations

FilterRestrictions/NonFilterableProperties
Defines whether a Property can be used for filtering data.

FieldGroup
Defines a group for a filter field.

TextArrangement
Describes the arrangement of a code value and its text.

FieldControlType/Hidden
Defines whether the filter is visible.

ValueList
Contains annotations that provide information for rendering a ValueHelpList that has been set for a Property.

Label
A short, human-readable text for the filter name.

LineItem/Label
A short, human-readable text suitable for the filter name.

FilterRestrictions/RequiredProperties
Defines the filter field as mandatory filter.

FilterExpressionType/MultiValue
Defines whether multiple values can be used in a single filter.

FilterExpressionType/SingleValue
Restricts the filter to allow only one value entry.

FilterExpressionType/SingleInterval
Restricts the filter to a specified interval, such as a date interval.

SelectionFields
Defines whether certain fields should be initially visible in the SmartFilterBar control.

Control Configuration

Control Configuration Properties

key
The key property corresponds to the field name from the OData service metadata document.
Default value is string

groupId
The groupId can be used to move a field from one group to another. The groupId corresponds to the EntityName from the OData metadata. It is also possible to move a field from the advanced area to the basic area by specifying the groupId _BASIC.
Default value is string

label
You can use this property to overwrite the label of a filter field in the SmartFilterBar.
Default value is string

visible
Data type: boolean
You can use this flag to hide fields from the OData metadata.
Default value is true

hasValueHelpDialog
Data type: boolean
Specifies whether a value help dialog is available or not.
Default value is true

controlType
Data type: sap.ui.comp.smartfilterbar.ControlType
The SmartFilterBar calculates which kind of control will be used for a filter field, based on multiple OData attributes and annotations. You can use this property to overwrite the OData metadata.
Default value is auto

filterType
Data type: sap.ui.comp.smartfilterbar.FilterType
The filter type specifies whether the filter field is for a single value, multiple values, or an interval. The filter type calculated by the SmartFilterBar is based on the OData metadata. You can use this property to configure the filter type manually.
Default value is auto

index
Data type: int
You can use the zero-based index to specify the initial order of fields (without any variants).
Default value is -1

Control Configuration Properties

hasTypeAhead
Data type: boolean
You can use this property to enable the TypeAhead service. Note that TypeAhead does not work with all controls (for example, it is not supported for the DropDownListbox).
Default value is true

mandatory
Data type: sap.ui.comp.smartfilterbar.MandatoryType
You can use this property to overwrite the mandatory state of a filter field. This property can only be set during initialization. Changes at runtime will be ignored.
Default value is auto

width
Default value is string
The width of the filter field in a CSS compatible format. The width can be set only once during initialization. Changes at runtime will not be reflected. The width is not applied to custom controls.

visibleInAdvancedArea
Data type: boolean
If set to true, this field will be added to the advanced area (aka. Dynamic Selection) by default.
Default value is false

preventInitialDataFetchInValueHelpDialog
Data type: boolean
If value help annotations are available for this filter field, you can prevent the the table in the value help dialog for this field from being filled with the initial data fetch.
Default value is true

displayBehaviour
Data type: sap.ui.comp.smartfilterbar.DisplayBehaviour
The displayBehaviour specifies how to display the content on certain controls. For example: DescriptionOnly for Combobox (DropDown text), Description and ID for MultiInput (token text)
Default value is auto

conditionType
Data type: any
The condition Type class name to use for this filter item. Implementation should derive from sap.ui.comp.config.condition.Type.

Group Configuration

Group Configuration Properties

key
Data type: string
The key property shall correspond to the name EntityTypeName from the OData service $metadata document.

index
Data type: any
Zero-based integer index. The index can be used to specify the order of groups. If no index is specified, the order defined by the OData metadata will be used.
Default value is undefined

label
Data type: any
You can use this property to overwrite the label of a group in the advanced area of the SmartFilterBar.
Default value is undefined

Resources

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

Elements and Controls

Filter Bar/ Smart Filter Bar (guidelines)

Implementation

Smart Filter Bar (SAPUI5 samples)

Smart Filter Bar (SAPUI5 API reference)

UI Development Toolkit (SAPUI5 samples)