Intro
The smart table creates a responsive table, grid table, tree table, or analytical table based on an OData (Open Data Protocol) service and its annotations. The table toolbar comes with additional built-in features, such as personalization, export to spreadsheet, and variant management.
When to Use
Use the smart table if:
- You use an OData service for your app (OData version 2 only).
- The feature set of the smart table fits for your app. In this case, the smart table is faster to implement.
- You need more than one of the major features of the smart table. Otherwise, you might not benefit from a shorter implementation time. For example, if you just need the export to spreadsheet feature, creating a responsive table directly is usually faster than using the smart table.
Do not use the smart table if:
- You use a different technology to OData version 2. Use the corresponding table control directly.
- You need more flexibility in the content design, such as several different row templates or less complex personalization features. Use the responsive table directly.
- You do not have complex data. Another control like a select, combo box, list, grid list, tree, or smart list might do the job better.
- You have very complex data. Did you check the chart?
- Users need to switch between a chart and table. The smart table is not designed to work inside an existing chart container. In this case, use either the smart chart or the corresponding table directly.
- You need to layout different controls in a table-like grid. Use a flexible grid instead.
- You need to layout different input fields with labels. Use a form, simple form, or smart form.
Components
The smart table consists of a table toolbar (1), an infobar (2), and a table (3).
Table Toolbar
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
Item Counter
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
Show Details / Hide Details
View Settings
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.
- 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.
Group
Group settings are only available for the responsive table (all columns, one level only) and the analytical table (dimension columns only, multiple levels).
The following text is usually shown on the group header:
[Label of the grouped column]: [Grouping value]
Within the analytical table, the grouped column remains visible by default if it is grouped using the P13n Dialog. The column is hidden if it is grouped using the column header menu.
Column Settings
Export to Spreadsheet
-
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.
-
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.
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
- 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
- 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
- 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
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).
-
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).
- 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.
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.
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.
- 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).
- 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.
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.
- 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.
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).
-
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.
Clicking the column header reveals sort and filter options (responsive 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:
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).
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).
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.
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.
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.
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.
Related Links
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)
- Export to Spreadsheet (guidelines)
- Action Placement (guidelines)
Implementation
- 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)
Visual Design
- Table (visual design specification)
- Toolbar (visual design specification)
- Variant Management (visual design specification)
- P13n Dialog (visual design specification)