Asset relation properties and asset reference child features

Context

In the censhare data model, relation properties are stored as features and child elements of relations.

Introduction

The censhare data model provides the possibility to add properties to Asset relations. Asset relations are stored as independent data objects in a separate table of the database. Asset relations are referenced in the source and the target asset with the <child_asset_rel/> and the <parent_asset_rel/> element, respectively. An asset relation property belongs to the Asset relation object, not to the child or parent asset. However, asset relations cannot be edited directly, but only on the asset page of the child or parent asset. Likewise, asset relation properties are managed there in the respective widgets.

Asset relations properties can be qualifying or quantifying. For example, in an author relation, the type of author can be qualified; or in a budget receiver relation, the allocated budget can be quantified. Relation properties are configured similar to asset features in the Master data/Features table of the censhare Admin Client.

From the user's perspective, asset relation properties can only be added, when an asset relation has been created. This article describes how to configure the dialogs for asset relation properties in the Single relation widget, the Multi relation widget and in the Properties widget. For each configuration, an example is given.

For the configuration of your system, select one of the configuration methods below.

The metadata dialog provides the data model and UI controls for the users to edit the relation metadata. It is stored in a Dialog asset. When you create a dialog using the Relations widget configuration (Single- or Multi-relations widget), censhare by default assigns the usage key "censhare:meta-data-relation-dialog-definition" to the dialog asset. This tells censhare that the dialog is to be used for an asset relation. As the metadata are stored in the relation and not in the related assets, they cannot be edited like asset metadata. However, relations cannot be displayed in censhare Web on a page like assets. They are displayed and managed through Relations widgets. These can be placed on either of the assets related to each other. For example, Widget 1 shows Widget 2, which is assigned to it in a "placement" relation. The relation from Widget 1 to Widget 2 indicates the child direction. Therefore, it is shown as "Placements". On the other hand, Widget 2 displays the same relation to Widget 1 as "Placed in". The relation metadata can be edited in both assets in the respective widgets, if configured accordingly.

Create a relation property feature

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

Configure a relation property feature as follows:

1. Open the Master data/Features table.

2. To create a new feature, click .

3. Fill in the respective fields. In the Target object field, select Asset relation. The configuration options for a feature are vast and cannot be covered in this description. For a comprehensive documentation of features, read Create a new feature. For an example, see the section below.

4. To save the feature, click OK.

Example: Type of author property

This property can be used with the Author relation (ID: user.author.). The Author relation assigns a Person resource to an article or image asset. The Type of author property characterizes the author relation as Main author, Co-author or Publisher. For that purpose, the feature is configured as Value list and the respective values are stored in the feature definition. However, relation properties can be of any value type. The configuration of these value types - and the configuration of the respective metadata dialogs - is different.

In the Create new: Feature dialog, enter the following values:

Note: The table only shows the mandatory and relevant fields for this configuration.

Scroll down to the Values section and enter the values according to the following table:

Save the feature. For the following configuration steps, you need the Trait key and Property key of this feature.

Create a relation metadata dialog asset

Note: This step is carried out in censhare Web.

Relation metadata dialog assets provide the dialog elements that allow users to edit the asset relation property. The relation metadata dialog uses standard HTML and the <cs-metadata-row/> directive.

To create and configure a relation metadata dialog asset:

1. Create a Module / Dialog asset. In the dialog, enter the values as follows:

2. Enter a name. We recommend to use the name convention "[relation property] relation metadata dialog".

3. Enable the resource.

4. In the Key field, enter a resource key. For more information see Resource key.

5. In the Usage field, select Relation meta data dialog definition.

6. To save and create the asset, click OK.

7. In the Overview tab, edit the Dialog properties widget and add the Trait key of the feature you created in the first step.

8. To save the changes to the widget and close the dialog, click OK.

9. Go to the Editor tab, select the MIME type HTML and click Create file.

10. In the editor, enter the HTML snippet with the <cs-metadata-row/> directive that retrieves the data from the feature you created in the first step.

For more information about the <cs-metadata-row/> directive, see censhare metadata directives. For an example, see the following section.

Example: Type of author relation metadata dialog

This relation metadata dialog works with the Type of Author feature created above. Configure the Dialog asset as follows:

<div class="cs-grid-wrapper"> 
   <div class="cs-grid-cell-2of3">    
      <cs-metadata-row 
 property="relation.traits.origin.authorType" />
   </div>
</div>

Save the Dialog asset. For the following configuration steps, you need the Resource key of this asset.

Single relation widget with relation property dialog

Note: This step is carried out in censhare Web

This widget can be placed on the asset page of an Article asset (parent) or Person asset (child). The proper direction must be chosen in the widget configuration. If placed on Article asset pages, users can assign a Person asset as author of the article. If placed on Person asset pages, users can assign Article assets of which the person resource is the author. The configuration and usage of the relation property dialog are identical for both ways.

Proceed as follows:

1. Open the asset page and go to the tab where you want to place the widget.

2. Switch to the Developer mode of censhare Web. 

3. In the page actions menu, select Add widget type.

4. In the Add widget dialog, select Asset list based on related assets and click OK.

5. Open the widget actions menu and select Configure widget.

6. For the Generic configuration section, see Generic widget configuration.

7. In the Relation or reference section, select the asset relation type, direction and the further options.

8. In the Edit relation metadata section, select the Relation dialog asset created in the previous step from the Template list.

   Tip: You can also create the Dialog asset (see previous step) or edit the dialog snippet and settings of the Dialog asset by clicking Edit template.

9. Configure the Add relation and Asset picker options.

10. To save the configuration, click OK.

Example: Authors widget and author type dialog

See the example configuration for the Multi relation widget below.

Multi relation widget with relation property dialog

Note: This step is carried out in censhare Web.

This widget can be used in the same way as the Single relation widget. The configuration is similar. You can configure and manage multiple asset relation types and their respective relation properties in one widget.

Proceed as follows:

1. Open the asset page and go to the tab where you want to place the widget.

2. Switch to the Developer mode of censhare Web. 

3. In the page actions menu, select Add widget type.

4. In the Add widget dialog, select Asset list based on multiple related assets and click OK.

5. Open the widget actions menu and select Configure widget.

6. For the Generic configuration section, see Generic widget configuration.

   Note: This widget requires a Widget title.

7. In the Multi relation or reference section, select the asset relation type in the Type field.

8. Click Show details to expand the configuration dialog.

9. Select a direction.

10. Optionally, select the desired sorting and drag-&-drop options, and a limitation. For more information about these parameters, see Configure Multi relation widget.

11. In the Edit relation metadata section, select the Relation dialog asset created in the previous step from the Template list.

    Tip: You can also create the Dialog asset (see previous step) or edit the dialog snippet and settings of the Dialog asset by clicking Edit template.

12. Configure the Add relation and Asset picker options.

13. To add another asset relation type and relation properties, click Add relation type and repeat the previous steps.

14. To save the configuration, click OK.

Example: Authors widget and author type dialog

This widget shows the authors of an article. It must be placed on Article asset pages. The table shows the basic configuration of the asset relation and relation property. The generic configuration and the Asset picker settings are not shown in the table. For more information about these topics read Generic widget configuration and Asset picker configuration.

Remarks:

(1) To configure the widget as Author of on a Person asset page, select the Parents direction.

To edit the Author type relation property, first click  in the widget header and assign an author to the article. Next, move the cursor over the assigned person, click  to open the actions menu and select Edit relation properties. In the dialog, select a value from the Type of author list and click OK.

Properties widget with asset relation and relation property dialog

The Properties widget can be configured to show and manage asset relations. For this purpose, the <cs-asset-relation2/> directive was implemented. This directive also allows you to configure a relation property dialog.

The following steps describe the basic configuration For a comprehensive documentation of the Properties widget, see Configure the Properties widget:

1. Open the asset page and go to the tab where you want to place the widget.

2. Switch to the Developer mode of censhare Web. 

3. In the page actions menu, select Add widget type.

4. In the Add widget dialog, select Metadata and click OK.

5. Open the widget actions menu and select Configure widget.

6. For the Generic configuration section, see Generic widget configuration.

   Note: This widget requires a Widget title.

7. In the Metadata definitions section, click  next to the Type field.

8. Enter a Resource key and a Name for the new template.

9. Click CREATE to save and create the template.

10. Enable the Show edit dialog field.

11. Click Edit content to open the template editor.

12. In the template tab, enter the HTML snippet with the respective <cs-asset-relation2/> directive. The following attributes are mandatory:

    • relation-type: the ID of the asset relation type to be displayed in the widget

    • direction: can be "child" or "parent"

    • asset-id: set to "asset.traits.ids.id"

    • read: this attribute has no value

13. To save the template, click OK.

14. In the Metadata definitions section, click Edit dialog to open the template editor.

15. In the template tab, enter the HTML snippet with the respective <cs-asset-relation2/> directive. The following attributes are mandatory:

    • relation type: the ID of the asset relation type to be displayed in the widget

    • direction: can be "child" or "parent"

    • asset-id: set to "asset.traits.ids.id"

    • flavor: set to "csAssetListItemRendererWidgetmxn_1rows"

    • metadata-template: enter the resource key of the relation metadata dialog created.

    • multivalue: this attribute has value

16. To save the template, click OK.

17. To save the widget configuration and close the dialog, click OK again.

Example: Authors widget with relation type dialog

This widget shows the authors of an article. It must be placed on Article asset pages. The table shows the basic configuration of the metadata display and dialog template.

<ul class="csAssetProperties__list">  
   <cs-asset-relation2 
read relation-type="user.author." 
asset-id="asset.traits.ids.id" 
direction="child"/>
</ul>

<ul class="csAssetProperties__list">
 <cs-asset-relation2 
     relation-type="user.author." 
     asset-id="asset.traits.ids.id" 
     direction="child" 
     flavor="'csAssetListItemRendererWidgetmxn_1rows'" 
     metadata-template="censhare:author-type.relation-metadata" 
     multivalue />
</ul>

To add and edit an author and select an author type:

1. Click  to open the widget dialog.

2. Click  to add a new field and select an author.

3. Move the cursor over the field and click  to open the actions menu.

4. Select Edit relation properties and in the dialog, select a value from the Type of author list. 

5. Click OK to save the selection and click OK again to save and close the dialog.

XML configuration in workspace templates

The following examples show the XML configuration of asset relation properties. Add these to the XML file of a workspace template. For more information about workspaces see also Customize with XML files.

Single relation widget

<widget kind="csRelatedAssetWidget">
 <configuration xmlns:censhare="http://www.censhare.com/xml/3.0.0/censhare">
  <relationOrReference censhare:_annotation.datatype="string">relation</relationOrReference>
  <relationType censhare:_annotation.datatype="string">user.author.</relationType>
  <direction censhare:_annotation.datatype="string">child</direction>
  <groupType censhare:_annotation.datatype="string">relation-feature</groupType>
  <groupFeature censhare:_annotation.datatype="string">censhare:type-of-author</groupFeature>
  <templateKey censhare:_annotation.datatype="string">censhare:author-type.relation-metadata</templateKey>
  <propertyName censhare:_annotation.datatype="string">typeOfAuthor</propertyName>
  <trait censhare:_annotation.datatype="string">origin</trait>
 </configuration> 
</widget>

Remarks

Multi relation widget

<widget kind="csMultiRelatedAssetWidget">
 <configuration xmlns:censhare="http://www.censhare.com/xml/3.0.0/censhare">
  <multiRelation1
   relationOrReference="relation"
   relationType="user.author."
   direction="child"
   groupType="relation-feature"
   groupFeature="censhare:type-of-author"
   templateKey="censhare:author-type.relation-metadata"
   propertyName="typeOfAuthor"
   trait="origin" />
 </configuration>
</widget>

Remarks