OpenWGA 7.5 - OpenWGA Concepts and Features

Collections show you links and other data of a number of resources. These might be documents, file attachments, relation groups or other. However the structure how these collections are built is always the same:

Also, the functionalities that work on collections are mostly the same:

Pageability

Most collections are "pageable" - identified by the attribute of same name on the reference object. This means that the collection will not put out the whole contents of the collection. Instead only a maximum of 10 entries are put out at once. The next "page" of the resultset is then offered as URL in a property "nextPage". So to completely retrieve a collection you might need to follow some page URLs. However this is better in most cases nevertheless than retrieving a very large collection at once. You could already use the data of the page you just retrieved, to display it for example, while retrieving even more data. This ensures that your app can react quickly and also may prevent resource exhaustion on both sides, client and server.

There are a couple of URL-Parameters which you can add to the URL to influence paging behaviour:

• autoScroll="number" - Enables the autoscroll feature. See feature "Autoscroll".
• offset="index" - The index of the first entry to display in this collection. This normally is not used directly but implicitly by paging URIs. 
• size="pagesize" - Controls the maximum amount of entries to be returned per page. Defaults to 10.

Autoscroll

This can be used for collections which have property "supportsAutoScroll" to true. It is intended for collections where new entries are always added to the top of the collection - think of streams of postings, ordered by descending posting date. It allows gap-free scrolling through the results in situations where there are entries frequently added to the collection. Regular paging, which is index based, therefor would often put out the same entries twice because an entry of index 9 becomes the entry of index 10, 11, 12 in short time and suddenly is part of the next page.

Autoscroll prevents this by adding the ID of the next pages' first entry to the paging URI. When calling this URI OpenWGA knows what was suspected as the next entry. If it does not find this entry at the beginning of the next page it scrolls forward until it finds it. Then it starts the page from this point.

Autoscroll is enabled by adding a URL parameter autoScroll=number to the collection URL. The number denotes the number of steps that OpenWGA may scroll forward in order to find the entry. If it cannot find the entry in these steps - it may have been pushed down even further or deleted - the call fails with HTTP error code 412. At this time you rest client may decide to load the whole collection anew.

Enhancing output

If the resources that your collection shows are documents then there are some ways to enhance the data that is shown about each individual resource right inside the collection. If you only need a number of items and metadata fields from these documents then you can enhance the collection to directly give you all data you need and do not need to retrieve the resources themselves.

Enhancing is controlled using the following URL-Parameters:

• enhancer=enhancerName - Calls a custom enhancer for each single document which may add custom fields. See feature "Custom collection enhancers".
• item=itemName - On content collections this will add the value of the given item field for each document to the collection. May be used multiple times on the URL with differing item names.
• meta=metaName - Adds the value of the given metadata field for each document to the collection. May be used multiple times on the URL with differing metadata field names.
• relation=relationName - On content collections this will add the URI of target of the the given relation for each document to the collection. May be used multiple times on the URL with differing relation names.

See the following example of adding "meta=title&item=description" to the URL of the HDBModel example application for REST. This is a single reference inside this collection. The added data is printed in bold:

Custom collection enhancers

These are TMLScript functions that are called for each individual reference of a collection. They may add custom items and metadata fields to the reference that they generate by arbitrary functionalities.

To create a custom enhancer:

• Create a TMLScript module in your design on path "scripts/tmlscript/wga/rest/collection-enhancers.tmlscript"
• The contents of this module is a Custom TMLScript object of which every method is a separate custom collection enhancer. The name of the enhancer is the method name.
• Each method receives two parameters:
• A RESTReference object representing the reference that is to be added to the collection
• The WGAPI object of the document resource that this reference points to. For example, a WGContent for content documents.
• By using the methods on the RESTReference object the script can add custom items, metadata fields and relations to the reference to display.

An example of a custom collection enhancer "imageURL" which adds the URL to the primary file attachment of a content document as item "imageurl" to the reference:

This enhancer could be used on any collection by adding it the URL parameter "enhancer=imageURL".