Create dynamic value lists - SysAdmin

Dynamic value lists provide a list of selectable items for a feature. 

Context

Dynamic value lists are used in widget dialogs in censhare Web to provide drop-down lists of asset feature values. They can be created from asset key references or asset references, text values or integers. The lists are created dynamically through an asset query. They can be configured in the display or edit dialog of properties widgets using the <cs-metadata-row> directive. When a user edits the widget properties, all existing values are provided in a drop-down list. This article describes, which steps and configurations are necessary to create a dynamic value list.

Prerequisites

censhare provides value lists that can be reused to create Features with dynamic value lists. To create your own value lists, you must be familiar with the data model and master data configuration of censhare.

Introduction

Asset properties that store an asset reference can be configured as dynamic value list. A dynamic value list is a more user friendly way to manage asset references. The user does not have to search for the asset that represents the value in the Asset chooser or asset picker. Instead, the dynamic value list creates a drop-down list from which the user selects the desired value.

Drop-down lists are frequently used in the standard censhare configuration:

• Select the type of an asset in the Create asset dialog

• Select keywords from a list of keyword assets in the Keywords widget

• Select the value of a product property in a Product asset.

Dynamic value lists can be maintained and managed in censhare Web. Users with the respective permissions simply add or edit an asset that represents a value from the list. For example, they add a new keyword asset. The dynamic value list is automatically updated and new or changed values are added to the list.

Dynamic value lists can be configured for any asset feature with one of the following value type:

• Asset key reference (1)

• Asset reference (1)

• Text (String)

• Integer (Long)

Remarks:

(1) Asset key reference (with an Asset Resource key) and Asset reference (with an Asset ID) work identically. For portability reasons between censhare platforms, we recommend to use the Asset resource key whenever possible. For more information, see Resource key.

The values of a dynamic value list are themselves assets. They can be of any asset type, for example keyword or person assets. The asset types Module / Feature and Module / Feature / Feature item can be used with dynamic value lists out-of-the-box. For example, in a PIM solution, configure a product property Clothing size and add the respective feature items (the available sizes) XS, S, M, L, XL. For more details, see the Preconfigured value lists section.

Caution: In earlier censhare versions, the asset types Product feature and Product feature item were provided with censhare PIM. These asset types are deprecated. If they are still in your system, do not use them or replace them with the asset types Feature and Feature item. The functionality of these asset types is identical.

Dynamic value lists can be used in the edit dialog of the metadata widget using the <cs-metadata-row> directive with the respective attributes. When a user opens the edit dialog of the widget, the corresponding property field is rendered as a drop-down list and contains all existing values. Depending on the configuration, the user can select one or multiple items from the list. A dynamic value list is always based on assets. Each asset provides a value for a list item. Depending on the configuration of the value list, this can be the asset ID or resource key, a string or integer. In the first case (asset ID or resource key) an asset reference is created. In the second case (string or integer), any asset property can be retrieved using an XPath expression. For more information about the configuration of value lists, see the examples in the section Create value list, and the sections Preconfigured value lists  and Automatically created value lists.

A dynamic value list is rendered and stored in an asset of the type Module / Value list. In this asset, an XSLT file executes a query and creates an XML output with all list items. The XML output is then loaded in the background in the corresponding dialog field. Therefore, you have to tell censhare which dynamic value list to use for a certain feature. You do this in the feature definition of the censhare Admin Client in the field Value list resource key of the corresponding feature.

This configuration has obvious advantages over the static value lists, which are created in the feature definition in the censhare Admin Client. Above all, users with the respective permissions can add, edit and remove list items in censhare Web. It is also possible to adjust the value list itself, this means, the XSLT that queries items and generates the output. Finally, it is even possible to reuse one and the same value list in different asset features (even though this might be a rather rare case).

The following sections show you step by step the necessary configurations for dynamic value lists.

Prepare the asset feature

Note: This step is carried out in the censhare Admin Client.

First, you need an asset feature where you want to store the value(s) a user selects from the dynamic value list. Asset features are created in the censhare Admin Client in the table Master data/Features. The following table only contains the fields relevant for dynamic value lists. For a comprehensive description of all fields and configurations, read the article Create a new feature.

With these settings, your feature is prepared for a dynamic value list. You can now proceed to create the actual value list.

Create the value list asset

Note: This step is carried out in censhare Web.

Create an asset of the type Module / Value list. If you have already value list assets in your system, you can also duplicate one of them. The following table shows the minimum configuration. You can, of course, add further configurations, for example define a main domain or second domain.

With this configuration, you can proceed to edit the query and output of your list items. To do this, edit the XSLT master file of the value list asset. You can do this in the Editor tab of the asset. The following examples show transformations for an asset reference, a string and an integer. The query string retrieves all assets of the type module.feature-item.. You can specify or filter the list further by adding placeholders or more filter strings. You can use placeholders (for example module.feature-item.*) to include sub-types, or add further filter strings to select items more specifically. For example, if you want to create a dynamic value list with the washing instructions for clothing articles, you can filter feature items whose resource key starts with: clothing:laundry.washing.*. For more details check the explanations below each code block:

Asset reference

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="2.0"
    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    xmlns:censhare="http://www.censhare.com/xml/3.0.0/xpath-functions">

    <!-- parameters -->
    <xsl:param name="value" select="()"/>

    <!-- root match -->
    <xsl:template match="/">
        <options>
              <xsl:variable name="collectedAssets" select="(cs:asset()[@censhare:asset.type = 'module.feature-item.'])"/>
                <xsl:for-each select="$collectedAssets">
                  <option>
                    <xsl:attribute name="value">
                      <xsl:value-of select="@id"/>
                    </xsl:attribute>
                    <xsl:attribute name="display_value">
                       <xsl:value-of select="@name"/>
                    </xsl:attribute>
                  </option>
                </xsl:for-each>
        </options>
    </xsl:template>
</xsl:stylesheet

This transformation queries all asset of the type Feature. It then creates an output list with the respective IDs and names. The name is displayed in the drop-down list (stored in the attribute "display_name"). When the user selects an item, the ID associated with the item is stored as the actual value of the feature. In this case, this has to be an asset ID, as the value type of the feature is an asset reference.

For example, if the list contains the feature items with the washing instructions for clothing articles, these were assets like "Wash at 30°C" and so on. The advantage to have an asset for this instead of a simple number wit a unit ("30 °C"), is that you can add text and images to the asset, such as "Wash at or below 30 °C", and  . The XML representation of the feature looks as follows:

  <asset_feature asset_id="23859" feature="demo:clothing.laundry.washing" value_asset_id="25263"/>

The asset ID "25263" references the feature item (asset) "Wash at or below 30°C".

String

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="2.0"
    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    xmlns:censhare="http://www.censhare.com/xml/3.0.0/xpath-functions">

    <!-- parameters -->
    <xsl:param name="value" select="()"/>

    <!-- root match -->
    <xsl:template match="/">
        <options>
            <xsl:variable name="collectedAssets" select="(cs:asset()[@censhare:asset.type = 'module.feature-item.'])"/>
                      <xsl:for-each select="$collectedAssets">
                        <option>
                          <xsl:attribute name="value">
                            <xsl:value-of select="@name"/>
                          </xsl:attribute>
                          <xsl:attribute name="display_value">
                            <xsl:value-of select="@name"/>
                          </xsl:attribute>
                        </option>
                      </xsl:for-each>
                </options>
    </xsl:template>
</xsl:stylesheet>

This transformation queries the same feature items as in the first example. This time, the value is stored in the feature as a string. For that purpose, the asset ID cannot be used. Instead, the asset name is used for the display value and the actual feature value.

As an example, the same list of assets with the washing instructions as above is used. This time the asset title "Wash at 30°C" is stored as value of the feature. Of course, the localized name can be used as well. The XML representation of the feature looks as follows:

 <asset_feature asset_id="23859" feature="demo:clothing.laundry.washing" value_string="Wash at or below 30°C"/>

The value of the same feature as in the first example is now a string with the name of the respective feature item.

Integer

<xsl:stylesheet version="2.0"
    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    xmlns:censhare="http://www.censhare.com/xml/3.0.0/xpath-functions">

    <!-- parameters -->
    <xsl:param name="value" select="()"/>
    <!-- root match -->

    <xsl:template match="/">
        <options>
           <xsl:variable name="collectedAssets" select="(cs:asset()[@censhare:asset.type = 'product.feature-item.'])"/>
                      <xsl:for-each select="$collectedAssets">
                        <option>
                          <xsl:attribute name="value">
                            <xsl:value-of select="translate(@name, 
          translate(@name,'0123456789',''),'')"/>
                          </xsl:attribute>
                          <xsl:attribute name="display_value">
                            <xsl:value-of select="@name"/>
                          </xsl:attribute>
                        </option>
                      </xsl:for-each>
                </options>
    </xsl:template>
</xsl:stylesheet>

This transformation queries the same feature items as in the other examples. This time, the value is stored in the feature as an integer. Therefore, it has to be transformed into a numeric expression without any non-numeric characters. Otherwise, censhare would not store the value, as it accepts integers only. The XSLT expression "translate" removes all non-numeric characters from the asset name. Now again, the list contains the feature items with the washing instructions for clothing articles. In this case, the asset title is stripped down to "30" and this value is stored as integer value of the feature. This can be processed using placeholders and inserted in a text: "Wash at or below {Feature-ID} °C". The XML representation of the feature looks as follows:

 <asset_feature 
     asset_id="23859" 
     feature="demo:clothing.laundry.washing" 
     value_long="30"/>

The value of the same feature as in the examples above is now an integer that retrieves its value from the name of the respective feature item.

Preconfigured value lists

The censhare standard configuration contains preconfigured value lists that are used in core functions and special solution. For example, keywords, target groups, asset categories, workflow targets, or roles are core asset management features that are controlled via dynamic value lists. Do not change respective value list assets!

The Feature items value list (resource key: censhare:value-list.feature-item-assets) is a reusable value list that can be used in any asset feature with assigned feature item assets. The value lists is context-specific, you do not need to change or copy this value list!

The Feature items value list is designed to be used in a PIM solution for Product properties. Product properties are configured at Product category level, and automatically inherited to child Product categories and Products that are assigned to a category. Therefore, you do not need to configure a Properties widget with the Dynamic value list on the Product page.

To use this value list in a feature with assigned feature items, do the following:

1. In the censhare Admin Client, create a new feature and enter "censhare:value-list.feature-item-assets" in the field Value list resource key. For more information, see Create a new feature.

2. In censhare Web, open the Feature asset of the feature you created in the first step, and assign the desired Feature item assets. Each feature item asset represents a value.

3. Configure a Properties widget to display and edit the feature on an asset page. For more information, see Configure the Properties widget.

Automatically created value lists

In a censhare PIM solution, you can import third party Product classification systems, for example the Global Product Classification standard GS1. censhare automatically creates the required value lists to map the possible values of a classification item. You can identify these automatically created value lists by their resource key, for example: gpc:value-list.20001548. Do not delete or change these value lists, otherwise your Product classification system does not work properly. For more information, see Product classification in censhare PIM.

Note: In a PIM system, product properties are configured at Product category level, and automatically inherited to child Product categories and Products that are assigned to a category. Therefore, you do not need to configure the Dynamic value list on the Product page!

Configure the dialog in a metadata widget

Users edit the asset features (called asset properties in censhare Web) in a Metadata widget. You can add widget configurations to asset pages, where you enable the dynamic value lists created in the previous steps.

Proceed as follows to configure a widget:

1. Open the asset (type) where you want to add the widget on a new page.

2. Switch to the tab where you want to place the widget or add a new tab.

3. Start the developer mode.

4. In the asset menu, select "Add widget type" and then select the "Metadata" widget from the list. Click OK to confirm.

5. In the widget, open the actions dialog and select "Configure widget". Enter a widget title, if you do not want to use the default title.

6. In the "Metadata definitions" section, click the "+" button to create a new template.

7. Add a resource key, a name and, optionally, a description for the template and click CREATE.

8. The "Show edit dialog" field must be enabled. Otherwise, users cannot edit the features you are going to add.

9. Configure the displayed items of the widget. Click Edit content to start the Template editor. When finished, click OK to return to the widget configuration dialog.

10. Configure the editable items of the widget. Click Edit content to start the Template editor. When finished, click OK to return to the widget configuration dialog.

11. Save the configuration by clicking OK and refresh the browser page.

The template editor

In the metadata dialog template, you can configure the displayed items and the editable items separately. This way, you can display more items than users can actually edit, for example. However, both configurations are very similar in the template editor:

1. Switch to the "Options tab" and add the trait keys of the feature(s) you want to configure in the widget. You can select multiple trait keys.

2. Go back to the "Template" tab and add a <cs-metadata-row> tag for each feature you want to configure in the widget.

   In the Edit content template, use the following pattern:

   <cs-metadata-row read property="asset.traits.[trait].[property]"></cs-metadata-row>

   
   

   The "read" attribute is used to display a feature. Replace [trait] and [property] with the respective keys.

3. In the Edit dialog template, use the following pattern:

   <cs-metadata-row property="asset.traits.[trait].[property]"></cs-metadata-row>
   
   

   Note that the "read" attribute must not be used, otherwise the feature cannot be edited. Replace [trait] and [property] with the respective keys, as in the Edit content dialog.

Example

Following the example given in the previous sections, the widget configuration for a feature "Laundry / Washing" would be something like the following:

For the widget display:

<cs-metadata-row read property="asset.traits.clothing.laundryWashing"></cs-metadata-row>

For the widget edit dialog:

<cs-metadata-row property="asset.traits.clothing.laundryWashing"></cs-metadata-row>

Resuming all the previous steps, these code snippet reference an asset feature with the trait key "clothing" and the property key "laundryWashing". In that feature, one of the supported value types and a value list resource key have to be configured which retrieves all assets that represent the list items.

Result

If a user edits a widget where a feature with a dynamic value list is configured, he can select a value from the dynamically created list. If new values are added in the feature, they appear automatically in the dynamically created drop-down list.