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.

Syntax

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

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.

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 must put the tag within the first 4096 bytes of a page. It can be positioned after a cfsetting or cfsilent tag.
If there are multiple occurrences of the tag in one page with the pageEncoding attribute, the attribute must specify the same value; if not, ColdFusion throws an error.
You cannot embed the tag within conditional logic, because the tag is evaluated when ColdFusion compiles a page (not when it executes the page). For example, the following code has no effect at execution time, because the cfprocessingdirective tag has already been evaluated:
```
<cfif dynEncoding is not "dynamic encoding is not possible">
  <cfprocessingdirective pageencoding=#dynEncoding#>
</cfif> 
```

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:

<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:

If a BOM is present, ColdFusion uses the encoding that it specifies to read and parse the page.
If no BOM is present, ColdFusion uses the system default encoding to read and parse the page.

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">