Metadata directives - overview

Configuration for displaying and editing metadata in censhare 5 Web. How to create, display and edit metadata features using the metadata widget in censhare 5. Information about the available censhare directives to create controls in the censhare 5 user interface.

Feature definitions in censhare Admin Client

The requirement for working with metadata in censhare 5 is correctly set up features in the master data section of the censhare Admin Client. For a full reference on how to set up features, see article Creating a new feature.

censhare 5 Metadata Widget

The Metadata widget provides access to definable metadata, to display and optionally edit features of an asset, based on the asset page.

It consists of two components, the display and dialog configuration template. Both are stored as module assets.

Widget configuration

To set up the widget with existing or newly created metadata templates, there are several configuration settings required in the widget configuration dialog.

• Widget title: Manual widget title, displayed in the widget header

• Widget traits

  • Available traits: Displays the defined and default available feature traits in an expandable list

  • Additional traits: Custom traits can be added by adding the specific trait name and clicking the round plus button

• Widget and dialog definitions

  • Template: Dropdown menu displays all available asset metadata templates (showing assets with resource usage „Metadata view definition“). With the round plus button, a new template can be defined.

    • A. Adding a new template

      • Key: Defines the unique resource key of the metadata templates

        • Conventions: The prefix customer:metadata should be used to identify resources as specific metadata dialogs. Example: censhare:metadata.general

        • Rule: If the metadata template is editable, the dialog asset is automatically added with an assignment relation to the display asset and an added .dialog suffix.

        • Example: censhare:metadata.general.dialog

      • Name: Asset name of the template

      • Description: Asset description of the template

      • Editable: If checked, the defined metadata can be edited by users (a dialog template is created)

    • B. Choosing an existing template

      • Template: Dropdown menu displays all available metadata templates (assets of type module.dialog.) that can be assigned for this widget instance. As right now there is no separate asset subtype for dialog assets, you have to choose the correct display template from the menu.

      • Edit content: Opens the Template Editor in which the HTML snippet for the widget content (what is displayed in the widget) can be defined

      • Edit dialog: If the Editable option is checked, this option opens the Template Editor in which the HTML snippet for the widget editing dialog (what is displayed in the edit dialog) can be defined

Asset Structure

• If you create a metadata template within the configuration dialog, the required module assets are created in the background

  • Display asset (view in the widget)

    • Asset type: Module/Dialog

    • Resource usage: Meta data view definition

    • Resource key: As defined in dialog

  • Dialog asset (edit dialog of the widget)

    • Asset type: Module/Dialog

    • Resource usage: Meta data dialog definition

    • Resource key: Resource key of display asset plus .dialog

TIP: Of course you can also set up these assets manually outside of the Metadata Widget if you provide the required resource information.

Template Editor

• The content of metadata templates is stored as HTML storage file

• The Template Editor of the metadata widget gives access to the source of the metadata template

  • Source tab

    • Displays the content of the template asset‘s HTML content in a source code editor

  • Preview tab

    • Provides a live preview of the template definitions, based on the context assetChanges in the Source tab are reflected in the Preview

  • Model tab

    • Displays the JSON update data model of the context asset in read-only mode. This data model is the foundation for the template definitions

Asset Data Model

• The metadata widget makes use of the JSON representation of the update data model that was introduced with censhare 5

• There is a logical model and an update model

  • Logical model

    • Standard censhare 5 asset data model and API

    • High level model that represents a logical structure of objects and hides physical representation (database schema)

    • Available as XML, JSON, Java API

    • Expandable

  • Update model

    • Extended censhare 5 asset data model

    • Displays all available traits and properties, not only given values but also empty values

    • More complex data structure. Example XML representation: information is encapsulated in element structures instead of inlined attribute lists.

    • Used to display all information within the metadata widget

Example: Trait display of a dialog asset in the logical model

<display description="Show the basic properties of the asset" name="General Meta Data Display"/>

Example: Trait display of a dialog asset in the update model

<display>
  <name name="name" is_multivalue="false" label="Name" value_type="string" exists="true" has_children="false">
    <value value="General Meta Data Display" self="property/name"/>
  </name>
  <description name="description" tooltip="Asset description in free text" label="Description" value_type="string" placeholderText="Description" has_children="false" exists="true" is_multivalue="false">
    <value value="Show the basic properties of the asset" self="property/description"/>
  </description>
  <color name="color" is_multivalue="false" label="Color" value_type="integer" exists="false" has_children="false">
    <value/>
  </color>
  <localizedName name="localizedName" is_multivalue="true" label="Name (localized)" value_type="string" name="false" has_children="false">
    <value/>
  </localizedName>
  <localizedDescription name="localizedDescription" is_multivalue="true" label="Description (localized)" value_type="string" exists="false" has_children="false">
    <value/>
  </localizedDescription>
</display>

Asset Data Model: REST URLs

• The data model of an asset can be accessed via the censhare REST interface

• Support for XML and JSON format

• The following URL schemas are provided

  • Logical model

    • Representation: /json or /xml

    • Parameters

      • format: logical (default)

    • Example: http://SERVERPATH/ws/rest/service/assets/asset/id/ID/model;format=logical;/json

  • Update model

    • Representation: /json or /xml

    • Parameters

      • format: update

      • trait: Comma separated list of traits

      • generator-inline-limit: Max number of inlined options (optional)

    • Example: http://SERVERPATH/ws/rest/service/assets/asset/id/ID/model;format=update;traits=TRAITS;generator-inline-limit=0/json

HTML Template Structure

The template storage files are based on an HTML structure that is displayed in the widget content and widget edit dialog.

To access information in the JSON data model of an asset, the template structure is enhanced by AngularJS expressions.

Expressions are used to navigate in the JSON data model and to access and display metadata (e. g. labels, values) by synchronizing the expression with asset data (data binding).

• Syntax: {{JSON path}}

• Example: {{asset.traits.display.name.value[0].value}} accesses the asset name (in the trait display)

Custom censhare AngularJS directives provide user interface controls and functions that give access to metadata properties.

Directives introduce a new syntax to the HTML document object model. They represent dynamic HTML extensions that are compiled into specific HTML behavior or DOM elements/transformations.

Custom directives allow us to pre-define re-usable UI components and logic (of any complexity) that can be accessed by a simplified syntax.

• Syntax: custom HTML elements, attributes or comments, according to HTML naming conventions

• Example:

  CODE

  <cs-metadata-row property="asset.traits.type.type"></cs-metadata-row>

  This provides a label and select input to choose the asset type. The compiled HTML structure is as follows:

  CODE

  <li class="csDialogForm__row ng-isolate-scope" required="required" property="asset.traits.type.type">
    <div class="csDialogForm__cell-label ng-scope">
      <span class="cs-label ng-binding">Module</span>
    </div>
    <div class="csDialogForm__cell metadata-transclude ng-scope">
      <cs-hierarchical-value ng-model="property.value[0]" data="property.generator.options">
      …

Template Examples

Display template for general asset meta data

<ul class="csAssetProperties__list">
  <li read>
    <span class="csAssetProperties__list-label">{{asset.traits.display.name.label}}</span>
    <span class="csAssetProperties__list-value"><strong>{{asset.traits.display.name.value[0].value}}</strong></span>
  </li>
  <cs-metadata-row read property="asset.traits.type.type"></cs-metadata-row>
  <cs-metadata-row read property="asset.traits.display.description"></cs-metadata-row>
  <cs-metadata-row read property="asset.traits.origin.author"></cs-metadata-row>
  <cs-metadata-row read property="asset.traits.domain.domain"></cs-metadata-row>
  <cs-metadata-row read property="asset.traits.domain.domain2"></cs-metadata-row>
  <cs-metadata-row read property="asset.traits.rating.rating"></cs-metadata-row>
  <cs-metadata-row read property="asset.traits.display.color"></cs-metadata-row>
  <cs-metadata-row read property="asset.traits.ids.id"></cs-metadata-row>
</ul>

Edit dialog for general asset meta data

<cs-dialog-group title="{{'csCommonTranslations.properties' | csTranslate}}">
  <ul>
    <cs-metadata-row required property="asset.traits.display.name"></cs-metadata-row>
    <cs-metadata-row property="asset.traits.display.description">
      <cs-input multilines="3" ng-model="property.value[0].value"></cs-input>
    </cs-metadata-row>
    <cs-metadata-row required property="asset.traits.type.type"></cs-metadata-row>
    <cs-metadata-row required property="asset.traits.domain.domain"></cs-metadata-row>
    <cs-metadata-row required property="asset.traits.domain.domain2"></cs-metadata-row>
    <cs-metadata-row property="asset.traits.rating.rating"></cs-metadata-row>
    <cs-metadata-row property="asset.traits.display.color"></cs-metadata-row>
    <cs-metadata-row property="asset.traits.type.application"></cs-metadata-row>
  </ul>
</cs-dialog-group>

censhare 5 Directives

Styleguide

• URL: http://SERVERPATH/censhare5/client/styleguide

• Coding reference for censhare 5 Web frontend

• Defines basic principles and rule sets for HTML and CSS code

• Two parts

  • Styleguide: Rulesets, coding conventions and user experience principles

  • Pattern Library: Definitions and examples for all types of structures and their combinations, based on Atomic Design

• Benefits

  • We can build features consistently, focus our energy on business logic and workflows instead of pixel alignment or table stylings.

  • We reuse existing code and do not have to reinvent design elements and UI components.

  • For testing purposes we can see our front end code in one place, quickly revealing styling issues.

Directives

Reference of metadata related censhare UI directives:

<cs-groupbox title="group box">
  Group box content
</cs-groupbox>

<cs-expandgroup title="Expand group" expanded="false">
  Expand group content
</cs-expandgroup>

<cs-dialog-group title="Dialog group">
  Dialog group content
</cs-dialog-group>

<cs-input 
   ng-model="asset.traits.display.description.value[0].value" 
   label="Description" 
   multilines="3">
</cs-input>

<cs-select 
   label="Type" 
   ng-model="select01" 
   ng-options="type.name for type in data.assetTypes" 
   placeholder="Select a value">
</cs-select>

<cs-multiselect 
   placeholder="cs-multiselect" 
   values="example.value" 
   options="example.options">
</cs-multiselect>

<cs-hierarchical-value 
   ng-model="relation.type" 
   data="relationTypes">
</cs-hierarchical-value>

<cs-checkbox 
   label="Example checkbox" 
   ng-model="example.checkbox" 
   value="1">
</cs-checkbox>

<cs-radio 
   label="Example button" 
   ng-model="example.radio" 
   value="value">
</cs-radio>

<cs-datepicker 
   required show-weeks="true" 
   format="YYYY/MM/DD" 
   ng-model="example.date01">
</cs-datepicker>
<cs-datepicker-table 
   show-weeks="true" 
   ng-model="example.date02">
</cs-datepicker-table>

<cs-timepicker 
   ng-model="example.time">
</cs-timepicker>

<cs-colorpicker 
   ng-model="example.colors01">
</cs-colorpicker> 
<cs-colorpicker 
   palette-model="examplePalette" 
   custom-input ng-model="example.colors02">
</cs-colorpicker>

examplePalette: [
  ['#334433', '#6699aa', '#88aaaa', '#aacccc', '#447799'],
  ['#225533', '#44bbcc', '#88dddd', '#bbeeff', '#0055bb']
]

<cs-color value="#000000"></cs-color>

<cs-toggle 
   title-off="no" 
   title-on="yes" 
   ng-model="example.toggle">
</cs-toggle>

<cs-rating ng-model="example.rating"></cs-rating>

<cs-slider 
   min="0" 
   max="10" 
   step="1" 
   ng-model="relation.type">
</cs-hierarchical-value>

<cs-button 
   type="cta" 
   ng-click="click()">
</cs-button>

<cs-button-group>
  <cs-button ng-click="click()">Left</cs-button>
  <cs-button ng-click="click()">Right</cs-button>
</cs-button-group>

<cs-progress 
   progress="40" 
   ng-model="example.progress">
</cs-progress>

<cs-workflow-state 
   asset="example.asset">
</cs-workflow-state>
<cs-workflow-state 
   workflow-state-id="example.id">
</cs-workflow-state>

<cs-worst-workflow-state 
   data="example.asset">
</cs-worst-workflow-state>

<cs-multivalue-repeat 
   value="asset.traits.address.address.value[0].addressType">
      <ul>
         <li class="csDialogForm__row">
             <cs-input 
                 ng-model="value.zipCode.value[0].value">
             </cs-input>
             <cs-input 
                 ng-model="value.city.value[0].value">
             </cs-input>
        </li>
     </ul>
</cs-multivalue-repeat>

<cs-multivalue-repeat 
   value="asset.traits.address.address.value[0].addressType">
      <ul>
         <li class="csDialogForm__row">
             <cs-input 
                 ng-model="value.zipCode.value[0].value">
             </cs-input>
             <cs-input 
                 ng-model="value.city.value[0].value">
             </cs-input>
        </li>
     </ul>
</cs-multivalue-repeat>

cs-metadata-row
Description	Creates a row for an asset metadata information with automatic mapping of standard control elements, depending on the value type
Syntax	cs-metadata-row
Parameters	property: The property to edit in this row row-label: Custom label for the row read: Render in read only view translate-prefix: Prefix of a translation key for the value, for read only filter: Filter to apply, fo read only hide-root: Hides root value, only for hierarchical (cs-hierarchical-value) values multilines: Renders a textarea with the number of rows given by this attribute, only for String values.
Example	CODE <cs-metadata-row read property="asset.traits.type.type"> </cs-metadata-row> <cs-metadata-row read property="asset.traits.display.color"> </cs-metadata-row> <cs-metadata-row required property="asset.traits.display.name"> </cs-metadata-row> <cs-metadata-row property="asset.traits.display.description"> <cs-input multilines="3" ng-model="property.value[0].value"> </cs-input> </cs-metadata-row> <cs-metadata-row read property="asset.traits.type.type"> </cs-metadata-row>
The following mappings of value types are available for the cs-metadata-row directive: Hierarchical attribute (String) cs-hierarchical-value with cs-multiselect Enumeration (String) cs-select or cs-multiselect with cs-radio Integer (Long) cs-input String cs-input Timestamp cs-datepicker and cs-timepicker Boolean cs-checkbox Double cs-input Date cs-datepicker