Skip to main content

Event

Events are used to call actions from elsewhere in the app.

This is either achieved by triggering a fireEvent action and specifying the event that is to be called or by defining a success or error event in an action that supports it (e.g. request action).

Just like functions or methods in a programming language, “events” execute a list of actions as soon as they are called. There are local and global events:

  • local: used within the same template they are defined in
  • global: available in the entire application.

Local events​

Local events are defined within the events field of a template as follows:

{
  "name": "myTemplate",
  "content": {
    "viewType": "layered",
    "content": { ... },
    "events": [
      {
        "type": "myEvent",
        "actions": [
          {
            "type": "showMessage",
            "params": {
              "text": "My event has been triggered."
            }
          }
        ]
      }
    ]
  }
}

This code snipped describes the event myEvent which triggers a showMessage action when called. An event like this could be used to notify the user after a successful call to a third party API (see the request action).

The type of the event can be chosen freely (except for those mentioned in Predefined events).

info

To define events in a template, the template must be a node template (templateIsNode has to be true), see showView.

Global events​

Global events are defined as individual JSON files in the ./event directory of the configuration. The basic structure of an event is as follows:

{
  "name": "myEvent",
  "content": {
    "type": "myEvent",
    "actions": [
      {
        "type": "showMessage",
        "params": {
          "text": "My event has been triggered."
        }
      }
    ]
  }
}

In addition to the type, an event must be assigned a name which should match the filename. The type is similar to a function or method name in other programming languages. When calling an event, this will be the identifier the callee will look for. The name on the other hand has no significant importance and only serves as a simple identifier.

Predefined events​

There is a list of predefined events which are automatically executed depending on certain triggers:

Global Lifecycle​

  • appDidStart: triggers after a fresh app start (e.g. after completely wiping the app from memory)
  • appResumed: triggers when the app enters the foreground (e.g. after switching to a different app and back again)
  • appPaused: triggers when the app enters the background (e.g. when switching to a different app)
app lifecycle app lifecycle

Other predefined events include:

  • returnActionPerformed: triggers when the return key on the keyboard is clicked in a textBox
  • actionPerformed: triggers when clicking on an element of a form
  • navbarLogoClicked: triggers when clicking on the navbar logo
  • onlineStatusChanged: triggers when the online status changes. The parameter isOnline will contain the new status
  • networkTypeChanged: triggers when the network type changes. The parameter networkType will contain the new type. This can be wifi, ethernet, cellular or unknown

Local Lifecycle​

These events exist on a local level for a specific layout:

  • viewCreated: triggers when a view is created
  • viewResumed: triggers when a view moves to the foreground again (in Android also after a system pop-up)
  • viewPaused: triggers when a view moves to the background (in Android also during a system pop-up)
  • viewDestroyed: triggers after a view is destroyed (e.g. when leaving/navigating out of a screen)
local lifecycle local lifecycle

Delimiters​

Data which is sent to an event can be accessed via a mustache like syntax like {{data}}. In some circumstances these delimiters are reserved e. g. for data binding in a template. In this case a custom set of the delimiters can be defined using the parameters leadingDelimiter and trailingDelimiter of the event.

Conditional events​

An event may have conditions attached to it that limit when the event is triggered and optionally whether a set of different actions ("elseActions") should be triggered instead:

{
  "name": "myTemplate",
  "content": {
    "viewType": "layered",
    "content": { ... },
    "events": [
      {
        "type": "myEvent",
        "leadingDelimiter": "{$",
        "trailingDelimiter": "$}",
        "conditions": {
          "left": {
            "context": "parameter",
            "field": "viewCount"
          },
          "mode": "greaterThan",
          "right": "0"
        },
        "actions": [
          {
            "type": "showMessage",
            "params": {
              "text": "There have been {$viewCount$} views so far."
            }
          }
        ],
        "elseActions": [
          {
            "type": "showMessage",
            "params": {
              "text": "There have been no views so far."
            }
          }
        ]
      }
    ]
  }
}

This event evaluates the field "viewCount" in a condition and checks whether it is greater than zero. If so, a message is shown with the current view count but using custom delimiters. In addition, an elseAction is defined that is triggered if the condition is not met, i.e. if viewCount is 0 or less, and display an alternative message instead.

info

elseActions are optional. Alternatively, an if action or multiple conditions can be used to achieve the same behavior.