Constraints - AtlasOfLivingAustralia/ecodata-client-plugin GitHub Wiki

Data model items with type "text" or "stringList" can include a constraints attribute. This attribute specifies valid values for the data item. This would normally be used with a view model type of "selectOne", "selectMany", "select2" or "select2Many" to provide options for an HTML select element.

The value passed to the constraints can take a few forms.

1. An array of values. e.g. ["1", "2", "3"]
2. An array of name/value pairs:

[
  {"id":"1", text:"Item 1"}, 
  {"id":"2", "text":"Item 2"}
]

If your name/value pairs do not use the attributes "id" and "text" (for example because they are pre-populated (see item 3.2)), you can specify the attribute names using the "textProperty" and "valueProperty" attributes:

{  
  "type":"literal",
  "literal": [
    {"value":"1", "label":"Item 1"}, 
    {"value":"2", "label":"Item 2"}
  ],
  "textProperty":"label",
  "valueProperty":"value"
}

3. An object with an attribute named "type". Valid values for the "type" attribute are "computed", "pre-populated", and "literal". Note: "computed" and "pre-populated" constraints are potentially vulnerable to the declaration dependency issue for computed variables and behaviours as well as a load sequence problem. When re-populating a saved form, the saved value of the field must be available to be selected from the available constraints or it will be overwritten with undefined by the knockout binding. To resolve this, either the declaration order needs to be taken into account, or the superset of constraints can be supplied in the "defaults" attribute. The field can use the "enable" behaviour to require a selection from its dependencies so the defaults are not viewable by the user.

3.1) Computed constraints must take the form:

{
   "type":"computed", 
   "default":["1", "2"], 
   "options":[
       {
          "condition":"expression1", 
          "value":["2","3"]
       }, 
       {
          "condition":"expression2", 
          "value":["1", "2"]
       }
    ]
}

The expressions in the options attribute are evaluated in order, the first expression to return true supplies the constraints via the "value" attribute. If all expressions return false the value of the "default" attribute is used.

3.2) Pre-populated constraints follow the same configuration options as the "pre-populate" top level model element. The mapping must be constructed in a such a way as to return either an array of values as per item 1 or an array of objects as per item 2.

{
   "type":"pre-populated", 
   "default":["1", "2"], 
   "config": {
      "source": {
        "context-path": "owner.custom.dataSets"
      }
   },
   "textProperty": "name",
   "valueProperty": "dataSetId"
}