Smart Table

The sap.ui.comp.smarttable.SmartTable control is used to create different types of tables based on OData metadata. The control allows the user to define personalized table settings.

The frequently asked questions section below aims at answering some basic questions that you might have when using the SmartTable control.

Note The code samples in this section reflect examples of possible use cases and might not always be suitable for your purposes. Therefore, we recommend that you do not copy and use them directly.

Overview

The SmartTable control is a wrapper control around any SAPUI5 table. The control analyzes the $metadata document of an OData service and renders a table for a specific entitySet.

The control allows the consuming application to build list patterns based on OData services in an efficient and consistent way and thus makes it easy for the user to create tables without much effort. For example, the control enables the automatic creation of columns.

The consuming application can overwrite the OData default information. The SmartTable control offers you additional built-in features, such as a row count and an export to a spreadsheet application.

The control is closely linked to the following controls:

VariantManagement
SmartFilterBar
P13nDialog

The control also supports the popover of the SmartLink control.

For more information about the various smart controls, see sap.ui.comp.

Details

When using SmartTable with an internal responsive table, you can set the demandPopin property to true. This property renders columns that exceed the space available on the screen by displaying popins.

SmartTable checks the custom data section for the columns and reads the columnIndex attribute to determine when the columns that are defined in the XML view are rendered.

If you want to show and follow navigationProperty fields for EntityType, the SmartTable control automatically performs a $expandoperation for these fields.

FAQ

Question

How can I enable personalization for columns I add in the XML view in the SmartTable control?

Answer

You can specify custom data for the personalization of the columns in your table as shown in the examples.

Example 1 for a normal aggregation:

<table:Column id="Ledger" hAlign="Left" minScreenWidth="Tablet" demandPopin="true">
	<table:customData>
		<core:CustomData key="p13nData"
		   value='\{"columnKey": "Ledger", "leadingProperty":"Ledger",
		    "additionalProperty":"LedgerName""sortProperty": "Ledger",
		    "filterProperty": "Ledger", "type":"numeric"}' />
	</table:customData>
	<Label text="Ledger" />
	<table:template>
		<Text text="{Ledger}" />
	</table:template>
</table:Column>

To use the SAPUI5 shortcut notation, add the following namespace part in the XML view:

xmlns:customData="http://schemas.sap.com/sapui5/extension/sap.ui.core.CustomData/1"

Example 2 for use of the shortcut notation:

<table:Column id="CompanyCode" hAlign="Left" minScreenWidth="Tablet" demandPopin="true"
	 customData:p13nData='\{"columnKey": "CompanyCode", "leadingProperty":"CompanyCode", "additionalProperty":"CompanyName","sortProperty": "CompanyCode", "filterProperty": "CompanyCode", "type":"numeric", "maxLength":"4"}'>
	<Label text="Company Code" />
	<table:template>
		<Text text="{CompanyCode}" />
	</table:template>
</table:Column>

In the p13nData object you can specify the following properties:

columnKey
A unique key used to save, retrieve, or apply personalization for a column.
leadingProperty
Retrieves data for the OData property specified here from the backend system when the column is made visible.

OData model property name must be used.
additionalProperty
Property has to be requested if a column is visible.

OData model property name must be used.

Multiple property names can be specified here as comma-separated values (CSV).
sortProperty
Sorts the table based on the column specified.

OData model property name must be used.

This property is similar to the table column property.
filterProperty
Filters the table with the condition that has been defined.

OData model property name must be used.

This property is similar to the table column property.
type
Determines the type of a control; its value can be either date, numeric, or empty string. The control will be adapted according to the type.
maxLength
Numeric value to restrict number of entries in input fields
precision
Numeric value for precision
scale
Numeric value for scale

Note Some properties that also exist in a table, for example, in sortProperty, will take precedence if specified in both places.

Question

Why do I not see data for my manually added column in the XML view? And why do I get an error "Select at least one column to perform the search" even though I have added several columns manually to the sap.m.Table inside the SmartTable control?

Answer

You need to specify custom data with at least one leadingProperty for the table columns without a leadingProperty available in the control itself so the SmartTable control can fetch the data correctly.

<Column> 
    <customData> 
          <core:CustomData key="p13nData" value='\{"columnKey":"Id","leadingProperty": "Id","sortProperty": "Id","filterProperty": "Id"}'/>
     </customData>
    <Text text="Sales Order" /> 
</Column>

Without this, the SmartTable control cannot recognize the column.

Question

How can I define columns with my own style, for example, using the formatting or the controls I require, in a responsive SmartTable control (tableType="ResponsiveTable")?

Answer

For the sap.m.Table/ResponsiveTable, you need to provide a corresponding ColumnListItem in the items aggregation in addition to the columns, as you would when using this SAPUI5 table on its own.

<smartTable:SmartTable entitySet="Items"..>
	<Table>
	      <!-- Columns must have unique IDs if table personalization service is used -->
	      <columns>
		 <Column id="Name" width="auto" minScreenWidth="Tablet" hAlign="Left" visible="false"
		     customData:p13nData='\{"leadingProperty":"Name", "columnKey":"Name", "sortProperty":"Name", "type":"numeric"\}'>
		     <header>
			<Label text="{/#Item/Name/@sap:label}"/> 
		     </header>
		 </Column>    
	     </columns> 
	     <ColumnListItem id="columnListItem" vAlign="Middle" type="Navigation" press="onItemPressed">
		<cells>
	             <Text text="{path:'Name', formatter:'my.own.formatter.functionName'}" maxLines="2"... />
	        </cells>
	     </ColumnListItem>
      </Table>
 </smartTable:SmartTable>

The sap.m.Table uses the columns aggregation for the header and the items aggregation containing ColumnListItem with cells for the template control that is cloned for each row in the table.

Note For any supported SAPUI5 table, you can add custom columns in the XML view along with the required customData for the column.

Question

How do I use the SmartField control in combination with the SmartTable control? And how can I make use of metadata and field controls to manage the state of editable fields in my table?

Answer

For editing scenarios with backend metadata and field controls, it is recommended to use the SmartField control along with the SmartTable control. You can have the SmartTable automatically create SmartField controls using the following code:

<smartTable:SmartTable id="ItemsST" entitySet="Items" customData:useSmartField="true"...>

To make this work, the customData namespace has to be defined correctly in the XML view to enable SAPUI5 shortcut notation for custom data aggregations: xmlns:customData="http://schemas.sap.com/sapui5/extension/sap.ui.core.CustomData/1".

Question

How do I format the group headers shown in SmartTable of type ResponsiveTable? And why is a technical key shown instead of a description when grouping is done in SmartTable of type ResponsiveTable?

Answer

Grouping in ResponsiveTable is done by sorting table entries. You can define your own formatting for the group title in ResponsiveTable by specifying a group function for the first sorter. For more information on how this can be done, see the code sample in the Explored app in the Demo Kit.

When using the SmartTable control, you can use the beforeRebindTable event and get available sorters using the bindingParams (event parameter). Check if the first sorter there has a group.

onBeforeRebindTable: function(oEvent) {
	var mBindingParams = oEvent.getParameter("bindingParams");
	var oSorter = mBindingParams.sorter[0];
 //Check if sorter is for Grouping
	if(oSorter.vGroup){

There are two options. The first option looks like this:

//Replace the Group function
		oSorter.fnGroup = this.mGroupFunctions[oSorter.sPath];

You can also do the following:

//Replace the Grouping sorter itself		
		mBindingParams.sorter[0] = new Sorter(oSorter.sPath, bDescending, this.mGroupFunctions[oSorter.sPath]);
 }

For more information on how this.mGroupFunction has to be implemented, see the code sample in the Explored app in the Demo Kit.

You can replace group functions for the sorter or the sorter itself with the ones you have defined (with own formatter for grouping based on the property) if the sorter is used for grouping.

Question

How do I create and pass a search query ($search="foo") when using the SmartTable control?

Answer

Use the beforeRebindTable event and implement this manually.

onBeforeRebindTable: function(oEvent) {         var
        mBindingParams = oEvent.getParameter( "bindingParams" );       
		mBindingParams.parameters[ "custom" ] =
        {                        "search-focus" :
        sBasicSearchFieldName, //  the name of the search
        field                        "search" :
        sBasicSearchText //  the search text
        itself!                };  }

This will then be used internally when creating the table binding.

Note In the same way, you can also add any custom URL parameters or use this event to add OData $expand parameters: Instead of "custom", use "expand" as shown in the example above.

Question

How do I get data for custom columns (icons, formatters etc.) that are not present in the columns/binding (select = 'ColA,ColB,foo,bar') of the SmartTable control?

Answer

Use the beforeRebindTable event and implement this manually.

onBeforeRebindTable:  function  (oEvent) {  
        var   oBindingParams = oEvent.getParameter( "bindingParams" );
         if  (oBindingParams.parameters.select.search( "SomeIconCode1" ) < 0) {
                             oBindingParams.parameters.select +=  ",SomeIconCode1" ;
         }
      if (oBindingParams.parameters.select.search( "SomeIconCode2" ) < 0) { 
                             oBindingParams.parameters.select +=  ",SomeIconCode2" ;
         } . . .

This will then be used internally when creating the table binding.

Note If only one property is needed for a given column, you can also use additionalProperty in customData as already mentioned instead of the event-based approach as described here.

Note For an AnalyticalTable control or AnalyticalBinding, you have to use a dummy column (visible="false") with the leadingProperty you require and the set attribute inResult="true" instead.

Question

I would like to pass my own custom sorters, filters, and binding parameters when binding the table data in the SmartTable control. How do I do this?

And how can I have my own binding implementation for the SmartTable control?

Answer

You can modify the array of filters before binding is triggered in the SmartTable control by listening to the beforeRebindTable event.

To enable this, your code in the XML view should look like this:

<smartTable:SmartTable entitySet="LineItemsSet" beforeRebindTable="onBeforeRebindTable"…

You can now get the list of filters and sorters to be used in table binding using the following:

...
onBeforeRebindTable: function(oEvent) {
              var mBindingParams = oEvent.getParameter("bindingParams");
              var aFilters = mBindingParams.filters

With this, you need to set back the value to mBindingParams.filters, and you can pass a new filter array as well.

Note

In some exceptional cases, you can set mBindingParams.preventTableBind="true" to prevent table binding from taking place (optional) and do the binding at a later point in time. This is shown in the following method:

someMethod: function() {
           //get the smartTable and call the method rebindTable()
           oSmartTable.rebindTable();
       }
...

Note If you would like to trigger the binding manually, use the rebindTable method of the SmartTable control and do not use bindRows in the underlying table.

Note For a custom multi-filter scenario: If you want to pass multi-filters (filters combined with AND/OR explicitly) in your custom implementation, the SAPUI5 default logic in the core classes combines multiple multi-filters with an OR by default. If you would like to use AND in combination with the multi-filters returned in the beforeRebindTable event of the SmartTable control (if a filter is set in SmartFilter) and your own MultiFilter, you have to replace the filters in the beforeRebindTable event with an explicit AND MultiFilter. There is currently no way to combine multiple multi-filters in the SmartTable control itself. You as the consumer of the control have to make sure you combine these multi-filters yourself by checking first if any internal multi-filters exist. You also have to ensure that the internal multi-filter is added first in the array of filters present in the beforeRebindTable event.

onBeforeRebindTable: function(e) {  
                   var b = e.getParameter("bindingParams"); 
                    var aDateFilters = [new sap.ui.model.Filter("BindingPeriodValidityEndDate",sap.ui.model.FilterOperator.LE,d), new sap.ui.model.Filter("BindingPeriodValidityEndDate",sap.ui.model.FilterOperator.GT, null).....];
                    var oOwnMultiFilter = new sap.ui.model.Filter(aDateFilters, true);

                    //Special handling for multiple multi-filters
                    if (b.filters[0] && b.filters[0].aFilters) {
                            var oSmartTableMultiFilter = b.filters[0];
                            // if an internal multi-filter exists then combine custom multi-filters and internal multi-filters with an AND
                            b.filters[0] = new sap.ui.model.Filter([oSmartTableMultiFilter, oOwnMultiFilter], true);
                     } else {
                          b.filters.push(oOwnMultiFilter);
                    }
}

Question

How do I add custom toolbar buttons in the SmartTable control?

Answer

You can do this using the customToolbar aggregation, as shown below:

<smartTable:SmartTable id="ItemsST" entitySet="Items" ...  
        <smartTable:customToolbar> 
                <OverflowToolbar design="Transparent"> 
                        <ToolbarSpacer/> 
                        <Button text="Test"/> 
                        <Button text="Click me!"/> 
               </OverflowToolbar> 
       </smartTable:customToolbar>

Note We recommend to use OverflowToolbar instead of Toolbar, as shown above, to make the toolbar responsive.

Question

How do I fetch data from navigationProperty (or association entities) using the SmartTable control?

Answer

SmartTable provides a tableBindingPath property in addition to entitySet, which can be used to specify a navigation property path, for example, SalesOrder(123)/toItems.

Note For an AnalyticalTable control or AnalyticalBinding, you might have to pass entitySet in bindingParameters using the beforeRebindTable event. This is necessary if the entitySet path does not conform to the one that is checked internally by AnalyticalBinding, for example, in the beforeRebindTable event, as shown here:

var mBindingParams = oEvent.getParameter("bindingParams");

mBindingParams.parameters.entitySet = "NameOfEntitySet";