Contents > CFML Reference > ColdFusion Tags > cfprocessingdirective

cfprocessingdirective

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.

Data output tags

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

cfcol, cfcontent, cfoutput, cfsetting, cfsilent, cftable, SetEncoding, Developing Globalized Applications in Developing ColdFusion MX Applications

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.

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.

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

Contents > CFML Reference > ColdFusion Tags > cfprocessingdirective

ColdFusion 8 | ColdFusion MX 7 | ColdFusion MX 6.1 | ColdFusion MX | Forums | Developer Center | Bug Reporting

Version 6.1

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

Comments

Add Comment

chesto said on Jan 9, 2004 at 9:33 AM :

spelling error, change "insformation" on line 2 to "information"

spage said on Mar 3, 2004 at 5:07 PM :

I don't think you can use this in a .cfc to specify encoding, I put:
<cfprocessingdirective pageencoding="utf-8">
on the first line of a trivial .cfc on Solaris and got "JRun Servlet Error 500 Invalid CFML construct found on line 2 at column 1"

Adding a Byte Order Mark (Modify > Page Properties > Title/Encoding in Dreamweaver MX) made it work.

spage said on Mar 3, 2004 at 5:34 PM :

To answer my own comment, if you use the <cfcomponent> tag in a .cfc then it must be the first tag; so put <cfprocessingdirective> after it.

Simon.Harper said on Sep 8, 2004 at 10:17 AM :

To be even more precise, you can do this:

<cfcomponent>
<cfprocessingdirective pageencoding="iso-8859-1">
<cffunction name="show" access="public">
.. etc.,

adi_venuma said on Oct 24, 2004 at 2:14 AM :

i need more explanations please.

jrunrandy said on Oct 24, 2004 at 5:44 PM :

Did you look in the Developing Globalized Applications chapter? http://livedocs.macromedia.com/coldfusion/6.1/htmldocs/i18n.htm#wp1141005

dmw said on Oct 29, 2004 at 6:08 AM :

The example:

<cfprocessingdirective pageencoding=#dynEncoding#>

is misleading as the pageencoding paramater cannot be dynamic. This would actually generate an error 'This expression must have a constant value.'
As it cannot be dynamic and it cannot be conditional this tag is useless if you have a page which must handle multiple character sets dynamically.

mellon@mnr.org said on Nov 18, 2004 at 7:25 AM :

Perhaps you could work around the need for a constant encoding type by making a .cfc for each supported type, and then conditionally calling the correct component.

MarkZet said on Dec 22, 2004 at 3:56 AM :

I have looked into CFMX white space suppressing by decompiling the classes in the CFCLASSES directory. There is an abundance of calls like:
_whitespace(out, "\r\n\r\n\t")
Is this in any way related to suppressWhiteSpace, and can those calls be avoided?

Amalaan said on Jan 20, 2005 at 4:55 AM :

Hi,
You state:
"If you specify only the pageencoding attribute, do not use a separate end tag"
However, is it legal to use an XML-style, empty element closing slash, e..g
<cfprocessingdirective pageencoding="ISO-8859-1" />
The reason I ask is that using a single tag without a closing slash causes the CFC "Methods View" to fail in CFEclipse v.1.1.17.2 .

Amalaan said on Jan 20, 2005 at 6:29 AM :

Apologies, please ignore my post above. I've just noticed that the example at the top of the page does indeed possess a closing slash. Is this a general rule, that all CFML 'empty elements' can be legally terminated with /&gt; ?

mindtrap said on Jan 21, 2005 at 7:15 AM :

What's the difference between:

<cfprocessingdirective pageencoding="utf-8">

and

<cfcontent type="text/html; charset=utf-8">

I'm sure that the underlying Java code is different,.

sillyworm said on Feb 10, 2005 at 10:51 AM :

Hi,

I'm curious as to why in the example here

<cfprocessingdirective suppresswhitespace=#whitespaceSetting#>

you don't have variable #whitespaceSetting# in quotes. Though it works, it seems inconsistent with variable reference in most other tags. It does in fact work with quotes as well. Can you point me to a resource on this? I've seen this in a couple of other tags as well.

Thanks.

alpsauto said on Oct 1, 2006 at 8:01 AM :

it seems even if you set suppresswhitespace="yes", your lines with coldfusion comments will still be displayed as blank lines in the view source (the carriage returns are maintained from the cf comments).

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

Current page: http://livedocs.adobe.com/coldfusion/6.1/htmldocs/tags-b15.htm

Add Comment