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.
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:
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.
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:
- 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:
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.
The following text is usually shown on the group header:
[Label of the grouped column]: [Grouping value]
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:
exportType). The front-end export allows for additional settings and can also be triggered with the shortcut Ctrl+Shift+E.
Maximize / Minimize
- Columns are created automatically. Items are rendered based on the properties and metadata of the underlying OData service (annotation:
ignoreFields). A column is generated for each OData entity property.
- You can define which columns are initially visible when the app is first launched. All other columns are initially hidden (annotation:
- For each column that is initially visible, the
LineItemannotation includes a
DataFieldrecord, 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
- 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:
Scalefor numeric data (property:
The calculated width is between 3 rem and 20 rem. Apps can change this default width if needed (annotation:
If the combined width of all the columns is less than the width of the table, the remaining space stays empty.
- Columns can be resized by dragging the column separator. If the combined width of all columns is less than the width of the table, the remaining space stays empty. The smart table provides column resizing automatically in the following cases:
- 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.
- You can specify a column header text for each column (annotation:
- 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:
- Group (only analytical table, only on dimension columns)
- Total (only analytical table, only on measure columns): This setting is not persisted (annotation:
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.
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:
- 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:
useSmartField), but also allows for:
- Better control of the visibility of a field per row (smart field, annotation:
- Use of value help for input fields
- Better control of the visibility of a field per row (smart field, annotation:
|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,
|Do not use editable status information.|
|Key identifier||Object identifier (responsive table)
(all other tables)
|Input field for the ID||SemanticKey,
|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:
|Dates||Text||Date picker||Edm.DateTime, sap:display-format, value: date, IsCalendarDate|
|Dates and times||Text||Date/time picker||Edm.DateTime, Edm.DateTimeOffset|
|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.|
|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).
Behavior and Interaction
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.
- 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.
- 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.
noData, changeable at runtime)
- If the user has hidden all of the columns in the personalization settings, the following text is shown:
Right now, there are no visible columns in the table. Please select the columns you need in the table settings.
This text cannot be changed.
Errors and Warnings
To indicate that the table contains items with errors or warnings, the smart table can show a message strip above the table (aggregation:
dataStateIndicator). On the message strip, information about errors or warnings is provided, as well as the possibility to filter down the table to the corresponding rows. When issues are solved or when new issues appear, the message strip is updated accordingly.
For details on displaying errors, warnings, and other messages, see Message Handling.
The smart table acts exactly like the embedded controls. For details see:
- Toolbar Overview
- Responsive Table via auto pop-in mode
You can use the
UI.Importanceannotation to influence the priority of each column.
You can provide a Show Details button to let users show/hide columns with low importance (property:
- 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.
- 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.
The following properties are available for
- The property:
toolbarStyleClassis deprecated. Do not use it.
- The property:
useOnlyOneSolidToolbaris deprecated. Do not use it.
Elements and Controls
- Smart Table (SAPUI5 samples)
- Smart Table (SAPUI5 API reference)
- Smart Table (Developer Guide)
- Toolbar (SAPUI5 samples)
- Smart Field (SAPUI5 samples)
- Smart Field (SAPUI5 API reference)
- Smart Field (SAPUI5 Developer Guide)
- Variant Management (SAPUI5 samples)
- P13n Dialog (SAPUI5 samples)
- P13n Dialog (SAPUI5 API reference)
- Spreadsheet Export (SAPUI5 samples)
- Spreadsheet Export (Developer Guide)