Composer Text Annotations

Text annotations in Composer let you insert in-line metadata so you can tag words or phrases with information from an externally-managed database. For example, if you have a database of entries for data such as stock tickers or celebrities, you can highlight text within your Composer story and tag that text with the metadata ID from your database.

As a Composer user, when you highlight text, click the book icon to open the annotations modal. There, you find the categories of content that your administrators set up. The search boxes below offer type-ahead search of your dataset, providing two layers to drill down into, which your administrators configure. After you select your desired annotation, click Add annotation. Then you see the annotated text marked in blue with the option to edit or remove the annotation when you click the highlighted text. 

Within Composer Settings, you can manage your data types under the Annotations section.

When you add a new annotation type, you must enter a name, which displays in the Composer UI as the annotation category type. Additionally, you must provide a link to a publicly hosted JSON file containing your dataset.

Format the JSON as follows: 

{
  "categoryId": "value",
  // other metadata that you wish to add
  "items": [
    {
      "id": "value",
      "title": "value",
      "description": "value",
      "children": [
       {
          "id": "value",
          "title": "value",
          "description": "value",
        }, 
        {
          "id": "value",
          "title": "value",
          "description": "value",
        }
      ],
      ...
    },
    ...
  ]
}

You can create two levels of categorization: a parent and child. For example, you might include a stock ticker and countries where that stock is traded. Composer requires that you adhere to this format. If you do not follow this format, the functionality does not work. Composer validates the shape of the JSON when you add the category to Settings.

categoryId, items.id, and children.id can support spaces but not special characters.

When you add an annotation as in-line text, this HTML mark is inserted in-line with your text within the story ANS:

<mark data-annotation-category="categoryId" data-annotation-item="itemId" data-annotation-child="childId">Text</mark>

Example: 

<mark data-annotation-category="tickers" data-annotation-item="msft" data-annotation-child="usa">Microsoft (USA)</mark>

Within the Annotations section in Composer Settings, you can add your JSON endpoint (we recommend S3) that you use for the library. You are responsible for managing the external process of updating the contents of the JSON endpoint, as that database management process is outside of Composer’s scope.