Creating XSLT skins



You can create your own XSLT skins to process the XML that ColdFusion generates. You must be familiar with XSLT and CSS programming. General information on writing XSLT transformations or CSS styles is not provided here. However, information about the following areas is provided:

  • How ColdFusion passes form attribute values to the XML file

  • How to extend XSLT skins that ColdFusion 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 extension, ColdFusion 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 Administrator. When you install ColdFusion, 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 uses the directory of the CFML page 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 sometimes move the default skin location folder out of CFIDE. Doing 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 cfformgrouptype 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 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 filenames start with an underscore (_), and multiple base skins share the files. The following table describes the XSL files, which are located in the cf_webroot\\x

File

Description

default.xsl

The default transform that ColdFusion 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 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 filename. 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 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 cfformitemtype 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.

Add support for cfformgroup and cfformitem types to the basic.xsl

  1. Create an XSL file.

  2. For each type attribute that you want to support, create an xsl:template element to do the formatting. The match attribute of the element 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']">

  3. Deploy your XSL file or files to the cf_webroot\\x

  4. 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 CSS files

Each ColdFusion 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 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 provides.