## Using Forms in the UI ontology

The User Interface ontology at `http://www.w3.org/ns/ui` defines RDF terms for describing forms. The `solid-ui` project provides functions to use these forms within your web application to create a quick user interface solution. This document describes how.

The form system allows you to define a user interface declaratively in RDF. In your web app, you then:

1. make sure the ontology files are loaded
2. load the file with the form itself
3. call `UI.widgets.appendForm(dom, container, {}, subject, form, doc, callback)`

where

dom | is the DOM HTMLDocument object, a/k/a document
container | is a DOM element to contain the form
{} | are unused at present
subject | is the RDF thing about which data will be stored
form | is the RDF object in the store for the form
doc | is the RDF document on the web where the data will be stored. Often, `subject.doc()`
callback | is a function taking an error flag and a message (if the error flag is true)

If the form is a complex form, as the user adds more data, more form UI will be created. The data in each field is saved back to the web the moment the user has entered it. There is no general Save Button.

There is a form form for editing forms. It is in the form ontology itself.

You can of course go and write other implementations of the form system using your favorite user interface language.

#### Go to the source

- The ontology (source file)
- The implementation code

## Form field types

Form fields may be named or blank nodes in your file; the form system does not care. It is often useful to name them to keep track of them.

Below, all Field Classes and Properties are in the UI namespace, `http://www.w3.org/ns/ui#`, except the data types, like Integer, which are in the normal XSD namespace.

Here are some properties which you can use with any field (except the documentation fields).

label | String | A label for the form field. This is the prompt for the user, e.g., "Name", "Employer". If the label is not given in the form, the system will make one from a label of the property in the ontology.
property | rdf:Property | When the user enters the data, it is stored in the web as a triple with this property as its predicate.
default | [according to field type] Optional | The input control is set to this value by default. It is easiest for the user to enter this value. (This value is not automatically stored by the form system if the user does not select or enter it in some way.
suppressEmptyUneditable | Boolean | Setting this flag (on a single form field not a structure) means that when the user is just reading the data, not editing it, the fields with blank data will be removed completely. This avoid things like a blank field for a region in an address when there isn't one given. This can make the UX much cleaner. Defaults to false.

Other properties are given for each field type.

#### Form

The form itself has a collection of fields. The `parts` property gives an order list of the fields in each form.

parts | rdf:Collection (aka List, Array) of Field | The parts of the form in the order in which they are
part | Field (Obsolete) | A field which is a part of the form or group. This property is obsolete. Use parts.

If you use the obsolete "part" method for listing the parts of a form, then each field needs an additional property:

sequence | Integer | The parts of the form in the order in which they are

For each part, declare its type, and the extra data that type requires, as below.

#### Group

Group is a field which is just a collection of other fields. It is in fact interchangeable with Form.

### Single Value fields - Numeric

These prompt the user for a single value. They typically take default values, and min and max values.

#### BooleanField

A checkbox on the form, stored an RDF boolean true or false value.

#### TriStateField

A checkbox on the form, stores an RDF boolean true or false value, or no value if the box is left in its third, blank state.

#### IntegerField

An RDF integer value

#### DecimalField

An RDF decimal value. Useful for monetary amounts

#### FloatField

A floating point number

### Single Value fields: Special Types

#### ColorField

A color picker is used, and generates a string which is a CSS_compatible color in a string like `#ffeebb`

#### DateField

Uses a date picker on a good browser. Leaves an RDF date literal as its value.

#### DateTimeField

Leaves an RDF dateTime literal as its value.

#### PhoneField

Leaves as its value a named node with a `tel:` scheme URI

#### EmailField

Leaves as its value a named node with a '`mailto:`' scheme URI

### Single Value fields - Text

#### SingleLineTextField

#### MultiLineTextField

### Complex fields

#### Group

A group is simply a static set of fields of any type. Its properties are the same as for Form.

weight | xsd:integer | 0:lighter than normal, 1: Normal, 2,3: heavier than normal
parts | rdf:Collection | The form fields, forms, in the group

#### Choice

The user choses an item from a class.

from | rdfs:Class | The selected thing must be a member of this class, e.g., Person.
property | rdf:Property | When the item is found, the new data links it from the subject with this property, e.g., friend.
canMintNew | xsd:Boolean | If the user doesn't find the thing they want, can they introduce an item of that class by filling in a form about it? [Boolean]

If a new thing is minted, that will be done with a form which is a `ui:creationForm` for the class.

#### Multiple

When the subject can have several of the same thing, like friends or phone numbers, then the Multiple field allows this. The user clicks on the green plus icon, and is prompted for a subform for the related thing. The user can also delete existing ones.

For each new thing, the system generates an arbitrary (timestamp) URI within the file where the data is being stored. The subform is then about that thing; the subject of the subform is not the subject of the original form. It is the field, or the address, and so on.

ordered | Boolean | If true, the user has an ordered array of things, and the data is in an RDF collection. If false, the UI is irrelevant and the data is a series of arcs.
property | rdf:Property | The API details or query endpoint and query details to be used to search the item in the databasse.
reverse | Boolean | If set, the form will write data triple like `X P S` instead of the normal `S P X`.
part | Form | The form to be used for each one.

#### Classifier

category | rdfs:Class | The object will already be in this class. The user will select subclasses of this class.

This form field leverages the ontology heavily. It pulls the subclasses of the given class, and makes a pop-up menu for the user to chose one. If and only if the ontology says that the class is a disjoint union (owl:disjointUnionOf) of the subclasses, then the user interface will only allow the user to pick one. If the user picks a subclass, and the ontology shows that that subclass has its own subclasses, then the user will be prompted to pick one of those, to (if they like) further refine the selection. And so on.

The classifier pops a menu to allow the user to select a set of values to classify the subject.

#### Options

An Options field is the 'case statement' of the form system. It will choose at runtime a subfield depending on a property, often the type, of the subject. Often used after a classifier.

Options property | range | significance
--- | --- | ---
dependingOn | rdf:Property | The predicate in the data used to select the case.
case | Case | A case object, with for x use y. (2 or more cases)

and for each case:

Case property | range | significance
--- | --- | ---
for | [The range of the dependingOn property] | The value this case applies to
use | Field | sub form to be used in case the value matches the "for"

#### Autocomplete

The autocomplete field alllows the user to select one out of a large number of existing choices, by typing enough of its name to be unambiguous.

The field stores two triples,one of the given `property` linking to the object the user has selcted, and the other stoting the name of that object, as seen in the completed feld, using the `labelProperty`.

The field must specify a `dataSource` which gives the paramters and form of the query make over the net.

labelProperty | rdf:Property | The property which will be used to store the name of the selected thing as a separate triple
dataSource | DataSource | The API details or query endpint and query details to be usde to search of the itemn in the databasse.
targetClass | rdfs:Class | Is tyhis is specified, it be used to replace any occurrences of "$(targetClass)" in the query template. this allows different instances of AutocompleteField to share the same DataSource, by specifying different values for `targetClass`.

### Documentation fields

#### Heading

Help the user find parts of a long form, or just for a title of a short form.

contents | String | The text content of the heading
suppressIfUneditable | Boolean | If data is uneditable,ie read-only mode, hide this comment

The `suppressIfUneditable` flag allow you to make a form which is much cleaner and simpler when the user is just reading information, not editing it.

#### Comment

Use comments in the form to help users understand what is going on, what their options are, and what the fields mean.

contents | String | The text content of the comment. (This should be displayed by form systems as `pre-wrap` mode.)
suppressIfUneditable | Boolean | If data is uneditable,ie read-only mode, hide this comment

## Conclusion

The form language and the form implementation in solid-ui can't do everything, but it can handle a pretty wide selection of tasks in common daily life at home and at work. It can be vary efficient as developers can reuse material between forms. Users can even generate their own forms.

Future directions include separate implementations of the form UI code in for various platforms, and using various UI frameworks. There may also be extensions of the system with new field types, more options for setting style from various sources, etc.