Forms

Introduction

Forms are a collection of one or more optional or required fields which can be published to Portfolio Owners who then fill in those fields and save the resulting item in their Resources for later use.

Form presentation logic

Adding a form definition

After having created a schema file for your form you can add a form definition.

1. Upload your form definition xsd file. (samples are attached to this page)
2. Click 'Add Form'
3. Enter a name and select the xsd file
4. Enter some instructions
5. Click 'Add Form'

You can now test your form by going to the resources tool and adding an item of type 'form'. If you need to make a change to your form, just upload a new version of the xsd file and link that to the form definition via the 'revise' button. Once your form is completed click 'publish' of 'global' publish to publish it.

Exporting / Importing forms

Forms may be exported and imported using the import and export functions. Multiple forms may be exported and imported at once by adding the forms to a presentation template and exporting/importing that. After the import the presentation template can be deleted, the form templates remain.

Changing a published form

Once a form has been published the only aspects that can be changed are the name and the instructions. If you have to change the form definition here's a way to do that:

1. Upload your new xsd form definition
2. Un-publish the form. Do that by setting the fields 'sitestate' and 'globalstate' to 0 in table 'metaobj_form_def'
3. Hook your form to it's new definition by revising it and selecting the uploaded xsd
4. Restore the published state for the form, either in the database or by clicking the publish buttons.

This procedure has been tested for the following changes:

• Enlarging a text field
• Changing a field from text to richText
• Adding fields
• Adding options to a select field (enumeration)
• Making a field optional by adding minOccurs="0" to the xsd element

For extensive changes such as removing fields or changing the structure of the form the instances of the form would have to be edited so they still validate against the xsd.

Technical Information

Forms are stored allong side the other resources. That means either in the database of on the filesystem. Uploading an xml file that is a valid form does not make it a form in the resources tool, the file remains an xml file.

Form definitions are stored in the database in the table metaobj_form_def. This table holds a copy of the schema that defines the form fields. After a form is created the uploaded file that was used to create (add) the form can be deleted.

When a form is viewed using the generic viewer that is in Sakai an xslt is applied that is capable of rendering any form that may exist. That xsl can be edited and lives here: metaobj/metaobj-api/api/src/bundle/org/sakaiproject/metaobj/shared/control/formView.xslt
An xsl programmer could add custom rendering for the specific forms used at you institution creating a more fancy form view.