Forms
Using the Forms Widgets
The forms widgets are used to create forms with different types of elements allowing user input. Individual form elements need to be nested within forms and optionally within form sections. See the diagram below to get a better idea of how this works:
Form Elements Nesting
FORMS: Mailer Form
Use the mailer form to create forms that gather some user input (or information) and send it using email to a specified email address. This widget has an opening and closing tag. All of the form elements have to be enclosed between the 2 tags. A form section is included by default when using the mailer form widget.
Syntax
<w:forms/form-start-mailer name="REPLACE" send-to-name="REPLACE" send-to-email="REPLACE" email-subject="REPLACE" thank-you-page="REPLACE" />
<w:forms/submit-mailer caption="REPLACE" />
<w:forms/form-end />
Attributes
- name="REPLACE"
The form name. This attribute is especially important if there are multiple forms on the same page. - send-to-name="REPLACE"
The name of the person that will receive the submitted form information via email. - send-to-email="REPLACE"
The email address of the person that will receive the submitted inforamtion via email. - email-subject="REPLACE"
The subject of the email message that will contain the submitted information. - thank-you-page="REPLACE"
Path to the page that will be presented to the user upon submitting the form. Use the link button to insert the link. Usually it is a good idea to make this page a sub-page of the page where the form is located and hide the page from navigation by setting the Show in navigation? option to Yes.
Additional Elements
- submit-mailer
This is the button that submits the form data when pressed. Use the caption attribute to provide the text that will appear on the button.
FORMS: Section
Use this widget to split up a complex form into smaller, logical parts. The secion widgets will be enclosed within a form and include form elements such as textboxes and text areas.
Syntax
<w:forms/section-start label="REPLACE" notes="REPLACE" />
INSERT
<w:forms/section-end />
Attributes
- label="REPLACE"
The section heading. The same label is also included within the submitted form data to clearly divide to form information. - notes="REPLACE" optional
Additional instructions or introduction for the particular section. The notes always appear between the section label and the first form element of the section.
FORMS: Textbox
Single line textbox that allows the input of simple text.
Syntax
<w:forms/textbox label="REPLACE" value="REPLACE" length="REPLACE" required="yes|no" notes="REPLACE" />
Attributes
- label="REPLACE"
Label that appears next to the textbox to identify what information is expected. - value="REPLACE" optional
Provide the text that should appear within the textbox by default. This attribute is optional. If you do not need to provide default text, simply delete the attribute. - length="REPLACE" optional
The length of the textbox visible input area. Input a numeric value that represents the amount of characters that will be visible when the textbox is completely filled in. This attribute is optional. If you wish to keep the default value, simply delete the attribute. - required="yes|no" optional
Set to yes if the textbox cannot be left blank. This will force the user to provide some information inside the textbox before the form can be submitted. - notes="REPLACE" optional
Additional instructions or notes for the textbox. This can be a clarification of the data expected to be inputed or the expected format for the element (e.g. for a phone number the following notes could be added "Format: (xxx) xxx-xxxx") - set-sender="name|first-name|last-name|email" optional : restricted
This attribute is quite special. It identifies the textboxes that should be used by the Mailer Form to assemble the Sender email address that appears in the E-mail client when the form email is received. Each option within the attribute can appear only once within one form. The 'name' option identifies the textbox which contents should be used for the "From" email field. The 'email' option identifies the textbox which will contain the email address of the sender (the one filling out the form). The 'first-name' and 'last-name' options can be used to assemble a name of the sender if the form contains 2 separate textboxes for a First Name and Last Name.
Note: This attribute is not included within the widget template. You need to insert it manually into the widgets.
FORMS: Textarea
Multi-line text area that allows the input of longer text.
Syntax
<w:forms/textarea label="REPLACE" value="REPLACE" columns-num="REPLACE" rows-num="REPLACE" required="yes|no" notes="REPLACE" />
Attributes
- label="REPLACE"
Label that appears next to the text area to identify what information is expected. - value="REPLACE" optional
Provide the text that should appear within the text area by default. This attribute is optional. If you do not need to provide default text, simply delete the attribute. - columns-num="REPLACE" optional
The length of the visible input area for the text area. Input a numeric value that represents the amount of characters that will be visible when a line within the text area is completely filled in. This attribute is optional. If you wish to keep the default value, simply delete the attribute. - rows-num="REPLACE" optional
The number of visible text rows within the text area. Input a numeric value that represents the number of lines that will be visible at a time within the text area. This attribute is optional. If you wish to keep the default value, simply delete the attribute. - required="yes|no"
Set to yes if the text area cannot be left blank. This will force the user to provide some information inside the text area before the form can be submitted. - notes="REPLACE" optional
Additional instructions or notes for the text area. This can be a clarification of the data expected to be inputed.
FORMS: Checkboxes
This widget enables you to insert a set of checkboxes presenting multiple options to the user. A user is then able to select one or more options by checking the appropriate checkboxes.
Syntax
<w:forms/checkboxes label="REPLACE" options="VALUE~CAPTION|VALUE~CAPTION..." notes="REPLACE" />
Attributes
- label="REPLACE"
Label that appears next to the set of checkboxes to identify what information is expected. - options="VALUE~CAPTION|VALUE~CAPTION|..."
The values and captions for the individual checkboxes. The caption will be always used to describe the checkbox to the user and the value will be actually submitted and processed by the form. You can include unlimited number of "VALUE~CAPTION" pairs separated by a vertical bar "|". Each pair represents a checkbox. Optionally, if the value and caption are one and the same, simply provide the values only (e.g. "VALUE|VALUE|VALUE|...") - notes="REPLACE" optional
Additional instructions or notes for the checkboxes element. This can be a clarification of the data expected to be inputed or further instructions for checking the boxes.
FORMS: Dropdown
The dropdown widget enables you to insert a dropdown (also knows as "combo box") that presents multiple options to the user of which only one can be selected at a time.
Syntax
<w:forms/dropdown label="REPLACE" options="VALUE~CAPTION|VALUE~CAPTION..." notes="REPLACE" />
Attributes
- label="REPLACE"
Label that appears next to the dropdown to identify what information is expected. - options="VALUE~CAPTION|VALUE~CAPTION|..."
The values and captions for the individual options available inside the dropdown. The caption will be always displayed inside the dropdown and is visible to the user. The value will be actually submitted and processed by the form. You can include unlimited number of "VALUE~CAPTION" pairs separated by a vertical bar "|". Each pair represents a separate option available within the dropdown. Optionally, if the value and caption are one and the same, simply provide the values only (e.g. "VALUE|VALUE|VALUE|...") - notes="REPLACE" optional
Additional instructions or notes for the dropdown. This can be a clarification of the data expected to be selected.
Utility Form Widgets
FORMS: Dropdown US States
This utility widget automatically populates a dropdown with all states within the United States.
Syntax
<w:forms/dropdown-us-states label="REPLACE" />
Attributes
- label="REPLACE"
Label that appears next to the dropdown to identify the contents of the dropdown box.
