Version 4 > Forms

Forms

The 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.

Making a new form

There are two ways to create a new form:

  1. copy an existing form (you can modify it later)
  2. start from scratch, by clicking the "+ new form" button

If starting from scratch, you will be asked to define:

  • The form title
  • The form permissions - who is allowed to use the form
  • The location of the form in your site. Select from one of the suggested locations, or enter the specific content ID of the form's parent content.

You can edit these settings later, using the configure tool.

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.
  • export - download all of the responses as a spreadsheet.
  • preview - view the form as it will be shown to users. You can actually fill out and submit the form from this pane.
  • configure - change the form setup parameters.
  • layout - create or revise a custom form layout.
  • questions - modify individual questions
  • +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.

Configure the form behaviour

Use the configure tool to configure the form behaviour. The form-specific configuration parameters are:

  • Email responses to - a copy of the form response will be emailed to this address every time the form is submitted.
  • Multipart form condition - see Multipart forms
  • Cross-post to - If you enter a Content ID here, the form response will also post itself to that content object. A value of -1 will cross-post to the parent object.
  • Submission status - sets the default/starting status of the response.
  • Submit button text - customize the submit button.
  • Title - include the form title as a heading, when displaying the form.
  • Captcha, Robot counter-measures - see Form Security.
  • Spam counter-measures - see Form Security.
  • Prepopulate with user data - if the user is logged in, we might be able to prefill the form with name, contact information, or other fields. The fields must be named using recognized names like first_name, last_name, or email.
  • Confirmation screen - the form will display a summary of the answers provided, which the user must confirm before it is actually submitted.
  • Simple buttons - replaces the submit, cancel, and reset buttons with a single submit button, for a cleaner look.
  • Block double-clicks - removes the submit button after it has been clicked, so that users won't click it (and resubmit) more than once.
  • Multipart form - see Multipart forms
  • Order form - if this form has a price associated with it, then filling out the order form will automatically add a purchase to the shopping cart.

Add questions to the form

There are two ways to add new questions to the form:

  1. Copy a similar question from another form. This is fast, accurate (fewer typos), and automatically makes use of existing translations.
  2. Create a new question from scratch.

When creating questions from scratch, the configuration options will automatically change to those that are appropriate for the question format you selected.

Question formats are explained below.

Re-order Questions

To change the order of questions, click the order button. Drag the questions into their new order, then click the save order button.

Note that if you have a custom form layout, the presentation of the questions is fixed by that layout. Re-ordering the questions will not change how the form appears. It will still change the order in which questions are shown in reports and exported data.

Similarly, if you use a custom layout, you can reposition questions in the layout without altering the question order.

Form Security

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

The access level determines who may submit responses to this form. Anyone of the selected access level or higher may post responses. Individual questions can also specify their own access levels; underprivileged users simply do not see those questions.

There are a few flags you can make use of to limit form abuse by users or robots:

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.
spam counter-measures
Spam posts can arrive even with captchas or robot counter-measures; this flag will help to filter some of the more annoying types of spam submissions. It will filter any text input that appears to contain raw HTML markup or links/URLs. If you have set deny_unicode_block in your Forms.conf file, it will also detect text inputs that have arrived with too many characters in those prohibited code blocks. This allows you to filter responses that come in other languages that you are not equipped to deal with, such as Russian or Chinese. Lastly, it will check the age difference between when the form was published and when the response was received; if too much time has elapsed, it will not accept the post.
single-submission only
If selected, the form will not accept responses from users who have already submitted a response. The form's access level cannot be public for this to work, otherwise this option will be ignored.

Additionally, you can disable a form by changing its status from published to some other setting, for example:

  • archived - leave the form up, but disallow responses
  • draft - resume editing the form, disallowing responses while you do so
  • canceled - disable the form entirely, removing it from public view

Replies

By default, when a form submission is received, the system will return a simple "Thank You". You can specify a custom reply message by clicking the reply button 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.

If you would like to receive a copy of all responses submitted to a form, enter the email address to send to in the form configuration screen.

Manage the questions on the form

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

  • Click the question name to reconfigure the question itself.
  • Click the + add question link to add a new question to the form.

Configure question

When you click into a question, you have options to preview, configure, or delete that question, as well as customize the layout.

If you delete a question, you also delete all answers that have been given to that question by any previous respondents.

Questions have many configuration settings:

  • Full question - this is what gets displayed to the user when they view the form.
  • Brief question - this is used in reports and other places where the full question might be too verbose.
  • Question name - this is used in form HTML encoding and layouts. The name should be unique (in this form), and should contain no spaces or punctuation characters.
  • Access level - who can see this question.
  • Format - the type of answer this question has.
  • Datatype - forces answers to conform to certain patterns.
  • Options - multiple-choice questions can list the allowed answers here. Separate each answer by the bar character, "|". Do not add spaces or carriage-returns around the bar character, as those will be considered to be part of the answer.
  • Default/preset - the question will be pre-filled with this value.
  • Placeholder hint - the question field will contain this suggestion, which can be used to suggest formatting or other expectations.
  • Size - the actual width of the input field.
  • Maximum length - the character limit of the input field.
  • Min, Max, Step - for numeric fields, this controls the range and intervals of the settings.
  • Required - the form will not submit until this question is answered.
  • Pre-checked - (for checkboxes only) the box will be checked by default.

Question Formats

FormatExampleNotes
short text  
long text  
select  
multiselect use click-drag, shift-click, and ctrl-click to select more than one option
radio choice 1
choice 2
 
radio+other choice 1
choice 2
other: 
 
checkbox yes  
checklist choice 1
choice 2
choice 3
 
checklist+other choice 1
choice 2
choice 3
other: 
 
password  
hidden   Input is invisible, but is included with the form post.
label, preformatted Any text or instructions you want to include in the middle of the form, but which does not actually ask for input. Simple way to include instructions, headings, or section breaks in mid-form.
file  
number limited browser support
range limited browser support
date limited browser support
time limited browser support
url limited browser support
email limited browser support


Customizing Layout of Individual Questions

By default, individual questions are presented like this:

question
input

For example:

Last Name

 

For checkboxes, the layout is input question, for example:

 I agree to the terms

 

If these defaults are sufficient, there is nothing more you need to do. But if this is inadequate, you can customize the question layout.

To make a custom question layout, use the question layout tool (not the form layout tool!) to update the question, and this new revision will be used as the question layout. You can place the question and input field in your layout using the tags [ [prompt] ] and [ [input] ].

If you leave [ [input] ] out, it will automatically be appended to the end of your question layout.

Custom question layouts are useful in the following cases:

  • You require special HTML formatting or layout in your question text.
  • You require the question and input tags to be placed in non-standard locations compared to other questions.
  • Your question text is longer than 255 characters.

Example (specialized placement of input field):

By submitting this form, I, [ [input] ], agree to the terms and conditions.

 

This will appear like (using a placeholder hint):

By submitting this form, I, , agree to the terms and conditions.

Long questions

The question itself (Full question, as displayed to the user) is normally limited to 255 characters. If you have a lengthly question that requires more characters than this, use the following procedure:

  1. Use the question layout feature to build a longer question. It can even include other HTML markup, such as tables, links, and images.
  2. Do not include the [ [prompt] ] code in your question layout; just type your full question as you would like it to appear.
  3. The regular question field (Full question, as displayed to the user) will not be used to display the question in this case. You can shorten it to be the same as the Brief form of question, used in reports.

Manage the responses received to a form

Responses can be viewed and exported using the responses tool. You can also use the stats tool to get an overview of the responses, with charts.

Note that you can submit responses to the form directly from the preview screen. When you post to the form, it will take you to the form's page on the live site.

Response status

If responses require more complex processing or workflows, you can use the response status code to manage that. Every response can be given a status code, which determines where the response is at in its processing. Response status codes are:

  • Completed - the processing of the response is complete
  • Archived - the response is no longer relevant, and can be excluded from reports
  • Pass - the response received a passing grade
  • Accepted - the response has been accepted for official processing
  • Submitted - the response has been submitted for official processing
  • Draft - the response is incomplete, and should not be considered yet
  • Returned - the response was not accepted for official processing, and can be revised
  • Fail - the response received a failing grade
  • Rejected - the response was rejected as inadequate or junk

Archived and rejected responses are considered inactive and will be excluded from stats reports. All other response status codes are considered active.

Response status codes are optional. By default, responses do not have a status code, and are functionally equivalent to "completed". Responses with no status code are still considered active.

To enable status code processing, configure your form and set the Submission Status. All new responses will be set to this status to begin with.

To manually process responses to change their status, use the configure tool in the response options.

The response status is included in the response reports. Use the filter tools to select only responses of a certain status. By default all responses are selected.

View all responses

Responses can be viewed using the responses button 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. Received - the date and time that the response was received
  4. From - the user who submitted the response, if known
  5. Language - the language used by the submitter
  6. Status - the status of the response
  7. ...all questions on the form are shown in the remaining columns

This information can be exported in various formats using the links in the footer.

Use the search tool to look for a certain text string in the data. (Note that exports will include all data, not just the ones that match your search. To export filtered data, use the filter options.)

Report Filters

Click on the Report Filters bar to get options for filtering the responses report. You can select:

  • Particular response status codes, or all active or inactive responses.
  • Start and end dates to select responses from a certain time period.
  • Select the include checkboxes to include those questions in the report. De-select them to remove those questions from the report. You can also include certain response metadata like date, language, status, and username.
  • You can provide answers to any questions; only reponses with matching answers will be selected. You can provide answer fragments here, and they are not case-sensitive.

After performing a filtered search, you can adjust your report filters, or you can export the selected set of answers.

Summary of responses

To get a simple overview of all responses received, use the stats button.

Each question is summarized, including the total number of answers received, and a % of all responses that answered that question. These statistics are summarized in a simple bar chart.

For multiple-choice answers, each answer option will be shown separately, with a count and % of responses that selected this answer. If the answers are numeric, it will also compute an average.

The stats can be exported in different formats:

  • excel: standard spreadsheet format
  • csv: portable data format
  • html: handy for cut and paste into another document
  • executive summary: an attractively-formatted overview of your responses

Response Workflow

In some applications, you may need to do extra administration/processing on responses before they are considered completed. For example, consider a support request form; you might need to track whether the request has been assigned to a customer support rep, and whether the issue has been resolved.

You have two tools at your disposal for this work:

  1. administrator fields - set special questions to executive or higher access, and regular end-users will not see those questions. Admins who review or edit those responses will see the questions, however, and can use them to add notes, or log additional information about the request.
  2. response status - every response can be marked with a status (eg. submitted, accepted, archived, completed, etc.) to help you track where it is in the processing workflow. The form configuration allows you to set the initial status of new responses, and you can use the configure tool on individual responses to change the status.

Both of these workflow tracking tools can be used to filter responses in reports to help you identify the responses that require attention.

Note that summary/stats reports (including the executive summary) will exclude responses whose status has been set to archived or rejected. Use archived to indicate that a response has been dealt with satisfactorily and should no longer be included in those summaries. Use rejected to exclude junk or spam responses.

Advanced form management

Special Form Layouts

Forms will automatically be given a simple and versatile layout. If you need to customize this layout, you can create a custom form layout. Your form layout is a block of HTML containing merge codes that determine where your questions will be placed.

For experts only! Custom layouts override your question ordering, and increase the amount of work you need to do when adding or removing your questions, since the layout also has to be modified to support your new question list. Only make use of this feature if this extra work is worth the effort. For similar reasons, it is best to setup your layout after your questions are settled and stable.

You can place whole questions using the question name. For example if you have a question whose short name is email, you can place it into your form layout using [ [email] ]. The entire question and input field will be substituted into that position. If you need to be more specific than that, use [ [email:prompt] ] or [ [email:input] ] to substitute just the question or just the input field.

If you neglect to include all question inputs, the missing ones will automatically be appended to the end of your form layout. If you neglect to include all prompts, the missing ones will be ignored.

The forms subsystem automatically generates useful form layouts, so that you don't have to. You can access these automatic layouts in the accordion panes below the layout editor. Copy-and-paste these (or sections of these) into the layout editor, and then modify to suit your needs.

Preambles

Some forms, such as assessment quizzes and customer surveys, require lengthly preambles to explain the process of using the form or other things the respondent may need to know before filling out the form. The preamble can simply be put at the top of the layout, as free-form text.

If you do not require any special layout of the actual form inputs, then do not include any of the merge codes in the layout. Only type in your preamble. Since any missing form elements are automatically appended, your form should appear right after the preamble with no extra work.

Matrix Layouts

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

Question A:
yes
no
maybe

Question B:
yes
no
maybe

 

You will instead get a matrix of radio buttons:

 yesnomaybe
Question A
Question B

 

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, you can configure questions to not group themselves by checking off "do not group" in the question's configuration settings.

Customizing Matrix Layouts

Radio buttons and checklists consist of a number of sub-inputs. 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.

The sample layouts at the bottom of the layout page include a layout with matrixes that replicates the default matrix layout. You can copy/paste this to modify it.

Multipart forms

Complex forms can be broken into multiple parts that are filled out and submitted separately. To make use of this feature, do the following:

  1. build each part as a separate form
  2. the second, third, etc. parts are given a location underneath the initial part
  3. check off the "multipart form" configuration option on each part

After doing this, the user will be automatically directed to the next part after filling out each part in turn.

When you view a response from a multipart form, it will also display related responses from other parts of the form.

Conditional Parts

If a sub-part should only be shown conditionally depending on an answer given in the previous form, you can set the "multipart condition" configuration setting:

  • question=answer to show this part if a certain answer was provided to a question
  • question!=answer to show this part if a certain answer was NOT provided to a question
  • question=~text to show this part if the answer to a question contains a text string
  • question
  • question>value to show this part if the answer to a question was greater than a value

In these examples, question is the name of the question that the condition triggers on. For example, a condition like province=BC will select a form part if the preceding form part had a question named province and the user answered BC. If the condition does not match, that sub-part will be skipped, and the user will jump to the next form in the sequence.

Translated forms

Forms can be built in multiple languages in such a way that you can automatically switch languages when viewing a form, and multiple-choice answers can automatically be translated back to English for easier data analysis of responses (for instance 'yes' and 'oui' will be treated as the same answer). To create a translated form:

  1. Create the original English form first.
  2. Create a new form to serve as the translation. Configure the new form, and under the "Relations" pane, set the language of your translation, and the original (the ID of your English form).

Translated forms will appear in your form listing right below the original English form. Responses received to translated forms are kept under the original English form, so that all your data is kept together in one place for easier data analysis. Multiple choice answers are automatically translated back to English for better statistics and filtering. If you do need to know who responded in other languages, the language of the response is also shown in the response reports.

The way translated content works is that the CMS looks at the original to see what content should appear. It then looks at the translation to see what translations of that content exist. If a translation exists, it is used in place of the original; if not, the original is used as a fall-back. This means that your translated form will automatically make use of the original English questions to begin.

You now have to translate each of your questions in a similar way. There is a fast way to do this: when you preview the form, the CMS will detect that the translations are incomplete and display warnings. It will give you a button to fix the warnings, which clones all of the English questions and puts them into your translated form so that you can edit them.

Once your questions are in place, you can visit them individually to translate them. You will need to translate:

  • the question title and label (but NOT the name; the name must remain the same as the original)
  • the answer options for multiple choice questions (radios and checklists); keep the same order of your options so they can be correctly related to each other. You must keep the same options in the same order.
  • the layout, if any

Special Types of Forms

Registration Forms

Any form named "form" and placed in a registration fee will automatically be used as the registration form for that fee. A form can also be placed in the event, and it will be shared by all fees in that event. The Registration module has a forms tool that will take care of setting this up for you. It is good practice to include fields named first_name, last_name, and email (and optionally, organization) to make it easier to identify the registrant. It is usually not necessary to collect detailed contact information (eg. address, phone number), because that is collected on the billing screen at checkout anyway, which is sufficient for most events. 

Membership Application Forms

Any formed named "application_form" and placed in a membership_type will automatically be used as the application form for that type of membership, and any membership types within it. The Membership module has a forms tool that will take care of setting this up for you. The membership system will try to create a profile and user from information provided on the form, so name your questions appropriately. Question names like the following will be recognized and used: first_name, last_name, organization, login, address, city, provstate, country, pcode, phone, email. Additionally, any question that matches the name of any profile setting will be used for that setting.

Order Forms

Turn your form into an e-commerce order form by checking off the order form option in the form configuration. This will enable the pricing tool that lets you set a price (or different pricing levels depending on the user's access level or the date) to purchase whatever the order form is selling.

When the user fills out the order form, an item will be added to their shopping cart, which they can then checkout and pay for. The item description will be either the price description, or the order form's title, and the item details will include all non-blank answers in the order form.

To get taxes, shipping, or other surcharges, set the price accounting codes appropriately.

Ballots

If you are holding a special election or ballot, you want to make sure that people only vote once. Select the option "single submission only" in the form configuration. This only works on restricted-access forms. Set the form access to user level or higher. That means that people need to log in before they can vote, which is how we validate their identity.

Note that people can actually vote as many times as they like, but each vote will replace their previous vote, so that only a single vote is recorded for any one UID. That makes it easy for people to revise their choices if they change their mind.

The stats or executive summary can be used to report election results without revealing individual voter choices.

Quizzes and Tests

You can build quizzes and tests using a special extension to the Forms module, the Quiz module. It allows you to setup forms with answer keys, time limits, and automatic marking. Consult the help documentation in that module for details.