# External

External type is designed for more complex data structure which might require the Producer to traverse through a categories tree (navigation) in order to narrow down data subset (data). These have the following attributes:

|        |                                                                                                                                           |
| ------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| source | <p>An object which specifies the location of the navigation and data feed.</p><p>Note that only <code>GET</code> method is supported.</p> |
| select | An object which controls what data selection mechanism is to be used.                                                                     |

`select` has these properties:

|           |                                                                                                                                                                                                                                                                                                                                                                                                        |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| mode      | <p>Defines how data selection mechanism should be implemented. Supported modes:</p><ul><li><code>list</code> one or more items from a list selected manually by Producer</li><li><code>dropdown</code> one item from a drop down selected manually by Producer</li></ul>                                                                                                                               |
| min       | Minimum number of items that Producer can select from a list for `list` mode                                                                                                                                                                                                                                                                                                                           |
| max       | Minimum and maximum number of items that Producer can select from a list for `list` mode                                                                                                                                                                                                                                                                                                               |
| filtering | <p>Controls data filtering mechanism. This works over keywords specified for data items and is supported only for <code>list</code> mode. Possible values:</p><ul><li><code>off</code> no filtering supported</li><li><code>freetext</code> free text entry with autocomplete</li><li><code>checkbox</code> a checkbox for each keyword</li><li><code>dropdown</code> a dropdown of keywords</li></ul> |

{% hint style="danger" %}

#### Filtering is not yet supported

{% endhint %}

### Example

```javascript
{
  "key": "podium",
  "type": "external",
  "source": {"url": "https://example.com/feeds/podium.json", "method": "get"},
  "select": {
    "mode": "list",
    "min": 2,
    "max": 2,
    "filtering": "off"
   }
}
```

### Navigation

Navigation is a hierarchy of categories. At the bottom of the navigation tree there is a layer of data for that navigation tree branch. Hierarchy is optional.

Both hierarchy and data can be split between several feeds. This allows to partition feeds in a flexible way to meet size or architecture restrictions. This is done by providing `categories-source` or `data-items-source` attributes.

Navigation object has these properties:

|                   |                                                                                                                                                               |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| categories-label  | Dropdown labels for category selection.                                                                                                                       |
| categories        | <p>An array of categories entries, used to populate</p><p>categories dropdown.</p>                                                                            |
| categories-source | <p>Source object with an url pointing to JSON feed</p><p>containing categories data array. This is ignored if</p><p><code>categories</code> is specified.</p> |
| name              | Name of a category as to be displayed in a dropdown.                                                                                                          |
| data-items        | An array of data entries.                                                                                                                                     |
| data-items-source | <p>Source object with a URL pointing to JSON feed</p><p>containing data entries array. Ignored if <code>data-items</code></p><p>is specified.</p>             |

### Data

|          |                                                                    |
| -------- | ------------------------------------------------------------------ |
| id       | An arbitrary id which can be used for debug/data tracing purposes. |
| name     | Name of this data item to be presented to the Producer.            |
| data     | Actual data                                                        |
| keywords | Array of keywords used for filtering.                              |

### Examples

#### Non-hierarchical data example

```javascript
[
    {
      "id": "a1",
      "name": "Player 1 name",
      "data": "some data here",
      "keywords": [ "keyword1", "keyword2"]
    },
    {
      "id": "b2",
      "name": "Player 2 name",
      "data": "some data",
      "keywords": [ "keyword1", "keyword2"]
    }
]
```

#### Hierarchical structure example

The following feed describes this hierarchy:

1. First layer - discipline selection of “Hockey” and “Figure Skating”, labelled “Discipline”
2. Second layer for Hockey - event selection of “Men’s tournament” and “Women’s tournament”, labelled “Events”
3. Third layer for “Men’s tournament” - match selection of “Men’s Gold Medal Game” and “Men’s Bronze Medal Game”, labelled “Match”
4. Fourth layer for “Men’s Gold Medal Game” is the data layer. It lists two items of data.

```javascript
{
  "categories-label": "Discipline",
  "categories": [
    {
      "name": "Hockey",
      "categories-label": "Event",
      "categories": [
        {
          "name": "Men's tournament",
          "categories-label": "Match",
          "categories": [
            {
              "name": "Men's Gold Medal Game",
              "data-items": [
                {
                  "id": "a1",
                  "name": "Player 1 name",
                  "data": "some data here",
                  "keywords": [ "keyword1", "keyword2"]
                },
                {
                  "id": "b2",
                  "name": "Player 2 name",
                  "data": "some data",
                  "keywords": [ "keyword1", "keyword2"]
                }
              ]
            },
            {
              "name": "Men's Bronze Medal Game",
              "data-items-source": {"url": "http://example.com/feeds/mbmg.json", "method": "get"}
            }
          ]
        },
        {
          "name": "Women's tournament",
          "categories-label": "Event",
          "categories-source": {"url": "http://example.com/feeds/wt.json", "method": "get"}
        }
      ]
    },
    { 
      "name": "Figure Skating",
      "label": "Events",
      "categories": {"url": "http://example.com/feeds/fs.json", "method": "get"}
    }
  ]
}
```

The categories data feed ([http://example.com/feeds/wt.json\\](http://example.com/feeds/wt.json/)) might look like this:

```javascript
[
    {
      "name": "Women's Gold Medal Game",
      "data-items": [
        {
          "id": "a1",
          "name": "Player 1 name",
          "data": "some data here",
          "keywords": [ "keyword1", "keyword2"]
        },
        {
          "id": "b2",
          "name": "Player 2 name",
          "data": "some data",
          "keywords": [ "keyword1", "keyword2"]
        }
      ]
    },
    {
      "name": "Women's Bronze Medal Game",
      "data-items-source": {"url": "http://example.com/feeds/wbmg.json", "method": "get"}
    }
]
```

The data feed ([http://example.com/feeds/mbmg.json\\](http://example.com/feeds/mbmg.json/)) might look like this:

```javascript
[
    {
      "id": "a1",
      "name": "Player 1 name",
      "data": "some data here",
      "keywords": [ "keyword1", "keyword2"]
    },
    {
      "id": "b2",
      "name": "Player 2 name",
      "data": "some data",
      "keywords": [ "keyword1", "keyword2"]
    }
]
```