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.
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:
Open the Master data/Features table.
To create a new feature, click .
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.
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.
Field | Value / selection |
ID | example:author.relation.type |
Name [en] | Author type |
Asset resource key | example:relation.feature.author |
Trait key | origin |
Property key | authorType |
Target object | Asset relation |
Type | Asset Feature |
Value type | Value list (String) |
Scroll down to the Values section and enter the values according to the following table:
Field | Value 1 | Value 2 | Value 3 |
Value | main_author | co_author | publisher |
Name [en] | Main author | Co-author | Publisher |
Sorting | 1 | 2 | 3 |
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:
Create a Module / Dialog asset. In the dialog, enter the values as follows:
Enter a name. We recommend to use the name convention "[relation property] relation metadata dialog".
Enable the resource.
In the Key field, enter a resource key. For more information see Resource key.
In the Usage field, select Relation meta data dialog definition.
To save and create the asset, click OK.
In the Overview tab, edit the Dialog properties widget and add the Trait key of the feature you created in the first step.
To save the changes to the widget and close the dialog, click OK.
Go to the Editor tab, select the MIME type HTML and click Create file.
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:
Field | Value / selection |
Name | Author Type Relation Metadata Dialog |
Enabled | true |
Resource key | censhare:author-type.relation-metadata |
Usage | Relation meta data dialog definition |
Traits | origin |
HTML master file |
CODE
|
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:
Open the asset page and go to the tab where you want to place the widget.
Switch to the Developer mode of censhare Web.
In the page actions menu, select Add widget type.
In the Add widget dialog, select Asset list based on related assets and click OK.
Open the widget actions menu and select Configure widget.
For the Generic configuration section, see Generic widget configuration.
In the Relation or reference section, select the asset relation type, direction and the further options.
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.
Configure the Add relation and Asset picker options.
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:
Open the asset page and go to the tab where you want to place the widget.
Switch to the Developer mode of censhare Web.
In the page actions menu, select Add widget type.
In the Add widget dialog, select Asset list based on multiple related assets and click OK.
Open the widget actions menu and select Configure widget.
For the Generic configuration section, see Generic widget configuration.
Note: This widget requires a Widget title.
In the Multi relation or reference section, select the asset relation type in the Type field.
Click Show details to expand the configuration dialog.
Select a direction.
Optionally, select the desired sorting and drag-&-drop options, and a limitation. For more information about these parameters, see Configure Multi relation widget.
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.
Configure the Add relation and Asset picker options.
To add another asset relation type and relation properties, click Add relation type and repeat the previous steps.
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.
Field | Value or selection |
Relation or reference | |
Type | Author |
Direction | Children (1) |
Edit relation metadata | |
Template | Author Type Relation Metadata Dialog |
Default tabs for "Add relation" | |
New asset | enabled |
Asset from template | disabled |
Asset from file | disabled |
Existing asset | enabled / Opened initially |
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:
Open the asset page and go to the tab where you want to place the widget.
Switch to the Developer mode of censhare Web.
In the page actions menu, select Add widget type.
In the Add widget dialog, select Metadata and click OK.
Open the widget actions menu and select Configure widget.
For the Generic configuration section, see Generic widget configuration.
Note: This widget requires a Widget title.
In the Metadata definitions section, click next to the Type field.
Enter a Resource key and a Name for the new template.
Click CREATE to save and create the template.
Enable the Show edit dialog field.
Click Edit content to open the template editor.
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
To save the template, click OK.
In the Metadata definitions section, click Edit dialog to open the template editor.
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
To save the template, click OK.
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.
Field | Value |
Metadata definitions | (Create new template) |
Resource key | example:author-relation.author-type |
Name | Author with author type |
Edit content | |
Template |
CODE
|
Edit dialog | |
Template |
CODE
|
To add and edit an author and select an author type:
Click to open the widget dialog.
Click to add a new field and select an author.
Move the cursor over the field and click to open the actions menu.
Select Edit relation properties and in the dialog, select a value from the Type of author list.
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
Element | Description |
<widget/> | This parameter specifies how large the asset symbols are displayed in the widget. Enter the value 1 (small) 2 (medium) or 3 (large). See also the article on generic Widget Configuration. |
<configuration/> | Allows you to create a new asset in the configured relation to the current asset. Enables the respective tab in the Asset chooser. |
<relationOrReference/> | Select "relation". Note: Asset references have child features, but no asset relation properties. |
<relationType/> | The ID of the relation. |
<direction/> | Select "child" or "parent". |
<groupType/> | Optionally, configure the asset relation feature as grouping parameter. Select "relation-feature". |
<groupFeature/> | Select the feature ID of the asset relation property to group by. |
<templateKey/> | References the Metadata dialog asset. Select the resource key. |
<propertyName/> | Select the Property key of the relation feature. The Property key is stored in the feature definition in the Master data/Features table. |
<trait/> | Select the trait key of the relation feature. The Trait key is stored in the feature definition in the Master data/Features table. |
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
Element / attribute | Description |
<widget/> | This parameter specifies how large the asset symbols are displayed in the widget. Enter the value 1 (small) 2 (medium) or 3 (large). See also the article on generic Widget Configuration. |
<configuration/> | Allows to create a new asset in the configured relation to the current asset. Enables the respective tab in the Asset chooser. |
<multiRelation1/> ... <multiRelationX/> | For each relation you want to configure in the widget, add a <multiRelationX/> element with a unique identifier X = 1, 2, 3, ... For a comprehensive documentation of all attributes see Configure the Multi relation widget. |
relationOrReference | Select "relation". Note: Asset references have child features, but no asset relation properties. |
relationType | The ID of the relation. |
direction | Select "child" or "parent". |
groupType | Optionally, configure the asset relation feature as grouping parameter. Select "relation-feature". |
groupFeature | Select the feature ID of the asset relation property to group by. |
templateKey | References the Metadata dialog asset. Select the resource key. |
propertyName | Select the Property key of the relation feature. The Property key is stored in the feature definition in the Master data/Features table. |
trait | Select the trait key of the relation feature. The Trait key is stored in the feature definition in the Master data/Features table. |