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:

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 templates (model questions). 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 model questions you want in the form, from those that you have available.

General Procedure

  1. First you must create a library of re-useable questions that you can build forms from.
  2. Next, you can create a form, and fill it with questions from your library.
  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.

Additional information is available on:

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:
  3. Start adding questions to the form.

[top] [TOC]

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 5 collapsible panes (click to expand/collapse):

[top] [TOC]

Review/export the responses

Reponses can be viewed using the 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 summary button to see an overview of all responses, charts showing the proportion of respondents who provided different answers.

[top] [TOC]

Manage the questions on the form

From the general form overview, you can see a table summarizing the questions on the form. From here you can:

[top] [TOC]

Configure question

NOTE: 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 libraries.

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:

[top] [TOC]

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.

[top] [TOC]

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.

[top] [TOC]

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.

[top] [TOC]

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:

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

[top] [TOC]

Manage your model questions

The questions in a 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.

[top] [TOC]

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 forms, this may damage the forms or responses.

[top] [TOC]

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.

[top] [TOC]

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.

[top] [TOC]

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:

[top] [TOC]

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 field. 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 <input ...>. 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.

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.

[top] [TOC]

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.

[top] [TOC]

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:

[top] [TOC]

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:

[top] [TOC]

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;
}