Configure Properties widgets - SysAdmin

The Properties widget is a versatile widget used to display and edit asset properties. In the censhare standard configuration, several configurations are available on asset pages and in the widget list. This article describes the configuration basics of the Properties widget.

Target group

Administrators
Power users

Context

The Properties widget is a generic widget that is used in censhare Web to edit and display asset properties. The censhare standard configuration includes many configurations of the Properties widget. For example, General, Details, Properties, Keywords, Flags, and Administration configurations. For a complete list of standard widget configurations, go to the Widgets tab of the System asset and search for csAssetMetadataWidget.

Introduction

Note: This article refers to asset properties in censhare Web. In the censhare Client, asset properties are called asset metadata. In the censhare Admin Client asset properties are configured as asset features.

censhare stores asset data either as asset properties or asset content (asset files). In censhare Web, users can edit and manage these properties through widgets - namely the Properties widget. Asset pages usually contain several configurations of the Properties widget. Each configuration displays a specific set of properties of the selected asset. The title of the widget configuration can vary. However, the widget functionality upon which these configurations are based is identical and described in this article.

By clicking the Edit icon in the widget header, users can access the widget dialog and edit selected properties. The properties displayed on the widget and the properties that can be edited in the dialog are configured separately. This means that some widgets display more properties than users can actually edit in the dialog of the widget.

As of censhare 2018.2, the Properties widget allows inline editing. You can use the inline editing directive in the widget display without further configuration. Users can edit properties directly on the widget, without opening the edit dialog.

Feature definition in the censhare Admin Client

Asset properties (features) are configured in the Master data/Features table of the censhare Admin Client. To look up the feature parameters listed below, you need access to the censhare Admin Client. Before you start to configure a Properties widget, familiarize yourself with the configuration of the features (properties) you want to add to the widget. For more information, see Create a new feature.

The properties widget configuration supports hierarchical properties and inherited properties. To display inherited properties, the feature inheritance must be configured accordingly. For more information, see Feature inheritance - Key concept.

The following parameters are required for the correct configuration of the Properties widget:

Trait key: This parameter groups properties. In combination with the Trait key and Property key form a unique identifier of a property.
Property key: This parameter designates a property within a trait. In combination with the Trait key and Property key form a unique identifier of a property.
Value type: This parameter determines the data format and the storage value of a property. For example, the value type can be a string, a numeric value or an asset ID. For more information, see the section "Notes on value types" in Create a new feature.
UI control: The default UI control element of some value types can be overwritten.
Unit / unit set: Numeric properties (floating-point) can be stored with a unit parameter. This parameter can be configured as a unit or unit set. A unit is fixed and cannot be selected by the user. A unit set allows the user to select a unit. For example, select a from list of length units (mm, cm, m, km).
Language: Some properties can be stored in localized versions. For example, the asset name. In this case, a language parameter can or must be set for each value of a property. To store localized values, make sure that the Multiple values parameter is selected.
Color: Optionally, a color value can be associated with a property. If enabled, censhare renders a color picker in the widget. The values are stored as hexadecimal values.
Multiple values: If a property can have multiple values, this parameter must be configured in the feature definition. In the Properties widget, censhare renders a + icon to add more than one value.
Relevance: This is an optional parameter that is used to weight a property. This parameter is used with multiple values. For example, if you define multiple keywords, the main keyword can have a relevance of 100 percent and other keywords lower values.

Note: The parameters Trait key, Property key, Value type, UI control, and Multiple values are technical parameters for internal processing, storing, and representation of an asset property. In contrast, the user can edit the Unit/unit set, Language, Color and Relevance parameters. These parameters are rendered in the widget display and dialog.

Configuration - key steps

Add widget to an asset page Place the widget on a tab of an asset page to display and edit properties of the respective asset type.
Generic configuration Setup the widget title and other UI options.
Metadata definitions Configure the displayed and editable data.
- Configure the Dialog asset to display asset properties
- Configure the Dialog asset to edit asset properties
- Inherited features setup
- Configure asset reference features
Display empty properties Configure whether empty properties are shown or hidden in the widget.
XML configuration in workspace templates Configure a Properties widget in the XML file of a workspace template.

Add widget to an asset page

To create a new widget configuration in censhare Web, open an asset page and select the desired tab.
Turn on the developer mode in your censhare Web.
In the page-actions menu, select Add widget type.
In the dialog, select Metadata widget from the list of available assets.
To add the widget to the selected tab, click OK.
Open the widget menu and select Configure widget.
In the Metadata dialog, coplete the generic configuration and configure the widget content and display dialog as described in the following sections.

Generic configuration

Complete the generic configuration as described in the Generic widget configuration - SysAdmin.

Metadata definitions

In the Metadata definition section, configure the widget content and edit dialog. Both can be configured independently. censhare stores the configurations in Dialog assets that can be reused in other widget configurations.

Important note: In order to use an existing dialog in the widget, select one from the drop-down list in the Widget content field. The list shows all available dialogs in your system. When you select a dialog here, censhare opens the respective templates into the editor. You can edit the templates with the Edit content and Edit dialog buttons. Be aware that the changes you make in the templates affect all widget configurations that use the same dialog templates!

Proceed as follows:

To create a new dialog template, click next to the Widget content field. The dialog shows the following fields:
- Resource key: Enter a unique resource key for the dialog.
- Name: Enter a name for the dialog. This name appears in the Widget content list. After you save the dialog, it can be reused in other widgets.
- Description: Enter here a description. The description is optional and for internal use only.
As soon as you have entered a valid resource key and a name, the CREATE button is available.
To save the new dialog template, click CREATE. censhare creates a new Dialog asset with the name you have entered.
To configure the dialog to edit the widget content, select Show edit dialog. This option is only necessary if you want allow user to edit the properties and if you do not want to use inline editing.
Note: If you configure both, the display and the dialog for the widget, censhare stores these configurations in two Dialog assets. However, if both configurations are identical, only one Dialog asset is created. As soon as the two configurations differ, censhare automatically creates a copy of the dialog configuration. The extension "dialog" is added to the template name you entered.
To save the configuration, click OK.

censhare creates the Dialog template for your Properties widget configuration. Next, configure the Dialog asset(s).

Configure the Dialog asset to display asset properties

Add trait keys

Dialog assets store an XML representation of the content that is displayed in the Properties widget and the dialog to edit the widget. To display and edit the desired properties, add the trait keys of the properties to these Dialog assets:

In the side navigation of censhare Web, select Last created list. A list of recently-created assets displays.
Search for the newly created Dialog asset and open the asset.
Edit the Properties widget and add the trait keys in the Traits field. Add only one trait key per field. To add more fields, click
. You can look up the trait keys the Master data/Features table of the censhare Admin Client.
To close the dialog, click OK. To save your changes in the dialog asset, click SAVE Dialog.
Note: To check if you entered a valid trait key, open the asset where you have configured the Properties widget. Open the Widget configuration and there open the template editor (click "Edit content" or "Edit dialog ). In the template editor, switch to the "Options" tab. The traits must be displayed under "Available traits".

You are now ready to configure the XML snippet for the display and edit dialog of the Properties widget. You can do this in one of the following ways:

In the Dialog asset: Go to the "Editor" tab and edit the XML content.
In the Template editor of the Widget configuration dialog: Open the widget configuration and start the Template editor by clicking "Edit content" or "Edit dialog". The XML snippet can be edited in the "Template" tab, which opens by default.

Add a property with <cs-metadata-row/>

Tip: This article shows the basic configuration of the dialog assets. For more details on elements, directives and attributes, see censhare metadata directives - SysAdmin.

The XML representation uses some standard HTML and censhare directives to include asset properties and output a proper styling. When you create a new template from scratch, you see the most basic representation of a template in the sample code:

<ul class="csAssetProperties__list">
  <cs-metadata-row read property="asset.traits.TRAIT.PROPERTY">
  </cs-metadata-row>
</ul>

The <ul/> element creates a list output and works as a container element. The <cs-metadata-row/> directive includes the actual asset property. Use one line per property. The "read" parameter tells censhare that this property is for display only. The property itself is identified by the combination of a TRAIT (key) and a PROPERTY (key). In the code snippet, replace these placeholders by the respective values. You can look up trait and property keys in the "Master data/Features" table in the censhare Admin Client.

You have now created a new template in the Properties widget, configured the Dialog assets and the code snippet that creates the properties output. To create a dialog that allows users to edit the properties, you must separate the content display from the dialog display. To create an edit dialog, proceed as described in the following section. If you do not want to create an edit dialog, skip the following section.

Configure the Dialog asset to edit asset properties

censhare stores the configuration to display and edit the content of a Properties widget in separate Dialog assets. You can edit these configurations independently one from one another. It is possible to configure different widget display and edit dialogs. Different configurations can be used in cases where you wish to show more details (properties) than a user can actually edit. For reasons of good user experience, we do not recommend this configuration.

In the edit dialog, you can add a validation of value list items. censhare runs a validation when an asset is moved into another domain (first domain and/or second domain). The validation checks the first and second domains of value list items. Value list items are asset properties with the value type Value list or Hierarchical value list. For more information, see Create a new feature.

If the domains of the value list item do not conform with the domains of the asset that a user is editing, an Invalid value message is shown in the dialog. The asset can still be saved with this invalid value, but users are notified that the selected value is invalid.

To setup the edit dialog, create the respective Dialog asset. Proceed as follows:

Open the widget configuration and activate the Show edit dialog field, if you have not done so yet.
Click the Edit dialog. The Template editor opens and shows the XML code snippet you have created in the previous section. For now, we assume that you did not change anything and that the placeholder looks exactly as shown above.
Remove the "read" parameter from the <cs-metadata-row/> directive. The edited directive now looks as follows:
```
<ul class="csAssetProperties__list">
  <cs-metadata-row property="asset.traits.TRAIT.PROPERTY">
  </cs-metadata-row>
</ul>
```
Note: In the widget configuration, you find the two buttons "Edit content" and "Edit dialog". Initially, both options reference the same Dialog asset. As soon as censhare detects a difference in the code snippets, it creates a second Dialog asset. This second asset has the same name as the one initially created with the suffix "Dialog" added to the name. Due to this, removing the "read" parameter causes censhare to separate both configurations and create the second dialog asset. Any change in the code snippet forces censhare to create the second asset. Because the "read" parameter must be removed for the dialog configuration, we recommend to do it in this step.
To close the Template editor, click OK. To close the widget configuration dialog, click OK once more.
In the Side navigation, select Last created and locate the Dialog asset that censhare automatically created. For example, if your initial template was called "My template" you find two dialog assets in the list ("My template" and "My template Dialog"). Open the "... Dialog" asset .
Add the trait keys to the Dialog asset. To add the trait key, proceed as described in the Configure the Dialog asset section above.

You have now created a widget configuration with a Dialog asset for the content display and a second Dialog asset for the content editing. To edit edit these these assets independently in the widget configuration dialog, click Edit content or Edit dialog. You can also edit the configuration directly in each Dialog asset.

Inherited features setup

When you configure a Properties widget, you need to be aware of inherited features. Inherited features require a special setup. For more information, see Feature inheritance - key concept.

Configure asset reference features

An asset feature can be an asset reference. With an asset reference, censhare does not store a string, numeric value, or date in the feature. The asset reference stores a reference to another asset. The value of an asset reference can be the ID or the resource key of the referenced asset. Both values are unique identifiers. An asset reference is technically a numeric value (asset ID) or string value (resource key).

You can manage asset references in a Properties widget with the asset chooser, the asset picker, or a dynamic value list:

Create references with the asset chooser dialog

The default method to create asset references in the Properties widget is with the asset chooser. When a user opens the dialog to edit the widget, a clickable drop zone displays. Users can drag an asset to the zone or click within the drop zone. A click within the drop zone opens the asset chooser dialog. For this option, no special configuration is required. Use the <cs-metadata-row/> directive for this configuration in the Properties widget.

Create references with the asset picker

The Asset picker is a convenient way to select an asset from a list or create a new asset to select. The selection is then stored as an asset reference. For more information, see Configure the Asset picker.

Create references with dynamic value lists

Dynamic value lists generate a drop-down list from which users can select an item. Each item represents an asset. Selection of an item from the list creates the respective asset reference. To use this option, you must create the dynamic value list itself and configure the feature accordingly in the censhare Admin Client. In the Properties widget, use the standard <cs-metadata-row/> directive for the configuration. For more information, see Create dynamic value lists - SysAdmin.

Configure asset relations and relation properties

The Properties widget can also be configured to show and manage asset relations. This configuration is an alternative to the Single relation widget and Multi relation widget. For this configuration, use the following setup and directive:

Directive / attribute	Description
<cs-asset-relation2/>	This directive retrieves related assets to the current asset and has the following attributes:
read	Use as in <cs-metadata-row/>.
asset-id	Set to "asset.traits.ids.id" to reference the context asset.
relation-type	Enter the ID of the asset relation type. For example, "user.author."
direction	Select "child" or "parent".

Relation properties

Asset relations have optional relation properties. These can also be configured in the Edit dialog of the properties widget. The configuration of relation properties requires a more complex setup. You need a relation feature and a relation metadata dialog template. The template is referenced in the <cs-asset-relation2/> directive. For more information, see Asset relation properties and asset reference child features.

Display configuration

In this section you define how empty properties are shown in the display mode of the widget. Empty properties are properties that are defined in the Metadata definitions but do not contain a value in the selected asset. By default, empty properties are not shown in the Properties widget to keep asset pages lean without showing unnecessary data. However, users do not always know, in which widget they can edit certain asset properties. To increase clarity, you can show empty properties in the widget. You can also add a toggle to the widget so that users can show or hide empty properties as desired.

Field	Default	Remarks
Show toggle switch to show or hide empty properties	disabled	Enable this option to display a Show empty properties toggle at the bottom of the widget. Users decide whether they want to see or hide empty properties. At the start, the toggle is set to the selected option below.
Show empty properties by default	disabled	(1) If this field and the field above are disabled, users do not see empty properties. (2) If this field is enabled and the field above is disabled, users always see empty properties in the widget. (3) If this field and the field above are enabled, the toggle is visible and users see empty properties at start. The user can switch the toggle to hide empty properties. (4) If this field is disabled and the field above is enabled, the toggle is visible and users do not see empty properties. The user can move the toggle to show properties.

XML configuration in workspace templates

When you set up a new system or workspace, you can add pre-configured workspace widget configurations to asset pages and to the list of available widgets. Workspaces provide a customized view of assets and are assigned to roles. For more information about the workspace concept, see Configuration of the workspace. For more information about XML templates, see Customize with XML files - SysAdmin.

In the XML configuration of a workspace, you can define for each workspace page (asset type) the workspace containers and (tabs) and widgets on each tab. Add the following </configuration> inside the respective </widget> element. For more information, see Generic widget configuration - SysAdmin.

<widget kind="csAssetMetadataWidget" >
 <configuration xmlns:censhare="http://www.censhare.com/xml/3.0.0/censhare" 
            title="[generic title]"
            title_de="[german title]"
            title_en="[english title]"
            description_de="[german description]"
            description_en="[english description]"
            description="[generic description]" >
  <description censhare:_annotation.datatype="string"></description>
  <templateKey censhare:_annotation.datatype="string">[resource key]</templateKey>
  <editable censhare:_annotation.datatype="boolean">[true/false]</editable>
  <showEmptyPropertiesToggle censhare:_annotation.datatype="boolean">[true/false]</showEmptyPropertiesToggle>
  <showEmptyPropertiesByDefault censhare:_annotation.datatype="boolean">[true/false]</showEmptyPropertiesByDefault>
 </configuration>
</widget>

Remarks

Element / attribute	Description
<widget/>	Add to a workspace container of the desired workspace page (asset type).
kind	Select "csAssetMetadataWidget".
<configuration/>	Contains the configuration parameters of the widget.
title	The generic title.
description	The generic description.
title_de, title_en, ...	Localized titles.
description_de, description_en, ...	Localized descriptions.
<description/>	Deprecated. Use localized description attributes instead.
<templateKey/>	References the Dialog asset by its resource key.
<editable/>	Controls the edit dialog of the widget.
<showEmptyPropertiesToggle/>	Controls the Show empty properties toggle as described in the section Display configuration.
<showEmptyPropertiesByDefault/>	Show or hide empty properties - use in combination with the </showEmptyPropertiesToggle> as described in the section Display configuration.

Result

Note: To enable the widget configuration, refresh your browser page (if you are still in developer mode) or log out from censhare Web and log in again.

Users can see and edit the configured properties in the widget. If you have chosen inline editing in your configuration, users can edit the displayed properties directly in the widget.

Next steps

This configuration is only available in your personal workspace and on asset pages of the same asset type. To make the configuration available to other or all users in the system, you must adapt the standard workspace of your system. For more information, see Customize by resource event templates and Customize with XML files - SysAdmin.