CFPROCESSINGDIRECTIVE |
Description
Provides the following insformation to ColdFusion on how to process the current page: Specifies whether to remove excess whitespace character from ColdFusion generated content in the tag body. Identifies the character encoding (character set) of the page contents.
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, cfsilent, cftable, SetEncoding, Chapter 17, "Developing Globalized Applications," in Developing ColdFusion MX Applications
History
ColdFusion MX: Changed suppresswhitespace attribute value behavior: you can specify the suppresswhitespace attribute value as a string variable. (ColdFusion 5 supported setting it only as a constant.) Added the pageEncoding attribute.
Usage
The cfprocssingdirective tag has limitations that depend on the attribute you use. For this reason, Macromedia recommends that you include either the pageencoding or suppresswhitespace attribute in a cfprocessingdirective tag, not both. To specify both values, use separate tags.
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 you use the tag on a page that includes other pages by using the cfinclude or cfmodule tags, custom tag invocation, and so on, the tag has no effect on the included pages. You cannot embed the tag within conditional logic, because the pageEncoding attribute 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>
If you have multiple cfprocessingdirective tags in one page that specify the pageEncoding attribute, they must all specify the same value; if not, ColdFusion throws an error. If you specify only the pageencoding attribute, do not use a separate end tag. ColdFusion accepts character encoding names that are supported by the Java platform. If an invalid name is specified, ColdFusion throws an InvalidEncodingSpecification exception. If a page has a byte order mark (BOM), and a pageengoding attribute specifies an encoding that differs from the BOM, ColdFusion generates an error.
The following rules apply to the suppressWhiteSpace attribute: 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>
The suppresswhitespace attribute only affects code that you put between the <cfprocessingdirective> begin tag and the </cfprocessingdirective> end tag.
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">

SUPPRESSWHITESPACE |
| Optional
Boolean; whether to suppress white space characters within the cfprocessingdirective block that are generated by CFML tags and often do not affect HTML appearance. Does not affect any white space in HTML code.

PAGEENCODING |
| Optional
Default value: "Character encoding identified by the page byte order mark, if any; otherwise, system default encoding" A string literal; cannot be a variable. Identifies the character encoding of the current CFML page. This attribute affects the entire page, not just the cfprocessing tag body. The value may be enclosed in single or double quotation marks, or none. The following list includes commonly used values:: utf-8 iso-8859-1 windows-1252 us-ascii shift_jis iso-2022-jp euc-jp euc-kr big5 euc-cn utf-16 For more information on character encodings, see:www.w3.org/International/O-charset.html.