diff --git a/README.md b/README.md
index 397b144ebceb9169cc4fd25c97092108b0be6dca..29c3e988c93417571e9959a8f6191e29f271b9b6 100644
--- a/README.md
+++ b/README.md
@@ -6,6 +6,8 @@
[Esign Bundle](https://gitlab.tugraz.at/dbp/esign/dbp-relay-esign-bundle) |
[Project documentation](https://dbp-demo.tugraz.at/site/software/esign.html)
+Esign - The digital signature service at the university.
+
## Prerequisites
- You need the [API server](https://gitlab.tugraz.at/dbp/relay/dbp-relay-server-template) running
@@ -68,149 +70,67 @@ npx @digital-blueprint/cli update-app signature
## Activities
-### dbp-qualified-signature-pdf-upload
-
-You can use this activity to qualifiedly sign PDF documents like this:
-[dbp-qualified-signature-pdf-upload/index.html](https://gitlab.tugraz.at/dbp/esign/signature/-/tree/master/examples/dbp-qualified-signature-pdf-upload/index.html)
-
-Note that you will need a Keycloak server along with a client id for the domain you are running this html on.
-
-#### Attributes
-
-- `lang` (optional, default: `de`): set to `de` or `en` for German or English
- - example `lang="de"`
-- `entry-point-url` (optional, default is the TU Graz entry point url): entry point url to access the api
- - example `entry-point-url="https://api-dev.tugraz.at"`
-- `auth` object: you need to set that object property for the auth token
- - example auth property: `{token: "THE_BEARER_TOKEN"}`
- - note: most often this should be an attribute that is not set directly, but subscribed at a provider
-- `nextcloud-web-app-password-url` (optional): Nextcloud Auth Url to use with the Nextcloud file picker
- - example `nextcloud-web-app-password-url="http://localhost:8081/index.php/apps/webapppassword"`
- - `nextcloud-web-dav-url` also needs to be set for the Nextcloud file picker to be active
-- `nextcloud-web-dav-url` (optional): Nextcloud WebDav Url to use with the Nextcloud file picker
- - example `nextcloud-web-dav-url="http://localhost:8081/remote.php/dav/files"`
- - `nextcloud-web-app-password-url` also needs to be set for the Nextcloud file picker to be active
-- `nextcloud-file-url` (optional): Nextcloud File Url to use with the Nextcloud file picker
- - example `nextcloud-file-url="http://localhost:8081/apps/files/?dir="`
-- `nextcloud-name` (optional): Name of the Nextcloud service
- - example `nextcloud-name="My Nextcloud"`
-- `nextcloud-auth-info` (optional): Additional authentication information text that is shown in the Nextcloud file picker
- - example `nextcloud-auth-info="You need special permissions for this function"`
-- `allow-annotating` (optional): Needs to be set to allow annotating the PDFs
- - example `allow-annotating`
-- `file-handling-enabled-targets` (optional, default: `local`): Needs to be set to allow using other filehandling
- targets than local, comma seperated list
- actual supported: `local`, `clipboard`, `nextcloud`
- - example `file-handling-enabled-targets="local,nextcloud,clipboard"`
-
-#### Exposed CSS variables
-
-- `--dbp-override-image-nextcloud` is used to override the cloud image on the connection screen of the Nextcloud file picker
- - example CSS: `html { --dbp-override-image-nextcloud: url(/icons/nextcloud.svg); }`
-
-### dbp-official-signature-pdf-upload
-
-You can use this activity to officially sign PDF documents like this:
-[dbp-official-signature-pdf-upload/index.html](https://gitlab.tugraz.at/dbp/esign/signature/-/tree/master/examples/dbp-official-signature-pdf-upload/index.html)
-
-Note that you will need a Keycloak server along with a client id for the domain you are running this html on.
-
-#### Attributes
-
-- `lang` (optional, default: `de`): set to `de` or `en` for German or English
- - example `lang="de"`
-- `entry-point-url` (optional, default is the TU Graz entry point url): entry point url to access the api
- - example `entry-point-url="https://api-dev.tugraz.at"`
-- `auth` object: you need to set that object property for the auth token
- - example auth property: `{token: "THE_BEARER_TOKEN"}`
- - note: most often this should be an attribute that is not set directly, but subscribed at a provider
-- `nextcloud-web-app-password-url` (optional): Nextcloud Auth Url to use with the Nextcloud file picker
- - example `nextcloud-web-app-password-url="http://localhost:8081/index.php/apps/webapppassword"`
- - `nextcloud-web-dav-url` also needs to be set for the Nextcloud file picker to be active
-- `nextcloud-web-dav-url` (optional): Nextcloud WebDav Url to use with the Nextcloud file picker
- - example `nextcloud-web-dav-url="http://localhost:8081/remote.php/dav/files"`
- - `nextcloud-web-app-password-url` also needs to be set for the Nextcloud file picker to be active
-- `nextcloud-file-url` (optional): Nextcloud File Url to use with the Nextcloud file picker
- - example `nextcloud-file-url="http://localhost:8081/apps/files/?dir="`
-- `nextcloud-name` (optional): Name of the Nextcloud service
- - example `nextcloud-name="My Nextcloud"`
-- `nextcloud-auth-info` (optional): Additional authentication information text that is shown in the Nextcloud file picker
- - example `nextcloud-auth-info="You need special permissions for this function"`
-- `allow-annotating` (optional): Needs to be set to allow annotating the PDFs
- - example `allow-annotating`
-- `file-handling-enabled-targets` (optional, default: `local`): Needs to be set to allow using other filehandling
- targets than local, comma seperated list
- actual supported: `local`, `clipboard`, `nextcloud`
- - example `file-handling-enabled-targets="local,nextcloud,clipboard"`
-
-#### Exposed CSS variables
-
-- `--dbp-override-image-nextcloud` is used to override the cloud image on the connection screen of the Nextcloud file picker
- - example CSS: `html { --dbp-override-image-nextcloud: url(/icons/nextcloud.svg); }`
-
-### dbp-signature-verification
-
-This activity shows an information page where to verify signed documents, you can use it like this:
-[dbp-signature-verification/index.html](https://gitlab.tugraz.at/dbp/esign/signature/-/tree/master/examples/dbp-signature-verification/index.html)
-
-#### Attributes
-
-- `lang` (optional, default: `de`): set to `de` or `en` for German or English
- - example `lang="de"`
-
-#### Slots
-
-You use templates tags to inject slots into the activity.
-These templates will be converted to div containers when the page is loaded and will not show up before that.
-
-##### additional-information
-
-The content of this slot will be shown below the other text and can be used to provide
-further information about the verification process. For example a link to a page with
-more information about verifying a document with Adobe Reader can be provided.
-
-Example:
-
-```html
-<dbp-signature-verification lang="de">
- <template slot="additional-information">
- <dbp-translated subscribe="lang">
- <div slot="de">
- <a target="_blank" href="#german-link">
- Weitere Information zur Verifikation mit Adobe Reader
- </a>
- </div>
- <div slot="en">
- <a target="_blank" href="#english-link">
- More information about verification with Adobe Reader
- </a>
- </div>
- </dbp-translated>
- </template>
-</dbp-signature-verification>
-```
-
-## "dbp-signature" Slots
-
-These are common slots for the appshell. You can find the documentation of these slot in the `README.md` of the appshell webcomponent.
-
-## Design Notes
-
-To ensure a uniform and responsive design the activity should occupy 100% of the window width
-when the activity width is less than 768 px.
-
-## Mandatory attributes
+This app has the following activities:
+- `dbp-acquire-3g-ticket`
+- `dbp-show-active-tickets`
+- `dbp-show-reference-ticket`
+
+You can find the documentation of these activities in the [esign activities documentation](https://gitlab.tugraz.at/dbp/esign/signature/-/tree/master/src).
+
+## Adapt app
+
+### Functionality
+
+You can add multiple attributes to the `<dbp-signature>` tag.
+
+| attribute name | value | Link to description |
+|----------------|-------| ------------|
+| `provider-root` | Boolean | [app-shell](https://gitlab.tugraz.at/dbp/web-components/toolkit/-/tree/master/packages/app-shell#attributes) |
+| `lang` | String | [language-select](https://gitlab.tugraz.at/dbp/web-components/toolkit/-/tree/master/packages/language-select#attributes) |
+| `entry-point-url` | String | [app-shell](https://gitlab.tugraz.at/dbp/web-components/toolkit/-/tree/master/packages/app-shell#attributes) |
+| `keycloak-config` | Object | [app-shell](https://gitlab.tugraz.at/dbp/web-components/toolkit/-/tree/master/packages/app-shell#attributes) |
+| `base-path` | String | [app-shell](https://gitlab.tugraz.at/dbp/web-components/toolkit/-/tree/master/packages/app-shell#attributes) |
+| `src` | String | [app-shell](https://gitlab.tugraz.at/dbp/web-components/toolkit/-/tree/master/packages/app-shell#attributes) |
+| `html-overrides` | String | [common](https://gitlab.tugraz.at/dbp/web-components/toolkit/-/tree/master/packages/common#overriding-slots-in-nested-web-components) |
+| `themes` | Array | [theme-switcher](https://gitlab.tugraz.at/dbp/web-components/toolkit/-/tree/master/packages/theme-switcher#themes-attribute) |
+| `darkModeThemeOverride` | String | [theme-switcher](https://gitlab.tugraz.at/dbp/web-components/toolkit/-/tree/master/packages/theme-switcher#themes-attribute) |
+| `gp-search-hash-string` | String | [greenlight activities](https://gitlab.tugraz.at/dbp/greenlight/greenlight/-/tree/main/src) |
+| `gp-search-self-test-string-array` | String | [greenlight activities](https://gitlab.tugraz.at/dbp/greenlight/greenlight/-/tree/main/src) |
+| `gp-self-test-valid` | Boolean | [greenlight activities](https://gitlab.tugraz.at/dbp/greenlight/greenlight/-/tree/main/src) |
+| `ticket-types` | Object | [greenlight activities](https://gitlab.tugraz.at/dbp/greenlight/greenlight/-/tree/main/src#shared-attributes) |
+| `show-preselected` | Boolean | [greenlight activities](https://gitlab.tugraz.at/dbp/greenlight/greenlight/-/tree/main/src) |
+| `preselected-option` | String | [greenlight activities](https://gitlab.tugraz.at/dbp/greenlight/greenlight/-/tree/main/src) |
+| `file-handling-enabled-targets` | String | [file-handling](https://gitlab.tugraz.at/dbp/web-components/toolkit/-/tree/master/packages/file-handling#attributes) |
+| `nextcloud-web-app-password-url` | String | [file-handling](https://gitlab.tugraz.at/dbp/web-components/toolkit/-/tree/master/packages/file-handling#attributes) |
+| `nextcloud-web-dav-url` | String | [file-handling](https://gitlab.tugraz.at/dbp/web-components/toolkit/-/tree/master/packages/file-handling#attributes) |
+| `nextcloud-file-url` | String | [file-handling](https://gitlab.tugraz.at/dbp/web-components/toolkit/-/tree/master/packages/file-handling#attributes) |
+| `nextcloud-auth-info` | String | [file-handling](https://gitlab.tugraz.at/dbp/web-components/toolkit/-/tree/master/packages/file-handling#attributes) |
+| `nextcloud-name` | String | [file-handling](https://gitlab.tugraz.at/dbp/web-components/toolkit/-/tree/master/packages/file-handling#attributes) |
+| `allow-annotating` | Boolean | [esign activities](https://gitlab.tugraz.at/dbp/esign/signature/-/tree/master/src) |
+| `file-handling-enabled-targets` | String | [esign activities](https://gitlab.tugraz.at/dbp/esign/signature/-/tree/master/src) |
+
+#### Mandatory attributes
If you are not using the `provider-root` attribute to "terminate" all provider attributes
you need to manually add these attributes so that the topic will work properly:
```html
<dbp-signature
- auth
- requested-login-status
- analytics-event
- initial-file-handling-state
- clipboard-files
+ auth
+ requested-login-status
+ analytics-event
+ initial-file-handling-state
+ clipboard-files
>
</dbp-signature>
```
+
+### Design
+
+For frontend design customizations, such as logo, colors, font, favicon, and more, take a look at the [theming documentation](https://dbp-demo.tugraz.at/dev-guide/frontend/theming/).
+
+## "dbp-signature" slots
+
+These are common slots for the app-shell. You can find the documentation of these slots in the [app-shell documentation](https://gitlab.tugraz.at/dbp/web-components/toolkit/-/tree/master/packages/app-shell).
+For the app specific slots take a look at the [esign activities documentation](https://gitlab.tugraz.at/dbp/esign/signature/-/tree/master/src).
+
diff --git a/src/README.md b/src/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..3be01166ac5a504bd9848a3c576aca5ab5e989bd
--- /dev/null
+++ b/src/README.md
@@ -0,0 +1,131 @@
+# Digital Signing activities
+
+Here you can find the individual activities of the `esign` app. If you want to use the whole app look at [esign](https://gitlab.tugraz.at/dbp/esign/signature).
+
+<!-- ## Usage of an activity
+TODO add description how to only use an activity alone here
+-->
+
+## Activities
+
+### Shared Attributes
+
+These attributes are available for all activities listed here:
+
+- `lang` (optional, default: `de`): set to `de` or `en` for German or English
+ - example `lang="de"`
+
+### dbp-qualified-signature-pdf-upload
+
+You can use this activity to qualifiedly sign PDF documents like this:
+[dbp-qualified-signature-pdf-upload/index.html](https://gitlab.tugraz.at/dbp/esign/signature/-/tree/master/examples/dbp-qualified-signature-pdf-upload/index.html)
+
+Note that you will need a Keycloak server along with a client id for the domain you are running this html on.
+
+#### Attributes
+
+- `entry-point-url` (optional, default is the TU Graz entry point url): entry point url to access the api
+ - example `entry-point-url="https://api-dev.tugraz.at"`
+- `auth` object: you need to set that object property for the auth token
+ - example auth property: `{token: "THE_BEARER_TOKEN"}`
+ - note: most often this should be an attribute that is not set directly, but subscribed at a provider
+- `nextcloud-web-app-password-url` (optional): Nextcloud Auth Url to use with the Nextcloud file picker
+ - example `nextcloud-web-app-password-url="http://localhost:8081/index.php/apps/webapppassword"`
+ - `nextcloud-web-dav-url` also needs to be set for the Nextcloud file picker to be active
+- `nextcloud-web-dav-url` (optional): Nextcloud WebDav Url to use with the Nextcloud file picker
+ - example `nextcloud-web-dav-url="http://localhost:8081/remote.php/dav/files"`
+ - `nextcloud-web-app-password-url` also needs to be set for the Nextcloud file picker to be active
+- `nextcloud-file-url` (optional): Nextcloud File Url to use with the Nextcloud file picker
+ - example `nextcloud-file-url="http://localhost:8081/apps/files/?dir="`
+- `nextcloud-name` (optional): Name of the Nextcloud service
+ - example `nextcloud-name="My Nextcloud"`
+- `nextcloud-auth-info` (optional): Additional authentication information text that is shown in the Nextcloud file picker
+ - example `nextcloud-auth-info="You need special permissions for this function"`
+- `allow-annotating` (optional): Needs to be set to allow annotating the PDFs
+ - example `allow-annotating`
+- `file-handling-enabled-targets` (optional, default: `local`): Needs to be set to allow using other filehandling
+ targets than local, comma seperated list
+ actual supported: `local`, `clipboard`, `nextcloud`
+ - example `file-handling-enabled-targets="local,nextcloud,clipboard"`
+
+### dbp-official-signature-pdf-upload
+
+You can use this activity to officially sign PDF documents like this:
+[dbp-official-signature-pdf-upload/index.html](https://gitlab.tugraz.at/dbp/esign/signature/-/tree/master/examples/dbp-official-signature-pdf-upload/index.html)
+
+Note that you will need a Keycloak server along with a client id for the domain you are running this html on.
+
+#### Attributes
+
+- `entry-point-url` (optional, default is the TU Graz entry point url): entry point url to access the api
+ - example `entry-point-url="https://api-dev.tugraz.at"`
+- `auth` object: you need to set that object property for the auth token
+ - example auth property: `{token: "THE_BEARER_TOKEN"}`
+ - note: most often this should be an attribute that is not set directly, but subscribed at a provider
+- `allow-annotating` (optional): Needs to be set to allow annotating the PDFs
+ - example `allow-annotating`
+- `file-handling-enabled-targets` (optional, default: `local`): Needs to be set to allow using other filehandling
+ targets than local, comma seperated list
+ actual supported: `local`, `clipboard`, `nextcloud`
+ - example `file-handling-enabled-targets="local,nextcloud,clipboard"`
+
+### dbp-signature-verification
+
+This activity shows an information page where to verify signed documents, you can use it like this:
+[dbp-signature-verification/index.html](https://gitlab.tugraz.at/dbp/esign/signature/-/tree/master/examples/dbp-signature-verification/index.html)
+
+#### Attributes
+
+See [shared attributes](#shared-attributes).
+
+#### Slots
+
+You use templates tags to inject slots into the activity.
+These templates will be converted to div containers when the page is loaded and will not show up before that.
+
+##### additional-information
+
+The content of this slot will be shown below the other text and can be used to provide
+further information about the verification process. For example a link to a page with
+more information about verifying a document with Adobe Reader can be provided.
+
+Example:
+
+```html
+<dbp-signature-verification lang="de">
+ <template slot="additional-information">
+ <dbp-translated subscribe="lang">
+ <div slot="de">
+ <a target="_blank" href="#german-link">
+ Weitere Information zur Verifikation mit Adobe Reader
+ </a>
+ </div>
+ <div slot="en">
+ <a target="_blank" href="#english-link">
+ More information about verification with Adobe Reader
+ </a>
+ </div>
+ </dbp-translated>
+ </template>
+</dbp-signature-verification>
+```
+
+## Design Note
+
+To ensure a uniform and responsive design these activities should occupy 100% width of the window when the activities' width are under 768 px.
+
+## Mandatory attributes
+
+If you are not using the `provider-root` attribute to "terminate" all provider attributes
+you need to manually add these attributes so that the topic will work properly:
+
+```html
+<dbp-signature
+ auth
+ requested-login-status
+ analytics-event
+ initial-file-handling-state
+ clipboard-files
+>
+</dbp-signature>
+```