Asset relation properties and asset reference child features

In censhare, you can define relation properties for asset relations. When a relation is created between two assets, and a property is configured for the respective relation type, users can select or enter a value. Learn more about the setup and configuration of the UI dialog of relation properties in censhare Web.

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 using 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 metadata 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 is 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 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 the 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

 

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 configuring 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  Workspace templates 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