Building XML skinnable forms



You build ColdFusion XML skinnable forms using standard ColdFusion forms tags, including cfformgroup and cfformitem tags. These tags create the elements of the form, the building blocks of the form.

ColdFusion converts the following tags to XML for processing by the XSLT:

Standard ColdFusion form data control tags
The cfgrid, cfinput, cfselect, cfslider, cftextarea, and tree tags specify the controls that the form displays.

cfformitem tags
Add individual items to your form, such as text or rules. The valid types depend on the skin.

cfformgroup tags
Group, organize, and structure the form contents. The valid types depend on the skin.

These tags are designed so you can develop forms in a hierarchical structure of containers and children. Using this model, the cfform tag is the master container, and its contents are children containers and controls. Each cfformgroup tag defines a container that organizes its child elements.

The specific tags and attributes that you use in your form depend on the capabilities of the XSLT skin. You use only the tag and attribute combinations that the skin supports. If you are using a skin provided by a third party, make sure that the supplier provides information on the supported attributes.

Using standard ColdFusion form tags

You use standard ColdFusion form tags, such as cfinput or cftree, as you normally do in standard CFML forms to generate form input elements. ColdFusion maps most of these tags and their subtags (such as option tags in the cfselect tag) to equivalent XForms elements. ColdFusion maps applet and Flash format cfgrid and cftree tags to ColdFusion XML extensions that contain Java applet or Flash objects. It converts XML format cfgrid and cftree tags to ColdFusion XML extension.

The specific attributes you can use and their meanings can depend on the skins.

Using ColdFusion skins: The skins that are supplied with ColdFusion support the attributes that you can use with HTML forms. You can also use label attributes to provide labels for the following tags:

  • cfinput with type attribute values of text, button, password, and file

  • cfselect

  • cfslider

  • cftextarea

Using other skins: If you use any other skin, some attributes are not supported, or the skin supports custom attributes. Get the information about the supported attributes from the XSLT skin developer.

Using cfformitem tags

ColdFusion does not process inline text or standard HTML tags when it generates an XML form; therefore, you use the cfformitem tag to add formatted HTML or plain text blocks and any other display elements, such as horizontal and vertical rules, to your form.

ColdFusion converts all cfformitemtype attribute values to all-lowercase. For example, if you specify type="MyType" ColdFusion converts the type name to "mytype".

ColdFusion makes no other limitations on the cfformitemtype attributes that you can use in a form, but the XSLT skin must process the attributes to display the items.

Using ColdFusion skins: The skins provided in ColdFusion support the following cfformitem types:

  • hrule

  • text

  • html

The hrule type inserts an HTML hr tag, and the text type displays unformatted plain text.

The html type displays HTML-formatted text. You can include standard HTML text markup tags, such as strong, p, ul, or li, and their attributes. For example, the following text from the Example: a simple skinnable form section shows how you could use a cfformitem tag to insert descriptive text in a form:

<cfformitem type="html"> 
    <b>We value your input</b>.<br> 
    <em>Please tell us a little about yourself and your thoughts.</em> 
</cfformitem>

Using other skins: If you use any other skin, the supported attributes and attribute values depend on the skin implementation. Get the information about the supported attributes and attribute values from the XSLT skin developer.

Using cfformgroup tags

The cfformgroup tag lets you structure forms by organizing its child tags, for example, to align them horizontally or vertically. Some skins use cfformgroup tags for more complex formatting, such as tabbed navigator or accordion containers. ColdFusion makes no limitations on the type attributes that you can use in a form, but the XSLT must process the resulting XML to affect the display.

Using ColdFusion skins: The skins provided in ColdFusion support the following type attribute values:

  • horizontal

  • vertical

  • fieldset

The horizontal and vertical types arrange their child tags in the specified direction and place a label to the left of the group of children. The following text from the Example: a simple skinnable form section shows how you could use a cfformgroup tag to apply a Name label and align first and last name fields horizontally:

<cfformgroup type="horizontal" label="Name"> 
    <cfinput type="text" name="firstname" label="First" required="yes"> 
    <cfinput type="text" name="lastname" label="Last" required="yes"> 
</cfformgroup>

The fieldset type corresponds to the HTML fieldset tag, and groups its children by drawing a box around them and replacing part of the top line with legend text. To specify the legend, use the label attribute. To specify the box dimensions, use the style attribute with height and width values.

The following code shows a simple form group with three text controls. The cfformgroup type="vertical" tag ensures that the contents of the form is consistently aligned. The cfformgroup type="horizontal" aligns the firstname and lastname fields horizontally.

<cfform name="comments" format="xml" skin="basiccss" width="400" 
        preservedata="Yes" > 
    <cfformgroup type="fieldset" label="Contact Information"> 
        <cfformgroup type="vertical"> 
            <cfformgroup type="horizontal" label="Name"> 
                <cfinput type="text" size="20" name="firstname" required="yes"> 
                <cfinput type="text" size="25" name="lastname" required="yes"> 
            </cfformgroup> 
            <cfinput type="text" name="email" label="E-mail" validation="email"> 
        </cfformgroup> 
        </cfformgroup> 
</cfform>
Note: Because XML is case-sensitive, but ColdFusion is not, ColdFusion converts cfformgroup and cfformitem attributes to all-lowercase letters. For example, if you specify cfformgroup type="Random", ColdFusion converts the type to random in the XML.

Using other skins: If you use any other skin, the supported attributes and attribute values depend on the skin implementation. Get the information about the supported attributes and attribute values from the skin developer.

Example: CFML for a skinnable XML form

The following CFML code creates the form shown in the image in About XML skinnable forms. It shows how you can use CFML to structure your form.

<cfform name="comments" format="xml" skin="basiccss" width="400" preservedata="Yes" > 
    <cfinput type="hidden" name="revision" value="12a"> 
    <cfformgroup type="fieldset" label="Basic Information"> 
        <cfformgroup type="vertical"> 
        <cfformgroup type="horizontal" label="Name"> 
            <cfinput type="text" size="20" name="firstname" required="yes"> 
            <cfinput type="text" size="25" name="lastname" required="yes"> 
        </cfformgroup> 
        <cfinput type="text" name="email" label="E-mail" validate="email" maxlength="35"> 
        <cfselect name="satisfaction" style="width:120px" multiple="false" label="Satisfaction"> 
            <option selected>very satisfied</option> 
            <option>somewhat satisfied</option> 
            <option>somewhat dissatisfied</option> 
            <option>very dissatisfied</option> 
            <option>no opinion</option> 
        </cfselect> 
        </cfformgroup> 
        </cfformgroup> 
    <cfformitem name="html1" type="html"> 
    <p><b>We value your input</b>.<br> 
    <em>Please tell us a little about yourself and your thoughts.</em></p> 
    </cfformitem> 
    <cftextarea name="thoughts" label="Additional Comments" rows="5" cols="66">We really want to hear from you!</cftextarea> 
    <cfformgroup type="horizontal"> 
        <cfinput type="submit" name="submit" style="width:80" value="Tell Us"> 
        <cfinput type="reset" name="reset" style="width:80" value="Clear Fields"> 
    </cfformgroup> 
</cfform>