Build custom workspaces with module assets.

The architecture

The Workspace based on assets was introduced with version 5.6. The main idea behind this implementation is that every element ( Page, Tab, Widget ) is a module asset (type: module.workspace.*), creating a hierarchical asset structure where:

  • A Workspace contains many Asset Pages (type: module.workspace.page.)
  • Every Asset Page contains Tabs (type: module.workspace.container.)
  • Every Tab contains Widgets Configurations (type:module.workspace.widget.config.)

The advantages

  • Updates on Pages, Tabs and Widgets are easier and more consistent
  • More flexibility is granted to 3rd party developers and administrators to create their own Pages, Tabs and Widgets
  • Dynamic visibility of Tabs and Widgets
  • Predefined Available Widgets based on asset pages and tabs
  • Workspace Templates based on Roles, where a Workspace Template consists of the delta of the changes based on the standard Workspace ( Resource events and Resource Replace Variants)

Prerequisites

Compatibility

For systems which are currently upgraded from a lower version into 5.6 and higher, we highly recommend to start fresh with Workspaces based on assets. Even though Workspaces based on XML might still work as they used to, they will no longer be updated to the newly introduced Widgets, Pages etc. New functionality and workspace definitions will only be added to the Workspace based on assets. The updates to Workspaces based on XML stopped with the release of the 5.5 Version.

These are the most important elements in a workspaces based on assets and their most essential properties:

Navigation

A Workspace navigation bar consist of two types of assets:

  • The Navigation Group - Asset Type: module.workspace.navigation-left.group
  • The Navigation Items - Asset Type: module.workspace.navigation-left.item

Navigation Groups

On the current Standard workspace set up, there are two groups for the Left Navigation Bar:

  • My pages - Resource Key: censhare:workspace.navigationgroup.Favorites
  • History - Resource Key: censhare:workspace.navigationgroup.History

These two groups are referenced within the Standard Workspace via the feature censhare:workspace.navigation.left, as shown below:

 <asset_feature feature="censhare:workspace.navigation.left" value_asset_key_ref="censhare:workspace.navigationgroup.Favorites" value_string2="censhare:resource-key"/>
 <asset_feature feature="censhare:workspace.navigation.left" value_asset_key_ref="censhare:workspace.navigationgroup.History" value_string2="censhare:resource-key"/>

Each Navigation Group asset contain the following set up

  • Resource key (censhare:resource-key) - Identical Key
  • Navigation group type (censhare:workspace.navigation.group.type) - my-pagesor history

The Navigation group 'My pages' references all navigation items which are part of the group. For example, the 'Dashboard' page reference within the Navigation group:

<asset_feature asset_currversion="0" asset_id="15451" corpus:dto_flags="pt" feature="censhare:workspace.navigation.item" isversioned="0" party="1" rowid="AAAHb6AAWAAACYwAAv" sid="122212" sorting="0" timestamp="2016-09-19T07:27:59Z" value_asset_key_ref="censhare:workspace.navigationitem._home" value_string2="censhare:resource-key">
    <asset_feature asset_currversion="0" asset_id="15451" corpus:dto_flags="pt" feature="censhare:workspace.navigation.locked" isversioned="0" parent_context="122212" party="1" rowid="AAAHb6AAWAAACYwABE" sid="122213" timestamp="2016-09-19T07:27:59Z" value_long="1"/>
</asset_feature>

Navigation items

The Navigation Items are individual pages which can be added in a Navigation group and in the Workspace. For example: Dashboard, Tasks, Last Edited etc.

A navigation item asset requires the following set up:

  • Resource key (censhare:resource-key) - Identical Key
  • Workspace Icon (censhare:workspace.icon) - Icon ID (from Styleguide) for the icon that will appear before the item name, eg. cs-icon-home
  • Navigation URL (censhare:workspace.navigation.url) - URL of that item page. For example: /tasks
  • Navigation item type (censhare:workspace.navigation.item.type)
    • item - For a simple item page
    • menu- For multiple items within the same item, eg. Stored Searches

Pages

Pages in workspaces fulfill the purpose of setting up a page that is adjusted to a particular asset type. For instance, an Image asset contains different tabs and metadata widgets than an Issue. These are the most important characteristics of a page asset:

After creating a new page, it must be added in the censhare Standard workspace template censhare-Server/install/system/required/web/workspace/06_workspace-templates/censhare_Standard.asset.xml. This will make the page available for usage in censhare.

  • Asset type: module.workspace.page.
  • It is defined for a particular asset type filter (feature: censhare:asset-type-filter) and MIME type filter (feature: censhare:mime-type-filter).
  • Example: Asset Image page, specified for asset type picture. and all MIME types
<asset name="Asset image" type="module.workspace.page." application="metadata" domain="root." domain2="root.">
    <asset_feature feature="censhare:asset-type-filter" value_string="picture.*">
    <asset_feature feature="censhare:mime-type-filter" value_string="*"/>
</asset_feature>
  • It defines a dedicated URL pattern for that asset page, via feature censhare:workspace.url-pattern
  • Example: Defining the URL assetImage/ for every image asset
<asset_feature feature="censhare:workspace.url-pattern" value_string="/assetImage/&lt;id&gt;"/>
  • It defines an icon for the asset page, via the feature censhare:workspace.icon. New icons must be included in the _cs-icons.scss.
<asset_feature feature="censhare:workspace.icon" value_string="cs-icon-asset"/>
  • It contains multiple Tabs sorted by priority, which work as containers to widgets. The priority of tabs is defined via the sorting attribute, this sorting corresponds to the position of the <asset_feature> element inside the asset xml. Tabs are referenced by resource key via feature censhare:workspace.container.

  • Example: Tabs Overview and Editor for the Image asset page

    <asset_feature feature="censhare:workspace.container" value_string2="censhare:resource-key" sorting="0"     value_asset_key_ref="censhare:workspace.container.image-overview"/>
<asset_feature feature="censhare:workspace.container" value_string2="censhare:resource-key" sorting="1"     value_asset_key_ref="censhare:workspace.container.image-edit"/>

  • It references (by resource key) all widget configurations available to be used in that page, via feature censhare:workspace.widget.config.

  • Example: References to widget configurations for widgets Image Metadata and General Metadata
<asset_feature feature="censhare:workspace.widget.config" value_string2="censhare:resource-key"     value_asset_key_ref="censhare:workspace.widget.config.csAssetMetadataWidget.generalMetadata"/>
<asset_feature feature="censhare:workspace.widget.config" value_string2="censhare:resource-key"     value_asset_key_ref="censhare:workspace.widget.config.csAssetMetadataWidget.imageMetadata"/>
  • It references a page application the page requires via the censhare:workspace.required-application feature.
<asset_feature feature="censhare:workspace.required-application"    value_string="com.censhare.api.applications.asset.metadata.AssetInfoApplication"/>
  • It sets a predefined page configurations via the censhare:workspace.configuration featuree.
<asset_feature feature="censhare:workspace.configuration">
    <xmldata>
      <configuration predefined="all" explorer_filter="censhare:metadata.default.asset.explorer.search.dialog"/>
    </xmldata>
</asset_feature>

The pageInstance.getConfig() config can be used in a page/component controller:

const config = pageInstance.getConfig().getValue();

Tabs / Containers

Tabs are responsible for defining which widgets are contained within a tab as well as configuring the sorting, size and other properties within the layout of tab. These are their most important characteristics:

  • Asset type module.workspace.container.
  • Feature censhare:resource-key defines a unique identificator used to link a container to a page
<asset_feature feature="censhare:resource-key" value_string="censhare:workspace.container.administration"/>
  • Contains the widget configuration (reference via the censhare:workspace.widget.config feature) along with the following additional properties for the widgets that will be shown on the container.
  • Example: Widget configuration properties, for height="4", width="1" and configurable="0" .

Available widget parameters

  • censhare:workspace.widget.height
  • censhare:workspace.widget.height.max-size
  • censhare:workspace.widget.height.min-size
  • censhare:workspace.widget.width
  • censhare:workspace.widget.width.max-size
  • censhare:workspace.widget.width.min-size
  • censhare:workspace.widget.configurable
  • censhare:workspace.widget.draggable
  • censhare:workspace.widget.resizable
<asset_feature feature="censhare:workspace.widget.config" sorting="0" value_asset_key_ref="censhare:workspace.widget.config.csAssetMetadataWidget.generalStatusMetadata" value_string2="censhare:resource-key">
    <asset_feature feature="censhare:workspace.widget.configurable" value_long="0"/>
    <asset_feature feature="censhare:workspace.widget.height" value_long="4"/>
    <asset_feature feature="censhare:workspace.widget.width" value_long="1"/>
</asset_feature>

  • Possibility to define the visibility of tabs and widgets based on certain conditions. Read more details on this topic here.
<asset_feature feature="censhare:workspace.visibility-condition" value_string="cs:has-asset-permission(asset, 'all')"/>

  • A container can be configured to set a layout, a class, etc:

    <asset_feature feature="censhare:workspace.configuration">
  <xmldata>
      <configuration layout="csTwoColumnsLayout" class="csIcmlEditor"/>
  </xmldata>
</asset_feature>

Widgets

In Workspaces based on assets, all default widgets exist in the system as module assets with type module.workspace.widget.

  • Every Asset Page contains a list of Available widgets, that defines which widgets will be available for selection on the Add Widget action for that particular Asset Page.
  • Every Tab contains a list of Widgets available for usage of that Tab.

In order to change/extend the default set up of the Available widgets on a Page or a Tab, it's required to create a Widget Configuration. The widget configuration references the resource key of the original Widget and will replicate its behavior.

In more detail:

  • A Widget asset contains the declaration of a widget (type: module.workspace.widget)
  • A Widget configuration asset (type: module.workspace.widget.configuration.) contains the configuration of a specific widget and replicates its behavior (censhare:workspace.widget feature)

Widget configuration set up

The censhare-Server/install/system/required/web/workspace/02_preconfigured-widgets directory contains predefined widget configuration assets. One widget asset can have several configuration assets.

  • The following features set the name, the label and the description of a widget in the widget list with translations:
    • censhare:name
    • censhare:label
    • censhare:description
<asset_feature feature="censhare:description" language="en" value_string="Administration of the access permissions of an asset"/>
<asset_feature feature="censhare:label" language="en" value_string="Access rights"/>
<asset_feature feature="censhare:name" language="en" value_string="Access rights"/>
  • censhare:resource-key - It sets a unique id to a configuration:
<asset_feature feature="censhare:resource-key"  value_string="censhare:workspace.widget.config.csAssetMetadataWidget.accessRightsMetadata"/>
  • censhare:workspace.configuration - It sets a default configuration for a widget. This configuration can be injected in a controller/component:
<asset_feature feature="censhare:workspace.configuration">
    <xmldata>
        <configuration hideWidgetTitle="true" tabTitle="csAcrolinxSidebarWidget.title"/>
    </xmldata>
</asset_feature>
  • censhare:workspace.widget - It links a widget though its resource-key to a widget configuration:
<asset_feature feature="censhare:workspace.widget" value_string2="censhare:resource-key"    value_asset_key_ref="censhare:workspace.widget.csAssetMetadataWidget"/>

Widget set up

The censhare-Server/install/system/required/web/workspace/01_widgets directory contains declarations for widget assets.

  • censhare:name - It defines the widget's name and its translations:
<asset_feature feature="censhare:name" language="de" value_string="Aktionen"/>
<asset_feature feature="censhare:name" language="en" value_string="Actions"/>
  • censhare:workspace.icon - Sets a widget icon
  • censhare:resource-key - It defines a unique id for the widget, which is used in the widget configuration
  • censhare:workspace.widget.type - It definds a widget type