Web Forms

The Web Forms plug-in allows you to create, edit, and publish forms on your website, and use them to collect data for various purposes, including but not limited to:

• order forms
• questionnaires
• surveys
• registration forms
• requests for information
• quizzes & tests

Responses can be saved to the database and/or emailed to a list of addresses.

Web Form Basics

Familiarize yourself with the following terms and concepts before attempting to create or edit web forms.

Web forms are built around the concept of questions and answers received to those questions. Questions are arranged into groups so they can be presented together. A complete group of questions is a form and the complete set of answers received from a given user is a response. Every question can keep track of its translations into various languages, and automatically map answers back to the default language.

Questions are created and managed as generic, reusable questions in your question bank, which is broken down into several question libraries for organization purposes. This allows you to re-use common questions (eg. name, address, phone number, etc.) without having to re-create and translate them every time you need them. To create a form, you simply pick the questions you want from your question bank, from those that you have available. If the desired question is not availble in your question bank, you will need to make it, first.

General Procedure

1. First you must create one more more libraries of re-useable questions that you can build forms from.
2. Next, you can create a form, and fill it with questions from your question bank.
3. Then you publish this form somewhere on your website so that users can find it and fill it in.

Getting Around

The administration interface is divided into Forms and Libraries.

The functions are similarly divided into Form management and Library management, arrived at through these two reports. Creating forms is very easy if the questions are already available in your libraries. You may need to spend a little time adding useful questions to your libraries before you can set up some forms.

Forms

Forms are for presenting a set of questions to the user, and processing their answers.

Making a new form

To create a new form:

1. Click the + new form link
2. Enter some information about this form:
• Name (optional) - this is used as a name for the form by custom processing code. In simple cases, you don't need to specify anything.
• Title (required) - this is used to title the form on reports and other places.
• Type (optional) - this gives the system some hints about how you intend to use the form, which may help to simplify some processes. For example, it will offer only questions from appropriate libraries.
• Template (optional) - this is the name of a template that you want to use to lay out the form. A default template will be provided if you leave this blank.
• Acceptance Message (optional) - this message will be displayed to the user after they complete the form.
• Notification Email To (optional) - whenever this form is filled out, a notification email will be sent to this address with the details.
• Settings (optional) - you can choose some optional form behaviours here.
• Status (required) - set the form to inactive if you want to disable it and prevent people from submitting it.
3. Start adding questions to the form.

Working on a form

To manage a form or its responses, click on the form name in the list of forms you have available. You will be presented with a toolbar that has the following options:

• stats - a summary of the questions answered by all of your respondents.
• responses - a listing of all responses; you can step through the pages, search for keywords, and sort by clicking on the column headings.
• filter - select a subset of responses, based on the date of submission or the answers to particular questions.
• export - download all of the responses as a spreadsheet.
• preview - the form as it will be shown to users. You can actually fill out and submit the from from this pane.
• configure - change the form setup parameters. These are the same questions you answered when you created the form.
• layout - create or revise a custom form layout.
• questions - modify or move your questions around. (see below)
• +add - add a new question to the form.
• publish - get the public URL to the form, or create a special page just for this form.
• copy - create a new form, with the same setup as this one.
• delete - discard the form and its responses. It will be moved to the trash bin, and can be recovered from there if you change your mind.

Review/export the responses

Responses can be viewed using the responses, filter, and export buttons in the form overview. Responses are listed in a table with the following columns:

1. Options - links to view, edit, or delete the individual response
2. Response - an ID number that uniquely identifies this response
3. Date - the date and time that the response was received
4. Member - the user who submitted the response, if known
5. Version - the language/version of the form that was used
6. all questions on the form are shown in the remaining columns

This information can be exported to Excel using the link at the end of the report, or directly from the form overview using the export button.

Alternativly, use the stats button to see an overview of all responses, with charts showing the proportion of respondents who provided different answers.

Manage the questions on the form

From the questions button in the general form overview, you can get a table summarizing the questions on the form:

• Click the question name to reconfigure the question itself.
• Click the up/down arrows to change the order of the questions.
• Click the + add question link to add a new question to the form.

Configure question

NOTE: the particulars of question phrasing, answer format, and so on are managed in your question libraries, not here. This is where you configure the question attributes that apply to this form only. If you want to change the general question details (on all forms that use it), you should use the link at the bottom to jump to the appropriate model question in your question bank.

A preview of the question is displayed at the top of the screen. You can also delete the question from the form, using the button here.

The question parameters than can be changed on this form are:

• Model question - use this to change the actual question that gets asked. Since this doesn't change the answers that have been received so far, you might end up with odd answers in your responses, unless the questions are similar enough to be interchangeable. Otherwise, consider deleting the question and its answers, and simply creating a new question to replace it.
• Flags
• required - check if the user must provide an answer to this question before the response will be accepted.
• placeholder - if you have a preset value (below), that value will be shown until the form field gets input focus. Then the placeholder value will disappear to accept the real input. This can be used to provide hints about formatting or types of input values that are sought. Placeholders are an HTML 5 feature, and are not supported on some browsers.
• Short Reference - this is used to name the input field in templates. Note that the question may already have a short reference name, as defined in the library, but you can override that name here if you want.
• Preset Value - this is used to prepopulate the input field.
• Sort Key - this is used to order the questions. You can set it explicitly here, or just use the arrows in the form overview to change it automatically.

Remove question

To remove the question from the form, click the Remove button. This will also remove any answers to that question that were received.

To restore the question to the form, without the original answers, simply add the question back in the normal way. To undo the removal, and restore all the removed answers as well, go to the Trash tool and restore the question from there.

Add new questions to the form

At the bottom of the list of questions in the form overview is a link to add a new question to the form. Clicking this link brings you to a list of all known questions in your question libraries, grouped by library. Simply click on a question to add it to your form.

Repeat this procedure as many times as required to create the complete form.

If the desired question is not available, you can create it by clicking on the add a new question links at the bottom of each library's list of questions.

Note that question libraries will not be offered to you if the library type and the form type do not match. To make a one-time exception, change your form type to match the library type temporarily to add the question, then change it back to the correct value.

Configure the basic form behaviour

You can change the basic form beviours in the configure pane. This brings up the same questions you answered when you created the form.

Question Libraries

Question libraries are for storing and organizing the questions that you will be using and re-using on various forms.

Creating a new question library is simple:

• Click the create new library link
• Enter a name for the library (eg. "Contact Information")
• Optionally provide a type of form that this library's questions will be used for. If you select a type (other than "other"), then you will only be able to choose these questions on forms that are also of that type.

Select one of the libraries to manage the questions in it.

Manage your question bank

Your bank of reusable questions is organized into multiple libraries. The questions in each library are listed in a table, with a link to add a new question to this library. Click on one of the questions to review it in detail.

Configure/edit question

When reviewing a model question, you have five panes that can be expanded or collapsed:

1. Preview - shows you what the question will look like to a viewer.
2. Details - summarizes information about the question.
3. Translations - shows the translations into your supported languages. Click on a translation to update it.
4. Edit - allows you to edit/reconfigure the question. Warning: this will affect the question everywhere it is used.
5. Delete - discards the question from your library. Warning: if the question is in use by any forms, this will also change the forms and responses.

Update translations

If you click on one of the translations you will be taken to a screen where the translations can be updated. The default (English) version is shown at top, and the translated versions below. If no translation exists, the English version will be shown in its place. Simply replace or edit this to provide a proper translation.

Delete question

Deleting the question moves the question to the trash, along with any instances of the question in forms, and their answers. This may damage active forms and responses. The forms that are using this question are shown to you so that you can decide whether deleting the question is safe.

Create New Questions

To add a new question to a library so that it is available for use in your forms, click the + create new question link at the end of the list of questions in the library. You must specify:

• Short Reference Name - used in custom templates. The short name should be only alphanumeric characters with no spaces.
• Question/Prompt - the question text that is shown to the user.
• Input Format - the type of answer that is needed, one of:
• string - a single-line text input
• textarea - a multi-line text input
• select - a drop-down option selector
• multiselect - a multiline option selector, in which more than one line can be selected
• radio - a list of checkboxes, only one of which can be selected at a time
• radio+other - a radio input that includes an "Other:" box that can be used to enter an option that was not offered.
• checkbox - a single checkbox
• checklist - a list of checkboxes, more than one can be selected at a time
• checklist+other - a checklist that includes an "Other:" box that can be used to enter an option that was not offered.
• password - a text input whose data will be masked when you type it
• hidden - an input field that is not displayed visibly in the form, and which cannot be modified. The value of this input can be set in the input responses field (below).
• label - this is not really an input. The question and input responses (which can contain arbitrary HTML) will be inserted into the form, but do not have any functional purpose. This can be used to add help text or other formatting in the form.
• Size - this sets the size of the input field. For text inputs, it is the number of characters wide. For textarea inputs, it is the number of characters that should be visible (the number of rows/lines is computed from this depending on the default width of a textarea input). For multiselects, it is the number of rows that should be shown at once.
• Input Responses - this sets the type of input values that will be accepted into this field. For selects, radios, and checklists, it is a list of values separated by the bar character "|", such as yes|no. For regular text inputs, it is an ExSite datatype that will define a regular expression the answer should match (eg. "email" or "url").

Form Layout and Templates

Forms will automatically be given a simple and versatile layout. If you need to customize this layout, you can create a custom form template as follows.

Your template is a block of HTML containing merge codes with the following format:

[[name:prompt]]
[[name:input]]

where name is the short reference name of the question. For example, if you are prompting for an email address, the short reference name of the field may be email, and you can use the following merge codes in the template:

[[email:prompt]]
[[email:input]]

Where ever you place [[email:input]] in your template, this will be replaced with the input field, such as . Where ever you place [[email:prompt]] in your template, this will be replaced with the question itself, such as Enter your email address:

You do not need to include the prompt merge code in the template. Instead, you could explicitly place the question text (or an image) into the template HTML, instead. If you do not include the input merge code in the template, the question will automatically be appended to the bottom of the template.

Some inputs consist of multiple related input fields; for example checklists and radio buttons have numerous inputs that are presented in a row. If you want to place these sub-inputs individually, they are numbered starting at 1, and you can place them individually using:

[[name:input:N]]

where N is the number of the sub-input. Note that this only places the sub-input, not any text that goes along with the sub-input.

Once you have your block of template HTML, save it to a content object somewhere in your website. (For instance, create a content object called registration_form_template and place this into a convenient content library.) Then type the name of this content object into the template field of the form configuration screen. ExSite will then attempt to find this named template and use it to format your form.

Automatic Layout

The default layout gives you a plain but legible layout that will suffice for basic tasks. You can switch a richer CSS-based layout with the following configuration setting:

template = 1

With this setting, you can enhance your form styles using the following CSS classes:

CSS class	description
div.QA_prompt	Wraps the question prompts/labels.
div.QA_input	Wraps the question input field.
div.QA_question	Wraps the prompt + input.
div.A, div.B	Wraps alternating questions.

The last CSS classes (div.A, div.B) are optional. You can enable alternate row highlighting using the following conf setting:

highlight_rows = 1

When possible, the system will try to enhance your form layout by grouping questions with similar inputs. For example, if you have three questions in a row with the same set of radio button answers, then instead of the default layout, which would be:

the system will reformat to present these questions as:

This helps to automatically group similar questions in surveys and other long forms, to keep things more organized. To take advantage of this feature, simply make sure that these questions are adjacent to each other in the form. If you have adjacent questions that you do not want grouped in this way, put a label or preformatted question in between them.

Form Security

In the form configuration, you have a few security options to control who may use the form.

members-only

If selected, you must be logged in to the website to use this form.

confirmation screen

If selected, the form does not actually get processed when you submit. Rather it echoes your inputs, and asks you to confirm them. This provides a helpful proof-reading check, and can also sometimes block the occasional robot that likes to fill out forms with random info to see what is behind them.

captcha

If selected, the user must solve a CAPTCHA to submit the form. This is a puzzle, typically requiring the user to correctly transcribe an image of distorted text.

robot counter-measures

If selected, the form will include a few additional tricks designed to prevent abuse by automated robots that like to fill out forms for illicit purposes. This can help to reduce spam or other automated abuses of your forms.

single-submission only

If selected, the form will not accept responses from members who have already submitted a response. The form must also be marked as members-only for this to work, otherwise this option will be ignored.

Reply Messages

By default, when a form is successfully submitted, the system will return a simple "Thank You". You can specify a custom reply message in the form configuration screen.

The custom reply message can include HTML mark-up, and also merge fields that will be replaced with appropriate data when displayed to the user. Merge fields are written like this: [[name]], where name is any of:

• short reference name of any field in the form - this will be replaced with the actual answer provided by the user in that field. For example: Thank you for your input, [[first_name]].
• _date - this will be replaced with the date and time the response was received.
• _summary - this will be replaced with the complete set of answers that the user provided, in a table format.

Customizing Response Handling

The default response handling of a form is:

1. save the response to the database
2. email the response to any email addresses listed in the "Notification Email To:" field of the form configuration
3. display the Acceptance Message to the user

Any additional action or follow-up is the responsibility of the persons receiving the notification email.

For simple data collection or survey-style forms, this is usually sufficient. The data is accumulated in the database for later analysis and reporting.

If you require special automated processing of the form data, there is a hook in the system for you to add your own code. Follow this procedure:

• make sure your form has a name
• in your myConfig.pm file, add a handler for QA_receipt
• in the same file, add your custom code in your handler routine

Example Custom Response Handler

# in myConfig.pm

sub my_handlers {
    my $this = shift;

    # install a handler for QA forms

    $this->handler("QA_receipt",\&my_qa_receipt);
}

sub my_qa_receipt {
    my ($this,$form,$response) = @_;

    # $form is a QA form object
    # $response is a QA response object

    # the return value from this routine is assumed to be an HTML
    # message that is displayed to the user
    my $output_message;

    # to take action on specific forms, you need to check the form name
    my $formname = $form->getdata("name");
    if ($formname eq "my_registration_form") {

        # fetch the response data as a hash of short reference name => answer

	my %response_data = $response->get_response_data();

	# ... perform any special functions that are needed based on 
	# the response data

    }

    # return any status messages to be displayed to the user
    return $output_message;
}