Add documentation for overriding slots in nested web components

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.

packages/common/package.json

 {
   "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": {

packages/file-handling/package.json

 {
   "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": {