Updated: June 2, 2021

Smart Table

sap.ui.comp.smarttable.SmartTable

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
The components of a smart table

Table Toolbar

Toolbar with all features provided by the smart table out-of-the-box
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:

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

In addition, you can add app-specific actions.

Title

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:

Variant Management

Variant management is optional (properties: persistencyKeyuseVariantManagement, 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. Columns with a low priority (low or medium priority on phones) are hidden in the pop-in area (properties: demandPopin, showDetailsButton, annotation: UI.Importance). You can define which column priority levels are hidden (property: detailsButtonSettings). The button only appears if there are corresponding columns in the pop-in area.

Details hidden
Details hidden
Details shown
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

App-Specific Actions

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

Developer Hint

Infobar

Infobar with filter information
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

Table

Responsive table within a smart table
Responsive table within a smart table

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

Table

The table provides the following features:

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

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.

Responsive table with automatically calculated column widths, resizing, and remaining space
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).
Guidelines
Provide a column header text for each column. (annotation: sap:label).
  • The column headers contain the following settings:
    • Sort AscendingSort 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.
Column header menu for a dimension column of an analytical table within a smart 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
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:

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

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

Related Links

Elements and Controls

Implementation