Skip to main content
Skip table of contents

Configure root and child queries for tables

In the table widget, you define a root and child query. These determine the asset tree displayed in the table. This article gives a basic understanding of how these queries are configured and some examples.

With the configuration of the root and the child query, you determine which assets and asset structures the table widget shows.

Context

  • Any asset page with a table widget

Prerequisites

As an administrator, you should be familiar with the query syntax of censhare and XSL transformations.

Introduction

Search queries can be represented and stored in censhare in an XSLT script. The table widget configuration uses these in the root query and child query. The table widget shows a hierarchical table of assets. The root query and child query create a hierarchical asset list that populates the table. The table columns define, which asset properties are shown for each asset.

The Table widget performs a two stage query (root and child query). The two queries create a hierarchical asset structure that is output in the table. The root query determines the root nodes of the asset structure. The root nodes can be any asset type. A special case of the root query is the "Context asset" which sets the root node to the current asset itself. In this case, only one root node exists, since every asset in censhare is unique. Otherwise, each asset that the root query gives back serves as context asset to the child query. For example, the root query finds all “Product category” assets. In the second stage, the widget performs the child query in each product category.

The child query searches direct children and deeper hierarchical structures of the top level nodes. The child query is executed as a context query. All results relate to the respective top level node. Therefore, root and child queries must match in order to produce the desired result. For example, the root query gives back all top-level product categories. The child query must search asset types that are related to a product category. Otherwise, the child query shows no results.

The child query is not restricted to direct child assets and can search in any direction (parent/child direction or feature/feature-reverse direction, respectively). The example below illustrates this. In this example, the child query searches for:

  • Product categories that have a parent product category,

  • Products with a product category reference,

  • Product items with a parent product relation.

This query is executed for each context node. That means, only assets related to the root asset of each context node will be shown. The result is an asset structure that shows:

  • Root product category

    • Child product categories

      • Products

        • Product items

Note: The child query is optional in a table widget. If you configure a table widget with a root query only, the result is a flat, non-hierarchical table showing all root node matches.

Add a new query

To add a new query, proceed as follows:

  1. Create a “Module / Search / Transformation” asset.

  2. Add a name and a resource key.

  3. Select the fields "Enabled" and "In cached tables".

  4. Click OK to save.

  5. Upload an XSL script as master file to the asset. This script contains the query definition. See the following section “Examples” for some example queries.

Examples and recipes

The following examples aim to give a better understanding of the concept of the root and child queries and how both must match in order to produce the desired result.

  • Setting the current asset as root node

  • Looking up all child assets with a user relation

  • Query all top-level product categories

  • Query all 2nd-level product categories, products and product items

  • Grouping the assets of a query 

Setting the current asset as root node

This search can be set in the root query. It sets the currently opened asset (i.e. the asset page, where the table widget is placed) as root node and context for the child query:

XML
<xsl:stylesheet version="2.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

  <xsl:param name="context-id"/>

  <!-- Get context asset -->
  <xsl:template match="/">
    <query>
        <condition name="censhare:asset.id" 
                   op="=" 
                   value="{$context-id}"/>
    </query>
  </xsl:template>
</xsl:stylesheet>


Looking up all child assets with a user relation

This search looks up all child assets of the given context that have a „user.“ relation. These are all relation types that a user can create and are no system relations. Read more about relation types and relation type hierarchies in the article “Configure asset relations and references”.

This is a rather generic query that works in any context. It can thus be defined as child query in combination with any root query:

XML
<xsl:stylesheet version="2.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  
  <!-- parameters -->
  <xsl:param name="context-id"/>

  <!-- search all user.* related child assets sorted by name -->
  <xsl:template match="/">
    <!-- query -->
    <query>
      <and>
        <relation direction="parent" 
                  type="user.*">
          <target>
            <and>
              <condition name="censhare:asset.id" 
                         op="=" 
                         value="{$context-id}"/>
            </and>
          </target>
        </relation>
      </and>
      <sortorders>
        <grouping mode="none"/>
        <order ascending="true" 
               by="censhare:asset.name"/>
      </sortorders>
    </query>
  </xsl:template>
</xsl:stylesheet>


Query all top-level product categories

This query searches for product categories that have no parent related product categories. In other words, these are top-level product categories. This query can be defined as root query in combination with the following example as child query:

XML
<?xml version="1.0" encoding="UTF-8" ?>
<xsl:stylesheet version="2.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  
  <!-- parameters -->
  <xsl:param name="context-id"/>

  <!-- search for all product root categories sorted by name -->
  <xsl:template match="/">
    <query>
      <and>
        <condition name="censhare:asset.type" 
                   value="product.category.*"/>
        <not>
          <relation target="parent" 
                    type="user.product-category-hierarchy.">
            <target>
              <condition name="censhare:asset.type" 
                         value="product.category.*"/>
            </target>
          </relation>
        </not>
      </and>
      <sortorders>
        <grouping mode="none"/>
        <order ascending="true" 
               by="censhare:asset.name"/>
      </sortorders>
    </query>
  </xsl:template>
</xsl:stylesheet>


Query all second-level product categories, products and product items

This query performs a series of distinct searches. It searches child product categories, products and product items. The results are sorted by the name of the assets:

XML
<xsl:stylesheet version="2.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  
  <!-- parameters -->
  <xsl:param name="context-id"/>

  <!-- search for all product categories and products of given context-id sorted by name -->
  <xsl:template match="/">
    <query>
      <or>
        <!-- show child product categories of a product category -->
        <relation target="parent" 
                  type="user.product-category-hierarchy.">
          <target>
            <condition name="censhare:asset.id" 
                       op="=" 
                       value="{$context-id}"/>
          </target>
        </relation>

        <!-- show products of a product category -->
        <relation target="feature" 
                  type="censhare:product.category">
          <target>
            <condition name="censhare:asset.id" 
                       op="=" 
                       value="{$context-id}"/>
          </target>
        </relation>
        
        <!-- show product items of a product -->
        <relation target="parent" 
                  type="user.product-item.">
          <target>
            <condition name="censhare:asset.id" 
                       op="=" 
                       value="{$context-id}"/>
          </target>
        </relation>
      </or>
      <sortorders>
        <grouping mode="none"/>
        <order ascending="true" 
               by="censhare:asset.name"/>
      </sortorders>
    </query>
  </xsl:template>
</xsl:stylesheet>


Grouping the assets of a query

To increase the usability of a table, group the displayed assets by a specific property. The grouping creates a flat list of assets with intersect 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. The grouping is enabled and configured in the <sortorders/> tag of the child and/or parent query configuration. Inside this tag, define the grouping mode and the order by which to sort.

There are two ways to sort the assets in a grouping:

  • Using an asset property: Any existing property in the queried assets can be defined as grouping parameter.

  • Using a dynamic value list: This is a variant of the former. Instead of an asset property, a dynamic value list is rendered as grouping parameter. For more information, see Create dynamic value lists.

XML
<xsl:stylesheet version="2.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  
<!-- parameters -->
 <xsl:param name="context-id"/>

<!-- search for all products of given context-id -->
<xsl:template match="/">
   <query>
      <and>
         <relation target="feature" 
                   type="censhare:product.category">
            <target>
               <and>
                  <condition name="censhare:asset.id" 
                             op="=" 
                             value="{$context-id}" />
               </and>
            </target>
         </relation>
     </and>

<!-- group assets by washing temperature --> 
     <sortorders>
         <grouping mode="auto" />
         <order ascending="true" 
                by="censhare:product.laundry.washing" />
     </sortorders>
   </query>
</xsl:template>
</xsl:stylesheet>


The grouping definitions are placed in the <sortorders/> tag. The <grouping/> tag enables the grouping with the "auto" attribute. The </order> tag contains two attributes. Set the sort order to ascending or descending. The "by" attribute references the feature ID of the grouping parameter. In the example code, the feature ID "censhare:product.laundry.washing" refers to a product feature with a dynamic value list. The assets will be displayed in groups that match the dynamic value list definition. In the example above, these the values are "Wash at 30°", "Wash at 40°", "Wash at 60°" and "No washing".

Next steps

Configure a table widget using the root and child queries you have created.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.