...

Introduction

This instructions has two sections.

...

"How to Create a New Custom Form" is a tutorial that steps through creating some new form fields and using XPATH/XSLT to control how they interact with XML.  This is geared towards someone who will add new fields to an existing form or who will troubleshoot issues related to how forms are interacting with XML.  This wiki does not cover XPATH/XSLT, and to use this information, you need to separately learn about XPATH/XSLT because the XML forms are using XPATH/XSLT to interact with XML records on your site.

How to Edit an Existing Form

The following section will show you where to access forms in your Islandora installation, and how to Copy and Edit a form, and associate it with a content model. This section gives useful information for people who do not have knowledge of XPath/XSLT, and covers only minimal configuration options - how to change names of forms, how to delete fields, and how to determine what content models a form appears as an option for.  The goal is that anyone can follow along with this first section, regardless of coding knowledge.

Where to Find Forms

Islandora's Built In Forms

Some forms are already built into your Islandora site.

...

Here you will see all of the forms currently installed on your site. From this point you can take existing forms and copy, edit, view, export, delete, or associate those existing forms.

Installing Forms from GitHub

Along the top of the screen at Islandora > Form Builder (admin/islandora/xmlform), you will also see an option to "Create Form" or "Import Form".

...

The main reason for examining forms used by the wider community is to find examples of how specific fields are handled.  For example, if something like ORCID is not handled in a default form, you may be able to get an example implementation from another institution using Islandora.

Copying from an Existing Form

When creating a new form, it is best to start by copying from an existing form, especially one already associated with the content model you plan to use the new form with.  In general, it is easier to shorten an existing form by deleting form fields and elements, than it is to add new form fields and elements.  Even without knowing XPath/XSLT, you can shorten a form and set up a workflow on your site which involves only seeing the fields you need to fill in.  This can save significant time for people uploading content and clicking through the form on each upload.

In the list of available forms, find the form you want to Copy and click “Copy.” On the next screen you will be prompted to give your new form a name: 

...

You will be redirected to the Form editing interface, and receive a message at the top that your form has been successfully created: 

About the Form Builder Interface 

1. Under “Form Properties” you can view the properties of your form.
2. Under “Elements” you can view the fields you have created for your form, as well as make changes to those fields. Clicking on an element name will allow you to view the way that element will be created, read, updated, and deleted when you interact with the form, and the resulting metadata that the form will write. 
3. Click “Save” to save changes, and “Save and Preview” to save the changes and render the form in the preview screen.

...

Click “Add Association.” Now, whenever you create an object in a collection that is associated with the content model you have used here, you will see your new form as an option to select in the drop down menu.

How to Create a New Custom Form

This section will discuss how to create a new form using the Islandora Form Builder.

...

A useful tutorial on how to create a new form is here:  Metadata and XML Forms, Donal Moses (UPEI), presented at Islandora Camp NY, November 20, 2013, available at http://islandora.ca/sites/default/files/Metadata%20XMLForms%20Islandora%20Camp%20NY%202013.pdf .  This tutorial steps through the process of building a simple Dublin Core form, and includes screenshots of each step.

Introduction

The XML Form Builder allows you to create and manipulate XML form templates and associate them with content models. This allows you to create custom forms to address the needs of your particular collection, or to pre-populate repeating fields. For example, if a collection of PDFs was all written by the same author, you may wish to create a custom form for this collection that has the author’s name pre-populated, so that users ingesting into this collection will not need to re-enter this information. Using custom forms you can also specify which metadata elements you wish to use to describe your object, and create validation rules for particular fields, among other features.

• If you are a developer, or somebody looking to install the XML Form Builder, you will want to review the section on the XML Form Builder (Copy) module, which discusses the module's installation and configuration.
• If you are a user, then the following documentation assumes that you have some understanding of metadata schemas and XML, as well as Islandora specific concepts such as Content Models, and Collection Objects. The greater grounding you have in XPath, XML Form Templates, and XML Schemas (.xsds), the greater use you will be able to make of the form builder.
• Solution Packs are designed to come pre-packaged with suitable forms written in MODS. These forms can be copied, and edited or modified to suit your needs.
• Forms can be created based on any schema.

Before You Begin

Review and install the XML Form Builder (Copy) module and its dependencies.

Metadata Schemas

Metadata schemas specify the names and properties of elements that can be used in an XML file that is based on that schema.

When developing an XML form in the XML Form Builder you’ll need to reference the schema of the metadata format you are working with. Throughout this document we’ll be using the OAI DC metadata schema as an example. The OAI DC XML format is the serialization of Simple Dublin Core metadata descriptions and we’ll be using Dublin Core elements in this example. You can view/retrieve the schema from http://www.openarchives.org/OAI/2.0/oai_dc.xsd

Sample XML Record

It is helpful to have an example record on hand while developing the form. Ensure that it matches the version of the XML schema you are working with.

...

<oai_dc:dc xmlns:oai_dc="http://www.openarchives.org/OAI/2.0/oai_dc/" xmlns:dc="http://purl.org/dc/elements/1.1/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/oai_dc/
[http://www.openarchives.org/OAI/2.0/oai_dc.xsd]">

<dc:title>Pioneer days & shanty ways</dc:title>
<dc:creator>Eldershaw, Edith V.</dc:creator>
<dc:subject>History</dc:subject>
<dc:subject>Social life and customs</dc:subject>
<dc:description>Edith V. Eldershaw.</dc:description>
<dc:description>Printed by Williams & Crue Ltd.; Summerside, P.E.I.</dc:description>
<dc:description>Contains "stories", poems, and photographs,</dc:description>
<dc:publisher>Eldershaw</dc:publisher>
\\

<dc:type>collection</dc:type>
<dc:type>ingested</dc:type>
<dc:format>electronic</dc:format>
<dc:identifier>ilives:257167</dc:identifier>
<dc:language>eng</dc:language>
<dc:coverage>Prince County (P.E.I.)</dc:coverage>
\\

<dc:coverage>Tignish (P.E.I.)</dc:coverage>
<dc:coverage>Prince Edward Island</dc:coverage>

</oai_dc:dc>

XML Editors (on your desktop; outside of Islandora)

When developing a metadata form it is important to have an XML editor to test you created and editted XML in. Typically these editors can help you determine the XPath of an element, whether the output you are producing is valid, etc. XML editors would include oXygen (commerical), XPontus (opensource), and there are many others.

Anytime you are working with software that writes XML, it's important to validate that XML against the schema, and also to ensure backward compatability when importing metadata that follows older versions of the schema.

XML Form Builder

XML Form Builder is a Drupal module that integrates the creation of XML based forms into Islandora. Once a form has been built, it is associated with a content model. This tutorial will take you through the process of creating a form, associating it with a content model, and implementing it with a collection. Once it has been created you will be able to create and edit your metadata.

To use the XML Form Builder navigate to the module in your Islandora site: Islandora > Form Builder (admin/islandora/xmlform)

Form Builder Interface

When you start the module you are presented with a list of forms (those are the forms that come bundled with your Islandora install) and a series of options to perform.

...

Associate: Links a form with a content model.

Creating a Form

...

This is the main form building/editing interface for creating XML forms and it provides methods for adding form properties, form fields and a preview pane.

Setting Form Properties

When creating an XML form the first thing you need to set in the Form Editor is the Form Properties. This is where having an example of an OAI DC record would come in handy and would provide the information you need to fill in the Form Properties. Here is the part of the record that you’ll use:

...

Click "Save" once you have the properties entered. Once the form properties have been saved you are ready to add fields to your form.

Adding form fields

Some schema specify that elements appear in a certain order (an order-based schema), that certain elements are required, that only certain elements are repeatable, or whether and how elements can be nested. Refer to your schema documentation and to any guidance it offers in the creation of records based on the schema. In the schema we are using in this tutorial, Simple Dublin Core, each of the fifteen elements is optional and may be repeated, but no nesting is allowed. We will create a simple form for this exercise that utilizes several Dublin Core elements. Let’s create a table listing the element names, the form field labels, the types of form fields, the content of the elements, and whether they are repeatable. We’ll use this information when adding fields to our form.

Adding a textfield type form field - the dc:title element

We can use the information in our table to fill out the "Element Form" pane. We can start with the title element.

...

Adding the creator element - an element that may have multiple values

...

The second step is to create a nested tag type element. The image below displays the values for the properties used for this element.

Adding a textarea type form field - the dc:description element

The "textarea type" of form field should be used for elements that require a description or that contain a large amount of text.

Adding a select type form field - the dc:type element

In many cases you will want to provide the user with a list of controlled terms and the select form field type is used. For the type element our controlled list of terms is based on the DCMI Type Vocabulary. The Vocabulary provides a general, cross-domain list of approved terms that may be used as values for the Resource Type element to identify the genre of a resource.

...

2. To add terms to your select form field, click on the "More Advanced Controls" tab in the "Element Form" pane. Review the image below and enter your terms in the Options panel.

Adding a datepicker type form field - the dc:date element

For this example we are using the datepicker type of form field. You will want to review your existing metadata as another type of form field may be more appropriate.

...

The remaining two elements for our sample OAI DC XML form, dc:subject (tags, tag) and dc:rights (textarea), can be built in the same manner as fields of a similar type that we have already created.

Adding a file upload type form field - pdf file uploader

One additional element that can be added for convenience is a file upload type form field. This will allow you to browse for a PDF document on your local machine as part of the Islandora ingest process. The image below illustrates what properties need to be filled in. 

Form Associations Module

Connecting the Form to a Content Model

Once you’ve completed and tested the form you’ve created in the XML Form Builder module, you can connect that form to an existing content model using the Form Associations module. You can navigate to the module using this path:

...

In this example we will associate the form we created - oai_dc_basic - with the islandora:sp_strict_pdf content model. Review the image below to fill out the Form Associations dialog.

Form Associations Dialog

Navigating to a Collection

Once the association has been successfully created, you can try ingesting new objects into a collection that has the islandora:sp_strict_pdf content model associated with it. Alternatively, access the Islandora demo VM which has a PDF collection associated with the islandora:sp_strict_pdf content model. Navigate to the PDF collection using the image as a guide and try creating new PDF objects there.

...

Once in the collection (you can tell where you are by the breadcrumb), select the Add tab to add a new PDF to the collection.

Adding a PDF to the Collection

You will be presented with a dialog requesting two pieces of information: the content model and the form to use for ingest.

Selecting the Associated Form

Entering Metadata

You will be presented with the form that we created during this tutorial. You’ll need to fill it in. Once you’ve completed your data entry, submit the form.

...