Squiz Matrix Custom Forms - The Definitive Guide
Squiz Matrix Custom Forms are one of the most useful features of the Matrix CMS platform.
If you’re a user of Squiz Matrix, Custom Forms are one of the features you’re going to want to take advantage of if you’re looking to build anything from a simple contact form all the way up to a dynamic multi-page survey.
In this guide we’ll provide you with the insider’s definitive guide to using Custom Forms. From basic tips and tricks to advanced implementation techniques, get ready to start utilising the full potential of Matrix Custom Forms.
Should I nest or build a stand-alone Custom Form?
One of the age-old questions when implementing Custom Forms in Matrix, is whether it’s best practice to nest your Custom Form inside a Standard Page, or build a stand-alone form? In 99% of all cases, the later is the best choice. And here are the reasons why:
- If you’re nesting a Custom Form within another element it may be prone to caching resulting in unexpected behaviour
- By implementing a stand-alone Custom Form, you'll have more control over the look and feel of your form using Design Customisations and Paint Layouts
If for some reason you do need to nest your Custom Form, there are measures you can take to limit caching issues. This includes:
- Using the Cache Manager to periodically clear caching on your nested form
- Using the Cache Manager to always clear cache on your nested form asset
Personally we're not fans of the second option although it does work. With a little bit of design ingenuity, Custom Forms always work better when built as stand-alone elements. So try and keep this in mind when setting up your next form.
Working with Questions and Sections
If you’re implementing a Custom Form in Matrix, you’re going to need to add some fields to your form for your users to complete. This is done using the Questions and Sections areas of the Form Contents screen.
For those of you who have built online services before it will make sense to use both simultaneously, firstly creating a Section, then adding questions to that section. This practice is something we recommend, even if you’re going to implement a custom Body Copy (discussed later) as it can help you to quickly identify the intended order and grouping of elements in your form.
At the time of writing this article, you can configure the following form fields in Squiz Matrix Custom Forms:
- Email Address
- File Upload
- Option List
- Tickbox List, and
- Tickbox Tables
As shown below, when configuring Questions, you can choose to configure questions separate to a section, or as part of a section.
However, our recommendation is to configure Sections each time you build a custom form. When doing so, you'll notice the name of your section appear as per below, and on the Asset Map underneath your Custom Form with your fields as direct children.
When you click the name of your Section, you’ll be able to view and order the form fields within your section. I recommend giving your form fields highly descriptive names such as the ones provided. It’s also best practice to choose the right Type of field for your Matrix fields, as this will be tied to in-built Matrix error checking.
Custom Form Body Copies
One of the really great features of Squiz Matrix Custom Forms is the ability to define body copies for the screens in your forms’ workflow.
The most common body copies that you’re likely to use are the:
- Page Contents Body Copy, and the
- Thank You Body Copy
The Page Contents body copy is where you can configure a custom layout of the fields in your form, whilst the Thank You body copy let's you configure a personal message to your users when they successfully complete your form.
If this is your first time configuring a Body Copy, you’re going to want to copy the HTML mark-up of each of your form fields into your Page Contents body copy. The easiest way to do this is by inspecting your page code and copying the HTML. You’ll notice the name and ID of the fields are the same as those in your asset map, so once you copy your first field you should be able to use this convention to reference the remainder of the fields and elements configured in your form.
Show below is the HTML mark-up for our First Name field wrapped in a form tag. We've also included a standard HTML label tag to identify our First Name field.
<form id="form_email_1943" enctype="multipart/form-data" action="" method="post">
<input type="text" name="q1947:q1" value="" size="30" maxlength="300" id="q1947_q1" class="sq-form-field">
Utilising Matrix keywords in Custom Form Body Copies
By now you will have managed to copy in the form fields you configured on your Form Contents screen, but what about a submit button or error handling? Sure you could have copied your submit button code directly from a standard implementation, but how would you handle errors? That's where Matrix keywords come into their own.
The Squiz Matrix Keywords Manual is a fantastic reference where you can lookup Matrix keywords for all form related assets. Some of the more common keywords you will likely want to add to your form body copies include:
- %submit_button%: Used to display a form submission button
- %form_errors%: Used to print any server-side errors when submitting a form
- %form_summary%: Used to display the values entered by a form respondent
There is a wide variety of keywords worth familiarising yourself with on the Matrix Manuals. Whether you're looking for a basic implementation or a advanced form with custom functionality, if you're using body copies, it's a given you're going to want to use keywords in your Custom Form.
Implementing Multiple Page Custom Forms
Often times you may want to implement a multi-page form. This is useful for splitting up form sections across multiple pages to provide a more logical and positive user experience.
To do so, check “Yes” underneath Multiple Page Form Options as show below. This will allow you to split your form across multiple pages In the below example we've added a second section called "Company Details". This will display the Company Details section on a second page once the Contact Details section is completed. In this instance you will notice that the submit button is replaced with a next page button on all pages leading up to the final submission page.
For basic configuration of form buttons, next and previous text, as well as page number formatting, this can be done via the Form Contents screen.
Email Options in Squiz Matrix Custom Forms
Squiz has provided three primary emails which can be configured to send to your form users. These include:
- Recipient Emails: A HTML capable email which is sent to one or more email addresses providing a summary of the form submission.
- Receipt Emails: A HTML capable email optionally sent to the person submitting the form containing receipt of the values entered or simply a confirmation that their form submission has been received.
- Send to a Friend (STAF) Emails: A list of emails which are linked to and notified of form submissions.
Below is an example of of the sort of data you would enter when completing Recipient Email data. This will send to a list of email addresses and includes both FROM and REPLY TO details. The body of the email includes all form fields configured for display using the %form_summary% keyword.
Managing Custom Form Submissions
One of the really useful features of Squiz Matrix Custom Forms, both from a practicality and a security stand point, is that all form submissions are stored online for you to retrieve in the future.
To do so, right click on Form Contents in your Asset Map and visit the Submission Logs screen.
Once you’ve received a submission through your form, you’ll begin to see submissions appear on this screen as show below.
Not only can you filter your form submissions by date range on this screen, but you can export those submissions to a CSV file or send submissions of a particular date range to an email address making this one of the most useful features within the Custom Forms module, especially if you’re looking to grow your email database.
Implementing Submission Actions
In certain circumstances you may want to extend the capability of your form. This may include the following:
- Connecting your form to a RESTful service
- Create a SharePoint List Item
- Make a SOAP call
- Run a Database Query, or
- Upload a video to YouTube
These are just a few of the options available to you to extend your forms. These options by nature are more ‘developer oriented’, however give you the ability to implement some incredible extensions and control across your form, and connect your form data with external systems.
SPAM prevention techniques in Matrix Custom Forms
Nobody wants to receive SPAM emails via their forms, and the good news is that Squiz provides a number of tools you can use to limit SPAM coming through your forms. This includes the following:
- CAPTCHA: Full configuration of CAPTCHA capability
- Google ReCAPTCHA: Inclusion of Google’s reCAPTCHA service
- Mollom Spam Check: Availability of Mollom Spam checking technology
- Honeypot: SPAM prevention via a Honeypot question
- Submission Time Thresholds: Configuration of submission timeouts to deter spammers
If you’re unfamiliar with these services, we recommend starting with the in-built CAPTCHA service provided by Squiz, or trialling the widely used Google reCAPTCHA service. Both of these services are easy to implement and provide solid protection against unwarranted time-wasting spam submissions.
Saving incomplete form submissions
Sometimes you’ll need to create a large form with multiple pages, or a form which requires users to return a second time to complete their submission.
To do so you may want to include ‘Save for later’ functionality. When doing so, you can configure this capability from the Form Contents screen. As part of this functionality you’ll be able to configure the following features:
- Save button appearance
- Return to form emails
These features work hand-in-hand with the functionality on the Incomplete Submissions screen available by right-clicking your Form Contents in the Asset Map. This screen allows you to expire submissions and send scheduled reminder emails. Similar to the sort of functionality available to you on the Email Options screen, you can manage your incomplete submissions and notifications with ease from this screen.
As you can see, Squiz Matrix Custom Forms come with a great deal of functionality making them a very powerful tool.
No matter what type of form you’re looking to implement, Squiz has provided the ability to build all the common functionality you’d be looking for in an online form.
If you’re looking for assistance developing your next Custom Form, get in touch with our Squiz Matrix development team. We’ve been working with Matrix Custom Forms for years, and can assist you to ensure your next Matrix form is a success.