# Anura Webcomponents A rewrite of Anura from the ground up using webcomponents. No jQuery, no dependencies, just **plain ES6.** Goals: * framework-agnostic (no node, no angular, no react) * source-agnostic (work with multiple DAM systems) * furthermore, it should be * easy to integrate * accessible * responsive > > > > > Internet Explorer is NOT supported anymore. If you need that, use the [jQuery](/anura/frontend) one (and may god have mercy upon your soul) [MINITOC] ## Demo See [https://anura.brix.ch/webcomponents](https://anura.brix.ch/webcomponents). ## Installation Anura is available via * [git submodule](https://gitlab.brix.ch/brix/celum/anura/webcomponents) (ask us for a user) * `git submodule add https://gitlab.brix.ch/brix/celum/anura/webcomponents.git lib/anura` (you may prefer to use [tags](https://gitlab.brix.ch/brix/celum/anura/webcomponents/-/tags), main is "bleeding-edge") * and to update `git submodule update --remote` * [npm](https://www.npmjs.com/package/anura-webcomponents) * `npm i anura-webcomponents` * [unpkg CDN](https://unpkg.com/anura-webcomponents) * `` * `` ### Usage In your `index.html` (or a CMS page), import at least the following two lines (use the `` if you can, otherwise lead with it). **Replace `$DAM` with `bynder`, `celum` or `sharedien`**! ```html ``` Instead of loading all components via `anura-components.js`, you might only want to load the one you need, e.g. `anura-gallery.js` (it will take care of its dependencies). ## Introduction [Webcomponents](https://www.webcomponents.org/introduction) are declarative, so where before you needed custom Javascript, you now just declare that you want a gallery: ```html ``` In order to abstract away the source of your assets, the concept of _adapters_ exists. These hold common settings (such as the URL) and know how to talk to their DAM. They are hooked up as follows: ```html ``` > > > > > > Note that you can update _locale_ at runtime, and the gallery will reload itself to reflect that change. To use multiple adapters at the same time: give them an ID like _id=my-id_, and refer to them as _adapter="#my-id"_. The same applies to hooking up different components to one another. Here's an example with a navigation tree: ```html
``` The tree is configured as the _search_ component for the gallery, so it will now listen to navigation events and update itself. ![Screenshot of anura-tree and anura-gallery side-by-side](anura-example.png) ## Page Anatomy When composing your own anura page, you will use a variety of different anura components, which you can mix-and-match alongside regular HTML as you see fit. For example: ![graphic of an anura page layout](basic-anatomy.png) Using just 4 different anura-components, we can simply create an easy-to-use media browsing experience - anywhere in the web! ![screenshot of a basic anura page](basic-anatomy-screenshot.png) In order for this to work, we need to hook them up to one another like so (note the `adapter` and `source` attributes): ```html

Media Database

``` Also note how components can contain other components, such as `` inside the gallery (done automatically, unless you specify something else in that [slot](./components/gallery#slots)). ## Component Anatomy Every component usually has: * **Attributes**: HTML attributes on component-level, such as `locale="de"` that can be updated "live" at any time. These can either be configured, or they appear as a result of an interaction, e.g. *anura-tree* will update its `value` attribute when a node has been selected. * **Events**: Emitted (or consumed) when something interactive happens, e.g. clicking on a node *anura-tree* yields a _node-selected_-event. * **Slots**: Places to add you own HTML into the component, e.g. *anura-tree* has a slot for a title, so you can `

my custom title

`. * **Parts**: Named parts of components that are available for styling, e.g. `anura-gallery::part(asset-title) { color: #f00 }` to make an assets title red. Note that unnamed shadow DOM objects are not styleable (by design). * **Variables**: CSS-variables allow you to specify some global default, without having to touch each `part`, e.g. `--button-color: blue`. ## AnuraQuery.selector As of 1.3, Anura ships with a custom [querySelector](https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelector#parameters), designed for accessing components from within other components, or the other way around. This facilitates abstracting page integrations into a web component of their own, wherein you couldn't use `search` from the example above, as it'd be shielded by the `shadowRoot` (i.e. `document.querySelector` wouldn't find anything). The following syntax is supported: * `<<<` to break out, e.g. `<<< #something-outside` breaks out of the web component, and `querySelector`s at every *shadowRoot* boundary, until having reached `document`. * `>>>` to break in, e.g. `>>> anura-something >>> #further-down` breaks into the web component, allowing you to address (or even access) internal things. *shadowRoot*s are traversed transparently, but you'll need to drill down explicitly into each web component along the way. * `<<< break-out-first >>> then-break-in` is also supported, should things ever get that hairy. **This is a bit naughty** and will only work if the web components use `mode: open`, which is the default. If you programmatically mess around inside of anura components and it breaks, you get to keep both pieces. ## Integration In the [Introduction](#introduction) we said that we can change the `locale` at runtime (or any other attribute marked `live: yes`). Let's do that: ### In JavaScript Example: change the `locale` attribute using an regular dropdown: ```html ``` ### In Angular Example: change the `locale` attribute using an external dropdown (`mat-select` in this case): ```html Language Deutsch English ``` ## Further reading * [Adapters](./adapters) * [Components](./components) * [Examples](./examples)