Configure Table widgets

The Table widget creates a hierarchical table view of asset structures.

The minimum configuration requires a table asset, a root query and a child query. It is also possible to define, whether users can add and remove relations in each level of the table. This article describes the Table widget configuration.

Target groups

Users (Personal workspace configuration)
Administrators (Workspace XML configuration)

Context

The Table widget can be used with any asset type. censhare provides preconfigured table and query assets to be used with Product assets, Product category assets, and User lists.

Prerequisites

You must be familiar with the key concepts of asset relations and references. You must also be familiar with the asset structures used in your system.

Introduction

When opening an asset page in censhare Web, users want to see immediately which asset structures this asset is part of. In other cases, user wish to browse hierarchical lists of assets in a wider context. In these structures, they want to have the possibility to add or remove asset relations.

The table widget offers this functionality. Its configuration is very flexible, since the displayed asset structures, the asset details and the relations to be added or removed are configured separately. This article describes the configuration of the table widget in censhare Web and how to add an XML configuration.

Before starting a configuration, read also the following section to learn more about the basic concepts of the table widget.

Basic concepts

The table widget displays hierarchical asset structures as a table. An asset structure consists of various assets that are related to each other. censhare represents these relationships as asset relations or asset references.

The structure shown in the widget represents only a small part of the overall asset structure of censhare. Therefore, you need to define the top-level assets shown in the table. This is done by a root query. This query outputs the top-level elements shown in the table. Basically, there are two options: The asset itself can be defined as root. this is the asset page, where the widget is placed - The asset is called the context asset. In this case, there is only one root element, since each asset is unique. The second option is to have root query, for example for a certain asset type. For example, all Product category assets. In this case, there is no single root element but multiple. In this use case, any asset that matches the search criteria is a root element.

The queries that you use in the table widget are configured outside the widget in a Module / Search/ Transformation asset. This asset type uses XSLT to search and create an output of the search results. Search criteria are defined in the XSLT master file of this asset.

In order to create a table output in the widget, you can define, which asset details are displayed in each column. The table is configured outside the widget in a Table asset. In the Table asset itself, you assign table columns. Each table column displays one asset property.

The widget displays the configured assets structures and also provides functionality to manage assets relations. To create new asset relations, users can add assets to the list. Existing relations can be removed. The configuration of the Add relation dialog is done separately in the widget configuration. You can configure the dialog for each asset type and relation type individually. Each relation dialog can be configured in both directions: from child assets to parent assets or from parent assets to child assets. Likewise, asset references can be configured in feature direction or feature-reverse. We recommend proper planning before you configure the relation management.

Example: A Table widget displays all product categories as root elements, followed by child product categories, products, and product items (standard structure of censhare PIM). The table relation management can be configured as follows:

(1) Add product items to a product: This creates a user.product-item.relation. The product asset is the parent, the product item asset the child.

(2) Add a product category to a product: This creates a product category reference in feature direction in the product asset.

However, from the user perspective, it can be more convenient and logical to add products to a product category. The table widget can be configured accordingly:

(3) Add products to a product category: This creates the same product category reference in a product asset as in (2). But now the reference is created feature-reverse starting from the product category.

Widget configuration

To configure a Table widget, place the widget on the desired tab on an asset page. This configuration applies to your personal workspace. You can either create your workspace as needed and then create a workspace template from it. For more information, see Workspace templates with resource events.

Proceed as follows:

Start the developer mode in censhare Web.
Open the asset where you want to place the table widget. Note: The widget is displayed on all asset pages of this asset type.
Open the desired tab or add a new tab.
Open page-actions menu and select Add widget type. In the dialog, select Table widget.
Place the widget and adjust the size.
In the widget header, click
and select Configure widget. The configuration dialog opens:

General configuration

In the General Configuration pane, you can define how the widget and list items in the widget are displayed on the asset page. Please read the article "General Widget Configuration" for more information.

Table configuration

In this section, you configure the asset structure displayed in the widget.

Field	Mandatory	Description
Table	Yes	Select a table asset that provides the columns and asset details displayed in the widget. Preconfigured tables are available in the censhare standard configuration. You can create custom tables to be used in table widgets. For more information read the article Create tables using table and column assets.
Transformation toolbar	No	Select a toolbar (XSLT transformation asset) to be displayed in the table header. Toolbars provide additional controls to filter assets or select the displayed language. Any asset property can be configured as filter criteria. For example, you can add a toolbar that provides a language selector. By clicking on a language, users can change the displayed name and other localized asset details. Preconfigured toolbar transformations are available in the censhare standard configuration. To create a new toolbar transformation, read the article Create toolbar transformations.
Root query	Yes	Select a root query to define the top-level node of the displayed asset structure. Assets of the type “Module / Search / Transformation” store the query. This asset type uses XSLT to query and output assets. The top-level node can be any asset type, for example "Products". A special case of the root query is the "Context asset" which sets the root node to the current asset itself. For more information read the article Configure root and child queries for the table widget. (1,2)
Child query	No	Select a child query to define which asset structures are displayed below each top-level node. The query executes a context query for each top-level node. Child queries are not restricted to direct child assets, but can expand to deeper hierarchical levels. If not set, only the root query will be used. For more information read the article Configure root and child queries for the table widget. (1,2)
Allow adding top elements	No	If you select this option, you need to configure at least one matching relation in the following section. Also, this option is only working with unique root elements, for example the "Context asset". Users can then add elements to the top-level of the table. To do this, an additional "+"-Button is shown in the table header when moving the cursor over it. (3)

Notes:

(1) Root and child query must match. The search performed in the child query only throws a result if the queried asset type is related to the assets from the root query. For example, select Root product categories, in the root query and Media related child assets in the child query. In this combination, the table shows only top-level items. This is because there are no child assets assigned as "Media" in product categories. If you select All child assets instead, the table also shows second-level product categories assigned to the top-level categories. However, the list does not show any products within the categories. Products are not assigned in a child relation to product categories. Product categories are referenced as children of products. Therefore, select Child product categories in the child query field. The table now shows the complete asset structure with product categories, products and product items.

(2) You can add a grouping parameter to the queries in order to group the assets by this parameter. This creates a flat list of assets with intersecting header rows for each value of the grouping parameter. For example, the root query lists Products and the child query all Product items of a product. Product items are available in different colors and sizes. You can group them by either size or color using the respective grouping parameter.

(3) This option is only available if the table widget is placed on an asset page. It is not available in table widgets on static pages.

Table relation configuration

In this section, select which relation types users can add or remove in the widget.

The configuration is stored in a Configuration asset. In this asset, relation type, direction, source, and target asset type are defined for each relation configuration.

In the widget configuration, select one or more relation configurations to be applied in the widget. Be aware that this configuration has to be coherent with the table configuration.

For example, if the table outputs a list of product categories, products and product items, you can configure the following relations here:

Add or remove a product category to another product category
(for example, building a product category hierarchy).
Add a product to a product category
Add a product category to a product
Add a product item to a product
Add a product to a product item

Each relation type and direction requires a separate table relation configuration. For more details, see Table relation configuration asset.

Workspace XML configuration

As a system administrator, you can create widget configurations and add them to the XML file of a workspace template. For more information, see Workspace templates with XML files.

The following code snippet shows the configuration schema:

CODE

<widget kind="csTableWidget">
 <configuration xmlns:censhare="http://www.censhare.com/xml/3.0.0/censhare"> 
  <tableId censhare:_annotation.datatype="string">[TABLE.ASSET.RESOURCE.KEY]</tableId>
  <toolbarTransformationKey>[TOOLBAR.TRANSFORMATION.RESOURCE.KEY]</toolbarTransformationKey>
  <rootQueryId censhare:_annotation.datatype="string">[ROOT.QUERY.RESOURCE.KEY]</rootQueryId>
  <childQueryId censhare:_annotation.datatype="string">[CHILD.QUERY.RESOURCE.KEY]</childQueryId>
  <relationConfigurations
   <_object_ 
       display_value="[NAME]"  
       value="[RELATION.CONFIGURATION.RESOURCE.KEY]" />
  <isPossibleToAddRootElements censhare:_annotation.datatype="boolean">[TRUE|FALSE]</isPossibleToAddRootElements>
 </configuration>
</widget>

Remarks

Element / attribute	Mandatory	Description
<widget/>	yes	References the widget this configuration is based on. For further attributes and elements see Generic widget configuration.
kind	yes	Select "csTableWidget".
<configuration/>	yes	Contains the configuration of the widget. The following elements show only the multi-relation configuration.
<tableId/>	yes	Select the table asset for this table.
<toolbarTransformationKey/>	no
<rootQueryId/>	yes	Select the root query asset for the top-level items.
<childQueryId/>	no	Select the child query asset for the context items.
<relationConfigurations/>	no	To allow users to add assets to the context items of the table, add this element.
<_object_/>	no	For each relation type that can be added at context level, add an <_object_/> element inside the <relationConfigurations/>.
value	no	Select the relations asset configuration.
display_value	no	The display value is shown in the table relation dialog.
<isPossibleToAddRootElements/>	no	To allow users to add root level items, set to "true"