The contentXXL mailform module is a quite useful  and versatile module. While it might not be very convenient to template compared to visual form designers, it still gives you a lot of options for setting  up mailforms. 

What can be done I'd like to show in this - and some following - articles.

The topics for this article will be

• Configuration
• Templating
  • Adding fields 
  • Adding field validation 
  • Use language placeholders for labels 
  • Add a captcha module to prevent spam 
  • Use HTML modules to allow your editors to easily change general text

Configuration

Basic Settings

• Form Template
  defines the layout of the mailform
• "Thanks"-Module
  feel-good message, that gets displayed if the mailform was successfully submitted to the server.

  The dropdown list shows all HTML modules in your installation. Unfortunately, you are unable to edit them from the mailform configuration.
  The best way to handle the HTML modules is to create a page, not visible to the public, onto which all "system" HTML modules are published and edited.

• Indentation
  By default, contentXXL send the results entered into a mailform in a plain text format to the defined email recipients. To make this plain text a bit more readable, you can define the number of characters to be used for the first column that includes the form labels.
  

      firstname          : value
      street             : value
      date of birth      : value

• Disable sending ip-address of Sender
  By default, the email includes the IP of the person submitting the form. Checking the option will exclude the IP address.

Form Settings

• Error Message
  error message to be shown if an error occurs when sending form content.
• E-Mail Template
  template for defining the layout of the result email
• Confirm Template
  template for a two-step sending process, that displays a summary page before finally submitting the form
• Sender Mail
  the email used to send the result email.
  Beware: depending on mail server configuration, external email addresses might not be permitted to send emails.
• use entered e-mail as sender address
  uses the e-mail address of the sender to send the result email.
  Beware: see above
• Default subject
  email subject
• Default recipient
  email of recipients (separated by semicolon)
• CC-recipient(s)
• BCC-recipient(s)
• Subject / recipient

Templating

Adding fields

contentXXL form field placeholders allow you add controls without the need to write the longer asp.net statements. However since they are still actually ASP.net Controls - or will be translated to internally ASP.NET Controls when the template is saved – you can use all attributes available for the respective ASP.NET Control.

A form field placeholder in your template will look like this:

[type:fieldname]
[type:fieldname:parameters]

Specifying parameters is optional.

Examples:

cssClass [tb:fieldname:cssClass=”textbox”]
style  [tb:fieldname:style=”width:50px;”]
TabIndex [tb:fieldname:TabIndex=”1”]

Multiple parameters can be queued with a blank: [tb:fieldname:cssClass=”textbox” TabIndex=”1”]

Fields

• Textbox
  [tb:fieldname] 

  Textbox with multiple rows (HTML element textarea):
  [tb:fieldname:Textmode="Multiline" style="height:200px;"] 

  Password field:
  [tb:fieldname:Textmode="Password"] 

  Max length for text:
  [tb:fieldname:MaxLength="50"] 

• Label
  [lb:fieldname] 
• DropDownList
  [ddl:fieldname]   
      [li:Mr:0]
      [li:Mrs:1]
  [/ddl] 

  Listitems:   [li:text:value]

• ListBox 
  [lbx:fieldname]
      [li:Mr:0]
      [li:Mrs:1]
  [/lb] 

  Listitems:   [li:text:value]

  Useful Parameters: 
  SelectionMode=”Multiple”

• CheckBox
  [cb:fieldname]

  Useful Parameters: 
  Text="labeltext"
  TextAlign="Left"

• CheckBoxList
  [cbl:fieldname][/cbl]

  Useful Parameters: 
  RepeatDirection="Vertical"
  RepeatDirection="Horizontal"

• RadioButton
  [rb:fieldname]
• RadioButtonList
  [rbl:fieldname]
  [/rbl]

  Useful Parameters:
  RepeatDirection="Vertical"
  RepeatDirection="Horizontal"

• FileUpload
  [ful:fieldname]

Buttons

• Button
  [bn:name:CommandName="Update" Text=”Send”]
• LinkButton
  [lbn:name:CommandName="Update" Text=”Send”]
• ImageButton
  [ibn:name:CommandName="Update" ImageUrl=”~/portaldata/1/resources/send.jpg”]

For a complete list of placeholders check
http://partner.contentxxl.com/desktopdefault.aspx/tabid-60/57_read-38/  

Special fields

Subject

 Adding field validation

It’s always a good practice to validate user input before sending the form to the server.

You can use the parameter mandatory=”1” to specify required fields.

After submitting the form (postback) contentXXL will display an error message, if not all required fields have been specified.

A better way however, is the use of the ASP.NET validation controls. While it’s always possible to directly add ASP.NET Validators to your mailform, contnetXXL also offers shortcuts:

Validators:

• RequiredField Validator
  Alert the users, that a field is required 
  ?

  1	[rfval:id:controltovalidateid:parameter][/rfval]

  Example
  ?

  1	Email: [tb:email] [rfval:EmailEval:email:display="dynamic"]Please enter your email address[/rfval]

• CompareValidator
  Compare field values 
  ?

  1	[cpval:id:controltovalidateid:comparecontrolid:operator:parameter][/cpval]

  Example
  ?

  1 2 3

  [tb:password:] [tb:password2:] [cpval:passwordval:password:password2:Equal:]The passwords don’t match.[/cpval]

  http://msdn.microsoft.com/en-us/library/system.web.ui.webcontrols.comparevalidator.aspx
  
  Operators:
  Equal, NotEqual, GreaterThan, GreaterThanEqual, LessThan, LessThanEqual

• Range Validator
  ?

  1	[rngval:id:controltovalidateid:type:minval:maxval:parameter][/rngval]

• Regular Expression Validator
  Check, if the field value matched a specified pattern:
  
  ?

  1	[rexval:id:controltovalidateid:ValidationExpression="expression"][/rexval]

  \b[A-Z0-9._%-]+@[A-Z0-9.-]+\.[A-Z]{2,4}\b

  Tip: You can find a useful tool to develop and test regular expressions here: http://gskinner.com/RegExr/

• Custom Validator
  ?

  1	[cusval:id:controltovalidateid:parameter][/cusval]

• Validation Summary:
  ?

  1	[valsum:id:parameter]

As a side note: Use labels for accessibility

You can use the <label> tag to connect the field description to the field itself, on order to enable screen readers to tell the user the meaning of a field, by reading the label. Also, when using labels with checkboxes, you can toggle the checkbox by clicking on the label, whereas you would have to hit the checkbox directly to toggle it without the label.

With contentXXL field placeholders the above sample would look like this:

You have to use <%= AGBCheckbox.ClientID %> to refer to the checkbox in the label as the webserver will change the ID of the control when rendering the page. AGBCheckbox  will be changed into something like ctl00_ctl09_mailformrepeater_ctl00_ctl00_AGBCheckbox in the rendered page.

Use language placeholders for labels

Even if you might not require it in the beginning – it takes much more time to go through all your templates later on, to substitute static labels with placeholders to display language specific labels. So use placeholder right from the start.

The best practice would be to use language files, e.g.

(A followup article will go into detail about how to add those language files to your portal).

Then you can use them in you mailform template like this:

Add a captcha module to prevent spam

contentXXL contains a separate captcha module that can be used for different scenarios, one of it obviously being the mailform.

1. Create a captcha module
   
   Sample template:
   ?

   1 2 3 4 5 6 7 8 9 10

   <div>     Captcha:* <br />     [CaptchaImage]<br />     <br />     [tb:captchatext:]     <span [mvif:errorcode:eq:1] style="color: Red; display: inline;"><br />     Your entry didn’t match the text in the image. Please try again.</span>     <br />     <a class="captcharefresh" href="javascript:CaptchaRefresh();">» generate a new captcha</a> </div>

2. Embed the captcha into the mailform template
   
   ?

   1	[module:idOfCaptchaModule]

Use HTML modules to allow your editors to easily change general text

Within a mailform there’s often some general text included, that in the most pragmatic way would be included in your template

However, that’s not the best practice in terms of localization.
So, you could move your text to your language files. But, in most cases that can be quite bothersome, since the text might contain markup, with would require special treatment for the use in an xml file (encoding the entities). Also, your editors might want to change the text now and then.

Therefore, the best way to handle longer texts that are too cumbersome for the xml language files by creating an HTML module and embedding that into your mailform.

1. Create a page in you system, set it visible for admins/editors only. It could hold any html modules you use for embedding in your template. It will give one place to edit them, without the necessity to go through the mailform template.
2. Create and add a HTML module to the page. Enter your text, save and make sure your text ist visible on the newly created page.
3. Embed the HTML module into your mailform template
   
   ?

   1	[module:idOfHTMLModule]

That’s it for now. Topics for part 2 will include:

• Using email templates to customize the mail
• Using the confirm template to present a summary page to the user
• Customizing mailform behavior