Example: Creating a "Contact us" custom form

The following example will create a Contact us custom form page on our web site. This form will contain a security CAPTCHA field. It will automatically send an email to both the user who completed the form and the site administrator.

Setting up the custom form

The *Personal information* section

  1. Add a custom form under your site, titled Contact us.

  2. Right-click on the custom form’s Form contents asset in the asset tree and select the Form contents screen.

  3. On the Form contents screen, create a new section on the form, titled personal information:

    1. Enter Personal information in the Add sections field.

    2. Click Save.

A new section asset will appear in the asset tree, as shown in the figure above.

Adding the form fields

The question assets

  1. Right-click on the Personal information section asset in the asset tree.

  2. Select the Details screen.

  3. In the Add form fields field, select the Text question type in the first list.

  4. Select 3 in the second list to add a total of three test type form fields.

  5. Click Save.

Three question assets will appear in the asset tree and be added to the current form fields list, as shown in the figures.

+ image::4-0-0_current-questions-list.png[The form fields added to the current form fields list]

Add a Select type question to the form:

  1. In the Add form fields field, select the Select question type in the first list.

  2. Select 1 in the second list.

  3. Click Save.

    A fourth question asset will appear in the asset tree and be added to the current form fields list.
    Repeat these steps to add three more form fields:

    • Two Numeric type form fields

    • One Email address type form field.

      Seven question assets now appear in the asset tree and are listed in the current form fields list:

      The form fields for the form in the current form fields list
      The unattached question asset

Add another question to the form outside of the Personal information section:

  1. Right-click on the Form contents asset in the asset tree and select the Form contents screen.

  2. In the Add form fields field, select Text in the first list.

  3. Select 1 in the second list.

  4. Click Save.

    A question asset will appear in the asset tree and be added to the current form fields section.

The unattached question in the current form fields list

Setting up each question

First name question

To set up the First name question:

  1. Right-click on the Question 1 (text type) asset under the Personal information section of the asset tree.

  2. Select the Details screen.

  3. In the Title field, enter First name.

  4. In the Maximum length field, enter 50.
    This setting will mean that users can only enter up to fifty characters in this field.

  5. In the Required entry field, select Required.
    This setting will mean that users will be required to answer this question on the form.

  6. In the Custom required error field, enter Please enter your first name.
    This text will be displayed on the form if the user does not answer this question.

  7. Click Save.

The name of the asset in the asset tree will change to First name.

Surname question

To set up the Surname question:

  1. Right-click on the Question 2 (text type) asset under the Personal information section of the asset tree.

  2. Select the Details screen.

  3. In the Title field, enter Surname.

  4. In the Maximum length field, enter 50.
    This setting will mean that users can only enter up to fifty characters in this field.

  5. In the Required entry field, select Required.
    This setting will mean that users will be required to answer this question on the form.

  6. In the Custom required error field, type Please enter your surname.
    This text will be displayed on the form if the user does not answer this question.

  7. Click Save.

The name of the asset in the asset tree will change to Surname.

Address question

To set up the Address question:

  1. Right-click on the Question 3 (text type) asset under the Personal information section of the asset tree.

  2. Select the Details screen.

  3. In the Title field, enter Address.

  4. In the Height field, enter 3.
    This setting will display a multi-line text field on the form for this question.

  5. Click Save.

The name of the asset in the asset tree will change to Address.

State question

The *Options* field for the state question

To set up the State question:

  1. Right-click on the Question 4 (Select type) asset under the Personal information section of the asset tree.

  2. Select the Details screen.

  3. In the Title field, enter State.

  4. In the Options field, enter the following options into the fields provided: QLD, NSW, ACT, VIC, TAS, NT, SA, and WA.

  5. Click Save.

The name of the asset in the asset tree will change to State.

Postcode question

To set up the Postcode question:

  1. Right-click on the Question 5 (numeric type) asset under the Personal information section of the asset tree.

  2. Select the Details screen.

  3. In the Title field, enter Postcode.

  4. In the Width field, enter 4.
    This setting will mean that the question field will be four characters wide.

  5. In the Maximum length field, enter 4.
    This setting will mean that users can only enter up to four characters in this field.

  6. Click Save.

The name of the asset in the asset tree will change to Postcode.

Email address question

To set up the Email address question:

  1. Right-click on the Question 6 (email address type) asset under the Personal information section of the asset tree.

  2. Select the Details screen.

  3. In the Title field, enter Email address.

  4. In the Required entry field, select Required.
    This setting will mean that users will be required to answer this question on the form.

  5. In the Custom required error field, enter Please enter your email address.
    This text will be displayed on the form if the user does not answer this question.

  6. Click Save.

The name of the asset in the asset tree will change to Email address.

Phone number question

To set up the Phone number question:

  1. Right-click on the Question 7 (numeric type) asset under the Personal information section of the asset tree.

  2. Select the Details screen.

  3. In the Title field, enter Phone number.

  4. In the Width field, enter 10.
    This setting will mean that the question field will be ten characters wide.

  5. In the Maximum length field, enter 10.
    This setting will mean that users can only enter up to ten characters in this field.

  6. Click Save.

The name of the asset in the asset tree will change to Phone number.

Comments question

To set up the Comments question:

  1. Right-click on the Question 1 (text type) asset under the Form contents asset in the asset tree.

  2. Select the Details screen.

  3. In the Title field, enter Comments.

  4. In the Height field, enter 3.
    This setting will display a multi-line text field on the form for this question.

  5. Click Save.

The name of the asset in the asset tree will change to Comments.

Defining the layout of the custom form

Page contents layout

The default layout of the Contact us form is shown in the figure below.

The default layout of the contact us form

The comments question in this layout appears at the top of the form. There is no heading for the page. We need to change this layout to move the comments question to the bottom of the page, add a heading, and include additional features.

The page contents bodycopy

To change this layout you need to add the page contents bodycopy:

  1. Right-click on the Form contents asset.

  2. Select the Form contents screen.

  3. In the Use bodycopy field, select Page contents.

  4. Click Save.
    A bodycopies folder will appear in the asset tree, containing the page contents bodycopy.

  5. Right-click on the page contents bodycopy and select edit contents.

  6. Enter the following content into the WYSIWYG editor.

    The WYSIWYG editor on the page contents bodycopy

The List of submission errors keyword replacement is added to the top of the form to display errors when the form is not completed correctly. The Submit button is also added so that the user can submit the form.

The new layout of the contact us is shown in the figure below.

The new layout of the contact us form

Thank you layout

The default layout of the Thank you page on the Contact us form is shown in the figure below. This layout is shown when the user submits the form.

The default layout of the thank you page

The comments response in this layout appears at the top of the form. There is no heading for the page. We need to change this layout to move the comments question to the bottom of the page, add a heading, and include additional features.

The thank you bodycopy

To change this layout you need to add the "Thank you" bodycopy:

  1. Right-click on the Form contents asset.

  2. Select the Form contents screen.

  3. In the use bodycopy field, select Thank you.

  4. Click Save.
    The thank you bodycopy will be added to the bodycopies folder, as shown in the figure to the right.

  5. Right-click on the Thank you bodycopy and select edit contents.

The content shown in the figure below is entered into the WYSIWYG editor.

The WYSIWYG editor on the thank you bodycopy

The new layout of the Contact us page is shown in the figure below.

LAThe new layout of the thank you pageBEL

Adding the CAPTCHA fields

To add the CAPTCHA field to the contact us form:

  1. Right-click on the Form contents asset in the asset tree.

  2. Select the Form contents screen.

  3. In the Require CAPTCHA field, select Yes.

  4. In the CAPTCHA key length field, enter 6.

This setting will mean that the CAPTCHA image will display six characters.

  1. In the CAPTCHA character zoom field, enter 3.
    This setting will mean that the CAPTCHA characters will be randomly zoomed between sizes 1 and 3.

  2. Click Save.

  3. Add the CAPTCHA keyword replacement on the page contents bodycopy, as shown in the figure below.

    The CAPTCHA keyword replacement

    The CAPTCHA field will now appear on the contact us form.

    The CAPTCHA field on the contact us form

Setting up the emails

Recipient email

The recipient email needs to be set up so that an email is sent to the site administrator.

To do this, follow these steps:

  1. Right-click on the Form contents asset in the asset tree.

  2. Select Email options.

  3. Navigate to the Recipient email options section of the screen.

  4. In the To field, enter the email address of the site administrator, for example, admin@example.com.

  5. In the From field, enter the 'from' email address.
    You can use the email address form field keyword replacement in this field (for example, %response_100_q6%). This replacement will use the email address that the user enters on the form.

  6. In the Subject field, enter a subject for the email, for example `%response_100_q1% %response_100_q2%` has contacted Squiz.

  7. In this example, we are using the user’s responses to the first name and surname form fields in the Subject of the recipient email.

  8. In the body field, the content shown in the figure below is added to the email’s HTML version.

The body content of the recipient email

The keyword replacements for each question can be found by clicking on the List of keywords available for use in emails hyperlink under the Keyword replacements section on the screen.

Receipt email

The receipt email needs to be set up so that an email is sent to the form user.

To do this, follow these steps:

  1. Right-click on the Form contents asset in the asset tree and select email options.

  2. Navigate to the Receipt email options section of the screen.

  3. In the Receipt recipient question field, select the Email address question.
    This option will send an email to the address that the user enters on the form.

  4. In the From field, enter the 'from' email address, for example, admin@example.com.

  5. In the Subject field, enter a subject for the email; for example: Thank you for contacting Squiz.

  6. In the Body field, the content shown in the figure below is added to the email’s HTML version.

The body content of the receipt email

The keyword replacements for each question can be found by clicking on the list of keywords available for Use in emails hyperlink under the keyword replacements section on the screen.

Final steps

Before making the Contact us form live to the public, check the following:

  • The layout of the page contents is correct.

  • The required form fields are validated, and the error messages appear on the form.

  • That you can fill out and submit the form.

  • The layout of the thank you layout is correct.

  • The recipient email is sent to the contact within the organization.

  • The receipt email is sent to the user who filled out the form.

  • The submission is logged to the database.

Once you are sure the custom form is working correctly, change its status to live and grant public read permission.

© 2015- Squiz Pty Ltd