Form Generator

The Form Generator is a module used to create forms and collect data from your site visitors online. Once data has been collected, Form Generator allows you to export the data into a tab delimited file (you can then import data into a spreadsheet program such OpenOffice.org Calc or Microsoft Excel). Form Generator also offers some basic reporting features of its own, but they are limited.

The Main Menu is always shown across the top while administrating the Form Generator module. This menu allows you to perform key operations in certain areas of the Form Generator. Some of these operations include: New Form, List Forms, Settings, Report, and Archive.
When first entering the Form Generator the Main Menu will only show two options: New Form and List Forms. The Menu will expand its options when a form has been selected from one of the lists of forms. Certain options are shown for saved forms and certain options shown for unsaved or unapproved forms.
There are two parts to forms: Settings and Elements. A form's settings can be altered at any time in any form. They include settings like your instructions for the form, the submission message shown upon successful submission of a form, whether or not only registered users can view the form, and whether or not the form can be filled out multiple times by your users. A form's elements are the actual "questions" within your form. The elements are selected from a list of HTML elements like text field, text area, drop box, check box, radio button, and multi select. These elements can be used to ask and gather all sorts of information. A form's elements can only be edited when a form is in the unsaved state.
Under List Forms, three separate lists are shown. Saved Forms are forms that have been saved and may or may not contain data. That depends on whether or not you have the form available to your site visitors and whether or not those visitors have filled out the form. Unsaved Forms are forms that are being built but haven't been fully saved. Unapproved Forms are forms that were created by a user that is designated as needing approval of their forms before they are made available to the public. Once an unsaved or unapproved form is saved, it will move to the Saved Forms list.
When clicking on a form in a list, you will be viewing the form as a visitor to your site would view it. However, as an admin you will see the Main Menu at the top. From the menu you can select to perform various operations on the form you are viewing. You can always return to the form listing by clicking List Forms.
Something to keep in mind when saving forms: Make sure you are positive the form is correct and ready to be viewed and filled out by your site visitors. Once a form is saved it will start collecting data. If you decide to edit the elements within that form, the data collected by the form must be cleared and archived . Hence, you reset the form when you edit its elements. A good practice is to Export the data from the form just before you edit it's elements. You can always edit a form's settings no matter which state it is in.

Creating a Form

It is a good idea to have your form planned out in advance before diving in and creating a form. In the plan, you should take into account the name of the form, the instructions for the form, the submission message for the form, the elements to be contained in the form and what HTML elements will be used to represent your form elements, and what type of users the form is geared towards (anonymous or registered visitors to your site). Once you have planned out the settings and elements for your form, follow these steps to create one:

Make sure you are logged into an administrative account that has permissions to use the Form Generator.
From your Control Panel, select the Site Content tab.
Find and select the Form Generator module.
From the Main Menu, select New Form.
You will be shown the Settings for your new form.
Fill out the Name, Instructions, Submission message, and other settings for your form.
If your form falls into one of your site's Categories, specify it as well.
Click Save Settings to save your settings and begin adding elements to your form.
You will notice that the menu now has a Settings option and an Elements option. Selecting >Settings will take you to editing the settings for your form and selecting Elements will take you to adding/editing of your form's elements.
To add an element to your form, select the element type you wish to add from the tool bar at the bottom and click Add.
See the section for adding the element you selected for more specific instructions for that element.
Continue adding elements until you have all your planned elements within your form.
Take a final look at your form to make sure everything is in order and make changes where needed.
When you are sure your form is complete, click the Save Form button on the tool bar across the bottom to save your form.

Adding a Drop Box Element

Make sure you have planned out the format of your drop box before continuing. You should have in mind the label or question for the drop box, the number of options, the option text to be shown to the user, and the actual value of each option to be stored when it is selected.

Make sure you are editing the elements of the form you wish to add the drop box to. Select Dropbox from the drop down list of elements on your tool bar and click Add. Follow these steps to finish adding the element:

Fill out the Name for your element. The Name is used to uniquely identify this particular element within the form. Form Generator will attempt to auto-assign a unique name to your element, but if you would like a different name you can change it. The only restrictions are: the name must contain only alpha and numeric characters, NO spaces, and be unique within the form you are editing.
Fill out the Associated Text for your element. The associated text is the text shown with your element. This text can be a simple label, question, or instruction. (e.g.: Please select your age range:)
Enter the Number of Options to be used with the drop box or select a Predefined Option Set (see section below: Predefined Option Sets).
If this element is required to be filled out, check the Required check box.
Click Next.
If you did not select a predefined option set, you will now need to fill out the information for each option in your drop box.
For each option, enter the Text which will be the actual text shown to inside the drop box.
For each option, enter the Value which will be the actual value stored if the corresponding option is selected. Optionally, if you the value you want to be stored is the same as the text entered for each option, you can select the Use option text as values check box at the bottom of the list of options. If that is selected, you do not need to fill out anything for the values of your options.
If you wish to have a certain option selected by default when the form is first shown to your site visitors, select the Default flag for the corresponding option.
If you wish to save the set of options you just created as a predefined option set, enter a name to save the option set as in the Save option set as field.
Double check your option set and click Save Dropbox when finished.
The drop box will be saved and added to the end of your form.

Adding a Text Field Element

Make sure you have planned out the format of your text field before continuing. You should have in mind the label or question for the text field and whether or not the text field is required to be filled out.

Make sure you are editing the elements of the form you wish to add the text field to. Select Textfield from the drop down list of elements on your tool bar and click Add. Follow these steps to finish adding the element:

Fill out the Name for your element. The Name is used to uniquely identify this particular element within the form. Form Generator will attempt to auto-assign a unique name to your element, but if you would like a different name you can change it. The only restrictions are, the name must contain only alpha and numeric characters, NO spaces, and be unique within the form you are editing.
Fill out the Associated Text for your element. The associated text is the text shown with your element. This text can be a simple label, question, or instruction. (e.g.: Please enter your full name:)
Optionally, you can enter a Size and a Maxsize for your element. The size will be the actual size of the text field and will affect how many characters are shown at one time in the text field. The maximum size is the maximum number of characters you are willing to accept. A user may type in more than the maximum size allows, but the Form Generator will store only the number of characters specified with maxsize. If no size or maxsize is specified, Form Generator will fill in default values for you.
If this element is required to be filled out, check the Required check box.
Double check your input and click Save Textfield when finished.
The text field will be saved and added to the end of your form.

Adding a Text Area Element

Make sure you have planned out the format of your text area before continuing. You should have in mind the label or question for the text area and whether or not the text area is required to be filled out.

Make sure you are editing the elements of the form you wish to add the text area to. Select Textarea from the drop down list of elements on your tool bar and click Add. Follow these steps to finish adding the element:

Fill out the Name for your element. The Name is used to uniquely identify this particular element within the form. Form Generator will attempt to auto-assign a unique name to your element, but if you would like a different name you can change it. The only restrictions are, the name must contain only alpha and numeric characters, NO spaces, and be unique within the form you are editing.
Fill out the Associated Text for your element. The associated text is the text shown with your element. This text can be a simple label, question, or instruction. (e.g.: Please enter your full name:)
Optionally, you can enter the Rows and a Columns for your element. The rows will be the actual number of rows in the text area and will affect how many characters are shown per line. The columns are the actual number of columns in the text area and will affect how many lines of text are shown at a given time. If no rows or columns are specified, Form Generator will fill in default values for you.
If this element is required to be filled out, check the Required check box.
Double check your input and click Save Textarea when finished.
The text area will be saved and added to the end of your form.

Adding a Mutliple Select Element

Make sure you have planned out the format of your multiselect before continuing. You should have in mind the label or question for the set, the number of options, the option text to be shown to the user, and the actual value of each option to be stored when it is selected.

Make sure you are editing the elements of the form you wish to add the multiple select to. Select Multiple Select from the drop down list of elements on your tool bar and click Add. Follow these steps to finish adding the element:

Fill out the Name for your element. The Name is used to uniquely identify this particular element within the form. Form Generator will attempt to auto-assign a unique name to your element, but if you would like a different name you can change it. The only restrictions are, the name must contain only alpha and numeric characters, NO spaces, and be unique within the form you are editing.
Fill out the Associated Text for your element. The associated text is the text shown with your element. This text can be a simple label, question, or instruction. (e.g.: Please select your age range:)
Enter the Number of Options to be used with the multiple select box or select a Predefined Option Set (see section: Predefined Option Sets).
If this element is required to be filled out, check the Required check box.
Click Next.
If you did not select a predefined option set, you will now need to fill out the information for each option in your multiple select box.
For each option, enter the Text which will be the actual text shown for options in the multiple select box.
For each option, enter the Value which will be the actual value stored if the corresponding option is selected. Optionally, if you the value you want to be stored is the same as the text entered for each option, you can select the Use option text as values check box at the bottom of the list of options. If that is selected, you do not need to fill out anything for the values of your options.
If you wish to have a certain option selected by default when the form is first shown to your site visitors, select the Default flag for the corresponding option.
If you wish to save the set of options you just created as a predefined option set, enter a name to save the option set as in the Save option set as field.
Double check your option set and click Save Multiselect when finished.
The multiple select box will be saved and added to the end of your form.

Adding a Radio Button Element

Make sure you have planned out the format of your set of radio buttons before continuing. You should have in mind the label or question for the set, the number of options, the option text to be shown to the user, and the actual value of each option to be stored when it is selected.

Make sure you are editing the elements of the form you wish to add the radio buttons to. Select Radio Button from the drop down list of elements on your tool bar and click Add. Follow these steps to finish adding the element:

Fill out the Name for your element. The Name is used to uniquely identify this particular element within the form. Form Generator will attempt to auto-assign a unique name to your element, but if you would like a different name you can change it. The only restrictions are, the name must contain only alpha and numeric characters, NO spaces, and be unique within the form you are editing.
Fill out the Associated Text for your element. The associated text is the text shown with your element. This text can be a simple label, question, or instruction. (e.g.: Please select your age range:)
Enter the Number of Options to be used with the radio button or select a Predefined Option Set (see section: Predefined Option Sets).
If this element is required to be filled out, check the Required check box.
Click Next.
If you did not select a predefined option set, you will now need to fill out the information for each option in your set of radio buttons.
For each option, enter the Text which will be the actual text shown next to the radio buttons.
For each option, enter the Value which will be the actual value stored if the corresponding option is selected. Optionally, if you the value you want to be stored is the same as the text entered for each option, you can select the Use option text as values check box at the bottom of the list of options. If that is selected, you do not need to fill out anything for the values of your options.
If you wish to have a certain option selected by default when the form is first shown to your site visitors, select the Default flag for the corresponding option.
If you wish to save the set of options you just created as a predefined option set, enter a name to save the option set as in the Save option set as field.
Double check your option set and click Save Radiobutton when finished.
The radio buttons will be saved and added to the end of your form.

Adding a Check Box Element

Make sure you have planned out the format of your check box before continuing. You should have in mind the label or question for the check box, the number of options, the option text to be shown to the user, and the actual value of each option to be stored when it is selected.

Make sure you are editing the elements of the form you wish to add the check box to. Select Checkbox from the drop down list of elements on your tool bar and click Add. Follow these steps to finish adding the element:

Fill out the Name for your element. The Name is used to uniquely identify this particular element within the form. Form Generator will attempt to auto-assign a unique name to your element, but if you would like a different name you can change it. The only restrictions are, the name must contain only alpha and numeric characters, NO spaces, and be unique within the form you are editing.
Fill out the Associated Text for your element. The associated text is the text shown with your element. This text can be a simple label, question, or instruction. (e.g.: Check if you wish to receive mail about upcoming events.)
Enter the Number of Options to be used with the check box or select a Predefined Option Set (see section: Predefined Option Sets).
If this element is required to be filled out, check the Required check box.
Click Next.
If you did not select a predefined option set, you will now need to fill out the information for each option in your set of check boxes.
For each option, enter the Text which will be the actual text shown next to the check boxes.
For each option, enter the Value which will be the actual value stored if the corresponding option is selected. Optionally, if you the value you want to be stored is the same as the text entered for each option, you can select the Use option text as values check box at the bottom of the list of options. If that is selected, you do not need to fill out anything for the values of your options.
If you wish to have a certain option selected by default when the form is first shown to your site visitors, select the Default flag for the corresponding option.
If you wish to save the set of options you just created as a predefined option set, enter a name to save the option set as in the Save option set as field.
Double check your option set and click Save Checkbox when finished.
The check boxes will be saved and added to the end of your form.

Editing, Removing or Moving Elements

Editing, removing, and moving elements within a form are all similar operations. When editing a form's elements, the existing elements are shown with the element name and a drop box of options to the right of each element. To edit an element, select the Edit option from the drop box next to the appropriate element and click Go. You will be taken to a page exactly like the page shown when creating that particular element. Follow the instructions given for creating that particular element in their appropriate sections within this document.

To remove an element, select the Remove option from the drop box next to the appropriate element and click the Go button. You will be asked to confirm whether or not you wish to remove the element. Upon selecting Yes or No you will be taken back to editing your form.

To move an element, select the Move Up or Move Down option from the drop box next to the appropriate element and click the Go button. The element will be moved up or down in the form. If you element is at the beginning of the form and you select Move Up, the element will wrap to the end of the form and vice versa.

Predefined Option Sets

Predefined option sets are sets of options that are used often when creating a form. Some examples might be Colors, Sex, Yes/No answers, etc. Predefined option sets are created when adding or editing a form element that can contain options. These elements are Dropbox, Radio Button, Multiple Select, and Checkbox. See step 10 for any of the mentioned elements for more details on actually saving predefined option sets. There is currently no method for administrating or deleting predefined option sets.

Adding an Existing Form

First, you must be aware of the state of the form you wish to edit. If the form is saved, make sure you have exported your data before you attempt to edit it (see section Reporting on Form Data). Once you start editing the elements of a saved form, the form data collected is archived and cleared. Editing an unsaved or unapproved forms have no "side-effects" as they contain no data.

Editing an Unsaved or Unapproved Form

Make sure you have planned out the changes you wish to make to your form. In the plan you should take into account the elements you wish to remove, elements you wish to add, and settings you wish to change. If you are adding elements to the form, make sure you have carefully planned the settings needed for the elements as well as where those elements will appear in the form. Once you have your plan, follow these steps to edit your form:

Make sure you are logged into an administrative account that has permissions to use the Form Generator.
From your Control Panel, select the Site Content tab.
Find and select the Form Generator module.
You will be shown a list of your current forms.
Find the form you wish to edit and click the linked Name of the form.
To edit the Settings for the form you selected, select the Settings link from the Main Menu.
Change any settings you had planned on changing and click the Save Settings button.
You will now be taken into editing the elements of the form you have selected.
Stick to your plan and remove or add elements in the same manner as when creating a form (see section Creating a Form).
When you have finished editing the elements within the form, take a moment to look over the form for typos or errors.
Select Save Form from the tool bar when you are ready to save the form.

Editing a Saved Form

If you are going to edit a saved form, make sure you have exported the form data before you continue (see section Reporting on Form Data).

Make sure you are logged into an administrative account that has permissions to use the Form Generator.
From your Control Panel, select the Site Content tab.
Find and select the Form Generator module.
You will be shown a list of your current forms.
Find the form you wish to edit and click the linked Name of the form.
Select the Settings link from the Main Menu.
If you are not editing the settings of the saved form, proceed to step 11, otherwise continue with step 8.
Change any settings you had planned on changing and click the Save Settings button.
You will be taken back to the form listing with the form's settings updated. If you still wish to edit the elements for the form, click the linked Name of the form you wish to edit.
Select the Settings link from the Main Menu
Click the Edit Elements button at the bottom of the settings page.
At this point, Form Generator will want to archive your form and it's data. If you are sure you wish to continue to edit the form's elements, archive the form, and clear the form data, select the Confirm button. Otherwise, select Cancel and do not continue following these steps.
You will now be taken into editing the elements of the form you have selected.
Stick to your plan and remove or add elements in the same manner as when creating a form (see section Creating a Form).
When you have finished editing the elements within the form, take a moment to look over the form for typos or errors.
Select Save Form from the tool bar when you are ready to save the form.

Deleting a Form

First, make sure you know which form you wish to delete and that you are absolutely sure you wish to delete it permanently. If the form is a saved form, go ahead and export it's data before you delete it (see section Reporting on Form Data). When you have completed that, follow these steps to delete the form:

Make sure you are logged into an administrative account that has permissions to use the Form Generator.
From your Control Panel, select the Site Content tab.
Find and select the Form Generator module.
You will be shown a list of your current forms.
Find the form you wish to delete and click the corresponding check box next to it's name.
Now select the Delete option from the drop box for the corresponding list (i.e.: Saved, Unsaved, or Unapproved).
Click Go.
You will now be asked to confirm the deletion of the form. Click Yes or No.
If you selected Yes, your form will be deleted and you will be returned to the form listing. If you selected No, the form will not be deleted and you will be returned to the form listing.

Archiving a Form

Archiving a form is a good way to save a particular "state" of a form. Only saved forms can be archived since they are the only forms which could possibly contain data. When a form is archived, the form, it's elements, and all it's data are all saved in an archive file on the server. To retrieve an archived form, you need to contact your system administrator. Follow these steps to archive a form:

Reporting on Form Data

Reporting is only available for saved forms since they are the only forms that could possibly contain data. There are a couple of ways to report on data entered into a form. Form Generator has a built in method for browsing current entries in a form as well as a method for exporting this data into a tab delimited file that can be downloaded and imported into any spread sheet program (e.g.: OpenOffice.org Calc, Microsoft Excel, etc.).

Some statistical data is calculated and displayed by Form Generator such as the number of complete and incomplete entries, the total number of entries, and the date and time of the last entry the form received. Shown below this information is a list of the actual entries received by the form. There are several options you have available for each entry. You can edit, delete, view, or print each entry.

When editing an entry, the form is loaded with the data populated, and you are allowed to change any value you wish. When viewing or printing an entry, just the raw data is shown and not the form in it's entirety. If you delete an entry, it is permanently removed from the form's data and can only be recovered through an archive if one exists. It is recommended you archive your form data before you edit or remove any of it's entries. This will ensure you have a backup copy in case of emergency.

To export all the data within the form, simply click the Export button. A archived ".zip" file will be created by the Form Generator and will be sent to you through your browser. Choose a suitable download location on your machine and save the file. To unzip the file you can use the unzip command in *nix or the winzip, winace, or winrar programs in a windows environment. A single file will be extracted that is a tab delimited file containing your form's data. Using a spread sheet program, import the file and then save it to a more workable format that is native to the program you're using (i.e.: *.sxc for OpenOffice.org Calc or *.xls for Microsoft Excel).

The Form Generator Module

Introduction