Configurations

This page describes the details of the JSON format used to describe SCFFLD configurations.

Overview

Configurations are JSON files which describe an object graph which is to be built by the SCFFLD container. Each JSON object describes an object to be built by the container, with its property names corresponding to named properties of the object to be built. Once each object is instantiated, it is configured by injecting the JSON property values into the new object. JSON properties may be simple values (e.g. booleans, numbers of strings), collections (e.g. maps of arrays) or may be other objects to be instantiated and configured by the container.

Keyword names

A small number of reserved keyword names are used to indicate special properties used by the SCFFLD container to build the object graph. A hyphen- at the start of a property name indicates a reserved name.

The following sections describe some of the standard keyword names.

-type

This is used to indicate the type of the object that the container should instantiate when building a configuration item. Types are standard component names mapped to platform specific class names; the use of type names in place of class names allows configurations to be shared across platforms. (The container must be configured with mappings from type names to class names else where).

-ios: & -and: prefixes

These prefixes are used to indicate properties which should only be used when the configuration is loaded on a specific platform, i.e. -ios: prefixed properties will only be used by iOS apps etc.. When used, the prefix is stripped from the property name before the remainder is used to configure the object being built. This provides a mechanism for only applying certain configurations on certain platforms, e.g. a property named -and:color will configure a property named color, but only on Android systems.

-class, -ios-class & -and-class

These names can be used to specify the platform specific class name of the object being built. It is generally better to use a -type specifier, but a class specifier, when provided, will be used in preference to a type specifier. The -ios-class and -and-class names can be used to provide iOS or Android specific class names (note that the package qualified class name must be given on Android). The platform specific prefixes also work here, so -ios:-class is equivalent to -ios-class.

-factory

This is used to specify a factory object which should be used to instantiate and configure the required object.

-extends

This allows a full object configuration to be described as an extension of a base configuration. This means that, given two JSON objects A and B, representing two configurations, then the operation A <= B (B extends A) derives a new configuration C by copying all of the properties on B over the properties defined on A.

For example, if configuration A is an object { a: 1, b: 2 }; and B is an object { b: 'b', c: 'c' } then A <= B gives a final configuration { a: 1, b: 'b', c: 'c' }. Note that the operation overwrites any properties in A that are also defined in B, but preserves values only defined in one or the other configuration. Note also that the operation only performs a top-level merge of the two objects, i.e. it doesn't attempt to merge nested object values.

The configuration extension mechanism also supports configuration parameters. Properties can be defined in the parent configuration using parameter values; the values for these parameters can then be defined in the child configuration. See below for more details.

-mixin

Whilst -extends describes a vertical parent/child relationship between two configurations, the -mixin property is used to describe a horizontal relationship between two configurations. When a mixin is specified on a configuration then the values on the referenced object are copied over (or mixed-in with the target configuration.

-config

The -config name is a synonym for -mixin.

Value modifier prefixes

SCFFLD configurations support a number of value prefixes which are used at the very start of a JSON string property value to modify the meaning of the value.

Parameter references $

A $ at the start of a value is used to indicate a configuration parameter name, e.g. $param1; see Parameterized configurations below for a full description.

Value templates ? or >

A ? or > at the start of a value indicates that the rest of the string should be interpreted as a value template; see Value templates below.

URI references @

A string beginning with @ indicates an internal URI reference. The property value will be resolved to the value referenced by the URI. See the internal URI section.

Hash references #

A hash # at the start of a value indicates a reference to another part of the configuration file. The string after the hash should specify the key path to another JSON property value, relative to the JSON document root; e.g. #top.title will be resolved by first looking for the value of the property named top in the root of the document, and then the value of its title property.

Backtick escape `

The ` character is used at the start of a value to disable interpretation of value modifier prefixes. When used, it is stripped from the start of the string value and no further modified processing of the string is done. This is useful if the required string value uses one of the modifiers described above.

Parameterized configurations

A powerful SCFFLD feature is the ability to parameterize a configuration; that is, the ability to define configuration values using parameters that are provided by another configuration. This essentially allows configurations to be converted into configuration templates. The purpose of this feature is to allow commonly used configuration patterns to be easily captured and reused by varying the parameter values in specific use cases.

A parameterized configuration value is defined by mapping a configuration property to a string with the $ prefix. So for example, the property configuration "title": "$ScreenTitle" resolves to the value of the $ScreenTitle parameter when the configuration is loaded. Note that parameters can be mapped to any possible configuration value and are not confined to simple or string values. This means that it is possible to insert whole object sub-graphs as property values using parameters. Property values can be inserted at any point in a configuration and are not confined to top-level property values.

Configuration parameters are provided by child configurations which use the -extends keyword to extend the parameterized configuration. The parameter values are specified in the child configuration by using parameter names with a $ prefix. When the extend operation is applied to the pair of configurations, any top-level property names in the child configuration with the $ prefix are removed from the child configuration and are used to populate any property values mapped to the same property name in the parent configuration.

This can be more clearly understood from the following example.

A parameterized configuration is defined for a standard webview:

    {
      "StandardWebView": {
        "-type":    "WebView",
        "title":    "$Title",
        "content":  "$Content"
      }
    }

This configuration contains two parameters, $Title and $Content. These parameter values can be provided in a child configuration which extends the StandardWebView:

    {
      "HelpView": {
        "-extends":  "#StandardWebView",
        "$Title":    "Help",
        "$Content":  "@app:help.html"
      }
    }

Note how a hash reference - #StandardWebView - is used here to refer to the parent configuration (this assumes that StandardWebView is a top level property name in the JSON configuration file). The parent configuration can also be referenced in other ways, e.g. by using an internal URI to load the configuration from another file.

Value templates

Property values prefixed with ? or > are interpreted as string templates and have value substitution performed upon them, taking values from the parameters passed to the configuration. The template format is a very basic format that uses curly braces { } to demarcate value placeholders, for example ">Put value {here}". The template format does not support conditionals, loops or other structures.