Custom Forms

The need to go beyond ontology-driven modeling

The editing capabilities of ontology editors are usually...ontology-driven. That is, data-entry forms are painted on the screen, and options for filling them are provided, by analyzing the axioms defined in the ontology vocabularies loaded in the dataset being managed, including both the W3C basic modeling vocabularies (RDF, RDFS, OWL, SKOS, SKOS-XL) and domain-specific ones. However, a purely ontology-driven approach has some limitations.

One typical limitation is the lack of axioms on annotation properties. The range of some properties is known "de facto", such as the use of language literals for RDFS and SKOS labeling properties, or rdfs:Resource in the case of rdfs:seeAlso, but no axiom is stating this information. We have solved this in previous versions of Semantic Turkey by introducing some hard-wired ranges in the system, taking precedence over the analysis of available axioms.

Yet, in many scenarios, users would benefit from a greater level of customization when valuing properties, as some objects only make sense when built according to well-known templates. For instance, a general-purpose RDF editor, would prompt the user with the possibility to select an existing skosxl:Label when valuing the skosxl:preLabel property, or to create a new one. However, a skosxl:Label instance only makes sense if a skosxl:literalForm is provided for it. Hence, a pattern with the mandatory skosxl:prefLabel --> skosxl:literalForm should be specified somehow. This is not limited to creation, but also to viewing: indeed, such kind of objects only makes sense if, in a view of the resource described by them, the skosxl:literalForm linked to the skosxl:Label is explicitly shown, and not the URI/bnode describing it. Again, we have solved such typical cases with built-in solutions tailored over notable vocabularies (such is the case of SKOS-XL). However, we felt the need for giving users the possibility to tailor the UI of Semantic Turkey to their specific needs.

User-Customizable Forms

Custom Forms are a flexible data-driven form definition mechanism that we devised for VocBench, allowing users to perform a declarative specification of the key elements that concur to the creation of a complex RDF resource. In particular, custom forms rely on the combination of the following four key elements:

Custom Ranges have been implemented in VocBench through a (rather unorthodox :-) ) use of CODA, the UIMA-based framework for Unstructured Information Acquisition, Management and RDF-Triplification. In UIMA, information acquired from unstructured content is processed and stored inside feature structures that can be later retrieved and stored into a target repository according to different technologies and models. CODA extends UIMA by focusing on the triplification of UIMA feature structures. CODA provides a highly-expressive transformation language, PEARL, thought specifically for transforming feature-structures into RDF graphs.

The implementation of Custom Ranges in VocBench exploits all the power of PEARL, to build forms by means of UIMA feature structures. User-defined feature structures are parsed by VB and used to create a form for filling their content. The rest of the PEARL rule describes how the user prompted content is converted into RDF nodes and then composed into an RDF graph

The construction of new resources in VB through Custom Forms is managed through two solutions:

Data Architecture

In this section we describe the components realizing the data architecture of Custom Ranges in ST.

The PEARL rule defining the templates for these structured objects is embedded into an XML file called Custom Range Entry (see figure below). The binding between an entry and each specific property is defined in another XML file, called Custom Range. In the next section, we will see how to create these files in Semantic Turkey.

Custom Range concept

Usage: the Custom Form Management Page

To configure Custom Forms, a management page is accessible through the VocBench Tools menu.

Custom Forms Page

The panel is composed of three main sections:

The Custom Form section lists available custom forms. The greyed ones are factory-provided custom forms that cannot be altered, yet their content can be inspected (in order to use them as examples), or they can be adopted as-is.

The following action buttons are available for interacting with the listed forms and for creating new ones:

Created custom forms are project-local. If users want to reuse a custom form across different projects, they can export them from a project and reimport them into a new project.

A click on the create button produces the following form for describing a Custom Form:

Custom Forms Page

Here follows a description of the fields in the form:

Editing Custom Forms

As anticipated earlier, Custom Forms are defined by specifying a PEARL document, declaring a set of RDF nodes that are created from a set feature structures. In fact, the node section of the CODA rule determines the fields that will compose the form. The graph section will then specify how these nodes are arranged into an RDF graph.

Custom Forms Editing

Let's explain how it works with an example, by considering the nodes and graph sections of the Form in the previous picture:

		...
nodes = {
    resource uri(coda:randIdGen("note", {})) .
    noteLit literal userPrompt/note .
    source literal userPrompt/source .
    related uri userPrompt/related .
    modified literal^^xsd:datetime userPrompt/modified .
    created literal(coda:datetime["yyyy-MM-dd"]) .
}
graph = {
    $resource rdf:value $noteLit .
    OPTIONAL { $resource dc:related $related . }
    OPTIONAL { $resource dc:source $source . }
    OPTIONAL { $resource dc:modified $modified . }
    $resource dc:created $created.
}
...

The nodes section is composed of various lines, each with three elements:

In the graph section, the placeholders for the created nodes are then used to assemble the description of the resource created through the form. The CODA placeholders that appears in OPTIONAL block in this section will be optional in the input form too. So, in this case, there will be five fields: note, source, related, modified and created and only the first will be mandatory.

Note that the resource and the created nodes are not created by transforming some user input, as the userPrompt element is missing from their rows. This means that these elements will be generated from scratch, as some converters are actually generators able to create new RDF nodes on the sole basis of some configuration (e.g. the coda:dateTime converter generates the representation for the current date and time when not dateTime expression is passed as the third argument of the node declaration).

The Form Editor supports syntax highlighting, though it does not currently provide syntax completion. A syntax helper for the converters has however been provided, in the form of a converter picker, that lists all the available converters already loaded into the system, their possible invocation signatures (converters supports invocation overloading) and copying their syntaxes to the editing textarea, as shown in figure below:

Custom Forms Page

For each converter, it is possible to select the proper signature by clicking on the pencil symbol besides the signature textfield, showing a chooser window like in figure below

Custom Forms Page

Overlaying Default Forms

Skos concepts, schemes, collections, etc.. all these kind of resources share default forms that expose advanced editing characteristics that cannot be (currently) represented through custom forms and that, in any case, should not be overridden by them. For instance, the concept creation form shows a list of schemes that will be associated to the new concept: this list. though editable, is defaulted to all schemes inherited from its parent concept (the one on which the "create child concept" action has been performed). Clearly this particular behavior *should* always be part of the concept creation form. In order to keep the peculiar characteristic of each resource's form, and yet to allow for a certain degree of customization, custom form adopt an overlaying mechanism in which the basic structure of known-resources' forms is kept, and the additional specification of a custom constructor is added to it.

In such overlaid custom forms, some of the information that is produced by the default part of the form could be necessary for computing some aspects of the custom part. E.g. the local name of a concept could be reused in the node section of the custom form, in order to create another resource connected to the concept whose URI is similar to the one of the concept. In order to support this possibility, all default forms fields are also mapped as

In the following figure, an editor opened on a new form cloned from the basic factory-based template for extending default forms

Custom Forms Page

CustomForm wizard

Writing a CustomForm may not be an easy task, especially for those users not familiar with PEARL, features, converters and all the related stuff. The CustomWizard comes in help providing an editor that aims to facilitate (as much as possible) the writing of the PEARL code of a CustomForm.

CustomForm wizard can be opened via the Wizard button placed at the right of the Ref textarea. The button prompts to chose between Custom Constructor and Custom Range (the need for this differentiation will be clearer later).

The wizard appears in a dialog as follows.

The wizard is quite full of information which it's understandable being the PEARL of a CustomForm something complex. But let's decompose the wizard editor in sub-sections. Broadly we can identify three main sections: the top one is dedicated to the definition of the fields that will be prompted in the form, the middle one manages the nodes of the PEARL, and the bottom one defines the relations between such nodes. Finally, on the right side of the wizard, a textarea shows a preview of the PEARL code that is automatically updated when a change is detected on any of the three sections above.

The wizard provides through the two buttons on the top-right corner, the possibility to export the status on the filesystem in order to reload it later and to resume the creation of the form.

Now, let's focus on one section at the time.

Fields wizard

In the top part of the wizard user can create the fields that will be shown in the resulting form. It is possible to choose between two types of field: Uri and Literal. This choice will determine the type of value user will be able to insert into the field.

When a field is selected, in the Field details panel it is possible to customize some aspects of the field, like the possibility to accept multiple values for the same field (optionally indicating the minimum and maximum amount) and the possibility to put constraints on it. The available constraints are:

A field can be also marked as optional through the dedicated checkbox in the Form fields panel, this means that the field in the form can be left empty.

Nodes wizard

When a field is defined, automatically a node is added in the Nodes panel, this happens because at each field corresponds a node (in some case even multiple nodes, as in language tagged literals, but let's not get lost in the details). The same is not true in the inverse direction, namely the definition of a node does not automatically implies the presence of a field in the form, this means that in the Nodes panel user can define an arbitrary amount of nodes that will not be prompted in the form. An example could be the definition of a node for automatically setting the creation date of the resource: user may not want to manually set the current date, so it would be useful that the form sets it behind scenes.

The previous image shows the Nodes panel. By first, let's notice the presence of the node resource. This is a node automatically set only in the wizard for Custom Range, while it is not present in case of Custom Constructor. In such case, this node is mandatory because a Custom Range is used to define a graph (or reified object) which is going to be "appended" as value to a subject-predicate pair (e.g. a reified note set as value to :aSubject-skos:note). Custom Constructor, instead, are used to add further predicate-object pairs to a resource (subject) created contextually during the creation of a resource (e.g. creation of a concept, class, individual, ...). So, the node resource represents exactly the entry point of the graph, namely the node that will be the object of the aforementioned subject-predicate pair.

A new node can be added through the + button on the panel header. The node is automatically named new_node (or, in case of duplicated name, new_node_i where i is a numerical index) and can be renamed by user. Only the nodes defined by user can be deleted using the "trashbin" button; the resource node cannot be deleted and nodes created from fields can be deleted only by removing the related field.

The second field represents the converter to use for producing the node. The pencil button opens a dialog that allows the selection of a converter (and its signature and parameters) among those available.

Finally, under the third column Feature, a combobox optionally (only in case the converter requires an input) allows the selection of a feature, namely the input value of the converter. These features are grouped in three groups:

Graph wizard

The third section of the wizard aims to help user in defining the relations among the nodes. This results in the definition of the graph section of the PEARL. This sections is splitted in two panels: the left one allows the definition of simple subject-predicate-object relations, the right one manages more complex graph pattern. Let's start from the left panel.

Clicking on the + button in the Nodes relations panel, a new subject-predicate-object row is added. The subject can be chosen among the nodes defined in the Nodes panel (in case of Custom Range wizard, the subject of the first row is locked on the entryPoint node). The predicate must contain the IRI of a property, it can be written manually or also picked by browsing the property tree clicking on the pencil button. The object can be both a Node or a Value. The first selector allows you to make this distinction and according the choice made the right part of the Object changes dynamically. In case of Node, a combobox allows the selection of a node among those defined, while in case of Value, user can provide a literal or IRI.

The right panel Advanced graph pattern aims to overcome the limitation of the Nodes relations one through the definition of complex graph patterns. The + button opens the following editor.

An advanced graph pattern needs to be bound to an input field which can be selected at the top of the dialog. Once selected, the related nodes are automatically listed into the Nodes panel where you can add further nodes to use in the graph pattern. The Graph pattern panel, as the name suggests, provides a textarea for writing the graph pattern. This pattern will be written as it is in the resultant PEARL code. In the latter panel there is also a sub-panel that lists the prefix-namespace mappings defined in the VB project and eventually allows to define further mappings useful in the graph pattern.
By clicking Ok, the pattern will undergo to a validation step and then a preview will be visible in the dedicated panel of the wizard.

Note: this is quite similar to the Advanced Graph application available in Sheet2RDF.

Once the user has completed the configuration of the wizard, the same can be closed with the "Ok" button. In case of everything is ok, the dialog is closed and the produced PEARL is placed into the Ref textarea of the CustomForm editor where it can be edited further.

Custom Form in action: customizing the reifiedNote CustomForm

In this section we learn how to reuse an existing custom form and to modify it for our own purposes. We will customize the "reified note" custom form.

A reified note is a skos:note modeled after the second pattern described in advanced documentation of the SKOS Primer, that is an RDF resource described in turn by other properties, the main one being rdf:value and having as object the literal content of the note. The basic reified note available with the standard installation of the system contains only the basic reification pattern:
<resource being described> --> skos:note --> <resource representing the note> --> rdf:value --> <the literal value of the note>
What we will do in this section is to create our own version of the note and to add to it a few more metadata properties.

In order to create and use a new Custom Form, it is necessary to:

If a Custom Form and Form Collection are already available, the only step to be performed is the third and last one, which is the one we are going to show in the next section, before diving into the more elaborated aspects of customization.

Mapping a Custom Form

In order to associate an existing custom form, available in an existing Custom Collection, we need to associate this last element to a resource. The Form Collections can be managed from the top-right panel of the Custom Forms Management page.

A Form Collection consists of the following:

As shown in the following image, the factory-provided Form Collection for the reified notes is composed by only one Custom Form (it.uniroma2.art.semanticturkey.customform.form.reifiednote) and according to the suggestions, it is advisable to use it with the skos note properties (skos:note and its sub-properties).

Custom Collection editor

The Form Collection needs thus to be mapped to a resource: property or class. This operation can be performed through the bottom panel, which allows for creation/deletion of such mappings.

When creating a new mapping, if the Form Collection that is going to be mapped has suggested classes or properties declared, the UI offers the possibility to exploit these suggestions.

A mapping to a class generates a "Custom Constructor". When an instance of that class is being created, the form is layered on top of the original form for creating instances of that class.

A mapping to a property generated a "Custom Range", that is, whenever that property is going to be valued, the Custom Form will be presented as an alternative to the usual range. In the case of Custom Ranges an additional option allows to "replace" the ordinary range (i.e. the range expressed by the owl:range property or derived by inference), thus directly prompting the user with the Custom Form.

Form Mapping editor

In the image below, the note Collection has been associated to the skos:note property and the "Replace" option has not been ticked.

Form Mapping panel

The Custom Form (in this specific case a Custom Range) is now ready to be used. After valuing the skos:note property (on any resource), a dialog for selecting the range type is shown. All the Custom Ranges contained in the Form Collection are listed among the available ranges (like we said, this step would have been skipped if the replace flag had been checked).

In this case the only CustomRange defined in the FormCollection is Reified note.

CustomRange range selection

Once the Reified note element has been selected, the Custom Form is prompted to the user.

CustomRange form

After filling the Custom Form, the prompted data has been added to the dataset and it is visible in the Resource View. As you can see in the following image, the reified resource, unlike the plain one ("plain note"), is rendered as an individual through its qname.

CustomForm in ResourceView

By double clicking on such value, the ResourceView of the reified note can be displayed containing the rdf:value entered in the previous form.

The rendering of reified resources, like the note in this example, can be improved by exploiting the Custom View mechanism.

Customizing the Custom Form fields

As stated before, the Custom Forms mechanism was designed to allow the user to tailor the UI of Semantic Turkey to their specific needs. With the following example, it will be shown how to extend the factory-provided reifiednote Custom Form in order to add a further field.
By first, since the new form will be based on the existing one for reified notes, it is advisable not to start from scratch, rather to clone the original one. This can be done by selecting the original form and clicking on the "clone" button on the Custom Forms panel. As a start, the only information that needs to be prompted is the ID for the new Form.

Note that all forms have an ID characterized by a namespace and a local name. By default, a namespace is provided (the one of Semantic Turkey, the backed system of VocBench), to allow users simply prompting a local name. However, by clicking on the lock button, it is possible to change the full name of the form.

Clone CustomForm

After creating the form, it is possible to edit its characteristics through the PEARL editor: the name, the description and the PEARL reference that will determine the prompted form.

The addenda to the original PEARL are highlighted in the previous image:

Now, as already shown for the standard reified note, it is necessary to add this new Custom Form to a Form Collection. Since it is not possible to edit the factory-provided it.uniroma2.art.semanticturkey.customform.collection.note collection, it is necessary to create a new one or simply to clone the latter and add the new created CF.

After mapping this new collection to skos:note, the new custom form will be added to the range of possible values

...and then, the new form can be filled.

The resulting note will be the following, thus showing also the source element

PEARL annotations

From version 8.0.0, Custom Forms have been enhanced with the introduction of PEARL annotations. By annotating a node declaration it could be possible to add semantic to the same node and this will be reflected on the produced Form. For instance it could be possible to state that a node can take only values x, y or z, or that it can only be an instance of a certain class, or even that it must be a resource taken from a specific external project.

The available annotations are:

For each of them we will see how they can be used and how they affect the Form. Combination of these annotations are allowed. For example Foreign can be combined with Range in order to constrain the selection from an external project of the instance of a given class, or again Collection with Role in order to allows the selection of multiple resources of a type.

In the examples that will follow the annotations will be tested by customizing the factory-provided Custom Form for reified note.

Collection

This annotation allows for prompting more values for the same element. It takes two optional numeric arguments: min and max (if not provided their value is assumed to be 0). Value 0 for min means that it is not necessary to provide at least one value, namely the form field will be optional. Value 0 for max means there’s no limit restriction on the number of values to create.

Now, let's extend the reifiednote Custom Form PEARL as follow (changes in yellow): 

      
    rule it.uniroma2.art.semanticturkey.customform.form.reifiedNoteExt id:reifiednote {
      nodes = {
        resource uri(coda:randIdGen("note", {})) .
        noteLang literal userPrompt/lang .
        noteLit literal(coda:langString($noteLang)) userPrompt/note .
        @Collection(min = 2, max = 4)
        listNode uri userPrompt/list .
      }
      graph = {
        $resource rdf:value $noteLit .
        OPTIONAL { $resource rdfs:comment $listNode . }
      }
    }

As it is highlighted, it has been added a new listNode node annotated with @Collection. This will be reflected in a new list field in the form. The annotation here determines that the field will allow multiple values, precisely from 2 to 4 values. Then these values will be linked to the reified note through the rdfs:comment property (for illustration purpose only). Side note: rdfs prefix is not declared in the original reified note Custom Form, it has to be manually added.

The resulting Form is the following

The list field has initially two textfields which allow the selection of IRI resources. The "trashbin" buttons are disabled since the minimum declared by the annotation is 2. It is possible to add up to 4 further elements to the list (through the plus button), then the add button will be disabled.

DataOneOf

This annotation declares a set of possible literal values that can be assigned to the related node. The Custom Form can be changed as follow 

      
    rule it.uniroma2.art.semanticturkey.customform.form.reifiedNoteExt id:reifiednote {
      nodes = {
        resource uri(coda:randIdGen("note", {})) .
        noteLang literal userPrompt/lang .
        noteLit literal(coda:langString($noteLang)) userPrompt/note .
        @DataOneOf({ "example"@en, "esempio"@it, "ejemplo"@es })
        dataOneOfNode literal userPrompt/dataOneOf .
      }
      graph = {
        $resource rdf:value $noteLit .
        OPTIONAL { $resource rdfs:comment $dataOneOfNode . }
      }
    }

Here it has been added a new dataOneOfNode node annotated with @DataOneOf. This determines that the new dataOneOfNode field will accept only the values specified as argument. As in the previous case, the value will be linked to the reified note through the rdfs:comment property.

The resulting Form is the following

Foreign

Foreign annotation constrains the selection of a resource value from an external project (hosted on VB). The argument of this annotation is the ID of a project. 

      
    rule it.uniroma2.art.semanticturkey.customform.form.reifiedNoteExt id:reifiednote {
      nodes = {
        resource uri(coda:randIdGen("note", {})) .
        noteLang literal userPrompt/lang .
        noteLit literal(coda:langString($noteLang)) userPrompt/note .
        @Foreign("TestProject")
        foreignNode uri userPrompt/foreign .
      }
      graph = {
        $resource rdf:value $noteLit .
        OPTIONAL { $resource rdfs:comment $foreignNode . }
      }
    }

A foreignNode node has been annotated with @Foreign with argument TestProject. This will add in the form a new dataOneOfNode field allowing the selection of a resource from the target project TestProject. Obviously in order to works, the ID of the project must identify an existing project, moreover the target project must grant access to the source project (see documentation about ACL).

As shown in the following image, next to the dataOneOfNode field a button with an arrows (in place of the usual "pencil") suggests that the value will be picked from an external source.

Once clicked, the selection of the project is prompted, then user needs to choose the type of picked resource and finally he can browse the desired tree/list.

ObjectOneOf

This annotation is very similar to DataOneOf previously seen. In fact it declares a set of possible IRI values that can be assigned to the related node. Custom Form pearl could be changed as follow. 

      
    rule it.uniroma2.art.semanticturkey.customform.form.reifiedNoteExt id:reifiednote {
      nodes = {
        resource uri(coda:randIdGen("note", {})) .
        noteLang literal userPrompt/lang .
        noteLit literal(coda:langString($noteLang)) userPrompt/note .
        @ObjectOneOf({ skos:ConceptScheme, <http://www.w3.org/2004/02/skos/core#Concept> })
        objOneOfNode uri userPrompt/objOneOf .
      }
      graph = {
        $resource rdf:value $noteLit .
        OPTIONAL { $resource rdfs:comment $objOneOfNode . }
      }
    }

The objOneOfNode node, annotated with @ObjectOneOf will add in the form a field objOneOf that through a combobox allows the selection of the only values provided as annotation argument. As shown in the previous PEARL code, arguments of the annotation can be both IRI and qname (in case of qname the prefix must be declared in the PEARL).

Range

This annotation describes the class that is meant to be used for feeding potential values to the annotated node. Its argument must be an IRI (or qname) that identifies a class. 

      
    rule it.uniroma2.art.semanticturkey.customform.form.reifiedNoteExt id:reifiednote {
      nodes = {
        resource uri(coda:randIdGen("note", {})) .
        noteLang literal userPrompt/lang .
        noteLit literal(coda:langString($noteLang)) userPrompt/note .
        @Range( skos:ConceptScheme )
        rangeNode uri userPrompt/range .
      }
      graph = {
        $resource rdf:value $noteLit .
        OPTIONAL { $resource rdfs:comment $rangeNode . }
      }
    }

The above is an example of how the annotation can be used in order to constrain the selection of values to the only instances of skos:ConceptScheme class.

In this way the picker of the range field opens a browsing modal allowing the selection of any instances of skos:ConceptScheme class, both from current and external project.

RangeList

This annotation is the extension of the previous with the only difference that can specify multiple classes as argument (e.g. @RangeList( { skos:ConceptScheme, skos:Concept } )) and the browsing modal allows the selection of their instances.

Role

This annotation constrain the role(s) that a certain node may assume. The only argument represents a list of string among those available in Semantic Turkey.

Assuming you want to restrict the selection to concepts, schemes or collections, the PEARL rule can be modified as follow 

      
    rule it.uniroma2.art.semanticturkey.customform.form.reifiedNoteExt id:reifiednote {
      nodes = {
        resource uri(coda:randIdGen("note", {})) .
        noteLang literal userPrompt/lang .
        noteLit literal(coda:langString($noteLang)) userPrompt/note .
        @Role({'concept', 'conceptScheme', 'skosCollection'})
        roleNode uri userPrompt/role .
      }
      graph = {
        $resource rdf:value $noteLit .
        OPTIONAL { $resource rdfs:comment $roleNode . }
      }
    }

By doing that, the usual resource picker placed next to the form field (that in this case will be labeled with role) will prompt a modal for selecting the type of resource among those specified as annotation argument.