Configure Single-relation widgets

Display and manage related assets with a certain relation type. The single relation widget allows users to manage assets of one relation type 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 single relation widget, you manage one asset relation in one widget. The widget is placed on an asset page and configured to display and add assets with a certain relation type.

The single relation widget displays a list of all assets that are related to the current asset with the defined relation type and direction (child/parent). Users can add, change or remove assets. The details displayed as well as the available functions can be configured.

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

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.

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).
Read-only access	No	If enabled, users cannot add or remove relations.
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-&-drop option. Files can be dragged from the computer. Asset can be dragged from the pinboard.
Limit relations	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, Grey scale 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 setup 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:

<widget kind="csRelatedAssetWidget">
 <configuration xmlns:censhare="http://www.censhare.com/xml/3.0.0/censhare">
   <description censhare:_annotation.datatype="string">[STRING]</description>
   <listSize censhare:_annotation.datatype="string">[1/2/3]</listSize> 
   <relationType censhare:_annotation.datatype="string">[RELATION_KEY]</relationType>
   <relationOrReference>relation</relationOrReference>
   <newAssetType censhare:_annotation.datatype="string">[ASSET_TYPE_ID]</newAssetType>
   <useAssetPicker censhare:_annotation.datatype="string">[TRUE/FALSE]</useAssetPicker>
   <allowToAddNew censhare:_annotation.datatype="string">[TRUE/FALSE]</allowToAddNew>
   <limitNumberOfRelations censhare:_annotation.datatype="string">[0...99]</limitNumberOfRelations>
   <groupFeature censhare:_annotation.datatype="string">censhare:socio-demographic.agegroup</groupFeature>
   <trait censhare:_annotation.datatype="string">targeting</trait>
   <propertyName censhare:_annotation.datatype="string">ageGroup</propertyName>
   <readOnlyAccess censhare:_annotation.datatype="boolean">[TRUE/FALSE]</readOnlyAccess>
   <assetDnDEnabled censhare:_annotation.datatype="string">[TRUE/FALSE]</assetDnDEnabled>
   <scrolling censhare:_annotation.datatype="string">[TRUE/FALSE]</assetDnDEnabled> 
   <direction censhare:_annotation.datatype="string">[CHILD/PARENT]</direction>
   <newAsset censhare:_annotation.datatype="boolean">[TRUE/FALSE]</newAsset>
   <useAssetPicker censhare:_annotation.datatype="boolean">[TRUE/FALSE]</useAssetPicker>
   <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>

XML

Remarks

Element / Attribute	Mandatory	Description
<widget/>	yes	References the widget this configuration is based on.
kind	yes	Select "csRelatedAssetWidget".
<configuration/>	yes	Contains the configuration of the widget. The following elements show only the multi-relation configuration.
<description/>	no	Enter a description of the widget configuration.
<listSize/>	no	For the configuration of the list size, see Generic widget configuration.
<relationType/>	yes	The ID of the relation or reference.
<relationOrReference/>	yes	Select relation or reference according to the value in the <relationType/> parameter.
<direction/>	yes	For asset relations, select "child" or "parent". For asset references, select "feature" or "feature-reverse".
<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. Not allowed in combination with <groupFeature/>!
<groupFeature/>	no	Enter a feature for automatic sorting/grouping of related assets. The parameters <trait/> and <propertyName/> must be set as well. Not allowed in combination with <sortable/>!
<trait/>	no	If you set a <groupFeature/>, enter the corresponding trait key in this parameter.
<propertyName/>	no	If you set a <groupFeature/>, enter the corresponding property key in this parameter.
<scrolling/>	no	If true, the widget shows a scroll bar if the list contains more related assets than can be shown. If false, or if no value is set, users must click at the ... icon at the bottom first to initialize the scroll bar.
<readOnlyAccess/>	no	Defaults to true. Set to false if you do not want users to allow to create or remove relations.
<fileDnDEnabled/>	no	If enabled, users can add files via drag & drop. censhare creates a new asset with the corresponding relation.
<limitNumberOfRelations/>	no	Optionally enter a number between 1 and 99 to limit the total number of relations that can be created.
<assetDnDEnabled/>	no	If enabled, users can drag & drop assets to the widget. censhare creates a corresponding relation.
<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.

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.