Today's conversation on UIOptions schema work

Antranig Basman antranig.basman at
Tue Jun 25 04:42:40 UTC 2013

Following on from last week's architecture meeting, Yura, Cindy and Justin have been producing initial 
implementations based on the "primary schema" and "auxiliary schema" concept for the UIOptions family of 
components (which will in time comprise all families of preference editors throughout the GPII, such as the 
PMT, PCP and Discovery Tool, etc.). Wiki pages describing these schemas are at
and the umbrella JIRA describing the purpose of this work at

Today's discussion was rather complex and didn't reach a complete conclusion about all aspects of the API 
plan, but a few issues were settled and some questions partially closed.

Firstly, looking at the "UIOptions Builder" described in this JIRA (in case it is edited, the sketch showed this structure for 
a schema-driven UIOptions:

// New uio defaults to include a dynamic grade which is returned by the fluid.uioBuilder
fluid.defaults("fluid.uiOptions", {
     gradeNames: ["fluid.viewComponent", "autoInit", "{that}.builtGrade"],

     primarySchema: "",
     auxSchema: "",

...) it was determined that the UIOptions design should be returned to its original form, and schemas only 
accepted by the UIOptions builder itself. This will lead to a simpler design with a clearer separation of 
schematic levels. We may choose, for convenience, to later expose an all-in-one "build and instantiate" API 
which operates both levels of construction in one step.

Questions remain about the "key structure" of the primary schema, as well as how different elements in the 
auxiliary schema are to be tied together. A crucial section of the auxiliary schema currently reads as follows:

    "emphasizeLinks": {
         "enactor": {
             "type": "fluid.uiEnhancer.emphasizeLinks",
             "cssClass": "fl-link-enhanced"
         "settingsPanel": {
             "type": "fluid.uiOptions.linksControls",
             "modelPath": "links"
     "inputsLarger": {
         "enactor": {
             "type": "fluid.uiEnhancer.inputsLarger",
             "cssClass": "fl-text-larger"
         "settingsPanel": {
             "type": "fluid.uiOptions.linksControls",
             "modelPath": "inputsLarger"

This is problematic for a couple of reasons - firstly, the intention that there is just ONE settingsPanel 
covering two options is not clear. Secondly, the specification of the additional "modelPath" option is in 
theory redundant and unclear - where there is scope for configuration, there is scope for misconfiguration.

By supplying more "metadata" in the grade structure of enactors and panels, which allows a declarative 
inspection of exactly which options are handled by a panel, we could arrive at a scheme which allows for 
more automation, as well as making more realistic the use case of a UIOptions which is driven entirely from 
the preference set with an "empty auxiliary schema".

This also reminded us of an issue which was discussed in last week's meeting but didn't manage to make the 
reports, that of "schema grades". Last Wednesday, Anastasia asked how users of UIO were intended to 
construct "primary schema documents", given their desire to have a UIO initially expressed only in terms of 
the identity of the preferences required. I suggested that this process would be helped by attaching the 
small section of (primary) schema associated with a preference to a dedicated grade - the total primary 
schema could then be assembled by the natural operation of grade merging. A sketch for such a schema grade 
is as follows:

fluid.defaults("fluid.uiOptions.schema.textSizer", {
     gradeNames: ["fluid.uiOptions.schema"],
     schema: {
         "": { // NB: Incorrect key here - see discussion
             "type": "number",
             "default": 1,
             "min": 1,
             "max": 2,
             "divisibleBy": 0.1

The key name appearing in the schema leads on to the final problem discussed. We temporarily floated the 
idea of reversing last week's decision and trying to key the primary schema by strings drawn from an 
existing GPII ontology, e.g. that of the common terms registry. However, reflection suggests that this is 
not correct and we should continue with the determination of last week to have all code-side artefacts 
follow what could be called the "code ontology". This is driven by the fact that the value range operated by 
the code implementation may not agree with that held in the common terms registry for a preference, and may 
require transformation - given this, we should also operate "code-side" naming for preferences. This implies 
that we place grade names in the code namespace directly corresponding to preferences - although these may 
or may not have any implementation. This could then be used to tie together instances of the three separate 
hierarchies (schema, enactor, panel) to stably identify which options they had in common. Our naming for 
these hierarchies is currently irregular but looks something like the following:

     fluid.uiOptions.enactor.textSizer (or fluid.uiEnhancer.textSizer)
     fluid.uiOptions.textSizer (settingsPanel name - currently collides)

This common grade name would then be what appears in the primary schema as key rather than the registry URL.

A tentative suggestion was the use of a special common option appearing in all three hierarchies, perhaps 
looking something like the following:

     fluid.defaults("fluid.uiOptions.linksControls", {
         gradeNames: ["fluid.uiOptions.settingsPanel", "autoInit"],
         handlesOptions: ["fluid.uiOptions.emphasizeLinks", "fluid.uiOptions.inputsLarger"], <= HERE we use 
"common grade names"

This still leaves some problems unresolved - for example, how exactly it is that the "model offset path" 
corresponding to a setting is determined. But this suggests that the "auxiliary schema" perhaps is separated 
into two sections - one which holds a mapping of model offset paths to common grades (as well as common 
options) and then a separate, optional section which provides dedicated configuration to specific enactors 
and panels to be configured. Configuration could be left blank, e.g. in the case of enactors which were the 
unique enactor which handled a particular common grade and required no further options.

This might look something like this:

     // First block: defines model paths and common grade contents
     "textSizer": {
         "type": "fluid.uiOptions.textSizer",
          // other common options
     // Second block: Flat lists of enactors and panels (optional)
     "enactors": [{
         "type": "fluid.uiEnhancer.textSizer", // or whatever it is
          // specific options - might use some kind of reference notation to refer to "first block" material
     "settingsPanels": [{
         "type: "fluid.uiOptions.linksControls"
          // specific options

In this model both enactors and settingsPanels are presented as a flat list, and the UIOptions builder uses 
the metadata at its disposal from the grade hierarchies to determine any interrelationships between those 
grades, as well as automatically inferring any "rules" entries (modelPath) based on the correspondence 
between common grade options. Under this model, the "primary schema" also becomes an optional input to the 
UIOptions builder, since it could be completely inferred by use of the metadata mapping for grades defined 
in the first block of the auxiliary schema onto the "schema grades".

Out of scope in this discussion so far is where "synthetic grade names" appear in the auxiliary schema. The 
overall action of UIO will be to construct some "overall UIOptions grade" which can then be instantiated. 
This should be named in the schema. We floated the idea today that some intermediate grade names might be 
constructed, perhaps keyed by "first block" material. It is also possible that a combination of the primary 
and auxiliary schema might be used to construct "new grades from old" - by altering either the schema grade 
contents or the grade content of enactors or panels to construct new grades handling new preferences

Some rambling analysis is also present in this PiratePad (although in the end no less rambling than this 

We will have a brief meeting tomorrow to talk over our settling ideas about these issues, and a longer one 
following our standard Fluid Community Meeting slot on Wednesday.


More information about the fluid-work mailing list