Skip to content
Snippets Groups Projects
Commit 7b078d79 authored by Steinwender, Tamara's avatar Steinwender, Tamara
Browse files

Adapt readme

parent 2f45e372
No related branches found
No related tags found
No related merge requests found
Pipeline #186841 passed
Stage: test
Stage: deploy
Stage: e2e
Hide whitespace changes
Inline Side-by-side
README.md
+ 57
− 137
View file @ 7b078d79
......@@ -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).
src/README.md 0 → 100644
+ 131
− 0
View file @ 7b078d79
# 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>
```
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment