Customize the Detailed search

Target groups

System administrators
Solution developers

Context

The configuration is applied to the Detailed search in the Top navigation of censhare Web.

Introduction

The Detailed search gives users fine-grained search options in censhare Web. The dialog displays input fields for dedicated asset properties. Searches for assets with matching values for one or multiple asset properties are possible. For example, a user can search for assets of the type Product / Product category AND with the keyword Products / Outdoor / Hiking.

The Detailed search dialog is configured in the Default Detailed Search Dialog asset and additional Dialog assets that are referenced in the dialog configuration snippet.

As of censhare 2020.3, dynamic search dialogs for specific asset types and user roles can be configured. For more information, see the default detailed search configuration below.

Concept

The Detailed search dialog is a unique workspace widget that is embedded in the Detailed search menu in the Top navigation:

The Detailed search widget renders the Detailed search dialog:

The dialog configuration is stored in the master file of the dialog asset. The dialog is built with the censhare UI components:

<cs-dialog-tabs id="[ID]">
   <cs-dialog-tab name={{ [PLACEHOLDER] }}> 
      <cs-dialog-group group-label={{ 'csCommonTranslations.[VALUE] | csTranslate' }} />
         <ul>
            <cs-search-metadata-row property="[RESOURCE_KEY]"/>
         </ul>
      </cs-dialog-group>
   </cs-dialog-tab>
   <cs-dialog-tab name={{ 'csCommonTranslations.[VALUE] | csTranslate' }}>
      <cs-include-dialog key="'[RESOURCE_KEY]'"/>
   </cs-dialog-tab/>
   <cs-dialog-tab name={{ [PLACEHOLDER] }}>
      <cs-include-dialog id="csDetailedSearchDialog__sub-template"
            observe asset-type="$ctrl.assetType"
            usage="'censhare:search-dialog-definition'"/>
   </cs-dialog-tab>
</cs-dialog-tabs>

Chunked, reusable dialogs

The Detailed search dialog is built from reusable dialog snippets. The dialog has also dynamic search options. The framework is given in the code snippet above. The <cs-include-dialog/> directive allows referencing dialog chunks that can be customized and reused individually.

To include a dialog chunk in the Detailed search dialog, reference the dialog to be included via the asset resource key:

<cs-include-dialog key="'[RESOURCE_KEY]'"/>

The directive renders the referenced dialog chunk as is, without any conditional rendering.

Note: All dialog chunks have also the Usage set to Asset search dialog definition. However, since the Resource key is unique, the usage attribute, it is not necessary to add the Usage attribute in the directive if you use the key attribute.

Dynamic dialog rendering

The Detailed search dialog uses dynamic dialog rendering that displays additional search fields for specific asset types. If a user selects an asset type that has additional search parameters in the General tab of the Detailed search dialog, the <cs-include-dialog/> directive renders an additional tab with these asset type-specific search parameters: 

<cs-include-dialog id="csDetailedSearchDialog__sub-template"
      observe asset-type="$ctrl.assetType"
      usage="'censhare:search-dialog-definition'"/>

The attributes are used as follows:

In dynamic dialog rendering, the usage attribute is mandatory, since the unique key attribute is not used.

How it works

The observe attribute checks any user input in the corresponding <include-dialog/> element. If user input is detected, the dialog is rendered again with the input value as attribute. The asset-type attribute sets user inputs in the Asset type field as the current context. User inputs in other search fields have no effect.

For each input value, the directive checks if a dialog snippet exists that matches the two following conditions:

• A source asset filter in the resource metadata that matches the current context asset type. For example: 

  <xmldata source-asset-filter=":starts-with(asset/@type, 'video.')"></xmldata>

  XML

• The usage value is Asset search dialog definition (resource key: censhare:search-dialog-definition).

Default configuration

The default configuration is no longer stored in a single configuration file. Therefore, check the following resource assets:

Customization strategies

To customize the Detailed search dialog, choose the appropriate strategy. You can combine different strategies as needed:

Customize individual dialog chunks

1. Create a Resource replace variant of the desired dialog chunk and open it in an asset page.

2. In the Editor tab, change the dialog items (dialog groups, directives) as desired.

3. Save your changes.

Result: The Detailed search dialog displays the customized dialog chunk.

Add new static dialog chunks to the Detailed search dialog

1. Create a new Module / Dialog asset and open it in an asset page.

2. In the Editor tab, configure the dialog items (dialog groups, directives) as desired.

3. Open the Edit properties dialog, and in the Usage field, select Asset search dialog definition.

4. Save your changes.

5. Create a Resource replace variant of the Default Detailed Search Dialog and open it on an asset page.

6. Add the dialog chunk that you created at the desired position using the <cs-include-dialog/> directive with the key attribute:

   • To add the dialog chunk in a new tab, wrap it in a <cs-dialog-tab/> element.

   • To add the dialog chunk in a new section in an existing tab, wrap it in a <cs-dialog-group/> element.

7. Save your changes.

Result: The Detailed search dialog displays the new dialog chunk in an additional tab, or in an additional section within a tab.

Add new dynamic dialog chunks to the Detailed search dialog

1. Create a new Module / Dialog asset and open it on an asset page.

2. In the Editor tab, configure the dialog items (dialog groups, directives) as desired.

3. Open the Edit properties dialog, and add the following:

   • in the Usage field, select Asset search dialog definition.

   • In the Resource metadata field, enter an XML snippet with at least one source asset filter. Leave the target asset filter empty. Escape the inner apostrophes as shown and replace [TYPE] with the desired asset type: 

     <?xml version="1.0" encoding="UTF-8"?>
     <xmldata source-asset-filter=":starts-with(asset/@type, '[TYPE].')"
              target-asset-filter="">   
        <selection needed="false"/>
     </xmldata>

     XML

4. Save your changes.

5. Create a Resource replace variant of the Default Detailed Search Dialog and open it on an asset page.

6. Add the dialog chunk that you created at the desired position using the <cs-include-dialog/> directive with the id, observe, asset-type, and usage attributes as shown above.

7. Save your changes.

Result: If a user selects the asset type, for which you created a specific dialog chunk in the General tab of the Detailed search, a new tab for this asset type with the respective search fields displays.

Create role-specific dialog chunks

1. Create a Resource replace variant of the dialog chunk for which you want to create role-specific search fields.

2. Open the Resource replace variant on an asset page.

3. In the Editor tab, change the dialog items as desired.

4. Save your changes.

5. Go to the Administration tab.

6. In the Resource replace variant of Widget, move the cursor over the Original dialog chunk, click  and select Edit relation properties.

7. In the dialog, in the Resource replace role field, select the desired user role. You can select multiple roles, if necessary.

8. Click OK to save your changes and close the dialog.

Result: If a user with that default user role opens the Detailed search, the respective tab shows the Resource replace variant instead of the original dialog chunk.

Configure the keyword search

censhare provides two ways of structured, hierarchical keywords. Which of these you are using determines as well the configuration of the Detailed search. Usually, either the keyword tree or the keyword asset structure is used in one instance. You can, however, use both simultaneously or, for example, in different domains. For more information, see Work with keywords.

Keyword tree

The keyword tree is stored as an asset feature. The keywords are stored in a hierarchical value list in the censhare Admin Client. To add, remove or edit these keywords you need the respective permissions. Keywords can be localized. These keywords cannot be edited from censhare Web.

Keyword structures

Keyword structures are based on assets. Each keyword is represented by a "Keyword" asset. Keyword assets can be related using the "Keyword hierarchy" relation (ID: "user.keyword-hierarchy."). This allows more flexible keyword structures than in the keyword tree. Users with the respective permissions can create new keyword assets and relate them to each other. keyword assets are assigned to an asset using the "Keyword" reference. 

Make sure that the "Calculate keywords hierarchical" module is enabled in the censhare Admin Client.