Managing Form Fields

Here we will explore how to manage fields available on forms of a given collection. We will take again the ex:Person collection as example.

First, you would need to navigate to the form of the desired collection, and go on the node shape you want to edit. Then you would see on that form the "Properties" field. From there, you can either edit, delete or create a new sh:PropertyShape, which will configure a new field on the ex:Person form.

fig 1: Go to Admin Workspace

fig 2: Go to the Collection of Collections

fig 3: Edit the desired Collection

fig 4: Open the form of the desired Node Shape

fig 5: Scroll to the "Properties" field, and create, edit or delete a PropertyShape from there

sh:PropertyShape fields

There are quite a few fields available on the form of a sh:PropertyShape. For anything that falls within the sh: namespace, more information can be found on the related spec page.

Label	Path	Comment
Name	sh:name	Label of the shape, used in forms as the label of the related field.
Description	sh:description	Description of the shape, used in forms as an information toogletip.
Order	sh:order	On the rendered form, fields are sorted by their sh:order value, from smallest to biggest. Undefined values are put at the bottom of the list
Property Group	sh:group	Fields can be grouped informs, like you might see with the "Presentation" and "Model Information" groups on the sh:PropertyShape form
Editor	hanami:editor	This is meant to configure the widget used as editor in the rendered form. More on this below
Path	sh:path	Path that this field is linked to. We currently support predicate paths and inverse paths
Or	sh:or	Used to combine multiple possible shapes into one. A typical use case for this would be to define that a field can point to either an xsd:string or an rdf:langString
Class	sh:class	Class of entities this field point to. Only Make sense when Node kind is sh:IRI or sh:BlankNode (or a combination of them)
Languages	sh:languageIn	List of language code that can be used. Only useful when making use of rdf:langString on the Datatype field
Datatype	sh:datatype	The datatype expected for this field. Useful only when the Node kind is sh:Literal (or a combination that makes use of it). A typical value for this field would be xsd:string, rdf:langString or xsd:date.
Node kind	sh:nodeKind	The type of object this field is pointing to. If this field is pointing to other nodes, then this should be either sh:IRI or sh:BlankNode, depending on how you manage your nodes.
One value per language	sh:uniqueLang	In case of the Datatype is rdf:langString, limit to have onl one value per language. For other cases, this does not have any effect.
Deactivated	sh:deactivated	If true, completely disables the shape, and it would then be ignore for both validation and form generation.
Selection	hanami:selection	If set to hanami:Item, the related widget will try and autocomplete on any item in the application. This is rarely useful and you would ideally limit what can be selected through sh:class or order constraints.
Node	sh:node	This is meant to specify that the property point to a node that follows the given sh:NodeShape. This i snot taken into account for form generation, and ideally should be used for the validation purpose.
Timezone encoding	hanami:timeZoneEncoding	Time zone used to encode xsd:dateTime in iso date time string. Possible value are coming from the standard IANA list and should look like "Europe/Brussels". If not given, will default to Zulu time (UTC) or to the time zone configured at the application level.
Purpose	hanami:purpose	Purposes of the shape, depending on given value(s). With hanami:ValidationPurpose, the shape will be used to validate data. With hanami:EditionPurpose, the shape will be used to generate form fields and options to the related "add" button. If no value is given, it will default to having both hanami:ValidationPurpose and hanami:EditionPurpose
List of	hanami:listOf	Defines that this property points to an rdf:List where each element in the list is validated against the given sh:PropertyShape.
Possible values	sh:in	List of possible values the field can have. Currently limited to string or IRIs.
Readonly	hanami:readonly	If true, the field is not editable, except by technical admin users.
Min Cardinality	sh:minCount	Minimum number of values the field should have. It is usually not set, or set to 1.
Max Cardinality	sh:maxCount	Maximum number of values the field should have. It is usually not set, or set to 1.
Min Length	sh:minLength	Minimal length of values for string-based fields. For example you might want to have ate least 20 characters for a title, or 200 for a description
Max Length	sh:maxLength	Maximal length of values for string-based fields.
Pattern	sh:pattern	Regex pattern to be followed by string based values given to this field

Editors

Making use of the hanami:editor field, one could configure the widget used when the form field is being rendered. For fields that point to literal values, it is usually not necessary to set the editor, as it is automatically computed:

• If hanami:editor is manually set, that editor will be used.
• If sh:datatype is xsd:boolean, a hanami:CheckboxEditor will be rendered
• If sh:datatype is xsd:date, a hanami:DateEditor will be rendered
• If sh:datatype is xsd:dateTime, a hanami:DateTimeEditor will be rendered
• If sh:datatype is rdf:langString, a hanami:LangStringEditor will be rendered
• If sh:datatype is one of xsd:double, xsd:int, xsd:integer, a hanami:InputEditor will be rendered
• If sh:in is given, a hanami:SelectEditor will be rendered, giving the values in sh:in as options
• If sh:class is given, a hanami:NodeEditor will be rendered, with a default linking strategy set to hanami:CreateLinkingStrategy.
• If sh:nodeKind is sh:IRI, a hanami:IRIEditor will be rendered
• Otherwise, a hanami:TextAreaEditor will be rendered

hanami:NodeEditor and linking strategies

Node editors are the editors that are most commonly set manually, as their hanami:linkingStrategy value drives what the users are able to do with this widget:

Uri	Label	Comment
hanami:CreateLinkingStrategy	Allow new node creation	Default value. When the user clicks on the related "add" button, a new node within the currently edited graph will be created, and the user will be navigated to the form of that new node
hanami:CreateManualLinkingStrategy	Allow new node creation and manually setting the uri	Like hanami:CreateLinkingStrategy, but the user is prompted to manually input the uri of the created node.
hanami:InternalReferenceLinkingStrategy	Allow reference to an existing node of the item	With this, the user will be prompted to select a node that already exists within the graph. A typical use case for this would be while editing a skos:ConceptScheme graph with its skos:Concept being part of the same graph, and filing the skos:related field on those concepts.
hanami:ExternalReferenceLinkingStrategy	Allow reference to a node that belongs to another item	Here, the user will be able to make reference to a node that exists outside of the current graph.
hanami:ExternalReferenceWithFormLinkingStrategy	Allow reference to a node that belongs to another item, with possibility to have a dedicated form	This works as hanami:ExternalReferenceLinkingStrategy, but it will also create a form fro that node with added properties based on other shapes in the collection. This is to be used when you want to reference something external, and add triples to it.

It is to be noted that a node editor can have multiple values for their linking strategy, and this is fine. In such case, the user filling the form will be prompted to use the option that suites their need. That being said, we advise to keep to a singular value to keep the flow easier for non-technical users.

Recipes

Adding a field that points to external nodes

Considering that we start with the ex:person collection, here is how one would add a birthplace field on the ex:Person class:

1. Go to the form the the collection
2. Within the form of the collection, navigate to the form of the node shape that targets the ex:Person class
3. Go down to the "Properties" field, click the "add" button and choose the "Blank Node" option (the other is fine too if you wish to create a proper node)
4. You will be navigated to the form of the newly created sh:PropertyShape. This then needs to be filled, with at least:
   1. Giving it a "Name", for example "Birthplace"
   2. Giving it a "Path" of the predicate form, with the value ex:birthplace.
   3. Giving it a "Class", typically ex:Country or skos:Concept for example. To be noted that known prefixes are automatically expanded in iri fields
   4. Optional: Node kind set to sh:IRI
   5. Give a proper cardinality if applicable. So most likely a "Max Cardinality" of 1, and maybe the same to "Min Cardinality".
   6. Add an "Editor" to the shape, with the type "hanami:NodeEditor", and set its Linking Strategy to "Allow reference to a node that belongs to another item"
5. Then click "save"

Now that the collection's changes have been saved, you can go and create or edit a Person and you should see the new "Birthplace" field.

Equivalent in .ttl

If we directly edited the collection .ttl file and upload it for on override, those would be the added triples to that file:

<Person> sh:property <Person/birthplace> .

<Person/birthplace>
    a           sh:PropertyShape ;
    sh:path     ex:birthplace ;
    sh:nodeKind sh:IRI ;
    sh:class    skos:Concept ;
    sh:minCount 1 ;
    sh:maxCount 1 ;
    sh:name     "Birthplace"@en ;
    hanami:editor [
        a                      hanami:NodeEditor ;
        hanami:linkingStrategy hanami:ExternalReferenceLinkingStrategy  ;
    ]
.

Adding a field that points to a literal

Considering that we start with the ex:person collection, here is how one would add a birthday field on the ex:Person class:

1. Go to the form the the collection
2. Within the form of the collection, navigate to the form of the node shape that targets the ex:Person class
3. Go down to the "Properties" field, click the "add" button and choose the "Blank Node" option (the other is fine too if you wish to create a proper node)
4. You will be navigated to the form of the newly created sh:PropertyShape. This then needs to be filled, with at least:
   1. Giving it a "Name", for example "Birthdate"
   2. Giving it a "Path" of the predicate form, with the value ex:birthdate.
   3. Giving it a "Datatype"of xsd:date. To be noted that known prefixes are automatically expanded in iri fields.
   4. Optional: Node kind set to sh:Literal
   5. Give a proper cardinality so most likely a "Max Cardinality" of 1, and the same to "Min Cardinality".
5. Then click "save"

Now that the collection's changes have been saved, you can go and create or edit a Person and you should see the new "Birthdate" field, automatically rendered as a hanami:DateEditor.

Equivalent in .ttl

If we directly edited the collection .ttl file and upload it for on override, those would be the added triples to that file:

<Person> sh:property <Person/birthdate> .

<Person/birthdate>
    a           sh:PropertyShape ;
    sh:path     ex:birthdate ;
    sh:nodeKind sh:Literal ;
    sh:datatype xsd:date ;
    sh:minCount 1 ;
    sh:maxCount 1 ;
    sh:name     "Birthdate"@en ;
.