The e-mail form allows site visitors to fill out and send information to specified recipients based on input detailed in the form. The form is capable of handling the following fields:
- Destination e-mail address (to: address) based on a user selected from a drop-down menu
- From address
- Subject
- CC list
- Bcc list
- Message body
In order for the e-mail form to work, you must first ensure that your e-mail service is configured to work with your organizations e-mail service. You can read about how to configure this here.
Note: the e-mail form will not submit the forms information to the Dashboard Forms Tracker Gadget. This service is intended only for a visitor to submit an e-mail to a destination address. It is also not possible to enable the 'Notify on form submission' property as described in the document here. It is only possible to select one function or the other.
Also note that at this time the Cc and Bcc fields are supported but the email address is not validated or encrypted. We recommend using them for controlled environments like Intranet sites until they are validated and encrypted in a future release.
Adding the e-mail form:
1) You must first add the Form Widget to a template or a page; this document will configure the e-mail form using a page. Bring a page into edit mode (make sure it has an open region for the form widget).
2) Select the Layout tab. From here, click 'Add Widget.' Drag and drop the Form Widget from the widget tray into an available region. Save.
3) Navigate to the Content tab of the same page. Double click the empty form.
4) From here, give the form a name and if desired a title.
5) The e-mail form recognizes 6 properties (mentioned at the top of this document). We will need to add the desired fields to the form in order for the e-mail form to submit successfully.
Configuring the e-mail form:
1) It is easiest to start with just the submit field. You may remove all other fields by clicking the 'x' button. Below is an image of what this looks like:
2) From here, let's add the 'Data Drop Down' field category by clicking the '+' icon on the right side of the widget. This field references shared assets that include the following fields:
- personFirstName
- personLastName
- personEmail
This can be configured through the 'People' widget or by creating a custom widget with the following fields. For more details on how to create a custom widget using this definition and using this widget as a shared asset, please refer to Appendix A. The Data Drop Down field then uses the person's e-mail defined in the shared asset as the 'To:' address. From the drop down, you will need to select the widget that contains these fields. For example, in my case the 'cwPeopleWidget' contains the three fields defined above:
3) Next, we will add the from address, the subject, the Cc list, and the Bcc list. Begin by adding 4 Entry Fields to the form. You may configure the text for these fields any number of ways, but the properties for each field must be configured in a specific way for the e-mail form to work. To configure the properties, we will click the wrench icon for each of the fields we just added. We need to populate the 'Name' property for each field. The 'Name' properties we need to add are:
- email-from
- email-subject
- email-cc
- email-bcc
Below is an image depicting this step for the 'From: ' field:
The remaining fields will need to be configured with the other properties mentioned above, respectively. I.E email-subject will propagate the 'Name' property for the 'Subject: ' field, etc.
4) Next, we may add the 'email-body' property. Add the 'Text Box' field to the form. Click the wrench and for the 'Name' value, add 'email-body.' This will be submitted to the recipients as the e-mail body content.
5) Lastly, expand the 'Meta-data' section. The form requires that you specify a success page and an error page for the form submission. We will also need to select the 'Email form' option button.
6) Publish the form. From here, when a user fills out the form, the appropriate fields will be passed to the email service and sent as an email.
Submitting the form:
Once published, the form will look something like this:
The 'To:' field recognizes people in the organization that have been configured with a 'People' widget, defined in Appendix A. This field pulls the e-mail property from the shared asset and uses it as the destination address. The 'From: ' address represents who the e-mail comes from. The 'Subject:' field specifies the subject of the e-mail, and the Cc and Bcc fields allow configuration of those fields in a list of comma separated values, respectively. The message field allows the user to submit a message as the e-mail body content.
Using a Custom Widget for the Drop down list
To create a custom widget that utilizes the 3 fields needed to populate the shared asset/To: address, follow the instructions below:
1) Navigate to the Widget Builder from the top-left dropdown menu. If you do not see Widget Builder, you may not have the appropriate privileges to access this tool.
2) Select the new widget icon on the top right.
3) Under the General tab, fill in the appropriate information. The version number must be in major.minor.micro format, such as: 1.0.0
4) Navigate to the Content tab. Create three fields as defined in the image below:
5) Navigate to the Display tab and select 'Auto Generate.' This is fairly basic, but it will provide users with the ability to create a shared asset with the required fields to populate the 'To:' field of the e-mail form.
6) Click 'Save.' Lastly, select the deploy button on the top right of the screen. From here, you will need to navigate to a desired directory under /Assets from the Editor, and create a new widget of the widget type you just created and deployed. Populate the new widget with a users first name, last name, and e-mail address. At this point the new shared asset can be selected from the email form data drop down field.