MetadataHandler

The MetadataHandler encapsulates and provides access to a set of metadata items needed by client-side apps in Go-Lab. In particular, these metadata items are also required by the ActionLogger (to add it to the action log) and by the StorageHandler (to add it to stored artefacts). Typical metadata items would be the name and identifier or the current user, name and identifier of the current working document, the current ILS etc.
Every instance of an app creates its own MetadataHandler, and passes it on to the ActionLogger and StorageHandler.
An app is responsible to update the information in the MetadataHandler in case of changes. At the moment of writing this, this is only necessary when an artefact is stored and given a new name (cf. setTargetDisplayName()).

What's in the metadata?

The metadata is based on the Activity Streams specification, since this is used for action logging as well and thus brings consistency by design. The metadata consists of the following sections:

• actor: holds information about the current user
• target: holds information about the current working document
• generator: holds information about the current app
• provider: holds information about the current context (i.e., the ILS)

Technical representation

In the current implementation, the metadata is represented as a JSON object. Using JSON integrates well with other technologies for the development of web-based applications, in particular with JavaScript. In addition, JSON can be serialised and parsed easily, while it still remains human-readable. The following MetadataHandler API returns and accepts the metadata items or metadata sections in JSON.
An example can be found [here](example metadata).

Creating a MetadataHandler

Currently, the MetadataHandler is created with a given set of metadata items. In future implementations, an increasing number of items will be automatically set through the ILS Metawidget API. For this reason, the construction of the MetadataHandler is handled asynchronously, requiring a callback function at construction time. The following code fragment illustrates this approach:

var hypothesisToolMetadataHandler;

new golab.ils.metadata.GoLabMetadataHandler({
  "actor": {
    "objectType": "person",
    "id": "e1b8948f-321e-78ca-d883-80500aae71b5",
    "displayName": "anonymized"
  },
  "target": {
    "objectType": "hypotheses",
    "id": "4b8f69e3-2914-3a1a-454e-f4c157734bd1",
    "displayName": "unnamed hypotheses"
  },
  "generator": {
    "objectType": "application",
    "url": "http://www.golabz.eu/app/hypothesis-tool",
    "id": "c9933ad6-dd4a-6f71-ce84-fb1676ea3aac",
    "displayName": "hypothesisScratchpad"
  },
  "provider": {
    "objectType": "ils",
    "url": "http://graasp.epfl.ch/metawidget/1/b387b6f",
    "id": "10548c30-72bd-0bb3-33d1-9c748266de45",
    "displayName": "unnamed ILS"
  }}, function(error, metadataHandler) {
      if (error != undefined) {
        console.error ("Something went wrong when creating the MetadataHandler: "+error);
      } else {
        hypothesisToolMetadataHandler = metadataHandler
      }
  })

API

---

#### setMetadata(newMetadata: object): void Sets a new, complete set of metadata in the MetadataHandler.

`newMetadata: object` The new metadata JSON object to be set in the MetadataHandler

---

#### getMetadata(): object Returns the complete JSON metadata object.

---

#### getActor(): object Returns the 'actor' sub-section of the metadata.

---

#### getGenerator(): object Returns the 'generator' sub-section of the metadata.

---

#### getProvider(): object Returns the 'provider' sub-section of the metadata.

---

#### getTarget(): object Returns the 'provider' sub-section of the metadata.

---

#### setTarget(newTarget: object): void Sets a new 'target' sub-section in the metadata object.

`newTarget: object` The new 'target' sub-section JSON object to be set in the MetadataHandler

Note: Typically, only the 'target' metadata (describing the current working document) changes during a tool's lifecycle. If other metadata sections change dynamically in future, more functions like this will be added.

---

#### getTargetDisplayName(): string A convenience function that directly returns the displayName of the 'target' sub-section (i.e. the current document name).

---

#### setTargetDisplayName(newName: string): void A convenience function to directly set a new displayName of the 'target' sub-section (i.e. setting a new document name).

`newName: string` The new target's displayName to be set in the MetadataHandler

---