Skip to content

Getting started

Trackers and custom data attributes are defined through JSON schema with some extensions that manage data capture and display.

Schema definitions follow the JSON schema specification. More information is available at json-schema.org with a step by step tutorial available and more information at understanding json schema.

Custom attributes

Custom attributes have been added to the definitions and prefixed with $.

Tracker display

When opened tracker displays are shown as 3 blocks ordered by the order attribute. The middle block is displayed as a table.

  • Header - chart, map (or map-header), header will display here
  • Body - most attributes will display here
  • Footer - map-footer, chart-footer, footer will display here

Tracker definition

If set the dispatch will show a template up front that can draw on the metric data to summarize the entry. This can provided by configuring Format (displayFormat in the API) and can also leverage Expression (displayExpression in the API) to compute some values.

The expression supports the same syntax as compute (see below). Example "values.a * values.b". To use the expression in the display format use {expression}. For example to convert a value called "rating" ranging from 1 to 7 to a % for display:

The template supports Markdown.

Expression: (values.rating / 7) * 100
Format: Your rating is {expression|numeral:0}%

Best practices

Follow these best practices when creating trackers:

  • Use camel case - a JavaScript standard - for metric property names. For example a metric called "Event Rating" would be eventRating in camel case.
  • Property names should follow JSON rules: start with a letter and can include a combination of letters and numbers but no spaces, dashes or other punctuation.
  • Always include an icon and color for the tracker. Always provide a format definition for the tracker. Expression is optional but can be used to make the format more usable.

$ref attribute

JSON schema supports a referral attribute called $ref that points to another part of the schema. This can be used to define shared components and re-use them within the document.

Tracker form configuration

The tracker view can be configured using $capture and $display custom attributes or by linking the tracker to a layout.

  1. Capture documentation
  2. Display documentation
  3. $data object
  4. $options object
  5. $marge array

Tracker icons

Icons supported

  1. Version 5.x from https://fontawesome.com/

Icon color can be modified by adding

  • text-danger
  • text-warning
  • text-success
  • text-info
  • text-forest
  • text-morpho
  • text-jacaranda
  • text-aqua
  • text-bold-green
  • text-white
  • text-muted

Example

{
    "title": "Wellness",
    "type": "object",
    "$options":{},
    "properties": {
        "stress": {
            "type": "integer"
            "minimum": 0
            "maximum": 7
            "enum": ["Not stressed", ...]
            "$capture": {
                "as": "range"
            }          
        }
        ... more properties ...
    }
    "required": ["stress", ...]
}

onSave scripting

Version 4

This feature is only available on the version 4 native app.

external fun props
external fun includes
external fun store
external fun at

// 夜,朝, 昼
var count_morning = 0
var count_noon = 0
var count_night = 0

for (var el of props()) {
  if (includes('.', '朝', el)) {
    count_morning = count_morning + 1
  }
  if (includes('.', '昼', el)) {
    count_noon = count_noon + 1
  }
  if (includes('.', '夜', el)) {
    count_night = count_night + 1
  }
}

var status = count_morning + count_noon + count_night
var goal = at("goal", 0, "int")
var summary = ""

if (status > 0 && status < goal) {
  summary = "◯"
} else if (status == goal) {
  summary = "◎"
} else if (status == 0) {
  summary = "✕"
}

store('morningActual', count_morning)
store('noonActual', count_noon)
store('nightActual', count_night)
store('status', status)
store('summaryResolved', summary)