Developing with Exhibitera

The apps in Exhibitera Apps are built using JavaScript. This approach ensures maximum flexibility, while also offloading many performance and security concerns to the rendering engine. It also makes developing your own app surprisingly easy!

Exhibitera Apps provides a JavaScript module, exhibitera_app_common.js, that enables easy connection with Exhibitera. In just a few lines of code, you can have an app up and running! Here is the complete code to create a blank Exhibitera app (the JavaScript file, at least):

import * as exCommon from 'exhibitera_app_common.js'

function loadDefinition (definition) {
  // A function to configure your app's content
  // based on the provided configuration.
  ... 
}

function parseUpdate (update) {
  // A function to respond to commands from
  // Exhibitera Hub.
  ...
}

exCommon.configureApp({
  name: 'other',
  loadDefinition: loadDefinition,
  parseUpdate: parseUpdate
})

Note that exhibitera_app_common.js is a JavaScript module, so your file must also be a module.

Definitions

Definitions are user-provided configuraitons for your app. Users can use the Other App setup page in Exhibitera Apps to pass parameters to your app. Based on those parameters, you can configure the app as needed. These parameters are given in the parameters field of the defintion:

{
  ...
  parameters: {
    'parameter 1': 'value 1',
    'parameter 2': 'value 2'
  },
  ...
}

You can ignore the other fields in the definition, as they are for interal Exhibitera use.

Updates

If your user is using Hub, your app will check in with the server every five seconds. This updates the Hub web console and retrieves any updates from the server.

Interaction status

Your app can communicate whether it is in active use by setting the value of exCommon.config.currentInteraction. Set the value to true when interaction begins and false when it ends. One common way of defining "ends" is when the attractor is shown again. Properly setting this variable helps your user understand how the app is being used and enables them to collect analytics.

Responding to commands

Hub may send a command in response to a user action, an event in the schedule, or another app. Built-in commands, such as refreshing, restarting, and shutting down, are handled automatically by Exhibitera.

Using the parseUpdate() function, your app can respond to custom commands.

Reading and writing local data

You can read and write local data by using exCommon.makeHelperRequest(). For example, here is the code used to save votes from Voting Kiosk:

exCommon.makeHelperRequest(
  {
    method: 'POST',
    endpoint: '/data/write',
    params: {
      name: 'votingData',
      data: {
        option1: 5,
        option2: 8
      }
    }
  })

makeHelperRequest() returns a Promise that resolves with two fields, the boolean success and the string reason. If the write fails, reason will provide helpful details.

/data/write POST

Write a JavaScript object to disk. Each request will write one line of JSON to the file. The user can download the file as a CSV spreadsheet from the Exhibitera Apps configuration page.

{
  data: {
    key1: 'value1',
    'key 2': ['value 2', 'value 3']
  },
  name: 'myDataFile'
}

data Object

A JSON-serializable object.

name String

A string filename without an extension. The extension '.txt' will be appended.

/data/writeRawText POST

Write the given text to file for later retrieval. If you wish to write JSON, you must call JSON.stringify() yourself first.

{
  text: 'A string of text',
  mode: 'a',
  name: 'myDataFile'
}

text String

The text to be written to file.

mode String

Pass 'a' (default) to append to the file or 'w' to overwrite the file.

name String

A string filename without an extension. The extension '.txt' will be appended.

/data/getRawText POST

Retrieve a previously-written data file.

{
  name: 'myDataFile'
}

name String

A string filename without an extension. The extension '.txt' will be appended.