This tutorial will give you an overview of Synergy 8 forms, and walk through implementation of a contact enquiry form as an example.
The contact enquiry form will:
1. Forward the form submission (contact enquiry) to a nominated admin email address.
2. Add the user as a new contact in the database.
3. Redirect the user to a page confirming that the form was submitted successfully.
Form, Rows & Fields
The following tags are commonly used when implementing forms on Synergy 8:
This tag renders a HTML form with many additional options for handling a submission, and introduces security and spam protection measures. When developing on the Synergy 8 platform, the standard html <form> tag should be replaced with the <ss:forms:form> tag.
An optional layout element to provide an easy way to layout forms. It's used inside a <ss:forms:form> tag to display a label and description, and ensures that form fields display nicely when form submissions are emailed.
Allows the user to input one line of text. Used in place of the standard html <input type="text"> field.
Allows the user to enter multiple lines of text. Used in place of the standard html <textarea > field.
Here's the code for the contact form:
- Contact Form Code
Modifying the Form
Options for handling a submission are controlled through the form's attributes. A list of the most common attributes can be found below.
You can also use any standard HTML form attributes (width, class, etc) in addition to these.
Click here to view the full API reference.
Each form must be assigned a unique id. The form id is displayed throughout the Dashboard to allow . (Use an id like: contact_us, quick_quote, get_started).
This attribute determines whether Synergy 8 will record / store the form submission. As an example; a contact form should record submissions, whereas a simple login form or newsletter subscribe should not.
This attribute defines the page to redirect to upon successful form submission. As standard practice, consider adding a new page under the contact form to act as a generic success page.
This attribute controls creation of the new contact. You will normally use "store", otherwise "register" when creating newsletter subscribe forms and "login" if you're implementing a login form. You may choose from the following valid values:
- Register - Registers a new contact, and fails validation if the contact already exists.
- Store - Optionally registers the member if they do not exist.
- Guest - Optionally registers the member if they do not exist, but does not log the user in.
- Login - Logs in the member (requires contact_email and contact_password fields).
- Logout - Logs out the member.
- Unsubscribe - Unsubscribes the member.
If set, an e-mail with the form submission details will be sent to the specified email address. You may separate multiple e-mail addresses with a comma.
This attribute defines the email subject when used in conjunction with OnSubmitEmail. It's common practice to include the form name and the name of the user who completed the form. For example: onsubmitemailsubject="'Website Enquiry: ' + $_POST['subject']"
Modifying Form Rows
Form rows are an optional layout element to provide an easy way for you to layout forms.
This tag renders a row, field label and description, and ensures that the form fields display properly when being emailed.
The full API reference of the form row tag can be viewed here. The row tag has the following commonly used attributes:
This attribute is used to define the text which will appear as the row label.
Description="Please enter your phone number"
This attribute places a short description in a small font.
This attribute defines the number of columns assigned to the row:
Modifying Form Input Fields
An <ss:forms:editbox> allows the user to input one line of text, and a <ss:forms:textarea> allows the user to input multiple lines of text.
If your form is creating a new contact record in the database, use ids on form fields that match the contact database fields. (eg. use contact_first_name, contact_e-mail). You can view all contact fields here via the API reference.
The only form field types needed for the above contact form example were the editbox and the textarea, however other form field types are also available for use (check out the API).
The editbox has the following commonly used attributes, and in addition to these you can add standard html attributes such as class, id and placeholder:
Each field must have a unique ID. If the current user is logged in, this will also allow the form to be prefilled with contact's details.
Sets the validations to be applied to the form item. In this case the editbox has a mandatory validation, which means the form will not submit until the user has completed this field.
In the above example, validations="mandatorty, email" has also been used on the e-mail input field to ensure that the e-mail address is valid.
Styling Form Rows with CSS
We include some standard CSS styling on form rows, however overriding these styles is easy.
When adding your own CSS styles to form rows, note that form rows are used on system pages such as unsubscribe.
If your CSS styles will only be applied to one single form, edit the page that the form appears on, edit the page and click SRC. Add your styles to the CSS tab of the src view.
Otherwise, simply add CSS to your website design.