`<forms:form>` </...>

This tutorial will provide an overview of the common elements used to put together web forms, and walk through implementation of a basic enquiry form.

To get started building forms, it's also possible to add pre-built web forms to a page using Oncord's visual page editor. For more information about Oncord's form builder, review this help article. Examining the SRC code of example forms is a great way to familiarise yourself with common form elements.

An Example Contact Enquiry Form

The contact enquiry form shown below will:

1. Forward the user's form submission (contact enquiry) to a nominated admin email address.

2. Add the user as a new contact. 

3. Redirect the user to a page confirming the form was submitted successfully.

<forms:form id="contact_us" recordsubmissions="true" onsubmitredirect="/contact-us/success/" contactmode="store" onsubmitemailsubject="[? 'Website Enquiry: ' + $subject.getValue() ?]" onsubmitemail="true"> <forms:row label="First and Last Names"> <forms:editbox id="contact_first_name" width="80" validations="mandatory" /> <forms:editbox id="contact_last_name" width="110" validations="mandatory" /> </forms:row> <forms:row label="E-mail Address"> <forms:editbox id="contact_email" width="200" validations="mandatory" transformations="tolower" /> </forms:row> <forms:row label="Phone Number"> <forms:editbox id="contact_phone" width="200" /> </forms:row> <forms:row label="Message Subject"> <forms:editbox id="subject" width="200" validations="mandatory" /> </forms:row> <forms:row type="one_column" label="Message"> <forms:textarea id="message" width="99%" height="130" validations="mandatory" /> </forms:row> <forms:row type="one_column" align="center"> <forms:submitbutton value="Submit" /> </forms:row> </forms:form>

Form UI Controls

The following UI controls seen in the example above are commonly used when implementing forms:

<forms:form>
This tag is used in place of a standard <form> tag, and introduces some additional options for handling a submission. Using this tag will also introduce security and spam protection measures. When developing on the Oncord platform, the standard html <form> tag should be replaced with the <forms:form> tag.

<forms:row>
A layout element used inside the <forms:form> tag to display a label and description, and ensures that form fields display nicely when form submissions are emailed.

<forms:editbox>
Used in place of the standard html <input type="text"> field. A basic field that allows the user to input a single line of text. 

<forms:textarea>
Used in place of the standard html <textarea > field.  Allows the user to enter multiple lines of text.

Modifying the Form

Options for handling a form submission are controlled by modifying / adding attributes to the <forms:form> tag. A list of common attributes can be found below.

You can also use any standard HTML form attributes (width, class, etc).

Id="contact_us"
Each form must be assigned a unique id. The form id is displayed throughout the Dashboard to log submissions, and when used with Automation. Define an ID such as contact_us, quick_quote, get_started etc.

RecordSubmissions="true"
This attribute determines whether Oncord will store submissions from this form in the database. As an example; a contact form should record submissions, whereas a simple login form or newsletter subscribe should not.

OnSubmitRedirect="/contact-us/success/"
This attribute defines the page users should be redirected to upon successful form submission. As standard practice, consider adding a new page under the form to act as a success page.

ContactMode="store"
This attribute controls creation of the new contact. 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.

"Store" is commonly used for enquiry forms, otherwise use "register" when creating newsletter subscribe forms and "login" if you're implementing a login form.

OnSubmitEmail="info@mywebsite.com"
If set, a notification 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. When set to "true", the email address associated with the Oncord account will be used (Dashboard > Settings > My Account). 

OnSubmitEmailSubject="[? 'Website Enquiry: ' + $subject.getValue() ?]"
The OnSubmitEmailSubject attribute defines the subject of the notification email. To make it easier to find notification emails in your inbox, it's common practice to include the form name, and either the name of the user who completed the form, or a message subject.

The .getValue() function can be used to retrieve and pass form fields by their ID. In this example, the 'subject' field is being used. To use the contact name, this could be changed to: $contact_first_name.getValue().

Because this attribute isn't simple text and needs to be evaluated, the value has been placed inside [? ?]. Alternatively, you could just specify simple text: 
OnSubmitEmailSubject="New Website Enquiry"

Click here to view the full API reference for the <forms:form> tag.

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 row tag has the following commonly used attributes:

Label="Phone Number"
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.

Type="one_column"
This attribute defines the number of columns assigned to the row:

• one_column
• two_column

Modifying Form Input Fields

An <forms:editbox> allows the user to input one line of text, and a <forms:textarea> allows the user to input multiple lines of text.

If your form will create a new contact record in the database, each form field should use ids 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 a basic contact form 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:

Id="contact_first_name"
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.

Validations="mandatory"
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

It is often a requirement of non-profits and membership organisations to accept donations on their website.

1) Build a Form

The form contains a <forms:paymentmethod> control and calls a function donate() on submit.

2) Server Code

In your page's Source > PHP tab, this is where the donate() function is declared. 
You can add items to the cart here with a custom amount.

By editing the settings of a page, you can specify that access should be restricted to contacts who meet certain conditions (more here). Automation can be used to place contacts into groups after form submissions, and you can add a password field to signup forms to allow contacts to set a password.

You can also code your own login forms and restrict access to certain pages or content if you wish. The following article shows a typical implementation of a login form on a Oncord powered website.

Determining Whether a User is Logged in

The <logic:if> control allows you to check whether a user is currently logged into the website. This will allow us to display different content to users, depending on whether they are logged into the website.

<logic:if test="\Components\Customers\Contacts::currentIsLoggedIn()"> <p>Content to display if the user is logged in</p> </logic:if> <logic:else> <p>Content to display if the user is not logged in</p> </logic:else>

The Login Form

The following code is a common implementation of a login form, wrapped in the above <logic:if> tag to determine whether a user is logged in:

<logic:if test="\Components\Customers\Contacts::currentIsLoggedIn()"> You are currently logged in as <strong><personalisation:fullname /></strong><br /> <br /> If you would like to change your login information, please choose from the options below.<br /> <br /> - <a href="/community/profile/">My Profile</a><br /> - <a href="/community/logout/" onclick="return confirm('Are you sure you wish to logout?\n\nYou only need to logout if you are using a public computer and are concerned about your privacy.\nUnlike some sites, this site does not require you to logout after each session.');">Logout</a> </logic:if> <logic:else> <forms:form contactmode="login"> <forms:editbox placeholder="E-mail" validations="mandatory,email" id="contact_email" /> <forms:password placeholder="Password" validations="mandatory" id="contact_password" /> <forms:submitbutton value="Login" /> </forms:form> <br /> <a href="/community/lost_password/">Lost / Forgot Password</a> </logic:else>

The form below will add a new subscribed contact to your database, and display a pop-up message on success. 

The attribute ContactMode="register" is set on the <forms:form> UI control, which will register a new contact, and throw a validation error if the contact already exists.

Request Marketing Consent

Contacts added to your database via other forms (such as contact forms), will be aded with the e-mail marketing status "Pending" to flag inferred consent.

Adding to the previous contact enquiry form article, you can explicitly ask users whether they want to receive e-mail newsletters, and set their e-mail marketing status to "subscribed" (line 12-14):

The idea of a two-stage registration form is to increase the likelihood a user will sign up, by breaking up a larger form into two separate stages.

A user will initially sign up with only an e-mail address or limited details, and then be asked for more details on a second page. If the user doesn't complete the second stage of registration, at least you have some limited information to add them to your contact database for follow-up.

Keep Your Database Clean & Valuable

Ideally to maintain a valuable, clean database you'll know at least these details about each of your contacts:

• First Name
• Last Name
• E-mail

Requesting a minimum of these details will ensure that your database stays clean and personalized.

The Registration Form

The first registration form requests an e-mail address, first name and last name from the user, and the second stage form requests their address, phone number and date of birth details.

The first stage registration form:
This form would be added to the website design, or on the first page of the two page registration process.

The second stage registration form:

After adding the above code to your second page, you'll need to add some server code to properly re-direct the user back to the page they were originally referred from. If you don't want to redirect the user, simply leave the onsubmitredirect="" attribute blank (or redirect to a success page) and don't worry about the below server code:

*Note: To access the server code for a page, simply open the page with the page editor and select the "Server Code" tab towards the top of the page.