This document describes how to implement custom forms for use in Vitro/VIVO using what we call N3 editing or the N3 editing system.

Overview

The Vitro/VIVO system comes with basic RDF editing capabilities to add object and datatype statements to individuals.  Frequently, people deploying Vitro/VIVO desire a web form which allows editing of multiple properties and individuals on the same form.  A contact information form would be an example of a feature that would be implemented with a custom form in Vitro/VIVO.
 

Custom forms in Vitro/VIVO are a java class that implements EditConfigurationGenerator and a FreeMarker template for the presentation.  The EditConfigurationGenerator controls how the values from the form will be used in the editing of the RDF, server side validation, which template to use, and other aspects of the edit.
 

Custom forms can be associated with a property so that they are used from an individual’s profile page or by a direct URL. 
 

The main concept of custom forms is that the values submitted by the HTTP request will be substituted into placeholders in RDF N3 strings.  These strings are then parsed to RDF and that RDF is added to the system.  For the modification of an existing value, a second set of strings is created and parsed which become the RDF statements to remove for the edit.  This substitution is why the editing system is frequently called “N3 Editing”.  In practice, the N3 strings use only the turtle subset of the N3 syntax.

Description of Steps of an Edit

1. Getting the link to the edit  

When a user is logged in, individual profile pages have edit links next to the listed properties. These links will take the user to a page with an edit form. The links on the individual profile page are routed to the EditRequestDispatchController which will determine which EditConfigurationGenerator to use.  The controller will create and run that EditConfigurationGenerator to generate an EditConfiguration. It will then send the values off to the FreeMarker template specified in the EditConfiguration.
 

The edit forms are created by the configuration created by a EditConfigurationGenerator. The system can be configured to associate a EditConfigurationGenerator with a property so that the edit links will use a custom EditConfigurationGenerator.  If no custom form is specified then the default object or data property EditConfigurationGenerator will be used.
 
 2. Generating the EditConfiguration  

A custom form is setup by the EditConfigurationGenerator which makes an EditConfiguration. The EditRequestDispatchController will run getEditConfiguration() on the EditConfigurationGenerator to create the EditConfiguration. The EditConfiguration will specify the FreeMarker template for the form, and the server side instructions for validating and processing the submitted result of the HTML form.  When creating a custom form a central task is the coding of the EditConfigurationGenerator to produce an EditConfiguration that encodes logic of how you desire the edit to happen.  The EditConfigurationGenerator is just a java class that creates an EditConfiguration. 
 

When generating the EditConfiguration an edit key will be created and the completed EditConfiguration will be associated with that key in the server side user session. This edit key is used to handle parallel editing and back button complexity. The EditConfiguration object for an edit is in a one to one relation with the HTML form for an edit. If the user goes to edit a street address and then goes to edit that street address again, the first edit will have an EditConfiguration and an HTML form and the second will have a different EditConfiguration and HTML form.  An HTML form created for a edit will have an “edit key“ to associate that specific instance of the form with an object stored in the user’s session. 
 

The EditConfiguration can specify SPARQL queries for existing values for fields of the form.  These are executed as part of the generation of the EditConfiguration.
 

3. HTML creation by FreeMarker

Once the EditRequestDispatchController has the EditConfiguration and put it in the session, it will set up some standard values for the template and pass them and the EditConfiguration to the FreeMarker template specified in EditConfiguration.getTemplate().
 

4. Response From Client

The form will be submitted by the client’s browser to ProcessRdfFormController. This will get the EditConfiguration based on the edit key from the submitted values. It will run validation and then