Tutorial: Custom Form Basics

Posted on 23 Jan 2010 5:30am by Aleks Bochniak

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.

Diagram of what happens after submit

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

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

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

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.

Three questions

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.

Seven questions

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.

A question asset

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.

Page contents layout

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.

Page contents Bodycopy

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.

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.

Form with design applied

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.

Default thank you page layout

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.

New layout for thank you page

The new thank you layout of the “Contact us” is shown below.

New design for thank you page

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.

Add the CAPTCHA keyword replacement

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

The CAPTCHA field on the front end

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 Email content

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:

Selecting the email address
  • 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 thank you Email content

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.

Comments

There are 2 comment(s) so far... say something?


30 Mar 2011 3:51am

Hi,
Thanks for this overview.
I have a very specific question about using the keyword replacement in emails.
One of my questions in my form asks the user to upload an image.
The keyword replacement works, but gives me several things lumped together, separated by commas: filename, mime type, filesize

I would like to separate these bits of data so they can be easily carried into other systems... For example the filename itself.

Is there a more detailed keyword replacement to get at these deeper attributes of this ?


26 Sep 2012 7:14am

There are certainly a lot of detials like that to take into consideration. That is a great point to bring up. I offer the thoughts above as general inspiration but clearly there are questions like the one you bring up where the most important thing will be working in honest good faith. I don?t know if best practices have emerged around things like that, but I am sure that your job is clearly identified as a fair game. Both boys and girls feel the impact of just a moment's pleasure, for the rest of their lives.

Leave a comment

Name (required)

Email (required)

Website

Your comment

Security key
Enter the above security word

I am human