formSubmission PowerLink

This PowerLink allows a web form to be displayed to a student and for the data entered to be forwarded as a WebCT mail message. An acknowledgement page may also be displayed to the student after they have submitted the form and a feedback email sent to them. The data entered may be saved before being submitted and also retained for displaying or updating in subsequent tasks. Values from columns in the grade book may be displayed and updated, thereby allowing forms to control selective release criteria. To make effective use of this tool users should be familiar with HTML and preparing web forms.

The formSubmission PowerLink is written for WebCT Vista 4.1.1 (or higher) and WebCT Campus Edition 6.1.1 (or higher). The Installation section lists the dependencies on other library files.

This PowerLink is installed in the same way as any other WebCT Vista 4+ PowerLink:

1. Create a directory called formSubmission in the deployablecomponents area of the WebCT domain directory on each application server (including the administration server for a cluster).
2. Copy the formSubmission.jar file into the formSubmission directory.
3. Copy the dependent jar library files into the deployablecomponents area of the WebCT domain directory on each application server (including the administration server for a cluster). If desired, an alternative location of the deployablecomponents/common directory may be used for the dependent files; this would allow them to be shared with any other PowerLinks with the same dependencies.
4. Configure the ProxyToolRegistry utility if it has not already been done (see the ProxyToolRegistry utility page for details)
5. Restart the WebCT service.
6. Log into WebCT as serveradmin.
7. In the Utilities, Settings area click on the link labelled formSubmission module in the System Integration column.
8. Enable the tool by selecting the radio button labelled True for the enable setting and click on the Save Values button at the bottom of the page.
9. In the Utilities, PowerLinks Proxy Tools area click on the Add Proxy Tool button.
10. Select formSubmission module from the drop-down list and click on the Next button.
11. Enter details as required in the boxes provided; for example:
    • Proxy Tool Name: Form submission
    • Version: 2.0
    • Description: Allow students to submit data via a web form.
    Note: the Proxy Tool Name is what will appear to Section Designers when they add the tool to their sections. Click on the Save button.
12. In the Utilities, Settings area click on the link labelled with the Proxy Tool Name entered in the previous step which should appear in the Tools column.
13. Clear the tick in the Lock setting checkbox for the Enable Tool setting. Click on the Save Values button.
14. Select the settings for the proxy tool again to enable the tool by default so that it is visible under the Add Content Link button within each section. Leaving it disabled will mean that Section Designers must enable the tool in each of their sections before it can be used.

The formSubmission PowerLink depends upon the following Java library files:

• webctdao.jar (2.3 or higher)
• ProxyToolRegistry utility
• velocity-1.6.2-dep.jar

The formSubmission PowerLink has the following custom configuration settings:

Note:

1. Files should normally be saved in the class files area of the section. Enter the location of the file in the setting; for example, if the file is called file.html and has been saved in a directory called forms then enter /forms/file.html. Note that the setting should start with a / character to reflect that this is an absolute path from the top of the class files area. It is also possible to specify files located at higher levels of the repository by adding the appropriate prefix to the file location setting:
   • Domain: //
   • Institution: //I
   • Division: //D
   • Group: //G
   • Course: //C
   The prefixes are case insensitive and may optionally be extended to the complete name; for example, //C and //course are equivalent. Thus, //DIVISION/forms/file.html would refer to a file named file.html in a directory named forms located at the Division level of the repository and ///forms/file.html refers to a file at the Domain level of the repository. System files may be referenced by prefixing their content ID, or pseudonym from the properties file, with //; for example //123456789 or //sample.

Properties file

The properties file should be located in the same directory as the formSubmission jar file and have the same name but with an extension of .properties.

A system file is normally referenced in WebCT by its content ID. To make it easier to reference shared files, and to make the settings more easily maintained, a pseudonym for a system file can be added to the properties file as follows:

//name=id

where name is the pseudonym and id is the content ID of the system file it refers to. The pseudonym may then be used to refer to this file. For example, if the properties file contains an entry of:

//sample=123456789

then the system file with a content ID of 123456789 can be referred to as:

//sample

in any of the configuration settings requiring the path to a file.

Follow these steps to add a form to a section:

1. enable the tool (if it is not already) by selecting the proxy tool from the Manage Course, Settings page
2. on the Build tab, click on the Add Content Link button and select the form submission proxy tool
3. select an existing instance of this tool, or click on the Create button to add a new one
4. enter a title to be displayed on the page and the path to the file containing the form; other settings are optional or have default values
5. click on the Save button

The settings for each instance of the proxy tool can be changed by clicking on the icon from the Build tab.

The following guidelines should be followed when preparing a web form (including feedback and resubmission files):

• The action attribute of the form element should be set to $Action, the method attribute should be set to POST and no target attribute should be included.
• References to other files (such as a style sheet or an image file) may be relative to the HTML file (and this is strongly recommended) rather than using absolute references.
• To avoid a form control from being included in the submission email do not give it a name; for example, avoid naming the submit button control.
• Javascript can be used to ensure that all required fields have been entered before the form is submitted.
• Properties of the student can be displayed in the page presented to students by inserting special references such as $User.UserId; see below for further details
• The special reference $Cancel is set to the URL which will return the user to the section's home page; this can be used, for example, in placing a cancel link (or button) on the form page (such as <a href="$Cancel">Cancel</a>).

Example

A simple example of a form follows:

To the student this form will look something like this:

Entry:

From the Teach tab a section instructor can review the current settings and open the form and feedback files in an edit box. The edit option is an alternative to editing the file using the file manager; access to the HTML editor is not available when editing the file using this tool.

When a form is submitted the data entered is sent as an email. Each field appears on a separate line prefixed with -> and the name of the field as specified in the form. The location of the form is used as the subject of the email.

 View movie illustration (3:48 minutes)

Any form fields with names starting with GB_ are assumed to refer to columns in the Grade Book. Thus, if a field named GB_Form1 is submitted with a value of 10 the grade book column named Form1 will be set to the value 10 for the current user. (Note that only students have grade book columns so the value will not be saved for other types of user.)

Special references

As seen above, when creating form, feedback and email template files there are a number of pre-defined special references which can be inserted into the content. All references are prefixed by a dollar sign ($). The following references are currently supported:

Displaying property values

When creating form, feedback and email template files it is possible to insert references to a User object which refers to the current user. Objects for the current section and parent course are also available. The feedback and email template files may also refer to values entered on the form by using the Form object. References to properties of these objects use the following syntax: $Object.Property, where Object is the name of the object and Property is the name of the property.

The User object supports properties such as:

• Firstname - the user's firstname
• Lastname - the user's lastname
• UserId - the user's WebCT user ID

The Section and Course objects support properties such as:

• Name - the name of the learning context
• LongDescription - the long description of the learning context
• FullDescription - the full description of the learning context
• ImsSource - the IMS source of the learning context
• ImsId - the IMS ID of the learning context

A full list of the properties and methods supported by the User, Section and Course objects can be found in the WebCTDAO documentation.

The Form object will contain a property for each control completed by the student on the form. For example, the value entered into a control called Name can be referenced as $Form.Name. If the control name contains spaces (which is not recommended) then its value can be referenced in the following manner: $Form.get("Your name"). Prefixing object names with an exclamation mark will prevent the reference from being displayed in the output when the property does not exist; this is a wise precaution to take especially for any optional fields which may not have a value. Multiple values for a parameter (as might be the case with a set of checkbox controls) are joined together into a single value separated with commas.

Below is a sample email template file for a form containing controls named Your name, Email and Telephone:

The resulting email will look something like this:

Note that the case of property names can be significant so it is best to enter them exactly as shown above or as used in the form. Anyone wishing to prepare more complex template files should refer to the User Guide for the Apache Velocity Project. This tool permits the use of conditional and looping statements. For example, the default template file is defined as follows:

If you experience any problems using this PowerLink try the following to trace the cause:

• inspect the webct.log file for any reported errors
• as serveradmin, set the logging level for com.spvsoftwareproducts to DEBUG; the messages logged will be included in the webct.log file.

Upgrade instructions

The following instructions provide a guide to the process of upgrading to a later release of this PowerLink. You are, however, strongly advised to follow them in conjunction with the installation instructions above, the administrator documentation provided for your release of WebCT, and to first try them on a test server.

Upgrading from version 1.0 to version 1.1

1. Shut down WebCT
2. Remove the old PowerLink jar file
3. Add the new PowerLink jar file
4. Restart WebCT
5. Log into WebCT as serveradmin
6. In the Utilities, Settings area click on the link labelled formSubmission Module in the System Integration column
7. Enable the tool by selecting the radio button labelled True for the enable setting and click on the Save Values button at the bottom of the page

After following the above steps. existing proxy tool instances should continue to work but none of the new settings will be available. To enable the new settings continue as follows:

1. In the Utilities, PowerLinks Proxy Tools area click on the Proxy Tool Name for a proxy tool created based on this PowerLink
2. Do not change the values of any settings but just click on the Save button at the bottom of the page
3. In the Utilities, Settings area click on the link in the Tools column labelled with the Proxy Tool Name
4. Tick the Unlock this setting box against the Enable Tool setting
5. Click on the Save button at the bottom of the page
6. Repeat the above steps for all proxy tools based on this PowerLink

The above steps will leave the proxy tool disabled in each section irrespective of any previous setting. It may be enabled for all sections as follows:

1. In the Utilities, Settings area click on the link in the Tools column labelled with the Proxy Tool Name
2. Select True for the Enable Tool setting
3. Click on the Save button at the bottom of the page

The enable setting may also be changed at lower levels of the learning context hierarchy (for example, at the section level). However, there is no known way of restoring the values for the enable setting as they existed before the upgrade.

Upgrading version 1.1 to a later release of version 1.1

1. Shut down WebCT
2. Remove the old PowerLink jar file
3. Add the new PowerLink jar file
4. Restart WebCT

Any existing proxy tool instances should continue working as before.

Upgrading to version 2

1. Shut down WebCT
2. Remove the old PowerLink jar file
3. Add the new PowerLink jar file
4. Ensure the ProxyToolRegistry utility file is available and configured on the server
5. Ensure the WebctDAO (version 2.3) utility file is available on the server
6. Restart WebCT
7. Log into WebCT as serveradmin
8. In the Utilities, Settings area click on the link labelled formSubmission Module in the System Integration column
9. Enable the tool by selecting the radio button labelled True for the enable setting, enter a value for the shared secret setting and click on the Save Values button at the bottom of the page

After following the above steps. existing proxy tool instances should continue to work but none of the new settings will be available. To enable the new settings continue as follows:

1. In the Utilities, PowerLinks Proxy Tools area click on the Proxy Tool Name for a proxy tool created based on this PowerLink
2. Do not change the values of any settings but just click on the Save button at the bottom of the page
3. In the Utilities, Settings area click on the link in the Tools column labelled with the Proxy Tool Name
4. Tick the Unlock this setting box against the Enable Tool setting
5. Click on the Save button at the bottom of the page
6. Repeat the above steps for all proxy tools based on this PowerLink

The above steps will leave the proxy tool disabled in each section irrespective of any previous setting. It may be enabled for all sections as follows:

1. In the Utilities, Settings area click on the link in the Tools column labelled with the Proxy Tool Name
2. Select True for the Enable Tool setting
3. Click on the Save button at the bottom of the page

The enable setting may also be changed at lower levels of the learning context hierarchy (for example, at the section level). However, there is no known way of restoring the values for the enable setting as they existed before the upgrade.

This work is written by Stephen Vickers (in collaboration with Tim Squires and Kim Picozzi) and is released under a Creative Commons GNU General Public Licence. The formSubmission PowerLink can be downloaded from OSCELOT where it is also possible to report bugs and submit feature requests.