Creating XSLT skins

This section provides information to help you create your own XSLT skins to process the XML that ColdFusion MX generates. It assumes that you are familiar with XSLT and CSS programming, and does not provide general information on writing XSLT transformations or CSS styles. It does provide information about the following areas:

How ColdFusion passes form attribute values to the XML file
How extend XSLT skins that ColdFusion MX provides as templates
Basic techniques for extending the basic.xsl file to support additional cfformgroup and cfformitem tag type attributes
How to extend the ColdFusion CSS files to enhance form appearance.

XSLT skin file locations

If you specify an XSLT skin by name and omit the .xsl suffix, ColdFusion MX looks for the file in the cfform script source directory and its subdirectories. You can specify the script source directory in your cfform tag scriptsrc attribute, and you can set a default location on the Settings page in the ColdFusion MX Administrator. When you install ColdFusion MX, the default location is set to /CFIDE/scripts/ (relative to the web root).

You can also use a relative or absolute file path, or a URL, to specify the XSLT skin location. ColdFusion MX uses the CFML page's directory as the root of relative paths. The following formats are valid:

Format	Location
<cfform format="xml" skin="basic">	Searches for XML/CSS in the default directory and its subdirectories.
<cfform format="xml" skin="c:\foo\bar\basic.xsl">	Uses the absolute path.
<cfform format="xml" skin="basic.xsl">	Searches in the current directory.
<cfform format="xml" skin="..\basic.xsl:">	Searches the parent of the current directory.
<cfform format="xml" skin="http://anywhereOnTheWeb/basic.xsl">	Uses the specified URL.

Note: Hosting companies might move the default skin location folder out of CFIDE; this lets them secure the CFIDE while giving site developers access to the files that you need for cfform.

Attribute and value passthrough

ColdFusion passes form tag attributes or attribute values that it does not specifically process directly to the XML, as follows:

It converts cfformitem and cfformgroup type attributes to xf:group element appearance attributes.
It passes the name and value of tag attributes that it does not recognize or process in cf:attribute elements.

This passthrough feature lets you create custom versions of any of the following items for your XSLT to process:

The cfformitem types, such as rules, spacers, or other display elements
The cfgroup types, such as divided boxes or tabbed dialog boxes
The custom cfinput types, such as a custom year chooser element
ColdFusion tag attributes, such as those used to control validation

Extending ColdFusion XSLT skins

ColdFusion MX 7 provides basic XSLT transforms that you can use as templates and extend for making your own skin. Each skin has a base XSL file, which include several utility XSL files. Utility file names start with an underscore (_), and the files are shared by multiple base skins. The following tables describes the XSL files, which are located in the cf_webroot\CFIDE\scripts\xsl directory:

File	Description
default.xsl	The default transform that ColdFusion MX uses if you do not specify a `skin` attribute for an XML format form. Identical to the basic.xsl file.
basic.xsl	A basic form format that arranges form elements using a table.
basiccss.xsl	A basic form format that arranges form elements using HTML `div` and `span` tags.
colorname.xsl	A basic form format that arranges form elements using a table and applies a color scheme determined by the colorname to the form. Based on the basic.xsl file.
_cfformvalidation.xsl	Applies ColdFusion MX validation rules. Used by all skins.
_formelements.xsl	Transformation rules for form elements except for those defined using `cfformgroup` tags. Used by all skins
_group_type.xsl _group_type_table.xsl _group_type_css.xsl	Transformation rules for `cfformgroup` tags. The tag `type` attribute is part of the file name. Files with table in the name are used by basic.xsl and its derivatives. Files with css in the name are used by basiccss.xsl.

All skins support the same set of CFML tags and tag types, and do a relatively simple transformation from XML to HTML. For example, they do not support horizontal or vertical rules.

The ColdFusion MX skin XSL files have several features that you can use when designing and developing your own transformation. They do the following:

Provide an overall structure and initial templates for implementing custom transformations.
Show how you can handle the various elements in the ColdFusion-generated XML.
Use a structure of included files that can form a template for your XSLT code.
The base XSL files include a separate file, _cfformvalidation.xsl, with complete code for generating the hidden fields required for ColdFusion onServer validation and the JavaScript for performing ColdFusion onSubmit and onBlur validation. You can include this file without modification to do ColdFusion validation in your XSLT template, or you can change it to add other forms of validation or to change the validation rules.
The base XSL files include files, that implement several form groups, laying out the child tags and applying a label to the group. These files can serve as templates for implementing additional form group types or you can expand them to provide more sophisticated horizontal and vertical form groups.
You can add custom cfformgroup and cfformitem type attributes by including additional XSL files.

Extending basic.xsl cfformgroup and cfformitem support

The following procedure describes the steps for extending the basic.xsl file to support additional cfformgroup and cfformitem types. You can use similar procedures to extend other xsl files.

To add support for cfformgroup and cfformitem types to the basic.xsl:

Create an XSL file.
For each type attribute that you want to support, create an xsl:template element to do the formatting. The element's match attribute must have the following format:
```
match="xf:group[@appearance='type_attribute_name']"
```
For example, to add a panel cfformgroup type, add an element with a start tag such as the following:
```
<xsl:template match="xf:group[@appearance='panel']">
```
Deploy your XSL file or files to the cf_webroot\CFIDE\scripts\xsl directory.

Add an include statement to the basic.xsl file at the end of the Supported groups section; for example, if you create a my_group_panel.xsl file to handle a panel cfformgroup type, your basic.xsl file would include the following lines:

<!-- include groups that will be supported for this skin-->
<xsl:include href="_group_vertical_table.xsl" />
<xsl:include href="_group_horizontal_table.xsl" />
<xsl:include href="_group_fieldset.xsl"/>
<xsl:include href="my_group_panel.xsl" />

Styling forms by extending the ColdFusion MX CSS files

Each ColdFusion MX skinnable form XSL file uses a corresponding CSS style sheet to specify the form style and layout characteristics. The following CSS files are located in the cf_webroot\CFIDE\scripts\css directory:

File	Description
basic_style.css default_style.css	Provides a plain style for ColdFusion XSL files that use table-based formatting. These files are identical and are used by the basic.xsl and default.xsl transforms. ColdFusion uses the default_style.css if you do not specify a skin in your `cfform` tag.
basic2_style.css	The basic_style with limited positioning changes for use with XSL files that have div-based formatting. Used by the basiccss.xsl transform.
css_layout.css	Style specifications for laying out forms that use div-based formatting. Used by the basiccss.xsl transform.
colorname_style.css	Used by the color-formatted ColdFusion MX skins. Defines the same classes as basic_style.css, with additional property specifications.

The ColdFusion XSL files and their corresponding CSS style sheets use classes extensively to format the form. The basic.xsl file, for example, has only one element style; all other styles are class-based. Although the CSS files contain specifications for all classes used in the XSL files, they do not always contain formatting information. The horizontal class definition in basic_style.css, which is used for horizontal form groups, for example, is empty.

You can enhance the style of XML skinnable forms without changing the XSL transform by enhancing the style sheets that ColdFusion MX provides.

View comments in LiveDocs