mirror of
https://github.com/opencloud-eu/opencloud.git
synced 2026-01-05 11:51:16 -06:00
Merge pull request #6090 from owncloud/fix_notification_readme
This commit is contained in:
Martin
@@ -1,28 +1,26 @@
|
||||
# Notification
|
||||
|
||||
The notification service is responsible for sending emails to users informing them about events that happened. To do this it hooks into the event system and listens for certain events that the users need to be informed about.
|
||||
The notification service is responsible for sending emails to users informing them about events that happened. To do this, it hooks into the event system and listens for certain events that the users need to be informed about.
|
||||
|
||||
## Email Notification Templates
|
||||
|
||||
The `notifications` service has embedded email body templates.
|
||||
The email templates contain placeholders `{{ .Greeting }}`, `{{ .MessageBody }}`, `{{ .CallToAction }}` that are
|
||||
replaced with translations, see the [Translations](#translations) section.
|
||||
These embedded templates are available for all deployment scenarios. In addition, the service supports custom
|
||||
templates.
|
||||
The custom email template takes precedence over the embedded one. If a custom email template exists, the embedded ones
|
||||
are not used. To configure custom email templates,
|
||||
the `NOTIFICATIONS_EMAIL_TEMPLATE_PATH` environment variable needs to point to a base folder that will contain the email
|
||||
templates. The source template files provided by ocis are located
|
||||
in [https://github.com/owncloud/ocis/tree/master/services/notifications/pkg/email/templates](https://github.com/owncloud/ocis/tree/master/services/notifications/pkg/email/templates) in the `shares`
|
||||
and `spaces` subfolders:
|
||||
[shares/shareCreated.email.body.tmpl](https://github.com/owncloud/ocis/blob/master/services/notifications/pkg/email/templates/shares/shareCreated.email.body.tmpl)
|
||||
[shares/shareExpired.email.body.tmpl](https://github.com/owncloud/ocis/blob/master/services/notifications/pkg/email/templates/shares/shareExpired.email.body.tmpl)
|
||||
[spaces/membershipExpired.email.body.tmpl](https://github.com/owncloud/ocis/blob/master/services/notifications/pkg/email/templates/spaces/membershipExpired.email.body.tmpl)
|
||||
[spaces/sharedSpace.email.body.tmpl](https://github.com/owncloud/ocis/blob/master/services/notifications/pkg/email/templates/spaces/sharedSpace.email.body.tmpl)
|
||||
[spaces/unsharedSpace.email.body.tmpl](https://github.com/owncloud/ocis/blob/master/services/notifications/pkg/email/templates/spaces/unsharedSpace.email.body.tmpl)
|
||||
The `notifications` service has embedded email body templates. Email templates can use the placeholders `{{ .Greeting }}`, `{{ .MessageBody }}` and `{{ .CallToAction }}` which are replaced with translations when sent, see the [Translations](#translations) section for more details. Depending on the email purpose, placeholders will contain different strings. An individual translatable string is available for each purpose, finally resolved by the placeholder. Though the email subject is also part of translations, it has no placeholder as it is a mandatory email component. The embedded templates are available for all deployment scenarios.
|
||||
|
||||
```text
|
||||
template
|
||||
placeholders
|
||||
translated strings <-- source strings <-- purpose
|
||||
final output
|
||||
```
|
||||
|
||||
In addition, the notifications service supports custom templates. Custom email templates take precedence over the embedded ones. If a custom email template exists, the embedded templates are not used. To configure custom email templates, the `NOTIFICATIONS_EMAIL_TEMPLATE_PATH` environment variable needs to point to a base folder that will contain the email templates. This path must be available from all instances of the notifications service, a shared storage is recommended. The source templates provided by ocis you can derive from are located in following base folder [https://github.com/owncloud/ocis/tree/master/services/notifications/pkg/email/templates](https://github.com/owncloud/ocis/tree/master/services/notifications/pkg/email/templates) with subfolders `shares` and `spaces`.
|
||||
|
||||
- [shares/shareCreated.email.body.tmpl](https://github.com/owncloud/ocis/blob/master/services/notifications/pkg/email/templates/shares/shareCreated.email.body.tmpl)
|
||||
- [shares/shareExpired.email.body.tmpl](https://github.com/owncloud/ocis/blob/master/services/notifications/pkg/email/templates/shares/shareExpired.email.body.tmpl)
|
||||
- [spaces/membershipExpired.email.body.tmpl](https://github.com/owncloud/ocis/blob/master/services/notifications/pkg/email/templates/spaces/membershipExpired.email.body.tmpl)
|
||||
- [spaces/sharedSpace.email.body.tmpl](https://github.com/owncloud/ocis/blob/master/services/notifications/pkg/email/templates/spaces/sharedSpace.email.body.tmpl)
|
||||
- [spaces/unsharedSpace.email.body.tmpl](https://github.com/owncloud/ocis/blob/master/services/notifications/pkg/email/templates/spaces/unsharedSpace.email.body.tmpl)
|
||||
|
||||
Custom Email templates referenced via `NOTIFICATIONS_EMAIL_TEMPLATE_PATH` must be located in subfolders `shares`
|
||||
and `spaces` and have the same names as the embedded templates. This naming must match the embedded ones.
|
||||
```text
|
||||
templates
|
||||
│
|
||||
@@ -36,28 +34,22 @@ templates
|
||||
│ unsharedSpace.email.body.tmpl
|
||||
```
|
||||
|
||||
Custom email templates referenced via `NOTIFICATIONS_EMAIL_TEMPLATE_PATH` must also be located in subfolders `shares` and `spaces` and must have the same names as the embedded templates. It is important that the names of these files and folders match the embedded ones.
|
||||
|
||||
## Translations
|
||||
|
||||
The `notifications` service has embedded translations sourced via transifex to provide a basic set of translated languages.
|
||||
These embedded translations are available for all deployment scenarios. In addition, the service supports custom
|
||||
translations, though it is currently not possible to just add custom translations to embedded ones. If custom
|
||||
translations are configured, the embedded ones are not used. To configure custom translations,
|
||||
the `NOTIFICATIONS_TRANSLATION_PATH` environment variable needs to point to a base folder that will contain the translation
|
||||
files. This path must be available from all instances of the notifications service, a shared storage is recommended.
|
||||
Translation files must be of type [.po](https://www.gnu.org/software/gettext/manual/html_node/PO-Files.html#PO-Files)
|
||||
or [.mo](https://www.gnu.org/software/gettext/manual/html_node/Binaries.html). For each language, the filename needs to
|
||||
be `translations.po` (or `translations.mo`) and stored in a folder structure defining the language code. In general the path/name
|
||||
pattern for a translation file needs to be:
|
||||
The `notifications` service has embedded translations sourced via transifex to provide a basic set of translated languages. These embedded translations are available for all deployment scenarios.
|
||||
|
||||
In addition, the service supports custom translations, though it is currently not possible to just add custom translations to embedded ones. If custom translations are configured, the embedded ones are not used. To configure custom translations,
|
||||
the `NOTIFICATIONS_TRANSLATION_PATH` environment variable needs to point to a base folder that will contain the translation files. This path must be available from all instances of the notifications service, a shared storage is recommended. Translation files must be of type [.po](https://www.gnu.org/software/gettext/manual/html_node/PO-Files.html#PO-Files) or [.mo](https://www.gnu.org/software/gettext/manual/html_node/Binaries.html). For each language, the filename needs to be `translations.po` (or `translations.mo`) and stored in a folder structure defining the language code. In general the path/name pattern for a translation file needs to be:
|
||||
|
||||
```text
|
||||
{NOTIFICATIONS_TRANSLATION_PATH}/{language-code}/LC_MESSAGES/translations.po
|
||||
```
|
||||
|
||||
The language code pattern is composed of `language[_territory]` where `language` is the base language and `_territory`
|
||||
is optional and defines a country.
|
||||
The language code pattern is composed of `language[_territory]` where `language` is the base language and `_territory` is optional and defines a country.
|
||||
|
||||
For example, for the language `de_DE`, one needs to place the corresponding translation files
|
||||
to `{NOTIFICATIONS_TRANSLATION_PATH}/de_DE/LC_MESSAGES/translations.po`.
|
||||
For example, for the language `de_DE`, one needs to place the corresponding translation files to `{NOTIFICATIONS_TRANSLATION_PATH}/de_DE/LC_MESSAGES/translations.po`.
|
||||
|
||||
### Translation Rules
|
||||
|
||||
|
||||
@@ -8,23 +8,23 @@ var (
|
||||
// Shares
|
||||
ShareCreated = MessageTemplate{
|
||||
bodyTemplate: "shares/shareCreated.email.body.tmpl",
|
||||
// ShareCreated email template, Subject field
|
||||
// ShareCreated email template, Subject field (resolves directly)
|
||||
Subject: Template(`{ShareSharer} shared '{ShareFolder}' with you`),
|
||||
// ShareCreated email template, Greeting field
|
||||
// ShareCreated email template, resolves via {{ .Greeting }}
|
||||
Greeting: Template(`Hello {ShareGrantee}`),
|
||||
// ShareCreated email template, Message field
|
||||
// ShareCreated email template, resolves via {{ .MessageBody }}
|
||||
MessageBody: Template(`{ShareSharer} has shared "{ShareFolder}" with you.`),
|
||||
// ShareCreated email template, CallToAction field
|
||||
// ShareCreated email template, resolves via {{ .CallToAction }}
|
||||
CallToAction: Template(`Click here to view it: {ShareLink}`),
|
||||
}
|
||||
|
||||
ShareExpired = MessageTemplate{
|
||||
bodyTemplate: "shares/shareExpired.email.body.tmpl",
|
||||
// ShareExpired email template, Subject field
|
||||
// ShareExpired email template, Subject field (resolves directly)
|
||||
Subject: Template(`Share to '{ShareFolder}' expired at {ExpiredAt}`),
|
||||
// ShareExpired email template, Greeting field
|
||||
// ShareExpired email template, resolves via {{ .Greeting }}
|
||||
Greeting: Template(`Hello {ShareGrantee},`),
|
||||
// ShareExpired email template, Message field
|
||||
// ShareExpired email template, resolves via {{ .MessageBody }}
|
||||
MessageBody: Template(`Your share to {ShareFolder} has expired at {ExpiredAt}
|
||||
|
||||
Even though this share has been revoked you still might have access through other shares and/or space memberships.`),
|
||||
@@ -33,37 +33,37 @@ Even though this share has been revoked you still might have access through othe
|
||||
// Spaces templates
|
||||
SharedSpace = MessageTemplate{
|
||||
bodyTemplate: "spaces/sharedSpace.email.body.tmpl",
|
||||
// SharedSpace email template, Subject field
|
||||
// SharedSpace email template, Subject field (resolves directly)
|
||||
Subject: Template("{SpaceSharer} invited you to join {SpaceName}"),
|
||||
// SharedSpace email template, Greeting field
|
||||
// SharedSpace email template, resolves via {{ .Greeting }}
|
||||
Greeting: Template(`Hello {SpaceGrantee},`),
|
||||
// SharedSpace email template, Message field
|
||||
// SharedSpace email template, resolves via {{ .MessageBody }}
|
||||
MessageBody: Template(`{SpaceSharer} has invited you to join "{SpaceName}".`),
|
||||
// SharedSpace email template, CallToAction field
|
||||
// SharedSpace email template, resolves via {{ .CallToAction }}
|
||||
CallToAction: Template(`Click here to view it: {ShareLink}`),
|
||||
}
|
||||
|
||||
UnsharedSpace = MessageTemplate{
|
||||
bodyTemplate: "spaces/unsharedSpace.email.body.tmpl",
|
||||
// UnsharedSpace email template, Subject field
|
||||
// UnsharedSpace email template, Subject field (resolves directly)
|
||||
Subject: Template(`{SpaceSharer} removed you from {SpaceName}`),
|
||||
// UnsharedSpace email template, Greeting field
|
||||
// UnsharedSpace email template, resolves via {{ .Greeting }}
|
||||
Greeting: Template(`Hello {SpaceGrantee},`),
|
||||
// UnsharedSpace email template, Message field
|
||||
// UnsharedSpace email template, resolves via {{ .MessageBody }}
|
||||
MessageBody: Template(`{SpaceSharer} has removed you from "{SpaceName}".
|
||||
|
||||
You might still have access through your other groups or direct membership.`),
|
||||
// UnsharedSpace email template, CallToAction field
|
||||
// UnsharedSpace email template, resolves via {{ .CallToAction }}
|
||||
CallToAction: Template(`Click here to check it: {ShareLink}`),
|
||||
}
|
||||
|
||||
MembershipExpired = MessageTemplate{
|
||||
bodyTemplate: "spaces/membershipExpired.email.body.tmpl",
|
||||
// MembershipExpired email template, Subject field
|
||||
// MembershipExpired email template, Subject field (resolves directly)
|
||||
Subject: Template(`Membership of '{SpaceName}' expired at {ExpiredAt}`),
|
||||
// MembershipExpired email template, Greeting field
|
||||
// MembershipExpired email template, resolves via {{ .Greeting }}
|
||||
Greeting: Template(`Hello {SpaceGrantee},`),
|
||||
// MembershipExpired email template, Message field
|
||||
// MembershipExpired email template, resolves via {{ .MessageBody }}
|
||||
MessageBody: Template(`Your membership of space {SpaceName} has expired at {ExpiredAt}
|
||||
|
||||
Even though this membership has expired you still might have access through other shares and/or space memberships`),
|
||||
|
||||
Reference in New Issue
Block a user