Notifications format

Notifications

File format

All notifications are stored and uploaded in a single json file containing one JSON array. Each object in this array is representing a notification, when and how a notification will show up

Notification

Each of this notification specifications can have the following attributes

• once - After the notification is run once the triggers are removed and the notification won't be run for this session
• triggers - an array of triggers defining the entry point to a notification
• conditions - an array of conditions which have to be fulfilled in order to run the notification
• handlers - an array of handlers which define how the user is informed
• ignoreDate - All conditions related date are ignored; testing purpose

DOM Selection

A concept which repeates itself on triggers, conditions and handlers is the selection.
Whenever a dom element is needed this can be defined either via htmlId or htmlSelector.

htmlId is the id of the HTML element, e.g. tabConfiguration
htmlSelector the htmlSelector of the HTML element, e.g. div.active, #tabConfiguration.active, ... Under the hood, jquery is used so see https://learn.jquery.com/using-jquery-core/selecting-elements/

Example The same element is selected with the following definitions:

{
    "htmlId": "tabConfiguration",
}

or

{
    "htmlSelector": "#tabConfiguration",
}

Triggers

If a notification has an empty array as triggers, or the triggers attribute is not given, the notification is run immediately. Otherwise event handlers on dom element are registered.

A trigger must use DOM selection to select a HTML element.

A trigger must contain one of the following attributes

• event - a HTML event, e.g. click, hover, ...
• addClass or removeClass - a class which will trigger the event if it is added or removed to the selected element

A trigger can also define conditions, see conditions These conditions are specific to this trigger and are only evaluated if this specific trigger is triggered.

Examples

{
    "htmlId": "tabProgram",
    "event": "click",
    "conditions": [
        {
            "equals": "calliope2017NoBlue",
            "guiModel": "robot"
        }
    ]
}

{
    "htmlId": "simButton",
    "addClass": "rightActive"
}

Conditions

If a notification has an empty array as conditions or has no attribute condition, these are considered as "fulfilled".

A condition can have one of the following attributes to start with:

• startTime or endTime - a start time or a end time for this notification, given in the format YYYY-MM-DD HH:mm and for the German timezone (+0200)
• hasClass - if a selected element has the given class; here is a selector needed (see DOM selection)
• guiModel - the value of guiModel gets evaluated while running, see further

Examples

{
    "endTime": "2020-10-09 11:57"
}

{
    "startTime": "2020-10-09 11:57"
}

{
    "htmlId": "simButton",
    "hasClass": "rightActive"
}

GUI Model

A condition can contain a guiModel attribute which gets evaulated while running. E.g. if "guiModel": "robot" this gets evaluated to require("guiState.model").gui.robot

Then the value can be checked with one of the following attributes:

• anyOf - given as an array, the evaluated value of guiModel has to be one of the elements of the array
• equals - given as a string, the evaluated value of guiModel must equal the value of equals
• notEquals - given as a string or an array of string,
  if it is a string - the evaluated value of guiModel must not be equal to the given string
  if it is an array - the evaluated value of guiModel must not be equal to any of the given strings

Examples

{
    "anyOf": ["ev3lejosv1", "calliope2017NoBlue"],
    "guiModel": "robot"
}

{
    "notEquals": ["ev3lejosv1", "calliope2017NoBlue"],
    "guiModel": "robot"
}

{
    "notEquals": "calliope2017NoBlue",
    "guiModel": "robot"
}

{
    "equals": "calliope2017NoBlue",
    "guiModel": "robot"
}

Handlers

Currently there are 3 possible handlers.

Time

All handlers have in common that they can (but don't have to) contain an attribute time. After this given time the notification hides itself autmatically. If the attribute once is not set and this notification is triggered again, while still runing, the timer gets reseted.

Localization

All handlers have also in common that every text which is shown is given localized. Every text attribute must be wrapped in a JSON object defining the language.

Example

{
    "content": {
        "en":"English content", // necessary, since fallback for all other languages
        "de":"German content", // optionally other languages
        "fr":"French content" // optionally other languages
        ...
    }
}

Start Screen

This notification appears on the startup of the lab, in red color, added to the bottom of the modal. The handler need a (localized) attribute content which defines which content to display for the start screen. This attribute can have HTML code as content.

Example

{
    "startScreen": {
        "time": 6000,
        "content": {
            "de": "Wir verschenken Calliope",
            "en": "We give away calliope"
        }
    }
}

Popup notification

This notification appears in the bottom right corner with a yellow background. This has to contain the following attributes:

• title - the title (displayed as h4) of the notification, can also be HTML code (again localized)
• content - the content of the notification, can also be HTML code (again localized)

Example

"popupNotification": {
    "content": {
        "de": "Hey, wir haben die Simulation angepasst.",
        "en": "Hey, we changed the simulation ..."
    },
    "title": {
        "de": "Simulationsanpassung",
        "en": "Simulation changes"
    },
    "time": 5000
}

Element Marker

This notification appears on dom elements as little badge. The handler has to define the following attributes:

• htmlId or htmlSelector - to select the dom element, see DOM selection
• content - the content of the badge, less text, can also be HTML code (again localized)

Example

"elementMarker": {
    "htmlId": "tabConfiguration",
    "content": {
        "de": "Neu",
        "en": "New"
    }
}

Complete file example

[
  {
    "handlers": [
      {
        "startScreen": {
          "time": 6000,
          "content": {
            "de": "Wir verschenken Calliope",
            "en": "We give away calliope"
          }
        }
      }
    ]
    // No triggers set, this notification runs immediatlly
  },
  {
    "once": true,
    "handlers": [
      {
        "popupNotification": {
          "content": {
            "de": "Hey, wir haben die Simulation angepasst.",
            "en": "Hey, we changed the simulation ..."
          },
          "time": 5000,
          "title": {
            "de": "Simulationsanpassung",
            "en": "Simulation changes"
          }
        }
      },
      {
        "elementMarker": {
          "htmlId": "debugMode",
          "time": 2000,
          "content": {
            "de": "Neu",
            "en": "New"
          }
        }
      }
    ],
    "triggers": [
      {
        "htmlId": "simButton",
        "addClass": "rightActive"
      }
    ],
    "conditions": [
      {
        "anyOf": [
          "ev3lejosv1",
          "calliope2017NoBlue"
        ],
        "guiModel": "robot"
      }
    ]
  },
  {
    "once": false,
    "conditions": [
      {
        "endTime": "2020-10-09 11:57"
      }
    ],
    "handlers": [
      {
        "popupNotification": {
          "content": {
            "de": "Hey, Calliope benutzt nun eine Konfiguration",
            "en": "Hey, Calliope now uses a configuration"
          },
          "time": 5000,
          "title": {
            "de": "Konfiguration",
            "en": "Configuration"
          }
        }
      },
      {
        "elementMarker": {
          "htmlId": "tabConfiguration",
          "content": {
            "de": "Neu"
          }
        }
      }
    ],
    "triggers": [
      {
        "htmlId": "tabProgram",
        "event": "click",
        "conditions": [
          {
            "equals": "calliope2017NoBlue",
            "guiModel": "robot"
          }
        ]
      },
      {
        "htmlId": "menu-calliope2017NoBlue",
        "event": "click",
        "conditions": [
          {
            "equals": "tabProgram",
            "guiModel": "view"
          }
        ]
      },
      {
        "htmlSelector": ".popup-robot[data-type='calliope2017NoBlue']:not(.slick-cloned)",
        "event": "click"
      }
    ]
  }
]