open-consul/ui/packages/consul-ui/app/components/data-source/README.mdx

# DataSource

Use the `@dataSource` decorator in your repositories to define URI to async
method mapping.

```javascript
class SomethingRepository extends Service {
  @dataSource('/:partition/:nspace/:dc/services')
  async youCouldCallItAnythingTodoWithGettingServices(params) {
    console.log(params);
    // {partition: "partition", nspace: "nspace", dc: "dc"}
    return getTheThing(params);
  }
}
```

```hbs preview-template
<DataSource
  @src={{uri "/partition/nspace/dc/services"}}
  @loading="eager"
  @disabled={{false}}
as |source|>
{{#each source.data as |service|}}
{{service.Name}}<br />
{{/each}}
</DataSource>
```


Please make sure you use the `uri` helper to specify src URIs, this ensures that it is very difficult to miss any URL encoding problems. If you don't use the `uri` helper then an error will be thrown.

## Attributes

| Argument | Type | Default | Description |
| --- | --- | --- | --- |
| `src` | `String` | | The source to subscribe to updates to, this should map to a string based URI |
| `loading` | `String` | eager | Allows the browser to defer loading offscreen DataSources (`eager\|lazy`). Setting to `lazy` only loads the data when the DataSource is visible in the DOM (inc. `display: none\|block;`) |
| `disabled` | `Boolean` | true | When disabled the DataSource is closed |
| `open` | `Boolean` | false | Force the DataSource to open, used to force non-blocking data to refresh (has no effect for blocking data) |
| `onchange` | `Function` |  | The action to fire when the data changes. Emits an Event-like object with a `data` property containing the data. |
| `onerror` | `Function` |  | The action to fire when an error occurs. Emits ErrorEvent object with an `error` property containing the Error. |

## Exported API

| Name | Type | Description |
| --- | --- | --- |
| `data`  | `object` | The loaded dataset once any data has been loaded successfully |
| `error` | `Error` |The error thrown if an error is encountered whilst loading data |
| `invalidate` | `function` | Invalidate the data represented by the datasource, therefore forcing a re-request of data for the DataSource |

The component takes a `src` or an identifier (a uri) for some data and then emits `onchange` events whenever that data changes. If an error occurs whilst listening for data changes, an `onerror` event is emitted.

Setting `@loading="lazy"` uses `IntersectionObserver` to activate/deactive event emitting until the `<DataSource />` element is displayed in the DOM. This means you can use CSS `display: none|block;` to control the loading and stopping loading of data for usage with CSS based tabs and such-like.

Consuls HTTP API DataSources use Consul's blocking query support for live updating of data.

Behind the scenes in the Consul UI we map URIs back to our `ember-data` backed `Repositories` meaning we can essentially redesign the URIs used for our data to more closely fit our needs. For example we currently require that **all** HTTP API URIs begin with `/dc/nspace/` values whether they require them or not.

`DataSource` is not just restricted to HTTP API data, and can be configured to listen for data changes using a variety of methods and sources. For example we have also configured `DataSource` to listen to `LocalStorage` changes using the `settings://` pseudo-protocol in the URI (See examples below).


## Examples

Straightforward usage can use `mut` to easily update data within a template using an event handler approach.

```hbs
  {{! listen for HTTP API changes}}
  <DataSource
    @src={{uri "/partition/nspace/dc/services"}}
    @onchange={{action (mut items) value="data"}}
    @onerror={{action (mut error) value="error"}}
  />
  {{#if error}}
    Something went wrong!
  {{/if}}
  {{#if (not items)}}
    Loading...
  {{/if}}
  {{! the value of items will change whenever the data changes}}
  {{#each items as |item|}}
    {{item.Name}} {{! < Prints the item name }}
  {{/each}}

  {{! listen for Settings (local storage) changes}}
  <DataSource
    @src={{uri "settings://consul:token"}}
    @onchange={{action (mut token) value="data"}}
    @onerror={{action (mut error) value="error"}}
  />
  {{! the value of token will change whenever the data changes}}
  {{token.AccessorID}} {{! < Prints the token AccessorID }}
```

A property approach to easily update data within a template

```hbs
  {{! listen for HTTP API changes}}
  <DataSource
    @src={{uri "/partition/nspace/dc/services"}}
  as |source|>
    {{#if source.error}}
      Something went wrong!
    {{/if}}
    {{#if (not source.data)}}
      Loading...
    {{/if}}
    {{! the value of items will change whenever the data changes}}
    {{#each source.data as |item|}}
      {{item.Name}} {{! < Prints the item name }}
    {{/each}}
  </DataSource>
```

Both approaches can be used in tandem.

DataSources can also be recursively nested for loading in series as opposed to in parallel. Nested DataSources will not start loading until the immediate parent has loaded (ie. it has data) as they are not placed into the DOM until this has happened. However, if a DataSource has started loading, and the immediate parent errors, the nested DataSource will stop receiving updates yet it and its properties will remain accessible within the DOM.

```hbs

  {{! straightforwards error/loading states}}
  {{#if error}}
    Something went wrong!
  {{else if (not loaded)}}
    Loading...
  {{/if}}

  {{! listen for HTTP API changes}}
  <DataSource
    @src={{uri "/partition/nspace/dc/services"}}
    @onerror={{action (mut error) value="error"}}
  as |source|>

    <source.Source
      @src={{uri "/partition/nspace/dc/service/{{source.data.firstObject.Name}}"}}
      @onerror={{action (mut error) value="error"}}
    as |source|>

      {{source.data.Service.Service.Name}} <== Detailed information for the first service

      <source.Source
        @src={{uri "/partition/nspace/dc/proxy/for-service/{{source.data.Service.ID}}"}}
        @onerror={{action (mut error) value="error"}}
        @onchange={{action (mut loaded) true}}
      as |source|>

        {{source.data.DestinationName}}

      </source.Source>

    </source.Source>

  </DataSource>
```

## See

- [Component Source Code](./index.js)
- [Template Source Code](./index.hbs)

---