Creating a Student (Tiger) Web Form Using the New (2009) Form Handler

Introduction

This document will help you create a new web form using SharePoint Designer and the new (2009) Tiger form handler. As you continue, remember that you can copy and paste source code directly from this page into your web editing application. Even if you're not using SharePoint Designer, you may find the code editing advice on this page useful.

The Ugly Truth and the Silver Lining

As the World Wide Web continues to evolve, the task of creating and maintaining web sites is getting more challenging all the time. Increasingly, those who wish to develop custom web sites from scratch will have to acquire more advanced technical skills to do so. Those who are chiefly interested in posting content—rather than in developing sites—will likely be served best by user-friendly tools built on Web 2.0 technologies (e.g., Facebook, WordPress, Google Sites, etc.).

As a case in point, those who have (or acquire) a free Google Gmail account can create web forms within Google Docs. This solution is remarkably user-friendly and yields forms that may be accessed via web browser or sent as e-mail to targeted respondents. Google Docs adds form submissions to a spreadsheet in your account; you can then download the spreadsheet and open it in Excel to process the data. As the Web continues to evolve, it is certain include more user-friendly solutions like this.

Opening Your Tiger Site in SharePoint Designer

In order to create a form, you will first need to open your Tiger site in SharePoint Designer (SPD); for step-by-step instructions, see Opening Your Tiger Web Site for Direct Editing....

Creating a New Page and Inserting a Form
(Creating a New Page and Inserting a Form)

1. Select File> New> Page... from the SPD menu bar.
2. Select General in the left pane and HTML in the right pane; then, click the OK button. SPD will open your new page in the editing area in whichever mode—Design, Split or Code—was last used. These steps proceed in Design mode.
3. Type a page heading and introductory text if you wish.
4. From the Form Controls section of the Toolbox pane located (by default) in the upper right region of the SPD desktop, drag a Form object onto your page and drop it wherever you want the form to display.
5. Save the page.

Inserting Form Fields
(Inserting Form Fields)

1. From the Form Controls section of the Toolbox pane, drag the desired form field into the form object (box) you inserted in the previous section. For information on each of the available field types—Drop-Down Box, Input (Button), Input (Text), etc.—click the Form Field Examples... link on the right or search the SPD Help system.  
2. To add a text field label, position the insertion point to the left of the field and type your label text. You may add whatever text you like around a field. To add space to your form, press Enter or Shift-Enter to insert blanks lines.
3. Repeat Step 1 to insert additional data fields.
4. Below your data fields but inside the form boundaries, insert an Input (Submit) button and an Input (Reset) button.
5. Save the page. 

Configuring Form Fields
(Configuring Form Fields

For each field on your form, complete the following steps. Different field types will present different Properties dialogs.

1. Right-click the form field and select Form Field Properties... from the context menu.
2. Complete the Properties dialog box as desired and click the OK button. Here are a few representative examples:
   1. Text Box Properties
      1. Name - Enter a unique name for the field; this name will appear next to its corresponding value in the default confirmation page (Figure 1: Default Confirmation Page) and email message.
      2. Initial value - If you wish for the field to contain a default value, enter it here.
      3. Width in characters - Enter a number of characters to set the display width of the field. This approach is more precise than dragging the resizing handles on the field border. 
      4. Tab order - Many users will press the Tab key to advance through the fields on your form. If you wish to control the order in which the cursor moves from field to field, enter a number in this field. If you leave Tab order blank, the cursor will step from left to right, top to bottom.
      5. Validate - Click the Validate button to open a separate dialog to set rules for acceptable values.
2. Radio Button Properties
   1. Group name - Enter a unique name for the group of radio buttons. For example, if you have a group of four radio buttons representing the seasons,  you might name each of them season.
   2. Value - Enter the value for this particular radio button. Within your group of four, this one might be Spring, and the next one, Summer.
   3. Initial state - If you wish for this radio button to be selected by default, choose Selected; otherwise, choose Not selected. Of course, only one radio button in the group may be selected. Consider this carefully; when analyzing form data, will you be able to distinguish between intentional responses and default responses from skipped questions?
   4. Tab order - Described above.
   5. Validate - Described above.
3. Drop-Down Box Properties
   1. Name - Described above.
   2. Choices - This is where you will build the list of options that appear in the drop-down box. Click the Add... button to open the Add Choice dialog. Repeat for each list item. 
      1. Choice - Enter an option to appear in the drop-down. By default, this will be the value recorded. Returning to our seasons example, if your visitor selected Winter from the drop-down, the data value Winter would be recorded. 
      2. Specify Value - Select this checkbox if you wish to record a data value that is different than the listed choice. Then, enter the desired value in the provided field. For example, if your visitor selected Winter from the drop-down, the data value 4 might be recorded. This useful when working with coding systems.
      3. Initial state - Described above.
   3. Height - Enter the desired display height of the field in number of lines.
   4. Allow multiple selections - Choose whether or not to allow users to select multiple items from the list by using the Ctrl-click and Shift-click selection methods.
   5. Tab order - Described above.
   6. Validate - Described above.
4. Text Area Properties
   1. Name - Described above.
   2. Initial value - Described above.
   3. Width in characters - Described above.
   4. Tab order - Described above.
   5. Number of lines - Enter the desired height of the text area field in the number of lines.
   6. Validate - Described above.
5. Submit and Reset Button Properties
   1. Name - Ordinarily, there is no need to rename this field.
   2. Value/label - Edit this value to change the text label on the button.
   3. Button type - Leave this set to Submit for a submit button or to Reset for a reset button.
   4. Tab order - Described above.
3. Save the page.

Associating Your Form with the Tiger Form Handler
(Associating a Form with the Tiger Form Handler

1. Right-click anywhere within your form and select Form Properties from the context menu.
2. Select Send to other and set the dropdown box to “Custom ISAPA, NSAPI, CGI, or ASP Script”.
3. Click the Options button.
4. In the Action box, enter (or paste) /formsubmit/tuformsubmit.php
5. If necessary, set the Method field to "post".
6. Leave the Encoding type field blank.
7. Click OK, then click OK again to return to your form.
8. Save the web page.

At this point, you have "told" the form what handler to use, but not what to do with the submitted data. Next, we will configure the form submission options.

General Information on Form Configuration 

There are two different ways of “telling” the form handler what to do with the form submission:

• Using the form configuration file in your home directory on Tiger (next section) is the simpler approach in that it does not require that you edit your form's source code.
   
• Specifying submission options within the form source code itself will give you more control over how individual forms work. For example, you might create three different forms and configure them to send data to three different text files in your home directory.

If both options are in place, the configuration settings in the form's source code will override the configuration file in your directory.

A form can include one, two, or all three of the following “action” settings:

• confirm
  When the user submits, Tiger will redirect the user to a web page you specify—
  perhaps a confirmation page or your homepage.
  
• writefile
  When the user submits, Tiger will add (append) the form data to a CSV (Comma
  Separate Values) text file in your home directory. CSV can be opened and
  processed in Microsoft Excel and other spreadsheet applications.
  
• email
  When the user submits, Tiger sends the form data to an e-mail address (or
  addresses) that you specify.

 
Using the Form Configuration File in Your Tiger Home Directory

In this scenario, your form gets its submission information from a hidden file (named .formconfig) in your home directory on Tiger. If you wish for most or all of your web forms to process submissions in the same way—to send you an email message, for example—this “universal” configuration represents the simpler approach.

Your Tiger home directory already includes a .formconfig file preset with your e-mail address.Consequently, if you associate your form with the Tiger form handler (as described above) and do nothing else, you will receive submitted data in the form of email messages.

But, let's say that as a rule you also want form submissions to be added to a text file in your home directory and that you want users to be redirected to your home page after submitting. For that, you will need to edit your .formconfig file.

To edit your .formconfig file using WebDisk: 
(Edit .formconfig with WebDisk)

1. Open webdisk.towson.edu in your browser.
2. Log in using your Towson NetID. WebDisk will display some of the folders and files in your home directory.
3. Select the Show hidden files and Single page checkboxes in the upper right corner of your screen to display all of your files.
4. Locate the file .formconfig and click the [Edit] link to the right of the filename. WebDisk will display the contents in a new Edit File window.
5. Carefully edit the text. You can specify the same three submission options we explored in the previous section.
   
   To the right of email=, revise the email address as desired. To add an additional address, insert a comma after the first address, then type the new address.
   
   To the right of writefile=, enter the name of the CSV (comma separated values) file to which you want to append form submissions. This can be useful if you plan to eventually analyze or process your form data; most spreadsheet and statistics applications will open CSV files.
   
   To the right of confirm=, enter the address (URL) of the web page to which your visitor should be redirected after submitting—perhaps a custom confirmation page or your home page. If you leave this blank, the form handler will display a default confirmation page (Figure 1: Default Confirmation Page). 
    
6. Click OK at the bottom of the window to save your changes and return to your directory display.
7. Click the Log Out button on the WebDisk toolbar to close your session.

Configuring Submission Options Within a Particular Page Using Hidden Form Tags

If you want to configure a particular form to "behave" differently than the others—to not use the settings in the .formconfig file—you can specify your submission options in the form itself following the steps below. You will start by inserting a few lines of PHP code at the top of the web page on which the form will reside; this lets the form handler know that the form submission originated from Tiger, and not a spammer’s website.
(Inserting PHP Code Into Form )

1. With your form open in SharePoint Designer (or another application that supports source code editing), click the Code button at the bottom of your screen to display the page in code view.
2. Scroll to the top of the page and type (or copy and paste) the following code on Line 1. The code must be added exactly as it appears here above the <html> tag.

3. Save the page.

Next, you'll need to add the code for one or more submission options so that the form handler will know what to do with the form submission. You'll do this by adding hidden fields to your form—the user won’t see them in the form, but they’ll be silently passed to the handler. Make sure you don’t reuse these field names elsewhere in your form!

Figure 2 shows the source code for a simple, but complete form page, including the necessary PHP code, the reference to the new form handler, and configuration options (shown in red). 

To configure your form...
(Inserting Code for Submission Options )

1. to send submissions to one or more email addresses, add the following line to the source code of your page (also shown on Line 14 in Figure 2: Source Code for Entire Form ). Be sure to insert the code below that representing the form fields and substitute you own email address(es) where noted.
    

   <input type="hidden" name="email" value="yourusername@students.towson.edu,anotherusername@gmail.com"/>

   
   
2. to append submissions to a CSV file in your home directory, add the following line to the source code of your page (also shown on Line 15 in Figure 2: Source Code for Entire Form ). Be sure to insert the code below that representing the form fields and substitute a file name of your choice for “myfile.csv”.
    
   

   <input type="hidden" name="writefile" value="myfile.csv"/>

    
   
3.  to redirect the user to a specific web page upon submission, add the following line to the source code of your page (also shown on Line 17 in Figure 2: Source Code for Entire Form ). Be sure to insert the code below that representing the form fields and substitute the URL of your choice for http://www.towson.edu.
    
   

   <input type="hidden" name="confirm" value="http://www.towson.edu"/>

   
   

When you have finished adding the configuration code, double-check for accuracy and save the page.