Child pages
  • Using the Form Builder Tool
Skip to end of metadata
Go to start of metadata
Unknown macro: {float}

Introduction

The attached how-to documentation has been contributed by rSmart and is specific to the rSmart Sakai CLE (our version of Sakai). Form Builder is stealthed in our 2.5 release because a few significant issues with the tool (noted in this documentation) have yet to be addressed. Even in its current unsupported contrib state, however, Form Builder has value to those who want a simplified way of building forms and are willing to work around its issues.

This tool allows you to author XSD files for site owners to use when they add forms in the Forms tool.

The Forms tool requires that form authors define valid content by specifying an XML Schema Definition (XSD) file. Schema files can be (and often are) created using external applications, but the Form Builder tool lowers the technical barrier for authoring XSD files by providing an intuitive interface and immediate feedback to form authors.

Important: Designing a form in Form Builder is a multiple step, iterative process. rSmart strongly recommends that you save your work often by using the "file" menu at the top of the tool to save each XSD file to Resources.

Warning: The design of this tool differs from that of other tools in the CLE in that all data is stored in the browser and none is saved to the CLE until the final step. Navigating away from the tool and immediately returning to it will result in a loss of all of the work up to that point.

Adding the Form Builder tool to a work site

The Form Builder tool has no permissions settings. Consequently, it is usually deployed only in the PortfolioAdmin site or another site that is not accessible to site participants. Even so, as system admin, you may add Form Builder to any group site if you choose to do so.

You cannot use the Site Setup or Site Editor tool to add Form Builder to any site. Instead, use the Sites tool to add tool ID "sakai.formbuilder" to the desired site. For information on adding sites via the Sites tool, see section 3.4.11, How do I add a stealthed tool to a site?

Warning: After you add Form Builder to a group site, all site participants will be able to use it to create and save XSD files. Therefore, if you deploy Form Builder in a site that will be visited by typical students and others who do not need to use it, you may want to consider hiding it from "normal" users by using the Page Order Helper tool (sakai-site-pageorder-helper). For information on using this tool, see http://bugs.sakaiproject.org/confluence/display/POH/Home.

Note: Access to Form Builder does not give users the ability to change forms that have already been added to the Forms tool from other sources.

The Form Builder UI

The Form Builder UI is divided vertically into two main sections.

Form Information Section

The upper section of the tool UI is a collapsible panel that contains fields that apply to the entire form. To hide or show this panel, click the tab in the lower right quadrant of the section.

Complete the fields in the Form Information section once for the entire form:

  • Form Name - The form name appears as the name of the root element of any XML created when users complete the form. It is never displayed to someone using the form. An entry in this field is required.
  • Languages - The Form Builder tool allows a form author to build a schema that allows for localization. By choosing more than one language, the form author will be prompted for same information in multiple languages.
  • Form Title - This is never displayed to someone using the form. An entry in this field is required.
  • Form Description - This is never displayed to someone using the form.
  • Form Inline Description - This appears as a text at the top of the form.

Main Section - Tool Views

The lower section of the tool has multiple purposes, depending on the view you have chosen. To switch the view, mouse over the "Change View" tool menu item at the top of the screen. The following views are available.

Form Preview View

This view renders a rough view of what the form will look like. It shows only the form field labels and places to enter data.

Note: The Forms tool may render a significantly different view of the form than the Preview View.

Edit View

This view presents a hierarchical list of groups and fields in the form. From this view, you may edit, delete, and reorder fields and groups.

To edit a field, click the edit icon to the left of the field name.

To delete a field, click the delete icon to the left of the field name.

HTML Source View

This view is of no use in the CLE.

XSD Source View

This view displays the XSD schema file that will be saved. If desired, you may copy the source from this display into an external XML editing tool for further customization.

Add Menu

The Add menu enables you to select a field type and enter data in a dialogue box to describe the field. The dialogue box varies depending on the type of field you select.

Field types

Field type

Display Shown to End User

Useful for prompting for...

Text

A small HTML text input area

A few words or a short sentence

Text Area

A larger HTML text area

Large chunks of plain text without formatting

WYSIWYG

Rich text editor (the FCKeditor used throughout Sakai)

Large chunks of text that may contain hyperlinks, embedded images, formatting and styling

Date

Date picker widget

Valid dates

Selection

A set of radio buttons, a drop down list, a set of checkboxes or a select box, depending on the number of options in the selection and whether or not more than one option can be selected at a time

Responses where only a fixed number of known possible responses are valid

File

A file picker widget to allow the user to select a file.

File attachments

Boolean

A single checkbox to indicate a response.

Yes/no, true/false responses or acknowledgement of a statement.


Common Form Field Properties

All fields require some basic information. Only Name and Label are required fields, but additional information can make a form easier to use.

Name (required) - Not shown to the user but displayed as the element name in completed form items (e.g., "firstName").

Label (required) - A short prompt that will be shown directly above the form field (i.e. "First Name").

Description - Information displayed as a tool tip when users mouse over the label (e.g., "The first part of your name.")

Inline Description - Information displayed directly above the field label (e.g., "Please enter your first name.")

Required - If checked, specifies that users cannot save the form item without entering data in this field (e.g., when you want to require that users provide both first and last names in a Contact Information form).

Repeated - If checked, indicates that users may provide multiple values for this field (e.g., you may want to allow multiple email address entries in response to an "Email address" field).

Special Field Properties

Some fields allow you to place restrictions on the type of content that is acceptable.

Validation - Text fields can be restricted to valid-looking email addresses, phone numbers, or numbers.

Min and Max Dates - Date fields can be restricted to dates within a specified range.

Label and Values - A fixed set of viewable labels and stored values for selection fields.

Groups

Groups allow you to place one or more form fields in a set (such as street address, city, state and zip code fields under an "address" group). Placing fields in a group will prompt users to navigate away from the main form to a "subform" screen where they fill out and submit the fields in the group.

Building a Form Schema

After you have navigated to a site that has the Form Builder tool, follow these steps to design a form.

  1. Complete the Form Information section (see Form Information Section above) and click Update form information.
  2. Add a field or group to the form:
    1. Mouse over the "Add" menu item and select a field type.
    2. Fill out the field properties dialogue for that field type (see Common Form Field Properties and Special Field Properties above).
    3. Click Apply.
    4. In the Preview pane, check that the field is displayed as expected.
  3. Save the form schema (this is optional, but it is a good idea to save often):
    1. Mouse over File menu item and select Save or Save As.
    2. Save the form schema in the Resources folder of your choice as a file with an.xsd extension.
  4. Repeat Steps 2 and 3 for each new field and/or group desired in the form.

After saving a schema file, you can use Forms tool to add a form based on this schema.

Known Issues

The use of the Form Builder to build schemas for the OSP Forms tool is known to have some issues.

  • There is no way to specify a maximum length of a "WYSIWYG" or "Textarea" field. Workaround: Edit the xsd file directly to modify the "maxLength" restriction of these fields.
  • The Forms tool does not recognize Label properties. Workaround: Make the label identical to the value in the selection field option.
  • Some browsers have issues when trying to add groups to a form.
  • Form Builder saves your work and stores it in Resources as an XML file, not as a valid W3C XSD file. However, the XSD source view is valid.
  • No labels