Control elements

The XML tags that follow the xf:bind element specify the form controls and their layout. The XML includes one element for each form control and cfformitem or cfformgroup tag.

CFML to XML tag mapping

ColdFusion MX maps CFML tags to XForms elements and ColdFusion extensions as the following table shows:

CFML tag	XML tag
cfinput type="text"	xf:input
cfinput type="password"	xf:secret
cfinput type="hidden"	None: instance data only
cfinput type="file"	xf:upload
cfinput type="radio"	xf:select1
cfinput type="checkbox"	xf:select
cfinput type="button"	xf:trigger
cfinput type="image"	xf:submit
cfinput type="reset"	xf:submit
cfinput type="submit"	xf:submit
cfselect multiple="false"	xf:select1
cfselect multiple="true"	xf:select
cftextarea	xf:textarea
cfslider	xf:range
cfgrid	cf:grid
cftree	cf:tree
cfformitem type="text"	xf:output
cfformitem type="html"	xf:output
cfformitem type="*" (all but text, html)	xf:group appearance="*"
cfformgroup type="*"	xf:group appearance="*"

ColdFusion converts cfformitem tags with text and html type attributes to XForms output elements with the tag body in a <![CDATA[ section. It converts all other cfformitem tags to XForms group elements, and sets each element's appearance attribute to the cfformitem tag's type attribute. The XSLT must process these elements to produce meaningful output. For example, the ColdFusion default skin transform displays the xf:output text blocks and processes the xf:group appearance="hrule" element, but it ignores all other xf:group elements.

General control element structure

Each control element that can be represented by a standard XForms control element has the following general structure. (For information on XML element structure for cfformitem, cfformgroup, cfgrid, and cftree tags, see the following sections.)

<xf:tagname bind="bindid" id="bindid">
   <xf:label>label</xf:label>
   <xf:extension>
      <cf:attribute name="type">controltype</cf:attribute>
      <cf:attribute name="attribname>attribvalue</cf:attribute>
      <cf:attribute name="attribname>attribvalue</cf:attribute>
      .
      .
      .
   </xf:extension>
</xf:tagname>

The following table describes the variable parts of this structure:

Part	Description
tagname	The xf or cf namespace element name, as identified in the table in CFML to XML tag mapping.
bindid	ID attribute of the model `xf:bind` element for this control. Specified by the control's CFML tag `name` attribute.
label	Control label text. Specified by one of the following: The CFML tag `label` attribute The `value` attribute of the `radiobutton`, `submit`, and `reset` `cfinput` tags The tag body content of `cfselect` `option` subtags, Not used for `cfgrid` and `cftree` tags.
controltype	Type of control. One of the following: The `cfinput` `type` attribute `Select`, `slider`, or `textarea`, for the `cfselect`, `cfslider`, or `cftextarea` tags, respectively. Not used for `cfgrid` and `cftree` tags.
attribname	Name of a CFML tag attribute. There is a `cf:attribute` tag for each attribute specified in the CFML code that does not otherwise have an entry in the XML.
attribvalue	Value of a CFML tag attribute.

Tag-specific element structure

The following sections describe tag-specific features of the XML for several types of input tags. It is not all-inclusive. For the specific structure of any ColdFusion form tag, see the XML generated from the tag by ColdFusion MX.

Selection tags

Tags that are used for selection, cfselect, cfinput type="radio", and cfinput type="checkbox" are converted to XForms select and select1 elements. These elements include an xf:choices element, which in turn has an xf:item element for each item a user can choose. Each item normally has an xf:label element and an xf:value element. Check boxes have a single item; select and radio button controls have more than one.

The following example shows the CFML code for a group of two radio buttons, followed by the generated XML control elements. This example also shows the use of a cfformgroup tag to arrange and label the radio button group.

CFML

<cfformgroup type="horizontal" label="Accept?">
   <cfinput type = "Radio" name = "YesNo" value = "Yes" checked>
   <cfinput type = "Radio" name = "YesNo" value = "No">
</cfformgroup>

XML

<xf:group appearance="horizontal">
   <xf:label>Accept?</xf:label>
   <xf:extension/>
   <xf:select1 appearance="full" bind="YesNo" id="YesNo">
      <xf:extension>
         <cf:attribute name="type">radio</cf:attribute>
      </xf:extension>
      <xf:choices>
         <xf:item>
            <xf:label>Yes</xf:label>
            <xf:value>Yes</xf:value>
            <xf:extension>
               <cf:attribute name="checked">checked</cf:attribute>
            </xf:extension>
         </xf:item>
         <xf:item>
            <xf:label>No</xf:label>
            <xf:value>No</xf:value>
            <xf:extension/>
         </xf:item>
      </xf:choices>
   </xf:select1>
</xf:group>

cfgrid tags

ColdFusion MX represents a cfgrid tag using the cf:grid XML tag. This tag has four attributes: format, which can be Flash, Applet, or XML; and the id, name, and bind attributes, which all have the value of the cfgrid tag name attribute.

For applet and Flash format grids, ColdFusion inserts cfgrid controls in the XML as HTML embed objects in <![CDATA[ sections in the body of a cf:grid tag. The controls can be Java applets or in SWF file format.

For XML format grids, ColdFusion converts the CFML to XML in the following format:

cf:grid bind="gridname" name="gridname" format="xml" id="gridname>
   <metadata>
      <cfgridAttribute1>attributeValue</cfgridAttribute1>
      ... 
      (There are an entry for attributes with a specified or default value.)
   </metadata>
   <columns>
      <column cfgridcolumnAttribute1="value" ... />
      ...
   </columns>
   <rows>
      <row>
         <column1Name>row1Column1Value</column1Name>
         <column2Name>row1Column2Value</column2Name>
         ...
      </row>
      <row>
         <column1Name>row2Column1Value</column1Name>
         <column2Name>row2Column2Value</column2Name>
      </row>
      ...
   </rows>
</cf:grid>

The following example shows a minimal grid with two nodes.

CFML

<cfgrid name="mygrid" Format="xml" selectmode="Edit" width="350   ">
   <cfgridcolumn name="CorName" header="Course Name" >
   <cfgridcolumn name="Course_ID" header="ID">
   <cfgridrow data="one0,two0">
   <cfgridrow data="one1,two1">
</cfgrid>

XML

Most metadata lines are omitted for brevity:

<cf:grid bind="mygrid" format="XML" id="mygrid" name="mygrid">
   <metadata>
      <autowidth>false</autowidth>
      <insert>false</insert>
      <delete>false</delete>
      <sort>false</sort>
      <italic>false</italic>
      <bold>false</bold>
      <appendkey>true</appendkey>
      <highlughthref>true</highlughthref>
      <griddatalines>Left</griddatalines>
      <gridlines>true</gridlines>
      <rowheaders>true</rowheaders>
      <rowheaderalign>Left</rowheaderalign>
      <rowheaderitalic>false</rowheaderitalic>
      <rowheaderbold>false</rowheaderbold>
      <colheaders>true</colheaders>
      <colheaderalign>Left</colheaderalign>
      <colheaderitalic>false</colheaderitalic>
      <colheaderbold>false</colheaderbold>
      <selectmode>Edit</selectmode>
      <notsupported>&lt;b&gt; Browser must support Java to view ColdFusion Java
Applets&lt;/b&gt;</notsupported>
      <picturebar>false</picturebar>
      <insertbutton>insert</insertbutton>
      <deletebutton>delete</deletebutton>
      <sortAscendingButton>SortAsc</sortAscendingButton>
      <sortDescendingButton>SortDesc</sortDescendingButton>
   </metadata>
   <columns>
      <column bold="false" display="true" header="Course Name"
         headerBold="false" headerItalic="false" italic="false"
         name="CorName" select="true"/>
      <column bold="false" display="true" header="ID"
         headerBold="false" headerItalic="false" italic="false"
         name="Course_ID" select="true"/>
   </columns>
   <rows>
      <row>
         <CorName>one0</CorName>
         <Course_ID>two0</Course_ID>
      </row>
      <row>
         <CorName>one1</CorName>
         <Course_ID>two1</Course_ID>
      </row>
   </rows>
</cf:grid>

The cftree tags

For applet and Flash format trees, ColdFusion inserts cftree controls in the XML as HTML embed objects in <![CDATA[ sections in the tag body. The controls can be Java applets or in Flash SWF format. The cf:tree XML tag has two attributes: format, which can be Flash or Applet, and id.

For XML format trees, ColdFusion converts the CFML to XML in the following format:

cf:tree format="XML" id="treename>
   <metadata>
      <cftreeAttribute1>attributeValue</cftreeAttribute1>
      ... 
   </metadata>
   <node cfml tree item attributes>
      <node //nested node with no children
         cfml tree item attributes />
      ...
   </node>
   ...
</cf:tree>

The following example shows a minimal tree with two nodes:

CFML

<cfform name="form2" Format="XML" >
<cftree name="tree1" hscroll="No" vscroll="No" format="xml" 
   border="No">
   <cftreeitem value="Divisions">
   <cftreeitem value="Development" 
      parent="Divisions" img="folder">
</cftree>
</cfform>

XML

The following code shows only the XML that is related to the tree appearance:

<cf:tree format="xml" id="tree1">
   <metadata>
      <fontWeight/>
      <align/>
      <lookAndFeel>windows</lookAndFeel>
      <delimiter>\</delimiter>
      <completePath>false</completePath>
      <border>false</border>
      <hScroll>false</hScroll>
      <vScroll>false</vScroll>
      <appendKey>true</appendKey>
      <highlightHref>true</highlightHref>
      <italic>false</italic>
      <bold>false</bold>
   </metadata>
   <node display="Divisions" expand="true" href="" img=""
      imgOpen="" parent="" path="Divisions" queryAsRoot="true"
               value="Divisions">
      <node display="Development" expand="true" href=""
         img="folder" imgOpen="" parent="Divisions"
         path="Divisions\Development" queryAsRoot="true"
                  value="Development"/>
   </node>
</cf:tree>

The cfformgroup and cfformitem tags

All cfformgroup tags and all cfformitem tags, except type="html" and type="text", generate xf:group elements. The following rules determine the element structure:

The CFML tag type attribute determines the xf:group appearance attribute.
ColdFusion MX converts type attribute values to all-lowercase characters.
For cfformgroup tags only, the CFML label attribute determines the xf:group label attribute.
All other CFML attributes are put in cf:attribute elements in a xf:extension element.
The cfformitem tags generate an xf:output element with the body text in a <![CDATA[ section.

The following example shows two cformitem tags, and the resulting XML:

CFML

<cfformitem name="text1" type="text" style="color:green">
   Please tell us a little about yourself and your thoughts.
</cfformitem>
<cfformitem type="hrule" height="3" width="200" testattribute="testvalue" />

XML

<xf:output><![CDATA[Please tell us a little about yourself and your
thoughts.]]> 
   <xf:extension>
      <cf:attribute name="style">color:green</cf:attribute>
   </xf:extension>
</xf:output>
<xf:group appearance="hrule">
   <xf:extension>
      <cf:attribute name="width">200</cf:attribute>
      <cf:attribute name="height">3</cf:attribute>
      <cf:attribute name="testattribute">testvalue</cf:attribute>
   </xf:extension>
</xf:group>

Example: control element XML

The following code shows the XML for the input controls for the form shown in the figure in About XML skinnable forms. This code immediately follows the end of the xf:model element.

<xf:group appearance="horizontal">
   <xf:label>name</xf:label>
   <xf:extension/>
   <xf:input bind="firstname" id="firstname">
      <xf:label>First</xf:label>
      <xf:extension>
         <cf:attribute name="type">text</cf:attribute>
         <cf:attribute name="size">20</cf:attribute>
      </xf:extension>
   </xf:input>
   <xf:input bind="lastname" id="lastname">
      <xf:label>Last</xf:label>
      <xf:extension>
         <cf:attribute name="type">text</cf:attribute>
         <cf:attribute name="size">25</cf:attribute>
      </xf:extension>
   </xf:input>
</xf:group>
<xf:input bind="email" id="email">
   <xf:label>Email</xf:label>
   <xf:extension>
      <cf:attribute name="type">text</cf:attribute>
      <cf:attribute name="validation">email</cf:attribute>
   </xf:extension>
</xf:input>
<xf:output><![CDATA[<b>We value your input</b>.<br>
   <em>Please tell us a little about yourself and your thoughts.</em>]]>
   <xf:extension/>
</xf:output>
<xf:group appearance="vertical">
   <xf:extension/>
   <xf:select1 appearance="minimal" bind="satisfaction" id="satisfaction">
      <xf:label>Satisfaction</xf:label>
      <xf:extension>
         <cf:attribute name="type">select</cf:attribute>
         <cf:attribute name="style">width:200</cf:attribute>
      </xf:extension>
      <xf:choices>
         <xf:item>
            <xf:label>very satisfied</xf:label>
            <xf:value>very satisfied</xf:value>
         </xf:item>
         <xf:item>
            <xf:label>somewhat satisfied</xf:label>
            <xf:value>somewhat satisfied</xf:value>
         </xf:item>
         <xf:item>
            <xf:label>somewhat dissatisfied</xf:label>
            <xf:value>somewhat dissatisfied</xf:value>
         </xf:item>
         <xf:item>
            <xf:label>very dissatisfied</xf:label>
            <xf:value>very dissatisfied</xf:value>
         </xf:item>
         <xf:item>
            <xf:label>no opinion</xf:label>
            <xf:value>no opinion</xf:value>
         </xf:item>
      </xf:choices>
   </xf:select1>
   <xf:textarea bind="thoughts" id="thoughts">
      <xf:label>Additional Comments</xf:label>
      <xf:extension>
         <cf:attribute name="type">textarea</cf:attribute>
         <cf:attribute name="rows">5</cf:attribute>
         <cf:attribute name="cols">40</cf:attribute>
      </xf:extension>
   </xf:textarea>
</xf:group>
<xf:group appearance="horizontal">
   <xf:extension/>
   <xf:submit id="submit" submission="comments">
      <xf:label>Tell Us</xf:label>
      <xf:extension>
         <cf:attribute name="type">submit</cf:attribute>
         <cf:attribute name="name">submit</cf:attribute>
      </xf:extension>
   </xf:submit>
   <xf:submit id="reset">
      <xf:label>Clear Fields</xf:label>
      <reset ev:event="DOMActivate"/>
      <xf:extension>
         <cf:attribute name="name">reset</cf:attribute>
      </xf:extension>
   </xf:submit>
</xf:group>

View comments in LiveDocs