Form Widgets

Form widgets provide a means by which your users can communicate with you via email in a structured format. You can construct a form from a number of form field options and choose what type of validation you want to apply, including which fields are mandatory.

Creating a form widget

Form widgets are created via the Add Form Widget link in the administration menu. 

The first thing a form widget needs is a unique name.

Then it needs a Legend. This is a value that appears above the form like a title. It is usually just a word or two such as Contact Us. 

Next, you need to provide a subject for the resulting email. 

You also need to provide email addresses for email message - one for the recipient of the email, and one for the sender. These can be the same value.

This is followed by a series of text editors which allow you to specify certain messages to users. The first is a message for users at the point they land on the page containing the form. This might, for example, contain detailed instructions on how to use the form or its purpose. The second text editor is for composing a message to be displayed to users after the email form has successfully been submitted and processed. The final text editor is for a message to be displayed to users in the event that the form was not processed successfully due to exceptional circumstances. Note, this is not the same as failed validation, where for example the user has not provided a value for a required field. Exceptional circumstances include such things as the mail server being unavailable.

The next option allows you to determine whether the form should be visible again after it has been sent successfully. The default is No. However, your business rules may dictate that a user should be invited to make further submissions. 

The final group of fields are for specifying the SMTP server that is to be used to send the resulting email, and ofr authenticating with it if necessary. The fields are the address of the SMTP server, the port that it accepts connections on, any user name and password that is requried to authenticate with the server and a flag to indicate whether Secure Sockets Layer (SSL) is to be used.  Google's Gmail service is one of the most widely used publicly available SMTP services. The values required for that are:

SMTP Address: smtp.gmail.com
Port: 587
User Name: your_gmail_email_address
Password: your_gmail_password
Use SSL: Yes.

You should check with your email provider or network administrator for the correct settings for your service.

Adding fields to the form widget

Once you have saved your form widget, you must add some fields to it. You will be taken to the page that enables you to add fields to the form one at a time.

Each form field needs a name.

Then you must select a field type from the following options:

Descriptions of the different types and their inbuilt validation is provided in brackets. The validation is provided on the client by jQuery unobtrusive validation. This is injected into the page by the Web Pages CMS but it relies on jQuery, which you must ensure is referenced in your layout. Jquery is included in the Default theme. Server side validation is performed by the Web Pages framework regardless. 

The next thing to add is Label text. This is the value that appears above the form field and explains what value the user is expected to provide. In the image below, the label text is "Label Text:"

Help Text is the additonal text that you can add to provide further, more detailed instructions to the user. It appears below the form field to which it relates. 

You can indicate that the field is required by ticking the appropriate box. If the user fails to provide a value for a field marked as required, the default error message is "This field is required". You can provide a tailored error message for each field. 

You can specify a minimum and/or maximum length (number of characters) for the value provided by the user. If you specify one or the other, you can provide an error message for the minimum or the maximum accordingly. If you specify both a minimum AND a maximum, you are specifying a range, and should therefore provide a range error message. any minimum or maximum error messages will be ignored.

Finally, you can dictate the position the field should occupy in the rendered form. The default value is the highest position of existing fields plus one.