README.md

Provider Web Components

GitLab Repository

You can install this component via npm:

npm i @dbp-toolkit/provider

Local development

# get the source
git clone git@gitlab.tugraz.at:dbp/web-components/toolkit.git
cd toolkit/packages/provider

# install dependencies (make sure you have npm version 4+ installed, so symlinks to the git submodules are created automatically)
yarn install

# constantly build dist/bundle.js and run a local web-server on port 8002 
yarn run watch

# run tests
yarn test

Jump to http://localhost:8002 and you should get a demo page.

Provider

Usage

You can provide attributes (e.g. global-name) for components inside the provider:

<dbp-provider global-name="value" global-name2="value2">
  <dbp-person-select subscribe="local-name:global-name"></dbp-person-select>
  <dbp-person-profile subscribe="local-name:global-name,local-name2:global-name2"></dbp-person-profile>
</dbp-provider>
<script type="module" src="node_modules/@dbp-toolkit/provider/dist/dbp-provider.js"></script>

All other components are also inherent providers (see below), so you don't really need dbp-provider in the shadow dom of other components. The use of dbp-provider is mainly suggested being used for namespacing (e.g. different languages or entry point urls on the same page) or to deliver attribute changes across different components.

Flow

Example 1

<dbp-provider lang>
  <dbp-language-select></dbp-language-select>
  <dbp-person-select subscribe="lang"></dbp-person-select>
</dbp-provider>

There is a provider, a language selector and a person selector. The flow looks like this:

sequenceDiagram
    participant P as Provider
    participant LS as LanguageSelect
    participant PS as PersonSelect
    Note over P,PS: Initialization
    P-->P: Has attribute "lang"
    PS->>P: Subscribe to "lang"
    Note over P,PS: Communication
    LS->>P: "lang" should be "en"
    P->>PS: "lang" was updated to "en"

Attributes

• init (optional): set your vars to values
  • example <dbp-provider init="foo=bar"></dbp-provider>
• id (optional): set an id, useful for debugging
  • example <dbp-provider id="p-1"></dbp-provider>

AdapterLitElement

This is a class you can derive your component class from instead of LitElement.

You can locally "subscribe" to attributes (e.g. local-name) that can be provided by a dbp-provider (e.g. global-name). You need to make this available attributes as LitElement properties.

Example

Multiple attributes can be subscribed when separated by a comma (,).

<dbp-person-select subscribe="local-name:global-name,local-name2:global-name2"></dbp-person-select>

If local-name and global-name are the same you could also instead of local-name:local-name just write local-name:

<dbp-person-select subscribe="local-name"></dbp-person-select>

Inherent provider

AdapterLitElement are themselves provider that will provide all their own attributes to all the elements in their shadow dom.

In this example dbp-auth-keycloak would use the set-property event to propagate an auth property. dbp-person-select-demo would act as provider for auth. dbp-person-select would subscribe to auth to receive the bearer token via this.auth.token.

<dbp-person-select-demo auth lang="de" entry-point-url="http://127.0.0.1:8000">
  <!-- #shadow-root -->
  <dbp-auth-keycloak></dbp-auth-keycloak>
  <dbp-person-select subscribe="auth" lang="${this.lang}" entry-point-url="${this.entryPointUrl}"></dbp-person-select>
</dbp-person-select-demo>

AdapterElement

This is a wrapper for third party webcomponents. you can wrap this class around to support the provider functionality in third party webcomponents.

You can locally "subscribe" to attributes (e.g. local-name) that can be provided by a dbp-provider (e.g. global-name). The dbp-adapter will set the attributes to his childnodes.

Example

Multiple attributes can be subscribed when separated by a comma (,).

<dbp-provider global-name="value" global-name2="value2">
  <dbp-provider-adapter subscribe="local-name:global-name">
    <third-party-webcomponent>  </third-party-webcomponent>
  </dbp-provider-adapter>
</dbp-provider>
<script type="module" src="node_modules/@dbp-toolkit/provider/dist/dbp-provider.js"></script>
<script type="module" src="node_modules/@dbp-toolkit/provider/dist/dbp-adapter.js"></script>