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

Version 6

Comments are no longer accepted for ColdFusion MX. ColdFusion 8 is the current version.

Comments

sundvor said on Aug 15, 2002 at 5:20 AM :

I would like to see a table of or reference to possible values for the encoding variable. That would be useful.

sundvor said on Nov 7, 2002 at 12:36 AM :

Furthermore, if you put <cfprocessingdirective pageEncoding="UTF-8"> in the application.cfm, everything goes weird-state.

E.g.
<cfprocessingdirective pageEncoding="UTF-8">
<cfset request.doh = 1>
<cfdump var="#request#">

will only display "cfdumpinited TRUE", not "doh 1".

If put in e.g. index.cfm , everything seems to be working fine.

Cheers,
jorgen[at]smith[dot]net

hlichtin said on Feb 28, 2003 at 2:16 PM :

For a list of valid character encodings, see http://java.sun.com/j2se/1.4/docs/guide/intl/encoding.doc.html.

RSS feed | Send me an e-mail when comments are added to this page | Comment Report

Current page: http://livedocs.adobe.com/coldfusion/6/CFML_Reference/Tags-pt214.htm