cfprocessingdirective

Description

Determines whether to suppress the output of extra white space and other CFML output, within the Tag scope. Used with applications that depend on the whitespace characteristics of their output stream.

Category

Data output tags

Syntax

<cfprocessingdirective
  pageencoding = "page-encoding literal string">
or
<cfprocessingdirective
  suppressWhiteSpace = "Yes" or "No"
  pageEncoding = "page-encoding literal string">
  CFML tags
</cfprocessingdirective> 

See also

cfcol, cfcontent, cfoutput, cfsetting, cftable

History

New in ColdFusion MX: You can specify the suppresswhitespace attribute value as a literal string variable. (ColdFusion 5 supported setting it only as a constant.)

New in ColdFusion MX: the pageEncoding attribute is new.

Attributes

Attribute Req/Opt Default Description
suppressWhiteSpace
Optional
 
Boolean. Whether to suppress white space and other output that is generated by CFML tags within a cfprocessingdirective block.
pageEncoding
Optional
 
A string literal; the character encoding to use to read the page. The value may be enclosed in single or double quotation marks, or none.

Usage

If you use the pageEncoding attribute, the following rules apply:

You can specify the suppresswhitespace attribute value as a constant or a variable. To use a variable: define the variable (for example, whitespaceSetting), assign it the value "Yes" or "No", and code a statement such as the following:

<!--- ColdFusion allows suppression option to be set at runtime --->

<cfprocessingdirective suppresswhitespace=#whitespaceSetting#>
    code to whose output the setting is applied
</cfprocessingdirective>

This tag's options do not apply to pages that are included by cfinclude, cfmodule, custom tag invocation, and so on.

Macromedia recommends that you include either the pageencoding or suppresswhitespace attribute; not both.

If you specify only the pageencoding attribute, you must code it within the tag (do not use a separate end tag).

If you specify the suppresswhitespace attribute, you must code it within the start tag, and use and end tag (</cfprocessingdirective).

When the ColdFusion compiler begins processing a page, it searches for a byte order mark (BOM). Processing is as follows:

ColdFusion accepts character encoding names that are defined by the Java platform. If an invalid name is specified, ColdFusion throws an InvalidEncodingSpecification exception.

The following example shows the use of a nested cfprocessingdirective tag. The outer tag suppresses unnecessary whitespace during computation of a large table; the inner tag retains whitespace, to output a preformatted table.

Example

<cfprocessingdirective suppressWhiteSpace = "Yes">
  <!--- CFML code --->
  <cfprocessingdirective suppressWhiteSpace = "No">
    <cfoutput>#table_data#
    </cfoutput>
  </cfprocessingdirective>
</cfprocessingdirective> 

The following example shows the use of the pageencoding attribute:

<cfprocessingdirective pageencoding = "shift-jis">

Comments