From b8b899fee36186d7b343feb6404939733ad36887 Mon Sep 17 00:00:00 2001
From: Patrizio Bekerle <patrizio@bekerle.com>
Date: Tue, 22 Jun 2021 11:36:42 +0200
Subject: [PATCH] Add documentation for overriding slots in nested web
components
---
packages/common/README.md | 44 +++++++++++++++++++++++++++++
packages/common/package.json | 2 +-
packages/file-handling/package.json | 2 +-
3 files changed, 46 insertions(+), 2 deletions(-)
diff --git a/packages/common/README.md b/packages/common/README.md
index 3beedf78..8e431c3a 100644
--- a/packages/common/README.md
+++ b/packages/common/README.md
@@ -38,3 +38,47 @@ You can use this web component to show translated html.
```
The English or German text will be shown according to the `lang` attribute.
+
+## Overriding slots in nested web components
+
+If slots are used in web components then it is best to derive your component class from `DBPLitElement`
+and subscribe to the attribute `html-overrides` everywhere you use it with `subscribe="html-overrides"`.
+
+This way integrators who are using topics or activities are able to globally override these slots
+in their root html.
+
+Example of the part of an `index.html` file for overriding the `auth-info` text in all Nextcloud
+file pickers of the signature topic:
+
+```html
+<dbp-signature html-overrides="global-override"></dbp-signature>
+
+<template id="global-override">
+ <template id="dbp-nextcloud-file-picker">
+ <div slot="auth-info">
+ <dbp-translated subscribe="lang">
+ <div slot="de">
+ Deutscher Text
+ </div>
+ <div slot="en">
+ English Text
+ </div>
+ </dbp-translated>
+ </div>
+ </template>
+</template>
+```
+
+By using `html-overrides="global-override"` in the topic `dbp-signature` you are able to define
+a template with `id="global-override"` that can hold one or more other templates for different components.
+
+In our case we have a template `id="dbp-nextcloud-file-picker"`, because we want to override slots
+in the component `dbp-nextcloud-file-picker` inside the signature topic.
+
+You can define one or more slots in that template that should be overridden.
+
+In our example we only want to override the slot `auth-info`, that holds additional text to add in
+the Nextcloud file picker component.
+
+We are using the `dbp-translated` component to insert translated text at the specified position
+in the Nextcloud file picker.
diff --git a/packages/common/package.json b/packages/common/package.json
index 49bd5631..d54f4bfb 100644
--- a/packages/common/package.json
+++ b/packages/common/package.json
@@ -1,7 +1,7 @@
{
"name": "@dbp-toolkit/common",
"homepage": "https://gitlab.tugraz.at/dbp/web-components/toolkit/-/tree/master/packages/common",
- "version": "0.2.8",
+ "version": "0.2.9",
"module": "index.js",
"license": "LGPL-2.1-or-later",
"repository": {
diff --git a/packages/file-handling/package.json b/packages/file-handling/package.json
index f2aff358..118af4fd 100644
--- a/packages/file-handling/package.json
+++ b/packages/file-handling/package.json
@@ -1,7 +1,7 @@
{
"name": "@dbp-toolkit/file-handling",
"homepage": "https://gitlab.tugraz.at/dbp/web-components/toolkit/-/tree/master/packages/file-handling",
- "version": "0.2.6",
+ "version": "0.2.7",
"main": "src/index.js",
"license": "LGPL-2.1-or-later",
"repository": {
--
GitLab