Tutorial

Sending notifications

With cplaceJS it's also possible to send notifications to users to inform them about certain events.

Note: In order for this api to work as expected user notifications have to be enabled in the system configuration.

Table of contents
  1. Basic command
  2. Messages & internationalization
  3. Critical notifications
  4. Targets
  5. Recipients
  6. Full example

Basic command

The most basic notification just carries a message to whoever triggers the script which calls the sendNotification method:

cplace.actions().sendNotification({
    message: 'The cake is a lie!'
});

Without a message sending notifications is not possible and will raise errors. A notification with only a message however probably won't suffice most use cases so we want to pour in some more information.

Messages & internationalization

We can add some more information by providing a title and an icon, which will be displayed at the top of the notification by providing the title and icon properties:

cplace.actions().sendNotification({
    message: 'The cake is a lie!',
    title: 'Attention!',
    icon: 'fa-birthday-cake' 
});

If you need help finding the name of an icon you can have a look at the icon setting for pages - notifications support all icons available in cplace - or browse the official font awesome documentation (this documentation does not cover cplace specific icons though).

Every text in a notification is capable of internationalization. To do so just provide a localized string object with a languageId-message-pair like:

{
    message: {
        de: 'Der Kuchen ist ein Schwindel!',
        en: 'The cake is a lie!'
    },
    title: {
        de: 'Achtung!',
        en: 'Attention!'
    }
    ...
}

Critical notifications

If the notification bears critical or urgent information you can flag it as important by setting the isCritical flag:

{
    ...
    isCritical: true,
    ...
}

This way the notification will be rendered in a different color (depending on the configured theme) so that it can be told apart from regular notifications easily.

Targets

It is possible to link a notification to a specific page or url so that the user will be redirected to the provided source when clicking the notification. To do so just provide a page object or Uid or a target url to the target property (be aware of the fact that linking an external url may be blocked or bear potential security risks, so be careful when linking to foreign domains):

{
    ...
    target: 'https://www.collaboration-factory.de',
    ...
}

Recipients

A crucial (but not mandatory) functionality of the sendNotification command is notifying targeted and/or multiple users at once. To do provide the users you want to notify to the recipients property. recipients accepts the following formats: Person, Group or SystemGroup object, Uid of a Person, Group or SystemGroup or an array of any of those (mixed types are also possible):

{
    ...
    recipients: [personA, groupB, 'person/uid_1', 'group/uid_2'],
    ...
}

or if you want to address all active users (use with care!):

{
    ...
    recipients: cplace.utils().getAllUsersGroup(),
    ...
}

Full example

If we apply all possible options to the command we get something like this:

cplace.actions().sendNotification({
    message: {
        de: 'Der Kuchen ist ein Schwindel!',
        en: 'The cake is a lie!'
    },
    title: {
        de: 'Achtung!',
        en: 'Attention'
    },
    icon: 'fa-birthday-cake',
    isCritical: true,
    target: 'https://www.collaboration-factory.de',
    recipients: cplace.utils().getAllUsersGroup()
});