Configure Multi-relation widgets

Display and manage related assets with multiple relation types in this widget. The Multi relations widget allows users to see, add and remove multiple relations to the current asset. Learn how to configure the widget in censhare Web and how to create widget configurations in XML workspace templates.

Context

The widget can be placed on any asset page and configured according to the requirements. Preconfigured widgets are available in the Add widget dialog of an asset page. Administrators can create widget configurations for workpace pages and in an XML workspace template.

Prerequisites

You should be familiar with asset relations and references.

Introduction

With the Multi relation widget, you manage several asset relations in one widget. The widget is placed on an asset page and configured to display and add assets in a multiple relation types. In the standard configuration, you can configure up to five asset relations per widget. Users can add, remove and sort assets in the configured relation.

The Multi relation widget displays all relationships in a grouped list. Users can add, change or remove relations for each relation type. The details displayed as well as the available functions can be individually configured for each type of relation in the widget.

If an asset relation property is configured, users can also manage this property in a context dialog. The asset relation property of an asset relation is also configured in the Single relation widget.

There are two ways of embedding and configuring the widget on an asset page: Users can customize their personal workspace by placing pre-configured widgets on an asset page or by changing the configuration of a preconfigured widget. As an administrator, you can customize the widget configuration in the censhare workspace via XML.

Configuration overview

System settings - set the number of relations users can manage in one widget.
Configuring the widget in your personal workspace - configure a widget on an asset page in your personal workspace. Use this configuration to create a workspace template.
Create a widget configuration using XML - create an XML configuration and embed it in an asset page or the widget chooser dialog in an existing workspace.

System settings

By default and due to system performance, you can manage up to five relation types in one widget. You can change the default value in the System asset. For more information, see Configuration of the System asset.

Configure the widget in your personal workspace

Note: The configuration described in this section is available to any user in censhare Web. If your are setting up a new workspace, you can follow the steps in this section and create a workspace template with resource events.

To add a new widget and configure it, do as follows. To configure an existing widget, skip the first two steps:

On the asset page, where you want to place the widget, go to the desired tab, click
to open the Page actions menu and select Add widget.
In the Add widget dialog, select the pre-configured Single relations widget and click OK.
In the widget header, click
and select Configure widget.

Generic configuration

In this section, define how the widget and list items in the widget are displayed on the asset page. For more information, see Generic Widget Configuration.

Multi relation or reference

To configure the widget:

Select an asset relation in the Type field.
To add another relation, click Add relation type and select the desired asset relation.
Repeat the previous step for each relation you want to configure in the widget.
To change the order in which the relations are displayed, click
and drag a relation to the desired position.
To configure the details for each relation, click Show details.

Show details

In this section, configure direction, sorting, grouping and optional asset relation properties for an asset relation:

Field	Mandatory	Description
Direction	Yes	Select the direction in which the relation is created (from source to target).
Manual sorting	No	Activate this field to allow manual sorting. This option is not available when you select a grouping.
Drag & drop	No	Select a drag and drop option. Files can be dragged from the computer. Asset can be dragged from the pinboard.
Limit assets	No	To limit the number of relations that a user can create, activate the checkbox and enter a number between 1 and 99.
Grouping	No	Optionally, select an asset property or asset relation property to group the assets. For example, select Color mode to group assigned images by RGB, CMYK, Greyscale and so forth. If a grouping is selected, the user-defined sorting is not available.

Edit relation metadata

In this section, you can configure an asset relation property. Relation properties quantify or qualify an asset relation. For example, add a Type of author property to the Author relation.

To add a relation metadata dialog, you have two options:

Use an existing template: Click on the field "Template" and select a template from the list. You can edit this dialog by clicking the "Edit template" button, if you wish.
Create a new template: Click
next to the Template field. Enter a resource key and name for the new template and save the new template by clicking CREATE. Next, click Edit template and edit the sample code.

For more information see Asset relation properties and asset relation child features.

Default tabs for "Add relation"

If a user adds an asset in the widget, the asset chooser opens. This dialog provides the following options. Each option can be enabled or disabled individually:

Field	Description
New asset	Allows users to create a new asset from scratch.
Asset from template	Allows users to create a new asset from a template.
Asset from file	Allows users to upload a file and create a new asset from scratch.
Existing asset	Allows users to relate an existing asset.
Open initially	Select the tab that is shown at start in the Asset chooser.

XML configuration in workspace templates

Note: Use this configuration to set up a new XML workspace template. For more information, see workspace template with XML files.

To create an XML configuration for the Multi relation widget, add the following code snippet to the XML master file of the workspace template:

CODE

<widget kind="csMultiRelatedAssetWidget">
 <configuration xmlns:censhare="http://www.censhare.com/xml/3.0.0/censhare">
  <listSize/>  
  <multiRelation1
      relationOrReference="[RELATION/REFERENCE]"
      relationType="[RELATION TYPE ID or REFERENCE FEATURE ID]"
      direction="[CHILD/PARENT/FEATURE/FEATURE-REVERSE]"
      groupType="[FEATURE/RELATION-FEATURE]"
      groupFeature="[FEATURE TYPE]"
      propertyName="[TRAIT PROPERTY]“
      trait="[TRAIT]"
      fileDnDEnabled="[TRUE/FALSE]"
      assetDnDEnabled="[TRUE/FALSE]"  
      sortable="[TRUE/FALSE]"
      limitRelations="[TRUE/FALSE]"
      disableLimitRelations="[TRUE/FALSE]"
      limitNumberOfRelations="[1-99]"
      showList="true"
      showHide="true" />
  <newAsset censhare:_annotation.datatype="boolean">[TRUE/FALSE]</newAsset>
  <assetFromTemplate censhare:_annotation.datatype="boolean">[TRUE/FALSE]</assetFromTemplate>
  <assetFromFile censhare:_annotation.datatype="boolean">[TRUE/FALSE]</assetFromFile>
  <existingAsset censhare:_annotation.datatype="boolean">[TRUE/FALSE]</existingAsset>
  <defaultSelect censhare:_annotation.datatype="string">[0/1/2/3]</defaultSelect> 
 </configuration>
</widget>

Remarks

Element / Attribute	Mandatory	Description
<widget/>	yes	References the widget this configuration is based on.
kind	yes	Select "csMultiRelatedAssetWidget".
<configuration/>	yes	Contains the configuration of the widget. The following elements show only the multi-relation configuration.
<listSize/>	no	For the configuration of the list size, see Generic widget configuration.
<multiRelation1/> ... <multiRelationX/>	yes	For each relation you want to configure in the widget, add a <multiRelationX/> element with a unique identifier X = 1, 2, 3, ...
relationType	yes	The ID of the relation or reference.
relationOrReference	yes	Select "relation" if the ID above refers to an asset relation. For example, "user-author." Select "reference" if the ID above refers to an asset reference. For example, "censhare:author.reference"
direction	yes	For asset relations, select "child" or "parent". For asset references, select "feature" or "feature-reverse".
groupFeature	no	To group assigned assets automatically by any feature, set the 'groupFeature' along with the following trait and property keys in the internal workspace configuration : groupType - feature type propertyName - trait_property trait - trait Example: groupFeature="censhare:asset.type" then groupType="reference" propertyName="type" trait="type"
groupType	no	Set to "feature", if the grouping feature is an asset feature. Set to "relation-feature", if the grouping feature is a feature of the relation itself.
sortable	no	Enable or disable manual sorting of assets in the list.
fileDnDEnabled	no	If enabled, users can add files via drag & drop. censhare creates a new asset with the corresponding relation.
assetDnDEnabled	no	If enabled, users can drag & drop assets to the widget. censhare creates a corresponding relation.
limitRelations	no	If "true", the number of assets that a user can add in this relation is limited. If "false", the limitation is disabled at start. See also the following attributes.
limitNumberOfRelations	No	Set the maximum number of assets that a user can add in this relation. The limitRelations attribute must be "true", otherwise this value will be ignored.
disableLimitRelations	no	If "true", users can disable the limitation defined in the previous attributes. If "false", users cannot change the default setting.
showList / showHide	no	Set the showList="true" attribute to display the list open at start. Set the showHide="true" attribute to display the list closed at start.
<newAsset/>	no	Asset chooser configuration: Enable the New asset tab.
<assetFromTemplate/>	no	Asset chooser configuration: Enable the Asset from template.
<assetFromFile/>	no	Asset chooser configuration: Enable the Asset from file.
<existingAsset/>	no	Asset chooser configuration: Enable the Exiting asset.
<defaultSelect/>	no	Asset chooser configuration: Set the active tab at start. 1 = New Asset 2 = Asset from template 3 = Existing asset 4 = Asset from file

Embed the widget configuration in an asset page

If you want to use the widget configuration you created for a specific asset type, create a resource replace variant of the corresponding workspace page and place the widget configuration asset in a tab of this page. To do this, open the resource change variant of the workspace page and find the workspace container (tab) in which the widget is to be placed.

Double-click the workspace container to open the related asset. Create a resource replace variant of this workspace container asset. Open the created asset and add the custom widget configuration to the list in the "Widget configurations" widget.

Go back to the resource replace variant of the workspace page you created earlier. Add the resource replace variant of the workspace container in the widget "Containers" and remove the relation to the original workspace container.

Add the widget configuration to the widget chooser

Alternatively, you can make widget configuration available in certain asset types via the widget chooser. Users can then add the custom widget configuration to the corresponding asset pages themselves. To do this, they select "Add widget" from the asset menu. This opens the widget chooser dialog. Here, they select the preconfigured widget and confirm the selection by clicking OK. The widget is placed in the opened tab.

The widget chooser can be configured individually for each asset type. To add the widget to the widget chooser of an asset type, open the workspace page asset of the corresponding asset type. In the Widget "Available widget configurations" add the custom widget configuration. If the widget configuration is not displayed in the widget selection list, restart your censhare system.

Note:

Users can always customize the widget configuration. To do this, no further authorizations are required. The procedure is described at the beginning of this article in the section "Configuring the widget".