...

Introduction

This instructions has two sections.

"How to Edit an Existing Form

...

" is geared toward people who do not know XSLT.  It provides instructions on interacting with forms to do things like copy an existing form, then delete elements from that longer form to make a shorter form, then associate that form with a specific content model.  This can support setting up a workflow, and you don't need to know XPATH/XSLT to do it.

"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.

Where is Forms Management on my Islandora Site?

1) Click to "Islandora" in the admin menu across the top of the page.

2) A window will pop up in the middle of the screen.  Click to "Form Builder".  This takes you to (admin/islandora/xmlform).

3)  This shows you all forms on your site.  There are several built in forms that cannot be deleted (you uninstall them by deleting the form association on each).  Any custom forms you have installed on  your site will show up at the bottom of the list.

Image Added

This is where you administer forms.

The forms show up when you go to upload an item and add metadata, or when you go to edit metadata on an item on your site.

In order for a form to show up, you need to (1) have the form installed on your site, and (2) add a form association and "Associate" that form with the specific Content Model you will use it with.

How to Associate a Form with a Content Model

In order for a form to show up for someone uploading material or editing metadata on a site, the form has to (1) exist on the site and be in that menu at Isladora > Form Builder (admin/islandora/xmlform), and (2) be associated with that Content Model.

Most of this wiki page is about getting the form onto the site.  A last step will always be adding the form association, and for that step, you should come back here for instructions on adding the association.

View an Existing Form Association

1) Click to "Islandora" in the admin menu across the top of the page.

2) A window will pop up in the middle of the screen.  Click to "Form Builder".  This takes you to (admin/islandora/xmlform).

3)  On the right hand side of the page, click on "Associate" next to an existing form.

This takes you to the existing form association(s) for that content model.

Below is the default form association for the Audio MODS form, which is one of the built-in forms that ships with Islandora:

Image Added

Add a New Form Association

1) Click to "Islandora" in the admin menu across the top of the page.

2) A window will pop up in the middle of the screen.  Click to "Form Builder".  This takes you to (admin/islandora/xmlform).

3)  First look at the forms and find a form with an existing form association that you feel is working well and is similar to how you want your form to work.  Next to this existing form, click on "Associate".  This will show you the existing form association.  You can use this as a template for setting up your new form association.

4)  In another tab of the browser, go back to the main forms management screen (admin/islandora/xmlform).  Next to the form you want to associate with a Content Model, click on the link to "Associate".

5)  This pops up a window with the form associations for that form.  In the "Add Association" section, click through each field: 

"Content Model" = the Content Model you want this form to show up for (Begin typing the PID of the content model you wish to associate a form with, and the name will auto-complete:)

"Metadata Datastream ID" = The datastream that the MODS form will create or edit.  (ie. MODS might be the datastream for a MODSXML file)

"Title Field" = Drop down menu lets you select any metadata form that that form is able to interact with.  You select which one you would like to map to the title of the Drupal representation of that item.

"XSL Transform" = Option to map from MODS XML (if you are installing a MODS form as opposed to some other metadata schema) to Dublin Core.  Select this if you are installing a MODS form.  Leave it "No Transform" if you are working with any other format.

"Self XSL Transform" =  Drop down menu shows transformations available to run on the XML on save.  You might use this to clean up the XML, for example, to remove empty elements.  You might also use this for functionality that cannot be implemented in the Form Builder's web forms, for example, to sequence elements relative to one another.  Instructions on how to add a .xsl file to the list of options are here https://github.com/Islandora/islandora/wiki/Creating-and-Working-With-XML-Forms#adding-an-xslt-transformation-to-the-list-of-available-transformations .  In general, your site or hosting company will have a standard transformation to be used for each metadata schema.

"Upload Template Document" = You can upload a sample metadata record in XML, and that will be used to prepopulate the form fields when someone creates a new item on the site.  This will have no effect on editing existing metadata for an item on the site.

How to Copy an Existing Form That is Already on Your Islandora Site

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.

1) Click to "Islandora" in the admin menu across the top of the page.

2) A window will pop up in the middle of the screen.  Click to "Form Builder".  This takes you to (admin/islandora/xmlform).

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

Image Added

Make sure your name is something that you will remember. 

 Once you have named your form, click “Copy.” 

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

Image Added

5) Add the form association for the content model.  Adding the association means that the new form will show up in the drop down menu when you go to edit or add metadata for that kind of Content Model.

First look at the default form association for the form you just copied.  Next, go to the main forms management area, and click to "Associate" to the right of the name of the new form you just made by copying.  Now, the next form will show up in a drop down menu of available forms when someone goes to add or edit metadata for that kind of content model.

How to Delete a Form from Your Islandora Site

1) Click to "Islandora" in the admin menu across the top of the page.

2) A window will pop up in the middle of the screen.  Click to "Form Builder".  This takes you to (admin/islandora/xmlform).

3) Click "Delete" to the right of the form you want to delete.

In general, it is a good idea to keep a local copy of the form you deleted.  For example, if a bug in the form resulted in metadata errors, then you may want to be able to clean up metadata on your site.  It also may be a good idea to delete form associations rather than delete the form.  By deleting associations, you ensure that the form will not show up to people uploading and editing metadata, but you can easily bring the form back by adding the association later.

How to Install a Form from Github

Where to Find Other Peoples' Islandora Forms

Along the top of the screen at Islandora > Form Builder , you will also see an option to "Create Form" or "Import Form".

Creating forms from scratch requires proficiency in XPath/XSLT.

Importing forms used by other sites can be a good way to look for source material beyond the built in forms that come with an out-of-the-box Islandora install.

Islandora's Built In Forms

Some forms are already built into your Islandora site.  To see those, click to "Islandora" in the admin menu across the top of the page. A window will pop up in the middle of the screen.  Click to "Form Builder".  This takes you to (admin/islandora/xmlform).

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 existing forms on your site.

Copying an existing form, and editing the copy can be a good way to make small changes and develop a new form.

GitHub sources for Islandora Forms

Here are some sources for forms:

• Islandora Foundation's forms repository: A community repository of Islandora Ingest forms is maintained in the Islandora Foundation's Github account. 
• DiscoveryGarden's forms repository:  https://github.com/discoverygarden/xml_forms
• Florida Virtual Campus' forms repository:  https://github.com/FLVC/fl_islandora_forms

How to Install a Form from XML (ie. from Github)

1) Click to "Islandora" in the admin menu across the top of the page.

2) A window will pop up in the middle of the screen.  Click to "Form Builder".  This takes you to (admin/islandora/xmlform).

3)  Locate a form on GitHub that you want to explore.  Download the XML file from GitHub.

4)  In Islandora, go to Islandora > Form Builder (admin/islandora/xmlform), and click "Import Form" along the top of the screen.  Click through to install the form on your site. (Please note: Depending on the type of form and form provider you choose, there may be additional steps to configure that are out of the scope of this tutorial.)

5)  Now, set the form association for the form you just installed.  Think what content model you would like that form to appear for.  On your Islandora > Form Builder (admin/islandora/xmlform), look next to the default form for the content model you want to associate the new form with, and click "Associate" on the default form.  This will bring up a screen showing you the settings for the form association.  On your new form that you want to association with that content model, go to Islandora > Form Builder (admin/islandora/xmlform), and click "Associate" next to the form you are working with.  Set up the new form association based on the form association you pulled from the default form for that content model.

Installing a form from GitHub, lets you look at forms used by other institutions or organizations.  Keep in mind, as mentioned above in the Please note: of step 4, that forms used by other organizations may have specific requirements or local metadata profiles that don't matter to you or cannot be covered here in this tutorial. Review any given documentation or READMEs from that provider's repository when possible. Also, keep in mind, Islandora is displaying content models on the web interface based on the MODS datastream, and the stylesheets installed on the form association are expecting MODS as input.  Not all, but definitely some forms available for download from GitHub work with other metadata formats.

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.

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.

The following section will show you where to access forms in your Islandora installation, and how to clone and edit a form, and associate it with a content model. This section is for people who do not have knowledge of XPath, and covers only minimal configuration options. If you are more familiar with XPath, and XML, then we suggest that you go straight to the section on creating custom ingest forms, which provides a more technical overview of the interface, as well as information for creating elements. 

To access the XML form builder, log into your Islandora site as an administrator, and navigate to Islandora > Form Builder (admin/islandora/xmlform). You should see the screen below: 

Image Removed

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

When creating a new form, it is best to start by cloning 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. 

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

Image Removed

Make sure your name is something that you will remember. 

 Once you have named your form, click “Copy.” 

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

Image Removed

About the Form Builder Interface 

...

To create a form using a new schema, you will have to create a new form from scratch, or clone a Copy a form of the appropriate schema. This requires knowledge of both XPath and the .xsd affiliated with that schema. To create a new element, you will also have to be familiar with XPath. 

...

In order to fill out this form appropriately, ensure that you are familiar with the details of your solution pack - particularly the name of the content model, and the name of the metadata stream it prescribes. If you are not sure, please review the Solution Pack documentation for your installed solution packs. the metadata stream it prescribes. If you are not sure, please review the Solution Pack documentation for your installed solution packs.  Alternatively, you can look at the list of forms on your site, find the default form for your desired content model, and click "Associate" next to it.  This will pull up the default form association for that content model.  You can recreate that on your new form.

At the top of the screen, you can see a list of all existing form associations.

...

The "XSL Transform" file you choose is used by lslandora to crosswalk the schema of your rich metadata XML to Islandora’s default DC stream. In this case, where you are cloning copying a form, you will want to select the default xsl for your content model. This information is provided in the Solution Pack section of your document. (For more information about Islandora’s use of .xslts, please review the “Islandora and Metadata” section of the guide. XSLT are called from a folder within islandora_content_model_forms (in the XML Forms modules).

...

How to Create a New Custom Form

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

This The following section presumes that you are using the Virtual Machine Image or are visiting http://sandbox.islandora.ca OR that you have installed and configured the XML Forms module, and that you have a basic knowledge of XPath and understand metadata schemas. For an overview of how Islandora handles descriptive metadata, read Chapter 11 - Metadata in Islandora - Ready for Review (KS). This section will discuss how to create a new form using the Islandora Form Builder.how Islandora handles descriptive metadata, read Chapter 11 - Metadata in Islandora. 

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.

...

<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 can be useful is important to have an XML editor to test code 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.

...

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

...

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

In some cases you will have multiple occurrences of an element, for example a digital object may have more than one creator (multiple authors) or may have many subjects that describe it. The Form Builder has several methods dealing with this use case. In our example OAI DC form we have decided that there could be multiple creators and the schema allows that. It is a two step process:

...

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.

DCMI Type Vocabulary

Source

When adding a select form field in the Form Builder there are two steps:

...