Choice item¶

The purpose of a choice item is to provide a way to capture and manipulate the object position in statements.

The allowed values for the object position are steered by available choices from either a fixed lists or detected via the chooser mechanism. In the editing view the user typically selects or searches for allowed values.

Choice item reference¶

Key	Explanation
type	Must be "choice" for choice items
id	Identifier for the item
property	A leading property required to be matched for this choice item. For example, `http://purl.org/dc/terms/subject` corresponding to the predicate of a RDF statement where the object is specified to be a value according to the choices.
pattern	A regular expression to match the provided value against.
cardinality	See separate section on cardinality.
nodetype	Allowed values are ONLY_LITERAL, LANGUAGE_LITERAL, DATATYPE_LITERAL, and URI, see separate section on nodetypes.
datatype	A single datatype. May be namespaced. Only used if nodeType is DATATYPE_LITERAL.
constraints	An object with attribute value pairs corresponding to predicate and objects constraints, that is, for a resource to be matched to this group there must exist a corresponding statements for each pair. A common case is to require a type, that is, `{"http://www.w3.org/TR/rdf-schema/type": "http://example.com/SomeClass"}`.
deps	Dependency path that determines if the statement will be expressed. See separate section on dependency paths.
value	A hardcoded value that will be used to create a statement if no matching statement is found.
language	A language value that will be used together with the value key to create a statement if no matching statement is found, only used if nodetype is LANGUAGE_LITERAL.
label	A multi-language label for the choice item.
editLabel	A multi-language edit label for the choice item, has higher priority than label in edit view (if provided).
description	A multi-language description for the choice item.
editDescription	A multi-language edit description for the choice item, has higher priority than label in edit view (if provided).
placeholder	A multi-language text that will be shown in input fields before user starts to type.
help	A multi-language help text that will be shown if the provided value does not fit the pattern.
text	A set of multi-language texts, parametrized by keys. The keys are typically something like "title", "purpose", "usagenote", "mapping", "example" etc.
styles	An open-ended list of attributes that is used by the different views to control behaviour. See separate section of well supported attributes.
cls	An array of css classes that will be inserted in the DOM structure for this choice item when renderered in a view.
uriValueLabelProperties	Array of properties to be used to detect a suitable label if the nodetype is URI.
choices	An optional array of choices, see explanation below.

Note, if no array of choices are provided in the template it is expected that choices will be generated dynamically by making a query based on the provided constraints. For this to work the surrounding application that embeds RDForms need to implement and register a chooser, see separate section on this.

Example¶

{
    "id":"http://example.com/rforms/subjectVocab",
    "type":"choice",
    "label":{"en":"Subject"},
    "description":{"en":"A subject in high school"},
    "nodetype":"URI",
    "constraints": {"http://www.w3.org/2004/02/skos/core#inScheme":"http://example.com/HighSchoolSubjects"},
    "property":"http://purl.org/dc/terms/subject",
    "cardinality": {"min": 0, "max": 1}
}

Choice expression¶

Reference¶

Key	Explanation
value	A string which corresponds to a URI or a literal as determined by the nodetype.
label	A multi-language label to show instead of the value.
editLabel	A multi-language edit label for the choice, has higher priority than label in edit view (if provided).
description	A multi-language description for the choice.
editDescription	A multi-language edit description for the choice, has higher priority than label in edit view (if provided).

Example with two fixed choices¶

We extend the example above with two fixed choices. We also indicate that we want to show them as radio buttons oriented vertically. Note that a requirement for the radio buttons to work is that the max cardinality is set to 1.

{
    "id":"http://example.com/rforms/subjectVocab",
    "type":"choice",
    "label":{"en":"Subject"},
    "description":{"en":"A subject in high school"},
    "nodetype":"URI",
    "constraints": {"http://www.w3.org/2004/02/skos/core#inScheme":"http://example.com/HighSchoolSubjects"},
    "property":"http://purl.org/dc/terms/subject",
    "cardinality": {"min": 0, "max": 1},
    "choices": [{
        "value": "http://example.com/physics",
        "label": {"sv": "Fysik", "en":"Physics"},
        "description": {"sv": "Ämnet fysik i gymnasiet.", "en":"The subject physics in high school."}
    },{
        "value": "http://example.com/chemistry",
        "label": {"sv": "Kemi", "en":"Chemistry"},
        "description": {"sv": "Ämnet kemi i gymnasiet.", "en":"The subject chemistry in high school."}
    },
    "styles": ["verticalRadioButtons"]
]

Binding mechanism¶

A choice item can be used to bind existing statements as well as create new statements. The binding step is performed by the RDForms engine that takes an RDF graph a template and a staring node as input and produces a binding tree as output. Below we describe both the matching and the creation step for statements.

Matching statements¶

A binding is created for every statements that matches:

the subject from the surrounding group
the given property
the given nodetype
the pattern (if any)
one of the given datatypes (if any)
one of the given languages (if any)
one of the given choices (if choices is given and the style strictmatch is set)

The result of the binding step is always a choice, either one of the fixed ones provided or a choice created automatically. For the fixed choice it is likely that it contains useful information that makes the value easier to present, e.g. a nice label and description. However, in the case where a choice is automatically created the properties provided by uriValueLabelProperties will be used to try to automatically detect a label for presentation purposes. Note also that the chooser infrastructure can be used to provide custom information for the automatically created choices.

Creating statements¶

A choice item can be used to create a statement based on the user input in the form of choices, either fixed or returned from a chooser. The value of the choice will be expressed based on:

The nodetype will decides if it is a URI or a literal.
If a datatype is provided in the choice item it will be added.
If a fixed language is provided in the choice item it will be added.