Configure table layouts and columns

Purpose

Create a table output that shows asset structures with further asset details. The "Table" asset defines the overall layout of the table and the asset properties shown in each of its columns. It does not contain or output any table data. The table output can be used in different assets and contexts. Users can select the table output in a table or report widget.

Context

• To be assigned to a "Table" widget

• To be assigned to a "Report" widget

• censhare PIM

Available since censhare 2017.5.

Prerequisites

You need basic understanding of the censhare data model as well as of the concepts of asset traits and asset properties. The configuration does not require working in the censhare Admin client. You should have access to the Admin Client, though, in order to look up the trait keys and property keys in the Master data for the used features.

Introduction

censhare provides several widgets that display asset lists and asset details in a table layout. Table layout and table content are defined separately in censhare. This has the advantage that you can re-use the same table layout in different contexts.

Basic usage

A table layout consists of a "Table" asset, where the basic layout (width and height), as well as the columns and pivot columns, are defined. Each row in the table presents information about one asset. Columns can display any asset properties. A table could show, for example, all "Product items" related to the currently displayed "Product" asset. In this table, each row would present information about a product item, for example, color, size and price. For each of these properties, a "Table column" asset is defined and referenced in the "Table" asset.

Each table column contains an asset property or transformation data. The table layout (column order) is configured in a table asset. There, the respective column assets are assigned. This article describes, how "Table" and "Column" assets are configured which can then be used in a "Table" or "Report" widget.

Advanced usage (Pivot tables)

The more items and dimensions a table shows, the more difficult can it be for a user to find relevant, aggregated information. Therefore, censhare gives you the option to create pivot tables. Pivot tables summarize and group items by selecting the desired dimensions.

In censhare, you can use any column as pivot column. A pivot column looks for distinct values in it and groups them. The pivot columns are either displayed horizontally or vertically. For this purpose, the table asset contains the two widgets "Pivot column X" and "Pivot column Y".

Table configuration

The overall table configuration is stored in a “Table” asset. To add a new table, proceed as follows:

1. Create a "Module / Table" asset and enter a name, for example, "Product items table".

2. Open the "Properties" widget and set the row height and table height. If you leave these fields empty, censhare adjusts the table automatically.

3. Create a "Table column" asset for each asset detail to be shown in the table. For example, create a column to display the asset description and another column to display the dimensions feature group. Read more about the configuration of this asset in the section "Table column configuration".

4. In the table asset, go to the "Columns" widget and assign the columns created in the previous step. You can sort the columns by clicking the up/down buttons in each column row.

5. If you want to create a pivot table, add the columns for data aggregation in the widgets "Pivot columns X" or "Pivot columns Y", respectively.

6. Save your changes.

Table column configuration

Table columns are configured in order to display asset properties. The configuration is stored in a "Table column" asset. The properties to be displayed in a column can be addressed in different ways. To learn more about this, see the “Examples” section.

To configure a table column, carry out the following steps:

1. Create a "Module / Table/ Table column" asset and enter a name, for example "Description", "Dimension" or "Modified by".

2. Define the display options in the “Properties” widget:

   Field	Description
   Key	Enter a key for the column. This key can be used to address the column from other assets.
   Type	Select a data value type for the column. If "Template" is selected, an additional field "Template" shows up at the bottom.
   Frozen	Selecting this field excludes the column from horizontal scrolling and fixes its position.
   Horizontal alignment	Select one of the values "Left", "Center" or "Right".
   Width in pixels	Define here the respective values for the column width.
   Width minimal in pixels
   Width maximal in pixels
   Template	This field is only shown if you select “Template” in the “Type” field. A template consists of a re-usable snippet that outputs asset data from the context asset. The context asset in a table is the current table row. The simplest usage of a template is a placeholder string. This string must point to the asset trait and key of the property to be shown in the column. See the “Examples” section for further details.

3. If the data to be displayed in this is retrieved from a view snippet or a macro, assign the respective asset in the “Macro” or “View snippet” widget. Learn more about these options in the “Example” section.

4. You can assign the column to a table in the widget “Assigned to”, or in the table asset in the widget “Columns”. Note that column sorting can only be done in the column widget.

5. Save the changes.

Examples

There are different ways to query the data you want to display in a table column. A table column represents a query and/or transformation of asset metadata. Each table row represents a context asset. For each table row, the query and/or transformation is carried out and the output is written in the table cell. See the following examples to understand the basic concept:

Templates

A template consists of a re-usable snippet that outputs asset data from the context asset. The context asset in a table is the current table row. If you select "Template" in the "Type" field, a text field is shown at the bottom of the dialog. You can enter two types of snippets in this field:

Using a placeholder

With a placeholder, you can address any asset detail in the following way:

<span>{{data.traits.display.description}}</span>

This placeholder snippet renders the asset description inside a "<span>" tag. The placeholder string a kind of variable that accesses the data of the respective asset whose data are shown in the column. It is built using the "Trait key" and "Property key" of the asset property. For more information read the article "Creating a new feature".

Using the "cs-item-renderer" element

To address asset details and provide additional rendering functionality, use the "<cs-item-renderer>" tag:

<cs-item-renderer 
    flavor="'csAssetListItemRendererWidgetmxn_1rows'" 
    item="data">
</cs-item-renderer>

The "<cs-item-renderer>" element uses the "flavor" attribute to output data in a predefined list view from the context asset. This example renders the asset name and icon from the "Widget list small" view. 

Using "View" snippets

As an alternative to the way described in the previous example, you can create a “Workspace view snippet” asset and store the template in this asset. View snippets are reusable in other contexts. See the article "Configuring how assets are displayed in lists" for a more detailed introduction on view snippets.

Create and configure a view snippet as follows:

1. Create an asset of the type “Module / Workspace / Workspace view / Workspace view snippet”.

2. Enter a name and resource key.

3. Select the fields “Enabled” and “In cached tables”.

4. Click OK to save.

5. Create a file with the desired placeholder or cs-item-renderer and upload the file to the asset using the “Files” widget. The uploaded file will be shown there as “Master file”.

6. Go to the “Table column” asset and assign the view snippet in the respective widget.

Using macros

Macros allow further transformation to the data retrieved from an asset and to be displayed in a table column. For example, you can add conditions and search over child or parent assets of the context asset. 

Create and configure macros as follows:

1. Create an asset of the type “Module / Macro”.

2. Enter a name and resource key.

3. Select the fields “Enabled” and “In cached tables”.

4. Click OK to save.

5. Create an XSL file with the data output you want to display in the table. The following example can be used on a product asset page. The table shows child product items. This macro is used in the column “Dimensions”. It retrieves the width, height and depth from an asset and creates an output as dimensions in the pattern “Width x Height x Depth”. If the queried asset does not contain dimensions, the macro returns the dimensions of the parent asset:

   <?xml version="1.0" encoding="UTF-8"?>
   <xsl:stylesheet version="2.0"
     xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
     xmlns:xi="http://www.w3.org/2001/XInclude"
     xmlns:xs="http://www.w3.org/2001/XMLSchema"
     xmlns:my="http://www.censhare.com/my">
   
   <!-- returns dimensions (width x height x depth) of context asset or rootAsset -->
   
     <!-- output -->
     <xsl:output method="text" omit-xml-declaration="yes" indent="no"/>
   
   <!-- params -->
     <xsl:param name="rootAsset"/>
     <xsl:param name="language"/>
   
   <!-- test if context asset has a width and, if not, select the parent asset -->
     <xsl:template match="asset">
       <xsl:variable 
                   name="featureKey" 
                   select="'censhare:product.width'"/>
       <xsl:choose>
         <xsl:when 
                    test="asset_feature[@feature=$featureKey]">
           <xsl:value-of select="my:getDimensions(.)"/>
         </xsl:when>
         <xsl:when 
                    test="$rootAsset and $rootAsset/asset_feature[@feature=$featureKey]">
           <xsl:value-of select="my:getDimensions($rootAsset)"/>
         </xsl:when>
       </xsl:choose>
     </xsl:template>
   
   <!-- get product feature IDs of given asset and all product category parent related assets -->
     <xsl:function name="my:getDimensions" as="xs:string">
       <xsl:param name="asset" as="element(asset)"/>
       <xsl:variable 
                   name="widthValue" 
                   select="$asset/asset_feature[@feature='censhare:product.width']/@value_double"/>
       <xsl:variable 
                   name="heightValue" 
                   select="$asset/asset_feature[@feature='censhare:product.height']/@value_double"/>
       <xsl:variable 
                   name="depthValue" 
                   select="$asset/asset_feature[@feature='censhare:product.depth']/@value_double"/>
       <xsl:choose>
         <xsl:when test="$language">
           <xsl:value-of select="string-join((string-join((if ($widthValue) 
                       then cs:localized-format-number($language, $widthValue, '#,###0.0') 
                       else (), 
                       if ($heightValue) 
                       then cs:localized-format-number($language, $heightValue, '#,###0.0') 
                       else (), 
                       if ($depthValue) 
                       then cs:localized-format-number($language, $depthValue, '#,###0.0') 
                       else ()),' x '), $asset/asset_feature[@feature='censhare:product.width']/@value_unit), ' ')"/>
         </xsl:when>
         <xsl:otherwise>
           <xsl:value-of select="string-join((string-join((if ($widthValue) 
                       then cs:format-number($widthValue, '#,###0.0') 
                       else (), 
                       if ($heightValue) 
                       then cs:format-number($heightValue, '#,###0.0') 
                       else (), 
                       if ($depthValue) 
                       then cs:format-number($depthValue, '#,###0.0') 
                       else ()),' x '), $asset/asset_feature[@feature='censhare:product.width']/@value_unit), ' ')"/>
         </xsl:otherwise>
       </xsl:choose>
     </xsl:function>
   
   </xsl:stylesheet>

   CODE

6. Upload the XSL file to the macro asset using the “Files” widget. The uploaded file will be shown there as “Master file”.

7. Go to the “Table column” asset and assign the macro in the respective widget.

Next steps

• Assign the table asset in a table widget to display a tree structure of assets with the asset properties defined in this table. Read more in the article “Configuring the table widget”.

• Assign the table asset in a report widget.