A web component for building SPAs consisting of one topic with multiple activities. Handles login, language selection, activity switching, menus etc.
npm install @dbp-toolkit/app-shellA web component for building SPAs consisting of one topic with multiple
activities. Handles login, language selection, activity switching, menus etc.
You can install this component via npm:
``bash`
npm i @dbp-toolkit/app-shell
`html`
Or directly via CDN:
`html`
type="module"
src="https://unpkg.com/@dbp-toolkit/app-shell@0.2.3/dist/dbp-app-shell.js">
You need Keycloak and other parts to be in place to really make full use of the AppShell.
Best take a look on examples like index.html
for more explanation.
- provider-root (optional): You need to set the provider-root attribute for the app-shell to "terminate" all provider eventsprovider-root
- If you don't want to set the app-shell as then you need to set the attributes auth,requested-login-status
and analytics-event as attribute for the app-shell or in a dbp-provider above it
- example lang
- (optional, default: de): set to de or en for German or English
- example src
- : The path to a topic metadata file (json)base-path
- (optional, default: /): An absolute base path for routingentry-point-url
- : Entry point URL to access the APIkeycloak-config
- : An object with the following keys: url, realm, clientId, silentCheckSsoRedirectUri, scopematomo-url
- (optional): set to your _Matomo_ server (required only for tracking)
- example matomo-site-id
- (optional): set to your site id (required only for tracking)
- example no-welcome-page
- (optional): skips the welcome page and welcome page isn't visible in menu
- example routing-url
- (optional): the property can be sent by an activity with sendSetPropertyEvent to change the routinghttps://server.com/en/activity-name
- for example if at the URL a routing-url of path?query=1#hash wouldhttps://server.com/en/activity-name/path?query=1#hash
result in a URL change to , this would then in turnrouting-url
trigger a sending out of a attribute (see below)routing-base-url
- (optional): the base URL for the activity. Should be an
absolute URL which loads the currently active activity.
The component emits dbp-set-property events for these attributes:
#### lang
The attribute lang is emitted to propagate a language change. Possible values are en and de.
#### requested-login-status
The attribute requested-login-status is emitted to propagate whether a user is logged in or notlogged-in
Possible values are and logged-out.
#### routing-url
The attribute routing-url is emitted to propagate a routing change. The value is the new part of URL after the activity name.
For example for the URL https://myhost.com/en/render-form/demo-form/123?test1=2&test2=7#testHash it woulddemo-form/123?test1=2&test2=7#testHash
be .
The routing-url is integrated directly in DBPLitElement and this.getRoutingData() can be used to get the structured data.
In this example this.getRoutingData() would return:
`json`
{
"pathname": "/demo-form/123",
"pathSegments": ["demo-form", "123"],
"queryParams": {
"test1": "2",
"test2": "7"
},
"queryString": "?test1=2&test2=7",
"hash": "#testHash",
"fragment": "testHash"
}
The attribute routing-base-url is emitted to propagate a the base URL for the
activity i.e. the URL which when loaded will lead to the currently active
activity being loaded. Can be used by the activity to set return/callback URLs
for API calls. The URL should be an absolute URL.
Example: https://myhost.com/en/render-form
#### dbp-lang
The component emits a dbp-lang event when the language is changed (for example in the language picker).details
The attribute of the event is the language (possible values en, de).
You use template tags to inject slots into the web component.
These templates will be converted to div containers when the page is loaded and will not show up before that.
#### Unnamed slot
The unnamed slot will be removed when the application is loaded and can be filled with a loading-spinner.
Example:
#### name
The content of this slot will be shown left in the header and can be used to set a name (e.g. the name of the institution).
Example:
Graz University of Technology
#### title
The content of this slot will be shown as big h1 headline instead of the name in the topic manifest file.
Example:
#### logo
The content of this slot will be shown right in the header and can be used to override the logo image.
Example: 
#### header
The content of this slot will override the whole content of the header.
You will need to provide your own language selector and auth component.
Example:
#### footer-links
The content of this slot will override the whole content of the footer link section, for example to set custom links.
Example:
#### footer
The content of this slot will override the whole content of the footer, for example to set custom links
and also overwrite the dbp-build-info tag.
Example:
`json`
{
"name": {
"de": "Beispiel",
"en": "Example"
},
"short_name": {
"de": "Beispiel",
"en": "Example"
},
"description": {
"de": "Ich bin eine Beschreibung der Applikation",
"en": "I am a description of this application"
},
"routing_name": "example",
"activities": [{"path": "example.metadata.json", "visible": true}],
"attributes": []
}
`json`
{
"element": "dbp-activity-example",
"module_src": "dbp-activity-example.js",
"routing_name": "activity-example",
"name": {
"de": "Beispielaktivität",
"en": "Example Activity"
},
"short_name": {
"de": "Beispielaktivität",
"en": "Example Activity"
},
"description": {
"de": "Eine Beschreibung",
"en": "A Description"
}
}
`bashget the source
git clone git@github.com:digital-blueprint/toolkit.git
cd toolkit/packages/app-shell
Jump to