01 Schema Description - abrice/zyanfsv GitHub Wiki

Schema

A [schema] is a JSON object that has an array of nodes that describe what will be drawn.

    {nodes: []}

Other key/values can be included in the JSON object but are ignored. For example:

    {description: "A useful description of the schema",
     nodes: []}

Nodes

An array of nodes that make up the schema. Each node is specified using the following properties:

  • id: a unique identifier for this node. Must only be composed of alphanumeric characters (letters and numerals)

  • shorttext: not used

  • groups: an array of groups to which this node belongs. Not used

  • type: One of:

    • "tile" A display element consisting of one or more layers
    • "validator": a [calculatorstring] and a [template] to perform a calculation validating tiles
    • "ignore": the node will not be processed. Available as a convenience so that individual nodes can remain in the schema but not appear in the visualisation. Useful for comments, code-spaces, or test tiles within the schema.

  • x: a value, in pixels, of the x position of the node within the parent container (eg: the holding [div])

  • y: a value, in pixels, of the y position of the node within the parent container (eg: the holding [div])

  • either:

    • sum: an array of translatorCodes that will be summed to provide the node's values or

    • calculator: an object made up of:

      • prefetchfields: an array of translatorCodes which will be used in the calculation. For example:

      ["revenue.total"]

      • calculatorstring: a string representation of the function that the calculator will calculate. For example:

      "return Math.round(d['revenue.total']+(d['revenue.total'])*1000)/10;"}

  • layers: an array of layers that make up the constituent parts of the node (see 'layers' section below)

An example of a node would be:

      "nodes": [
                {"id":"TotalLiabilities",
                 "shorttext":"Total Liabilities",
                 "groups":["balancesheet"],
                 "type":"tile","x":186,"y":200,
                 "sum":["liabilities.total"],
                 "layers":[]},
                 ...
               ]

layers

The constituent parts of a node. Each layer is a [type]. Layers are drawn in the order they are presented which therefore determines the depth of the layers on the screen.

Type: rect

Draws a rectangle

  • width: the width, in pixels, of the rectangle
  • height: the height, in pixels, of the rectangle
  • xadd: an offset, in pixels, to the parent x-position
  • yadd: an offset, in pixels, to the parent y-position
  • spec: an object containing:
    • fill: a colour value (#xxxxxx or "red") for the fill
    • stroke: a colour value (#xxxxxx or "red") for the border
    • strokewidth: a value, in pixels, for the width of the border
    • rx: a value, in pixels, for the horizontal rounding of all the bar's corners. rx and ry are normally equal.
    • ry: a value, in pixels, for the vertical rounding of all the bar's corners. rx and ry are normally equal.
    • style: a string value reference to a predefined style. Currently styles are defined in the colourmapService. [style] allows a consistent fill/stroke colour to be applied more easily to a range of [rect]s

For example:

       {"type":"rect","width":122,"height":10,"xadd":-1,"yadd":40,
            "spec": {"fill": "#8dd3c7","stroke":"#7795a9","strokewidth":"0"}
        }

Type: barchart

Draws the columns for a bar chart using the parent's values

  • width: the width, in pixels, of the containing rectangle
  • height: the height, in pixels, of the containing rectangle
  • xadd: an offset, in pixels, to the parent x-position
  • yadd: an offset, in pixels, to the parent y-position
  • title: an object containing:
    • shorttext: needed?
    • dataformat:
  • scale: One of:
    • "self"
    • "value" and use [scalevalue]
    • "fields" and use [scalefields]
    • "max" and use [scalefields]
  • scalevalue: used if [scale] is set to "value"
    • a single value that will be used to establish the upper and lower scale bounds
  • scalefields: used if [scale] is set to "fields" or "max"
    • "fields": an array of translatorCodes that will be summed to establish the upper bound. Zero is assumed for the lower bound.
    • "max": an array of translatorCodes where the maximum period value will be used to establish the upper bound. Zero is assumed for the lower bound.
  • spec: an object containing:
    • fill: a colour value (#xxxxxx or "red") for the bar's fill
    • barwidth: the width, in pixels, of an individual bar. This value will overwide the default bar width
    • barspacing: the width, in pixels, of the spacing between individual bars. This value will overwide the default bar barspacing
    • rangemaxvalue: the maximum height of any bar in pixels. This value will overwide the default barchart rangemaxvalue

For example:

       {"type":"barchart","width":120,"height":70,"yadd":50,
            "title":{"shorttext":": ","dataformat":",.4s"},
            "scale":"fields","scalefields":["liabilities.current.total"],
            "spec": {"fill": "#0e8e78"}

Type: circle

Draws a circle

  • r: the radius, in pixels, of the circle
  • xadd: an offset, in pixels, to the parent x-position
  • yadd: an offset, in pixels, to the parent y-position
  • spec: an object containing:
    • fill: a colour value (#xxxxxx or "red") for the fill
    • stroke: a colour value (#xxxxxx or "red") for the border
    • strokewidth: a value, in pixels, for the width of the border

For example:

       {"type":"circle","r":22,"xadd":-1,"yadd":20,
        "spec": {"fill": "#ff5522","stroke":"#cccccc","strokewidth":"0"}
       }

Type: text

Draws text. Three sources of text are supported:

1 User-specified using the [shorttext] property

2 Injecting a value, dvalue, or pvalue using [shorttextdatasource] and [shorttextdatasourceidx]

3 Injecting a value using translatorCodes which provides multi-lingual support

  • shorttext: the text to display

  • i18id: a string value of the id referenced within the taxonomy file. If available, that value will be injected (and shorttext will be ignored).

  • class: a string value of a pre-defined css class to be applied to the text

  • width: the width, in pixels, of the virtual width of the text. If the text is wider than the width, it will still fully display.

  • xadd: an offset, in pixels, to the parent x-position

  • yadd: an offset, in pixels, to the parent y-position

  • spec: an object containing:

    • fill: a colour value (#xxxxxx or "red") for the fill
    • textanchor: a string value of [middle], [start], or [end]
    • fontsize: a value, in pixels, for the size of font to use
    • fontweight: a string value of [bold] or [normal]
    • rotate: an angle, in degrees to rotate the text
    • opacity: a value, between 0 and 100, of the opacity of the text

  • shorttextdatasource: a string value of:

    • "values" - the actual values for each period or

    • "dvalues" - the difference to the prior period or

    • "pvalues" - the percentage difference to the prior period

           eg:  values = [10,20,50]
         dvalues = [ 0,10,30]
         pvalues = [ 0,100,150]

  • shorttextdatasourceidx: an index to the datasource. The datasource is in the same order as provided in the periods[] array. [0] means the first period in that array, n means the nth period in that array. [shorttextdatasourceidx] is zero-based.

  • shorttextdataformat: a string value of a d3 format specification. eg: ",.1f"

  • shorttextdataformatsuffix: a string value that will be appended to the end of the displayed text. eg "%"

  • abs: a boolean value that will apply Math.abs() to the shorttext value

For example:

       {"type": "text", 
        "i18id":"assets.noncurrent.investments",
        "class":"titlestrongtext",
        "width":46,
        "yadd":0,
        "spec": {"fontsize":9,"textanchor": "middle","fill": "#000000"}
       }