diff --git a/ui-v2/app/components/data-source/README.mdx b/ui-v2/app/components/data-source/README.mdx new file mode 100644 index 000000000..63c485a3d --- /dev/null +++ b/ui-v2/app/components/data-source/README.mdx @@ -0,0 +1,61 @@ +## DataSource + +```handlebars + +``` + +### Arguments + +| 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;`) | +| `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. | + +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 `` 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). + + +### Example + +Straightforward usage can use `mut` to easily update data within a template + +```handlebars + {{! listen for HTTP API changes}} + + {{! 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}} + + {{! the value of token will change whenever the data changes}} + {{token.AccessorID}} {{! < Prints the token AccessorID }} +``` + +### See + +- [Component Source Code](./index.js) +- [Template Source Code](./index.hbs) + +--- diff --git a/ui-v2/app/components/data-source/index.hbs b/ui-v2/app/components/data-source/index.hbs new file mode 100644 index 000000000..661f27adb --- /dev/null +++ b/ui-v2/app/components/data-source/index.hbs @@ -0,0 +1,4 @@ +{{#if (eq loading "lazy")}} +{{! in order to use intersection observer we need a DOM element on the page}} +