# Structured Text Feed

Structured text feeds are more complex text structured organized in categories, where each category contains a list of entries, and each entry contains a title and a content. The content of a structured text feed is equivalent to the `text` property in the [simple text feed](./simple-text.md).

## Example JSON

<img width="600" src="../../_static/feeds/structured.png" />

The example above shows a structured text feed with two categories (Wissen and Umwelt), the Wissen category shows three visible entries. The second entry is expanded, so its content is visible. Each entry’s title is shown.

```json
{
  "apiVersion": 1,
  "categories": [
    {
      "id": "umwelt",
      "label": {
        "de": "Umwelt"
      },
      "entries": {
        "en": [
          {
            "id": "category_1_entry_1",
            "title": "category_1 entry_1 title text",
            "content": "category_1 entry_1 rich text content"
          },
          {
            "id": "category_1_entry_2",
            "title": "category_1 entry_2 title text",
            "content": "category_1 entry_1 rich text content"
          }
        ],
        "de": []
      }
    },
    {
      "id": "wissen",
      "label": {
        "de": "Wissen"
      },
      "enableAnchor": true,
      "entries": {
        "de": [
          {
            "id": "category_2_entry_1",
            "title": "Unis bekommen mehr Budget",
            "content": "Dieses Jahr bekommen zahlreiche Unis mehr Budget"
          }
        ]
      }
    }
  ]
}
```

## Validations

- `apiVersion` must be set to 1 (as a number, not a string)
- `id` of a category is a string value and mandatory
  - This `id` needs to be unique within the whole feed
  - This `id` will be used as the html anchor in the URL (e.g. `#wissen`)
  - This needs to be a string ID (e.g. `"id": "0"`) and not numeric (e.g. `"id": 0`)
  - `enableAnchor` is boolean, optional and defaults to `false`
    - If `true` -> the category will be included as an anchor of the widget (similar to simple text widget) and thus be visible in the 2nd menu level using the text from the `label` property
    - If `false` -> the category will not be linked/visible in the 2nd menu level
  - `label` is an object and optional, except if `enableAnchor` is true, then it is mandatory, and must contain at least the default language of the captive portal page (this depends on the customer’s project)
    - The object maps language codes (ISO 639-1) to label strings
      - Each label string is mandatory for each provided language code property
    - This property will be used to render the anchor in the 2nd menu level
    - Allowed html entities:
      - soft hyphen: `&shy;`
  - List of entries:
    - For each language an array of entries must be provided
    - The array of entries for a specific language can be empty
    - The languages must match the languages in the `label` property if `enableAnchor` is `true`
    - For a single entry:
      `content` is string and mandatory
    - It is equivalent to the `text` property of the simple text widget described above
    - It’s recommended to not use the `h1` tag, as the title of the entry already uses `h1`
    - `title` is string and mandatory
    - This is rendered as an entry’s title text which can be expanded to view the content
    - This entry does not support rich text or html tags
      - Allowed html entities:
      - soft hyphen: `&shy;`
      - `id` of an entry is a string value and mandatory
      - This `id` needs to be unique within the whole feed, not just within the category.

## Internationalization Validations

If an entry is present in a certain language, and enableAnchor is true, then labels must be translated in the same languages as the entries and vice versa.
At least one language must be present.

The JSON example [above](./structured-text.md#example-json) shows:

- The feed contains two categories
- The first category contains two entries for English and zero for German
- The second category contains one entry for German
- The second category has the `enableAnchor` property set to `true`

The interpretation of this feed data is:

Two categories are shown below each other (see screenshot example above)
Only the category with the `id="wissen"` will be shown in the 2nd menu level, because its `enableAnchor` property is set to `true`.

## POI extensions

The POI extensions to the structured text feed allow matching individual entries to POI properties (e.g. stop name, stop id). Entries will be shown if any of the given matchers within the `POI_match` property matches.

To disable the `POI_match` feature, the property must not be present in the JSON document. An empty `POI_match` (e.g. `"POI_match": []`), will never show the entry.

Currently supported matching properties:

- `stop.id` (arbitrary id that must match the journey feed)
- `stop.ibnr` (if present in journey feed)
- `stop.ds100` (if present in journey feed)
- `stop.name`

Currently supported matching behavior:
Match any … matched string has to exactly match the property value, any matcher within the `POI_match` property can match to show the POI.

JSON structure:

- `POI_match` contains an array of matchers
  - Can be used within the entry object (see above)

Example POI_match:

```javascript
{
  // ...
  "POI_match": [
    { "stop": { "id": "VIE" } },
    { "stop": { "name": "Naumburg (Saale) Hbf." } }
  ]
  // ...
}
```

In this example the match contains two matchers, one matching the Stop’s ID property to `VIE` and another one that matches the stop’s name property to `Naumburg (Saale) Hbf.`. This `POI_match` would then show the entry if either condition was fulfilled.

Example JSON of structured text feed with `POI_match` extension:

```json
{
  "apiVersion": 1,
  "categories": [
    {
      "id": "umwelt",
      "label": {
        "de": "Umwelt",
        "en": "Environment"
      },
      "entries": {
        "en": [
          {
            "id": "category_1_entry_1",
            "title": "category_1 entry_1 title text",
            "content": "category_1 entry_1 rich text content",
            "POI_match": [{ "stop": { "id": "VIE" } }]
          },
          {
            "id": "category_1_entry_2",
            "title": "category_1 entry_2 title text",
            "content": "category_1 entry_1 rich text content",
            "POI_match": [
              { "stop": { "id": "VIE" } },
              { "stop": { "name": "Naumburg (Saale) Hbf." } }
            ]
          }
        ]
      }
    },
    {
      "id": "wissen",
      "label": {
        "de": "Wissen",
        "en": "Education"
      },
      "enableAnchor": true,
      "entries": {
        "de": [
          {
            "id": "category_2_entry_1",
            "title": "Unis bekommen mehr Budget",
            "content": "Dieses Jahr bekommen zahlreiche Unis mehr Budget",
            "POI_match": [{ "stop": { "name": "Naumburg (Saale) Hbf." } }]
          }
        ]
      }
    }
  ]
}
```

## Content revisions table

| Revision | Published date | Changes                                                                                                                       |
| -------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| 1.0      | 2018-07-01     | initial release                                                                                                               |
| 1.1      | 2018-09-08     | added POI information, clarified content                                                                                      |
| 1.4      | 2019-01-16     | added DS100 and IBNR match options for POI                                                                                    |
| 1.5      | 2019-01-19     | clarified on how to disable the POI_match feature<br>added support for soft hyphens<br>added support for video and audio tags |
| 1.6      | 2020-09-02     | added newsarticle\_\_lead<br>content-type header requirement                                                                  |
| 1.7      | 2023-08-31     | moved to public docs                                                                                                          |