Please note: This tutorial was written in 2008 for version 3.16. There may be some slight differences in later versions of MySource Matrix.

A Custom Form can be used to collect different types of information from your users. Examples include a contact us form, feedback form, job application, customer surveys etc. A form consists of either questions or questions grouped into sections. For example, you may have a section called “Personal Details”, which has the questions “Name”, “Address” and “Date of Birth”. You may then have a question called “Additional Information” which may not be part of a section.

By default, when you preview the Custom Form, the section and questions that you have added will automatically appear. If the sections are in the wrong order or you wish to add additional information (for example: instructions on how to use the form) you can change the layout through the Page Contents Bodycopy.

After the user has answered the questions on the Custom Form, MySource Matrix can do several things with the results. The figure below shows what can happen after a user has clicked the Submit button on the Custom Form.

Create a form

To understand how to set up a Custom Form consider the following example. We want to create a contact us form for our web site with the following fields:

• First name – this will be a required text field.
• Last name – this will be a required text field.
• Address – this will be a text field.
• State – this will be a select field.
• Postcode – this will be a numeric field.
• Email address – this will be a required email field.
• Phone number – this will be a text field.
• Comments – this will be a text field.

When the user submits the form an email should be sent to the email address they entered, and an email should be sent to the recipient of the form. A CAPTCHA field should also appear on the form.

Adding a custom form

Add a Custom Form under the Site called “Contact us”. To do this, right click on the Site and to go New Child -> Pages -> Custom Form. Enter the name of the form into the text field and click Commit. The Custom Form will appear in the Asset Map on the left hand side of the window, as shown in the figure to the right.

Adding a section

Add a section under the “Contact us” form called “Personal Information”. To do this, right click on the Form Contents asset in the Asset Map and select Form Contents. Enter “Personal Information” into the Add Sections field and click Commit. A Section asset will appear in the Asset Map, as shown in the figure to the right.

Adding the questions

Add the first name, last name, address, state, postcode, email address and phone number questions to the “Personal Information” section. To do this, right click on the “Personal Information” section in the Asset Map and select Details.

Add three (3) questions of type text. To do this, in the Add Questions field select Text in the first list, 3 in the second list and click Commit. Three question assets will appear in the Asset Map and they will be added to the Current Questions list, as shown in the figure below.

Add a question of type select. To do this, in the Add Questions select Select in the first list, 1 in the second list and click Commit. A fourth Question asset will appear in the Asset Map and it will be added to the Current Questions list.

Repeat this process and add the remaining question to the section. Once you have done this, seven Question assets should appear in the Asset Map and be listed in the Current Questions section, as shown in the figure below.

The comments question needs to be added to the form. To do this, right click on the Form Contents asset in the Asset Map and select Form Contents. In the Add Questions field select Text in the first list, 1 in the second list and click Commit. A Question asset will appear in the Asset Map and it will be added to the Current Questions section, as shown in the figure below.

Questions

Now that each question has been added to the form, the Title for each question needs to be changed as well as their attributes.

First name

To set up the first name question, right click on the Question 1 asset under “Personal Information” section in the Asset Map and select Details. Change the following on the screen:

• Title: enter “First name”
• Maximum Length: enter 50. This means that the user can only enter 50 characters into this field.
• Required Entry: as this is a required question, select Required from the list.
• Custom Required Error: enter “Please enter your first name”. This will be shown on the form if the user has not entered a value for this field.

Once you have done this, click Commit. The name of the asset in the Asset Map will change to “First name”.

Last name

To set up the last name question, right click on the Question 2 asset under “Personal Information” section in the Asset Map and select Details. Change the following on the screen:

• Title: enter “Last name”
• Maximum Length: enter 50. This means that the user can only enter 50 characters into this field.
• Required Entry: as this is a required question, select Required from the list.
• Custom Required Error: enter “Please enter your last name”. This will be shown on the form if the user has not entered a value for this field.

Once you have done this, click Commit. The name of the asset in the Asset Map will change to “Last name”.

Address

To set up the address question, right click on the Question 3 asset under “Personal Information” section in the Asset Map and select Details. Change the following on the screen:

• Title: enter “Address”
• Height: enter 3. This will show a multi line box on the form.

Once you have done this, click Commit. The name of the asset in the Asset Map will change to “Address”.

State

To set up the state question, right click on the Question 4 asset under “Personal Information” section in the Asset Map and select Details. Change the following on the screen:

• Title: enter “State”
• Options: enter each of the following options in a new box: QLD, NSW, ACT, VIC, TAS, NT, SA and WA.

Once you have done this, click Commit. The name of the asset in the Asset Map will change to “State”.

Postcode

To set up the postcode question, right click on the Question 5 asset under “Personal Information” section in the Asset Map and select Details. Change the following on the screen:

• Title: enter “Postcode”
• Width: enter 4. This means that the length of the box on the form will be 4 characters long.
• Maximum Length: enter 4. This means that the user can only enter 4 characters into this field.

Once you have done this, click Commit. The name of the asset in the Asset Map will change to “Postcode”.

Email address

To set up the email address question, right click on the Question 6 asset under “Personal Information” section in the Asset Map and select Details. Change the following on the screen:

• Title: enter “Email address”
• Required Entry: as this is a required question, select Required from the list.
• Custom Required Error: enter “Please enter your email address”. This will be shown on the form if the user has not entered a value for this field.

Once you have done this, click Commit. The name of the asset in the Asset Map will change to “Email address”.

Phone number

To set up the phone number question, right click on the Question 7 asset under “Personal Information” section in the Asset Map and select Details. Change the following on the screen:

• Title: enter “Phone number”
• Width: enter 10. This means that the length of the box on the form will be 10 characters long.
• Maximum Length: enter 10. This means that the user can only enter 10 characters into this field.

Once you have done this, click Commit. The name of the asset in the Asset Map will change to “Phone number”.

Comments

To set up the comments question, right click on the Question 1 asset under the Form Contents asset in the Asset Map and select Details. Change the following on the screen:

• Title: enter “Comments”
• Height: enter 3. This will show a multi line box on the form.

Once you have done this, click Commit. The name of the asset in the Asset Map will change to “Comments”.

Layout

Page Contents Layout

A default layout has already been created for the “Contact us” form, as shown in the figure below.

As you can see, the comments question appears at the top of the form and there is no heading for the page. We need to change this layout so that the comments question is at the bottom of the page and there is a heading as well as a design.

To select a design, right click on “Contact us” form and select Settings. Under the heading System Defined Frontend Design click Change button next to “New?”. The Asset Map should turn purple in colour. Select a design (right click Use Me) from in your Designs Folder.

To change the layout, add the Page Contents Bodycopy. To do this, right click on the Form Contents asset and select Form Contents. In the Use Bodycopy field, select Page Contents and click Commit.

A Bodycopies Folder will appear in the Asset Map which contains the Page Contents Bodycopy.

Right click on the Page Contents Bodycopy and select Edit Contents. This content shown in the figure below is entered into the WYSIWYG Editor.

The List of Submission errors is added to the top of the form so that when a user receives an error, they will see them. The Submit Button is also added so that the user can submit the form. The new layout of the “Contact us” is shown below.

Thank You Layout

A default layout has already been created for the “Contact us” form to show when the user submits the form, as shown in the figure below.

As you can see, the comments response appears at the top of the page and there is no heading saying thanks. We need to change this layout so that the comments question is at the bottom of the page and there is a Thank You message.

To change this layout, add the Thank You Bodycopy. To do this, right click on the Form Contents asset and select Form Contents. In the Use Bodycopy field, select Thank You and click Commit. The Thank You Bodycopy will be added to the Bodycopies Folder, just like the Page Contents Layout. 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 new thank you layout of the “Contact us” is shown below.

Validation

Adding the CAPTCHA Fields

To add the CAPTCHA field to the “Contact us” form, right click on the Form Contents asset in the Asset Map and select Form Contents. Changing the following fields:

• Require CAPTCHA: select Yes
• CAPTCHA Key Length: enter 6. This means that the length of the box on the form will be 10 characters long.
• CAPTCHA Character Zoom: enter 3. This means that the characters in the image will be randomly zoomed between 1 and 3.

Once you have done this, click Commit.

Add the CAPTCHA keyword replacement onto the Page Contents Bodycopy. To do this, right click on the Page Contents Bodycopy in the Asset Map and select Edit Contents. Just before the Submit Button keyword replacement in the WYSIWYG Editor, add the CAPTCHA keyword replacement, as shown below.

The CAPTCHA field will now appear on the form, as shown below.

Email

Recipient Email

The recipient emails needs to be set up so that an email is sent to a contact. To do this, right click on the Form Contents asset in the Asset Map and select Email Options. In the Recipient Email Options section, fill out the following fields:

• To: enter the email address to send the email, yours will do.
• From: enter a from email address. You can use a keyword replacement from a question on the form, for example %response_199520_q6%. This will put the email address that the user enters on the form in this form.
• Subject: enter a subject for the email, for example “Contact form submission”.
• Body: the content in the figure below is added to the HTML version of the 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 Keywords Replacements section on the screen. Now when a user submits the form, an email will be sent to the contact.

Receipt Email

The receipt emails needs to be set up to send an email to the user who submitted the form. To do this, right click on the Form Contents asset in the Asset Map and select Email Options. In the Receipt Email Options section, fill out the following fields:

• Receipt Recipient Question: select the “Email address” question in this field. To do this, click the Change button – the Asset Map will turn purple. Right click on “Email address” Question asset and select Use me. The Name and Asset ID of this asset will appear in this field. This replaces the From address field.
• From: enter a from email address, yours will do.
• Subject: enter a subject for the email, for example “Thank you for contacting us”.
• Body: the content in the figure below is added to the HTML version of the 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 Keywords Replacements section on the screen. Now when a user submits the form, an email will be sent to the address they enter in the form.

Final Steps

The “Contact us” form is now set up. Before making is Live to the public you should check the following things:

• The layout of the page contents is correct
• The required questions 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 page is correct
• The recipient email is sent to the correct contact
• The receipt email is sent to the user who filled out the form
• The submission is logged to the database

Once you have checked these things and you are happy with the way the form works, change the Status of the Custom Form to Live and grant Public Read Permissions.