Collection Types Definition

A detailed look into the structure and usage of collection type definitions: The data structure in yaml looks as follows:

---
id: MY_COLLECTION_TYPE
name: My Test Collection
description: A collection type for tutorial purposes

allowAllTags: false
permittedTags:
  - Tag 1
  - Tag 2

editableMetadata:
create:
edit:
  - key: my.element.metadata
    label: My Property
  - key: other.metadata
    label: Multiselect property
    options:
      - Option 2
      - Option 1

globalRules:
  - type: javascript
    name: global_rules
    scriptCode: |
      // global rules go here to be reused in multiple locations

eventRules:
  - type: javascript
    name: my_event
    scriptCode: |
      // custom event code goes here

views:
  - name: Example View 1
    elementRules:
      - type: javascript
        name: simple hierarchy
        scriptCode: |
          // element rules execute on each element once
        treeRules:
      - type: javascript
        name: sort rule
        scriptCode: |
          // tree rule

The Fields in Detail

id:

A unique name which has to match the requested type define in all corresponding collections. (Case sensitive!)

name:

A human-readable name for the collection type.

description:

A description for the collection type to describe its use case.

Tags:

Tags are a fixed property of collections. A collection can have no, one or multiple tags. These tags have no predefined functionality but a predefined UI to set and modify them. The idea is that these tags are used to group and sort elements in the collection. The exact rules have to be defined in the later sections of the collection type definition.

• allowAllTags:

  A boolean Flag which indicates if the collection allows any tag or only predefined ones. If this variable is set to true the user is able to enter a custom text for a tag. these Tags are the available throughout the collection.

• permittedTags:

A list of predefined tags to pick from. these Tags are permitted even when "allowAllTags" is set to false. These Tags are also always shown as an option even if no collection element currently owns this tag.

editableMetadata:

Editable Metadata is another predefined mechanism with an included UI for the user to modify the metadata of a collection element. All Metadata that can be modified by the user, has to be defined here.

• create:

  Metadata defined below the "create" field can be set even if the collection does not have this field initially. The field will be added to the elements metadata when saved.

• edit:

  Metadata defined below the edit field can be modified when the collection owns a corresponding metadata field. If the collection does not have this field initially the metadata can not be created when defined here.

  • Metadata entries:

    key: this is the corresponding key in the metadata structure which represents this entity
    label: here a readable text can be set to label the entity in the UI
    options: this field is optional and can set predefined values for the entity. This implicitly disallows any free text to be set for the variable.

globalRules:

To prevent writing duplicate code in multiple Views this section can be used to declare function which can be used afterward tn the event, element and tree rules. These functions can be defined in plain JavaScript.

A simple example for a function definition would look like this:

globalRules:
- type: javascript
  name: getTitleFromMetadata
  scriptCode: |
    const getTitle = function(element) {
      return element.metadata.title ? element.metadata.title : 'unknown Document';
    };

Another Use of this section is to define some code that is executed once before the assembly of the tree layout. For example:

- type: javascript
  name: createTitle
  scriptCode: |
    titleVisualization('html', '<em>' + collection.metadata.title + '</em> ');
    titleVisualization('text', collection.metadata.title);

eventRules:

These event rules can be used on Custom events. there are currently no fixed event rules and so thy must me implemented on the client side using the fusion SDK. the rules always represent a singular executable JavaScript fusion.

A simple Example would look like this:

eventRules:
- type: javascript
  name: setElementTypeToModifiable
  scriptCode: |
    if (element != null) {
      element.metadata.modifiable = true;
    }

views:

Views represent a selectable layout to display the collection in. this includes the tree hierarchy, sorting and titles for structure nodes and documents. Also, some behavioural changes can be made here like hooks on certain events and the initial state of branches in the tree. More on these configuration options tn the JS API section below.

• elementRules:

  Element rule give the tree its structure. This Function is executed on each element once and allows the element to define its position in the tree.

• treeRules:

  These tree rules allow post-processing of the tree after the element rules are already applied. Here things like empty structure node can be inserted, where no element is involved. This is also the place to sort nodes alongside siblings, because in the element rules only the hierarchy is defined but not the order of siblings. The tree rules are optional and if no rules are defined here the resulting order is the same as the definition in the collection, which is not always what we want.

A simple Example would look like this:

views:
  - name: Standard
    elementRules:
      - type: javascript
        name: All elements chronologically
        scriptCode: |
          createElementNode(element)
          .withVisualization('html', getTitle(element))
          .withProperty('sort-by-date', element.dateCreated.getTime());
        treeRules:
      - type: javascript
        name: Sort chronological branch chronologically
        scriptCode: |
          sorter().sort(function(a,b) {
            return a.properties['sort-by-date'] - b.properties['sort-by-date'];
          });

JS API:

Now we know which options we have to define rules we want to have a closer look at the available API we can use to modify the collection type to our needs.

API Variables:

collection: A collection data object containing the exact content of the json interpretation you use in REST API operations. (see: Creating Collections)

This variable as always available and can be used to make references against the current collection.

element: A collection element data object that is part of the collection. this is mainly used in the elementRules where it references the current element in the iteration.

These elements are the same that are also available over the collection variable. This additional variable acts as a pointer and provides ease of access to the current element in element specific rules.

API Functions:

findNode(...path?: string[]): Node : Provides access to a node if a path is provided any node that is a child of the root node can be accessed by providing an array of Strings which represent the Ids of all parent nodes as a path to the desired element. The root node can be accessed by calling this method without a path (or an empty path).

createNode(...path?: string[]): Node : Creates one or more Structure nodes. The provided path is created, if the path does not already exist. all stings in the path represent the ids of the structure nodes. Structure nodes don't have an element attached andy only act as intermediate nodes to structure actual element nodes.

• Node

  Node is the main class that represents a node in the tree an offers various builder and utility functions to create and customize the tree view of a collection type. the exact definition of this class can be found here: Node Class

createElementNode(e: Element, ...path?: string[]): Node : this functions allow you to create an element node which represents a leaf in the three where most commonly a document is attached. if a path is provided the element will be attached to the specified structure nodes. The element is a collection-element accessible via the 'collection' or 'element' API variable.

titleVisualization(key: string, value: string): void : This function should preferably be called in the global rules section to define a collection title. It is possible st define multiple representations of the title depending on the use case. for this we recommend to at leased define a 'text' and 'html' representation. The html representation will be used to display the collection title in the main ui, the text version is used for example as the tab title. the two parameters define the key, which represents the format and the value which represents the actual formatted representation.

sorter(): Sorter : Creates a sort API builder.

• Sorter

  The sorter Builder class is used to easily define sorting rules based on hierarchy levels in the tree. The base sorter returned by sortert() will return a sorter for the entitlements on the first hierarchy or all children of the root node. you can use a assortment of predefined sorting algorithms or define your own. Functions of the sorter:

  • presetSort(sortType: SortType, type?: string): Sorter : which allow sorting with the predefined sorting algorithms. At the moment SortType.Alphabetically and SortType.AlphabeticallyReversed are supported. Optionally you can define a type which corresponds to the node visualization key defined earlier.

  • propertySort(property: string): Sorter : sorting based on a property value. these Properties can be set on the node object. the Sorting of these properties is supported for numeric, boolean and text types.

  • sort(compareFn?: (a: Node, b: Node) => number): Sorter : This is the function for defining your own custom sort logic. you can define your own lambda function: A function that defines the sort order. The return value should be a number whose sign indicates the relative order of the two elements: negative if a is less than b, positive if a is greater than b, and zero if they are equal.