ColdFusion Objects in the Insertion Bar

[ LiB ]

Developers can access all tags that ship with ColdFusion from the insert bar in a ColdFusion page in a ColdFusion site. Most of the common ColdFusion tags have their own icons. Some ColdFusion tags are available to insert from the More Tags dialog box.

Server Variables

Server variables are tremendously useful constructions that return information about the environment of the browser, the server, and the page that is requesting information. You can use server variables to return information to the screen when the server variable is wrapped in a CFOUTPUT tag. You also can use the variable in a query to insert data into a database. When you click the server variable icon in the CFML insert bar, you can select one of several variables from a drop-down list, as shown in Figure 24.1. You can insert as many server variables as you like, but you have to insert them one at a time.

Figure 24.1. The Server Variable dialog box.

The server variables are as follows :

• ALL_HTTP Returns all the HTTP information for the request from the browser.

• AUTH_PASS Returns the password that the user logged in as if the server supports user authentication.

• AUTH_TYPE Returns the authentication method used to validate the user if the server supports user authentication.

• CONTENT_LENGTH Returns the length of the content.

• CONTENT_TYPE Lists whether the query is using GET or PUT to interact with the server.

• GATEWAY_INTERFACE Lists the revision of the CGI on the server.

• PATH_INFO The return path to the requested page from the root of the application.

• PATH_TRANSLATED Returns the physical address of the page on the server.

• QUERY_STRING Displays the query information following the ? when a form is submitted.

• REMOTE_ADDR The IP address of the remote browser that is hitting the page.

• REMOTE_HOST The hostname of the server that is hitting the page. If the server does not have this feature enabled, it returns the REMOTE_ADDR.

• REMOTE_IDENT If the HTTP server is configured to support RFC 931 identification, this returns the remote username from the server.

• REMOTE_USER If the server supports user authentication, the username that the user used to log in is returned.

• SCRIPT_NAME The path to the script that is executing.

• SERVER_NAME The name of the server, IP address, or DNS alias from the server.

• SERVER_PORT The port number that the request was sent to.

• SERVER_PROTOCOL Shows the server's protocol and the version number. (Usually this is HTTP.)

• SERVER_SOFTWARE Returns the server software and version of the remote server.

Inserting the HTTP_ALL server variable inside a CFOUTPUT tag looks like this:

 <cfoutput>#CGI.HTTP_ALL#</cfoutput> 

and returns this:

 HTTP_ACCEPT:*/* HTTP_ACCEPT_LANGUAGE:en-us  HTTP_CONNECTION:Keep-Alive HTTP_HOST:www.3981.com  HTTP_REFERER:http://localhost/test/TMPwtvOnhbkmb.cfm  HTTP_USER_AGENT:Mozilla/4.0 (compatible; MSIE 6.0; Windows  NT 5.1; .NET CLR 1.1.4322) HTTP_CONTENT_LENGTH:13  HTTP_CONTENT_TYPE:application/x-www-form-urlencoded  HTTP_ACCEPT_ENCODING:gzip, deflate HTTP_CACHE_CONTROL:no-  cache 

Note that you get the host, the URL of the page that called the page with the server variable, the user agent or browser type, and the version all in one server variable.

CFQUERY

The CFQUERY tag is inserted when you create a Recordset (Query) from the Application panel. When you insert the CFQUERY from the Insert menu, many more attributes are available to set, but you don't have the query builder or the ability to test the connection.

The general attributes for CFQUERY are as follows:

• Query Name (required)The query's name. This is how you reference the query in the code to display data. The query's name should not have spaces.

• Data Source (required)The name of the ODBC datasource that you have set up in the ColdFusion Administrator.

• User Name (optional)The database's username (if one is set).

• Password (optional)The password for the database (if there is one).

• SQL (required)The SQL that goes between the opening and closing CFQUERY tag.

Inserting the CFQUERY tag produces code like this:

 <cfquery name="getemployees" datasource="employeedatabase"> SELECT * FROM employeetable </cfquery> 

This code returns a set of data of all the records in the employee table in the employee database.

CFOUTPUT

CFOUTPUT, as shown in Figure 24.2, is the tag used to display information from a query or other operation to the browser.

Figure 24.2. The CFOUTPUT dialog box.

The attributes for CFOUTPUT are as follows:

• Query Name (optional)The name of the query that contains the data you want to display. When you add the name attribute, you create a loop in which each returned record is output in the order in which it was received from the query.

• Group Field (optional)The name of the field you want to use to group your results. For example, a query that gets the information for all the employees in a database lets you group the results by department or last name or some other field you specify.

• Start Row (optional)The row of data from which to begin showing data. If your result set of data from the query has 30 records, setting the Start Row to 100 displays only records 100 through 130. This attribute requires that the name attribute be set.

• Max Rows (optional)Sets the maximum number of records shown from the result set of data from the query. If your query has 30 records with Start Row set to 10 and Max Rows set to 10, the output shows only records 10 through 20. This attribute requires that the name attribute be set.

• Group Case Sensitive (optional)SQL query results are generally case-insensitive. Use this attribute if you want to group your results and respect their case.

Inserting the CFOUTPUT tag produces code like this:

 <cfoutput query="getemployees" group="department"  startrow="100" maxrows="100"></cfoutput> 

To display the results in the browser, you would reference each field name you want to display, wrapped in # signs between the beginning and end of the CFOUTPUT tag:

 <cfoutput query="getemployees" group="department" startrow="10"  maxrows="10"> #LastName#, #FirstName#, #Department#<br> </cfoutput> 

The result in the browser looks like this:

Smith, Bill, Accounting

Wilson, James, Accounting

Washington, Martha, Accounting

Russell, Dave, Engineering

Mugler, Sarah, Engineering

Louis, Ben, Engineering

Brown, Matt, Executive Staff

Davis, Karen, Human Resources

Davis, Andy, Human Resources

Lyons, Aaron, Human Resources

CFINSERT

CFINSERT inserts data from a form into a database table. This is shorthand for a SQL insert query.

The attributes for CFINSERT are slightly more confusing than other tags. There are more attributes available than you should use. Dreamweaver MX 2004 allows the development of ColdFusion documents for ColdFusion MX and earlier versions. The dialog includes attributes for connectString , dbName , dbServer , dbtype , provider , and providerDSN . These are all deprecated and should not be used if you are working with ColdFusion MX.

For the CFINSERT tag to work properly, you need to have the form elements named the same as the fields in your database for ColdFusion to map the data from the form to the database.

CFINSERT works only with forms using the post method. It fails silently if the form uses the get method.

Why would you use CFINSERT rather than a regular SQL update query? Because it is easier to type the CFINSERT tag, and it allows less room for errors than an insert query, which can get messy. However, it has the limitation of not being able to insert into multiple tables, and it cannot accept any input that doesn't come through a form.

If the table you are inserting data into has a primary key that is not auto-generated, CFINSERT must have a field from the form passed that is inserted into that key, or it generates an error. If you have a key that is auto-generated, it works fine.

The CFINSERT attributes that are valid for ColdFusion MX are as follows:

• Data Source (required)The datasource into which you want to insert the record.

• User Name (optional)The username (if one is needed) to access the database being inserted into.

• Password (optional)The password (if one is needed) to access the database being inserted into.

• Table Name (required)The name of the table you need to insert data into.

• Table Owner (optional)An optional attribute for databases that support table ownership, such as SQL Server and Oracle.

• Table Qualifier (optional)An optional attribute for databases that support table ownership, such as SQL Server and Oracle.

• Form Fields (optional)A comma-delimited list of fields you want to insert into the datasource. This attribute is optional. If you don't specify the form fields attribute, CFINSERT processes all the form fields. In effect, you use the Form Fields option to limit the fields you want to process to only the fields you list.

Here's an example:

 <cfinsert datasource="employeedata" tablename="employees"  formfields="FirstName, LastName, Department"> 

This code takes the data entered in a form that has fields named FirstName, LastName, and Department and inserts those values into the employees table of the employeedata datasource.

CFUPDATE

CFUPDATE updates data from the form into a database table. This is shorthand for a SQL update query.

The attributes for CFUPDATE, like CFINSERT, are slightly more confusing than other tags. There are more attributes available than you should use. Dreamweaver MX 2004 allows the development of ColdFusion documents for ColdFusion MX and earlier versions. The dialog box includes attributes for connectString , dbName , dbServer , dbtype , provider , and providerDSN . These are all deprecated and should not be used if you are working with ColdFusion MX.

CFUPDATE works only with forms using the post method. It fails silently if the form uses the get method.

Like CFINSERT, the names of the fields in the form must match the field names in the database for the CFUPDATE tag to be able to map the data correctly.

The CFUPDATE attributes that are valid for ColdFusion MX are as follows:

• Data Source (required)The datasource into which you want to insert the record.

• User Name (optional)The username (if one is needed) to access the database being inserted into.

• Password (optional)The password (if one is needed) to access the database being inserted into.

• Table Name (required)The name of the table you need to insert data into.

• Table Owner (optional)An optional attribute for databases that support table ownership, such as SQL Server and Oracle.

• Table Qualifier (optional)An optional attribute for databases that support table ownership, such as SQL Server and Oracle.

• Form Fields (optional)A comma-delimited list of fields you want to insert into the datasource. This attribute is optional. If you don't specify the form fields attribute, CFINSERT processes all the form fields. In effect, you use the Form Fields option to limit the fields you want to process to only the fields you list.

Here's an example:

 <cfupdate datasource="employeedata" tablename="employees"  formfields="FirstName, LastName, Department"> 

This code takes the data entered in a form that has fields named FirstName, LastName, and Department and updates those values in the employees table of the employeedata datasource.

CFINCLUDE

CFINCLUDE includes a ColdFusion file at the location of the tag in the document. This allows the developer to encapsulate functionality into separate files and then reuse them in multiple locations. It is also a great way to include footers and headers in documents that can be updated separately from the main file.

CFINCLUDE has only one required attribute template which points to the location of the file you want to include.

Here's an example:

 include file footer.cfm <address>123 Elm Street </address> 

Here's a sample file with CFINCLUDE calling the footer.cfm file:

 <html> <head> <title>My page</title> </head> <body> <h1>lots of things to say</h1> <p>Maybe not so much</p> <cfinclude template="footer.cfm"> </body> </html> 

Here's the resulting code in the browser:

 <html> <head> <title>My page</title> </head> <body> <h1>lots of things to say</h1> <p>Maybe not so much</p> <address>123 Elm Street </address> </body> </html> 

CFLOCATION

CFLOCATION redirects the browser to the specified URL. If you check the Append Client Variables to the URL check box, the parameters after the ? in the URL that calls the CFLOCATION are sent to the new URL that the CFLOCATION redirects to.

CFLOCATION has two attributes:

• URL (required)The URL of the HTML or CFML file you want your user to be redirected to.

• Addtoken (optional)Appends the parameters after the ? from the calling URL to the URL to the new page that the user is being redirected to. If the addtoken is not specified, it defaults to yes.

Here's an example:

 <html> <head> <title>My page</title> </head> <body> <p>You are being redirected to a new address.</p> <cflocation url="newresults.cfm"> </body> </html> 

When the user gets to this page, he or she is redirected to the newresults.cfm page.

When you use the CFLOCATION tag, it is processed in the order of tags on the page. If you include a CFLOCATION tag in a page after a CFUPDATE or CFINSERT, that CFUPDATE or CFINSERT is executed before the CFLOCATION is executed. This is very handy to use in different cases of CFIF clauses to route users to failure pages or login pages.

CFSET

CFSET sets a ColdFusion variable in your code.

Here's an example:

 <html> <head> <title>My page</title> </head> <body> <cfset foo = "bar"> My cat is named <cfoutput> #foo# </cfoutput>! </body> </html> 

This code displays the following:

My cat is named bar!

CFPARAM

CFPARAM tests for the existence of a variable and sets its type. It also can set a default value for the variable. This tag is used to test whether a variable exists and if it is a specified type. It also allows you to set the value of the variable if it does not exist.

CFPARAM has three attributes:

• Name (required)The name of the variable you're testing.

• Default (optional)Sets the value of the variable if it is not already set.

• Type (optional)Sets the variable's data type. The choices are any , array , binary , boolean , date , numeric , query , string , struct , UUID , and variableName .

Here's an example:

 <html> <head> <title>My page</title> </head> <body> <cfset foo="cat"> <cfparam name="foo"> My cat is named <cfoutput> #foo# </cfoutput>!<br> <cfparam name="pooh" default="bear"> My dog is named <cfoutput> #pooh# </cfoutput>! </body> </html> 

When this code is executed, it sets a variable named foo with a value of cat . The value is checked to exist with the first CFPARAM and is output in the next line. The second CFPARAM checks for a variable called pooh , which has not been defined. Then, with the default attribute, it assigns a value of bear , which is output in the next line.

This produces the following in the browser:

My cat is named cat!

My dog is named bear!

ColdFusion Comments

ColdFusion uses a special comment syntax for comments it should not process or render. ColdFusion comments use <!---...---> instead of <!--...-->. The ColdFusion Comments object takes your selection and wraps it in ColdFusion comments. Normal HTML comments are sent to the browser, but ColdFusion comments are not passed to the browser.

Surrounding Variables with #...#

ColdFusion treats everything between # signs as a server variable. When you are hand-coding, you can type your variable names, highlight them, and wrap them in # signs. This is a very handy hand-coding feature.

CFSCRIPT

ColdFusion has a less-used syntax of CFSCRIPT that allows you to code ColdFusion in a script syntax more like PHP or ASP. This is seldom used, but it is available to you in Dreamweaver MX 2004. When you insert a CFSCRIPT object into your document, Dreamweaver simply inserts a beginning and end CFSCRIPT tag and centers the insertion point in the middle so that you can begin scripting.

Here's an example:

 <cfscript></cfscript> 

CFTRY and CFCATCH

CFTRY and CFCATCH are debugging and error-handling tags that work together to process exceptions in ColdFusion pages. An exception is any event that disrupts the flow of the instructions on the page, such as missing include files, failed database operations, or events specified by the developer.

Developers need to build error-catching into industrial-strength applications.

Each CFTRY must have at least one CFCATCH. It may have more CFCATCHes to test for more than one problem. ColdFusion processes the CFCATCH tags in the order they appear in the code. See Figure 24.3.

Figure 24.3. CFCATCH options.

CFCATCH has the following attribute:

• Exception Type (optional)The type of exception the CFCATCH is looking for. The choices are application , database , template , security , object , missinginclude , expression , lock , custom_type (catches developer-defined exceptions defined in a CFTHROW tag), searchengine (catches Verity search engine exceptions), and any (catches all exceptions). If you do not specify one of the exception types, the tag defaults to all .

Here's an example:

 <cftry> <!--- Note the misspelled tablename "employees" as "eemployees"  --->   <cfquery name = "getemployees" datasource = "employeedatabase">     SELECT *     FROM eemployees   </cfquery>   <cfcatch type = "Database">     <p>You've encountered a database Error</p>     <cfoutput>       <!--- and the diagnostic message from the ColdFusion  server --->       <p>#cfcatch.message#</p>       <p>Caught an exception, type = #CFCATCH.TYPE# </p>     </cfoutput>   </cfcatch> </cftry> 

In this code, instead of just adding a query, the query is inside the CFTRY and has a CFCATCH to check for a database error. Because the name of the employees table is misspelled, the code inside the CFCATCH is executed. If there were no error, the page would process normally. If the CFCATCH were not there, ColdFusion would either throw an error or fail silently.

CFTHROW

CFTHROW is used in a CFTRY block. It can be caught by a CFCATCH tag with the custom_type , application , or any type.

The CFTHROW tag has the following attributes:

• Type (optional)An application or a custom type. If application is specified, you don't need to specify a type for CFCATCH.

• Message (optional)A message that describes the exception event.

• Detail (optional)A description of the event.

• ErrorCode (optional)A custom error code that you supply.

• ExtendedInfo (optional)A custom error code that you supply.

• Object (optional)Throws a Java exception when using CFOBJECT. Requires the value of the name of the CFOBJECT. If you use this attribute, you cannot use any other attribute for the CFTHROW tag.

Here's an example:

 <cftry> <cfif NOT IsDefined("URL.employeeid")>    <cfthrow message = "employeeid is not defined"> </cfif> <cfcatch type = "application"> <cfoutput>    <p>You have thrown an exception</p>    <p>#cfcatch.message#</p> </cfoutput> </cfcatch> </cftry> 

In this code, a CFTRY block is opened, and a condition is tested . If the test is true, the CFTHROW is executed, and a custom message is written. In the CFCATCH tag, if there is an error from the CFTHROW, the code in the CFCATCH block is executed.

CFLOCK

CFLOCK locks processes on a page temporarily so that multiple requests don't execute at the same time. CFLOCK has two kinds of locks. Exclusive locks allow only one request to be processed at a time. No other requests can begin processing until the first request is finished. Read-only locks allow multiple requests , but only to read data, not to write or modify data. If a request has an exclusive lock on shared data, the read-only lock waits for the exclusive lock to terminate.

In production, CFLOCK is used to ensure that modifications to shared data are made sequentially so that no two requests try to write to the same data at the same time. Also, if you are using any file manipulation, CFLOCK ensures that only one request writes to a file at one time. If two requests try to write to the same file, one request fails.

The CFLOCK tag has the following attributes:

• Name (optional)Only one request can execute within this tag with a given name. This lets different parts of your application have access to data but provides more-specific control than the scope attribute. You can use either the name attribute or the scope attribute, but not both.

• Timeout (required)The maximum length of time in seconds for the lock to remain in place.

• Type (optional)Read-only locks allow more than one thread to read data, but not write. Exclusive locks allow one request to read or write shared data.

• Scope (optional) application sets the lock to cover the application so that only the one application defined in the Application.cfm file can access the data. server sets the lock to all the applications on the server. session locks the data to only the active session. You can use either the scope or the name attribute, but not both.

• Throw On Timeout (optional)Tells the timeout attribute to behave when the timeout is reached. yes generates an exception (that you can catch with CFCATCH). no allows the request's execution to continue without an error.

Here's an example:

 <cflock scope = "Session" timeout = "30" type = "Exclusive">     <cfif NOT IsDefined("session.username")>       <cfset session.username = "guest">     </cfif>     <cfif NOT IsDefined("session.password")>       <cfset session.password = "guest">     </cfif> </cflock> 

This code locks the session for 30 seconds. The code takes a lot less time, but in 30 seconds, if it cannot execute for some reason, it throws an error. If it does execute, it checks to see whether a username and password are assigned in the session. If they are not, it sets both the username and password to "guest."

CFSWITCH , CFCASE, and CFDEFAULTCASE

CFSWITCH, CFCASE, and CFDEFAULTCASE are related flow control tags that allow you to branch your function to achieve different results based on results that occur while processing a page. CFSWITCH evaluates a passed expression and then passes control to a CFCASE that corresponds to the result. The CFDEFAULTCASE provides the default behavior if the CFSWITCH does not evaluate to any of the CFCASEs available in the CFSWITCH code block.

Here's an example:

 <cfquery name = "GetEmployees" dataSource = "employees">   SELECT  *   FROM  Employees </cfquery> <cfoutput query="GetEmployees"> <cfswitch expression="#Trim(Department)#">   <cfcase value="Sales">     #FirstName# #LastName# is in sales<br>   </cfcase>   <cfcase value="Accounting, Administration" delimiters=",">     #FirstName# #LastName# is in accounting or administration<br>   </cfcase>   <cfdefaultcase>     #FirstName# #LastName# is not in sales or accounting or  administration.<br>   </cfdefaultcase> </cfswitch> </cfoutput> 

This code queries a database to get a returned data set of all the employees. A CFOUTPUT is started that loops through and prints all the names in the database; however, the CFSWITCH catches each record and evaluates what department each employee is in. If the department is Sales, it prints the first name and last name, with a note that the person is in sales. If the department is Accounting or Administration, then it prints the first name and last name with a note that the person is in accounting or administration. If the employee is in any other department, the CFDEFAULTCASE kicks in, and the first name and last name are printed with a note that the employee is not in sales, accounting, or administration.

The CFSWITCH tag has one attribute, expression (required), which sets the expression to evaluate to determine which case to pass the request to.

The CFCASE tag has two attributes: value (required) and delimiters (optional). The value is the possible result of the expression that the CFSWITCH evaluates. delimiters is the character that separates the values in the list if you want a CFCASE to execute for more than one value. The default delimiter is a comma.

CFDEFAULTCASE has no attributes.

CFIF, CFELSE, and CFELSEIF

CFIF, CFELSE, and CFELSEIF are flow-control tags like CFSWITCH, CFCASE, and CFDEFAULTCASE. The difference between CFIF and CFSWITCH is that CFSWITCH executes faster than CFIF, although CFSWITCH can check against only one expression. CFIF can check against multiple expressions, one in each CFIF or CFELSE tag.

Here's an example:

 <cfquery name = "GetEmployees" dataSource = "employees">   SELECT  *   FROM  Employees </cfquery> <cfoutput query="GetEmployees"> <cfif Trim(Department) is "Sales" OR Trim(Department) is  "Accounting" >     #FirstName# #LastName# is in #Department#<br> <cfelseif Trim(Department) is "Administration" >     #FirstName# #LastName# is in Administration and available  to answer questions.<br> <cfelseif Trim(Department is "Engineering")>     <b>Engineers rule and #FirstName# is one of them</b> <cfelse>     #FirstName# is not in any of the departments we're looking  for. </cfif> </cfoutput> 

This code queries a database to get a returned data set of all the employees. A CFOUTPUT is started that loops through and prints all the names in the database. However, the CFIF/CFELSEIF/CFELSE catches each record, evaluates what department each employee is in, and prints different results based on the department. This example could easily be done with a CFSWITCH.

Here's an example:

 <cfquery name = "GetEmployees" dataSource = "employees">   SELECT  *   FROM Employees </cfquery> <cfoutput query="GetEmployees"> <cfif Trim(Department) is "Sales" AND Trim(Region) is "West  Coast" >     #FirstName# #LastName# is in #Department# for the West  Coast<br> <cfelse>     #FirstName# #LastName# is in #Department# for non-West  Coast regions.<br> </cfif> </cfoutput> 

This code could not be done with a CFSWITCH because in the CFIF, two expressions are evaluatedthe department and the region.

The CFIF and CFELSEIF tags have no attributes other than the expression they are evaluating. CFLESE has no attributes.

CFLOOP and CFBREAK

CFLOOP allows you to loop through a set of commands in a number of different ways:

• An index loop repeats for a set number of times, as defined by a numeric value. Traditionally, this is known as a for loop.

• A conditional loop repeats a set of instructions as long as the condition is true. Traditionally, this is known as a while loop.

• Looping over a query is very much like a CFOUTPUT, in which the instruction is repeated for each member of the returned dataset from a CFQUERY.

• Looping over a list or file steps through lists contained in variables, values returned from an expression, or a file.

• Looping over a COM collection or structure loops over a COM collection or object.

CFBREAK is used in CFLOOP constructions to terminate the loop in a given set of circumstances. Usually it is found in a CFIF inside the loop that is checked for every iteration of the loop.

The CFLOOP index loop has the following attributes:

• Index (required)This counter is incremented or decremented by the CFLOOP as it iterates. When it equals the to value, the loop stops.

• From (required)The index's beginning value.

• To (required)The index's ending value.

• Step (optional)The increment by which the index is changed with each iteration. If the step attribute is not set, this defaults to 1.

Here's an example of an index loop:

 <cfloop index = "counter" from = "1" to = "5" step = "1">   <cfoutput>The index of the loop is #counter#</cfoutput>.<br> </cfloop> 

This block of code produces the following in the browser:

The index of the loop is 1.

The index of the loop is 2.

The index of the loop is 3.

The index of the loop is 4.

The index of the loop is 5.

The CFLOOP conditional loop has only one attributethe condition that is required for the tag. The condition is tested with every iteration; while it is true, the loop continues.

Here's an example:

 <cfset CountVar = 0> <cfloop condition = "CountVar LESS THAN OR EQUAL TO 5">   <cfset CountVar = CountVar + 1>   The loop index is <cfoutput>#CountVar#</cfoutput>.<br> </cfloop> 

This code block sets a variable called CountVar to 0. The loop checks to see if the value of CountVar is less than or equal to 5. If it is, CountVar is increased by 1 in a CFSET tag, and the loop index is printed. The loop is repeated, and now CountVar equals 1. This continues until CountVar equals 5. At that point, the condition is false and the loop stops.

CFCOOKIE

The CFCOOKIE tag defines browser cookies, including cookies with security and expiration options.

The CFCOOKIE tag has the following attributes:

• Name (required)The name of the cookie variable.

• Value (optional)The value to assign to the cookie variable.

• Expires (optional)Specifies when the cookie expires. This can be a date, a number of days, now, or never.

• Path (optional)A subset of a domain to which the cookie applies. You might want the cookie to apply to only a portion of your site.

• Domain (required if the path attribute is specified)The domain in which the cookie is valid. You have to start the domain with a period, such as .newriders.com . For domains that end in a country code, you need to include the last three components of the domain, as in .tepapa.gov.nz . You cannot use an IP address as a domain.

• Transmit cookie securely (SSL) (optional)Requires that the browser support Secure Sockets Layer (SSL), or the cookie is not sent.

Here's an example:

 <cfif IsDefined(#Form.username#)>     <cfcookie name="username"       value="Form.username"       expires="5">     <cfcookie name="Cookie.userIPaddress"       value="#CGI.REMOTE_ADDR#"       expires="5"> </cfif> <cfoutput> The username is #Cookie.username# and their IP address is  #userIPaddress# </cfoutput> 

This code checks to see if data is passed from a form with a field called username. If there is, it writes a cookie with the username from the form and the IP address of the visitor from a server variable.

CFCONTENT (Advanced)

CFCONTENT downloads a file from the server to the client.

For more information on the CFCONTENT tag, consult the ColdFusion documentation that was installed with your ColdFusion server.

CFHEADER (Advanced)

CFHEADER generates custom HTTP responses to send to the client.

For more information on the CFHEADER tag, consult the ColdFusion documentation that was installed with your ColdFusion server.

ColdFusion Page Encoding (Advanced)

The ColdFusion Page Encoding object inserts a set of tags in the head of the document. You can modify them to set the page encoding for other character sets for foreign languages.

For more information on the Page Encoding tag, consult the Function Reference in the ColdFusion documentation that was installed with your ColdFusion server.

CFAPPLICATION

CFAPPLICATION defines the scope of a ColdFusion application, controls the storage of client variables, enables session variables, and sets various timeouts. This tag is typically used in the Application.cfm file that sets all the defaults for a ColdFusion application. (Case is important in the filename. The filename must be initial cap.)

The attributes of the CFAPPLICATION tag are as follows:

• Application Name (required)The application's name, such as Employee_Stock_Benefit_Application

• Session Timeout (optional)Sets the lifespan of session variables using the CreateTimeSpan function. For this option, Client Management must be enabled in the ColdFusion Administrator.

• Application Timeout (optional)Sets the lifespan of application variables using the CreateTimeSpan function.

• Client Storage (optional)Sets where client variables are stored. The choices are datasource_name , which sets the storage in an ODBC datasource, registry , which uses the system registry, and cookie , which stores client variables on the client computer. For this option, Client Management must be enabled in the ColdFusion Administrator.

• Enable client variables (optional) yes enables client variables. no (the default) blocks client variables.

• Enable session variables (optional) yes enables session variables. no (the default) blocks session variables.

• Set client cookies (optional) yes enables client cookies. no means that CFID and CFToken must be passed to each page that requires them manually via the URL or some other method.

• Set domain cookies (optional) yes sets the CFTOKEN and CFID cookies for a domain. no means that CFID and CFToken must be passed to each page that requires them manually via the URL or some other method. This is primarily for use in clustered server environments.

You need to have this turned on to use the default login and authentication server behaviors.

Here's an example:

 <cfapplication name="GetUsers" clientmanagement="no" sessionmanagement="yes" setclientcookies="no" setdomaincookies="no"> 

This code sets an application name of GetUsers and sets session management to yes . This would be the entire contents of an Application.cfm file needed to use the login and authentication behaviors in Dreamweaver MX 2004.

CFERROR (Advanced)

CFERROR displays a custom HTML page when an error occurs, letting you set up custom error pages to match your site's look and feel.

For a full explanation of the CFERROR tag and all the available error variables, consult the ColdFusion documentation that was installed with your ColdFusion server.

The CFERROR tag has the following attributes:

• Error Type (required)The type of error handled. The choices include application , database , template , security , object , missinginclude , expression , lock , custom_type , and any .

• Message Template (required)The path to a custom error page.

• Administrator Email (optional)An email address for the site's administrator.

• Exception The type of the exception throwneither an exception of the CFTRY tag or a custom exception in a CFTHROW tag.

Here's an example:

 <cferror type = "database"    template = "customerror.cfm"    mailTo = "[e-mail]"> 

This code returns an error and calls a custom error page that can list error variables for the user.

CFDIRECTORY (Advanced)

The CFDIRECTORY tag allows ColdFusion to interact with directories on the server to create, delete, and rename folders and to list the files in a given directory. To use the tag, it must be enabled in the ColdFusion Administrator.

Enabling CFDIRECTORY allows people to delete or rename directories. Be sure that you want this available on your server and that you have adequate protections enabled.

CFDIRECTORY has the following attributes:

• List:

• Directory (required)The absolute pathname to the directory you are listing.

• Query Name (required)The name of the output recordset of listed files.

• File Filter (optional)The file extension filter to return only files of a certain type.

• Sort Specification (optional)Sets the sort order of the list of the files returned.

• Create:

• Directory (required)The absolute pathname to the directory you are creating.

• Mode (optional)Octal values for permissions uploaded. Solaris and HP-UX only.

• Delete:

• Directory (optional)The absolute pathname to the directory you are deleting.

• Rename:

• Directory (optional)The absolute pathname to the directory you are renaming.

• New Directory (optional)The directory's new name.

CFFILE (Advanced)

The CFFILE tag allows ColdFusion to transfer files from the client browser to the server, move files on the server, rename files on the server, copy files on the server, delete files on the server, read files on the server, read files as binary on the server, write files on the server, and append files on the server. The syntax and attributes for each function are different. For a full explanation of the CFFILE tag, consult the ColdFusion documentation that was installed with your ColdFusion server.

This tag needs to be enabled in the ColdFusion Administrator.

Using the CFFILE tag to upload files can create a security problem for your server by introducing files that have not been checked for viruses.

The CFFILE tag to upload files to the server from the browser has the following attributes:

• Action (required) upload in this case. Other options are copy , move , rename , delete , append , write , read , and read binary .

• File Field (required)The name of the form field used to select the file. You do not need to use # signs around the name of the field for this tag.

• Destination Path (required)The absolute pathname of the directory or file on the server. The trailing slash in the directory name is optional in ColdFusion MX.

• Accept Files (optional)Limits the MIME type of files to accept. A comma-delimited list of file types.

• Attributes (optional)You can set the file to be hidden, read-only, or normal on the server after uploads.

• Mode (optional)Octal values for permissions uploaded. Solaris and HP-UX only.

• Filename Resolution (optional)Specifies what the server should do when the file is uploaded if the filename is not unique. error does not save the file and returns an error to the user. skip does not save the file and skips. overwrite overwrites the file on the server if the filename is the same as the uploaded file. MakeUnique makes a unique filename for the uploaded file if there is a file of the same name on the server in the directory specified.

Here's an example:

 <cffile action = "upload"   fileField = "contents"   destination = "c:\inetpub\wwwroot\uploads\"   accept = "text/html"   nameConflict = "MakeUnique"> 

This code uploads a file specified in a form with a field called contents. The file is saved to the server to the c:\inetpub\wwwroot\uploads\ directory. (This presents a security problem, because the file is sent to a directory on the server within the web root, where it can be accessed by any user who figures out the path. If this were a virus, you would be in big trouble. For a more secure location, upload the files to a folder outside the web root.) The server accepts HTML files and makes the filename unique so as not to overwrite existing files.

The CFFILE tag to write a file to the server has the following attributes (see Figure 24.4):

Figure 24.4. The CFFILE dialog box.

• Action (required) write in this case. Other options are copy , move , rename , delete , append , read , and read binary .

• Write to File (required)The absolute pathname to the file on the web server. Remember to use backslashes in Windows.

• Attributes (optional)You can set the file to be hidden, read-only, or normal on the server after uploads.

• Mode (optional)Octal values for permissions uploaded. Solaris and HP-UX only.

• Output String (required)The content of the file being written. Most of the time, this contains dynamic data that you will want to create by hand in the code after the object has been inserted in the document.

• Add New Line (optional)Appends the newline character to the ends of lines written to the file.

Here's an example:

 <cffile action = "write"   file = "c:\files\updates\#Form.FileName#.txt"   output = "#Form.Content#"> 

This code creates a file in the location specified, the title of which is specified in a form with a field called file. The contents of the file come from the Content field in the output attribute. The output could also have come from a CFQUERY.

CFMAIL (Advanced)

The CFMAIL tag allows ColdFusion to send mail from your application if your server administrator has enabled the mail features in the ColdFusion server. For a full explanation of the CFMAIL tag, consult the ColdFusion documentation that was installed with your ColdFusion server.

The CFMAIL tag has the following attributes (see Figure 24.5):

Figure 24.5. The General section of the CFMAIL dialog box.

• General:

• To (required)The address or addresses of the mail's recipients. This can be generated dynamically from a query.

• From (required)The sender of the emaileither a static string or dynamic data.

• Subject (required)The message subject. It can be static or dynamically generated.

• CC (optional)The address or addresses to copy the mail to.

• BCC (optional)The address or addresses to blind-copy the mail to.

• Dynamic Content:

• Query Name (optional)The name of a CFQUERY to draw data from for the mail.

• Group Field (optional)Sets the field on which to group your mail if you are getting the data dynamically. For instance, you can group on CustomerID to send out a set of records in one mail that relate to that CustomerID.

• Group Case Sensitive (optional)Specifies whether to consider case in the grouping.

• Start Row (optional)The row in the query to start from.

• Max Rows (optional)The maximum number of rows to return from the query.

• Message Body:

• Message Type (optional)Informs the receiving mail client that there is HTML in the message if the mail client previews HTML content in emails.

• Message A quick way to insert the content that goes out in the body of the mail. You'll probably want to hand-edit this portion of the mail after inserting the object.

• MIME Attachments:

• MIME Attachment (optional)The path to a MIME-encoded file attached to the mail.

• Server Settings:

• Server (optional)The SMTP server address to send messages. A server has to be specified here or in the ColdFusion Administrator. Any setting here overrides the setting in the ColdFusion Administrator.

• Port (optional)The TCP/IP port for the SMTP server.

• Timeout (optional)The number of seconds to wait for an SMTP server to respond.

Here's an example:

 <cfif IsDefined("form.mailto")>   <cfif form.mailto is not ""         AND form.mailfrom is not ""         AND form.Subject is not "">     <cfmail to = "#form.mailto#"         from = "#form.mailfrom#"         subject = "#form.subject#">         #form.body#     </cfmail>     <p>Thank you, <cfoutput>#mailfrom#: your message,  #subject#, has been sent to #mailto#</cfoutput>.   </cfif> </cfif> 

This code sends mail to a recipient defined in the mailto field of the form that calls this .cfm page. The first line checks to see if the mailto field exists in the URL that calls the page. If there is a variable in the URL called mailto, the code checks to see whether the values mailto , mail-from , and subject are not empty. If there is data in each field of the form, the page adds the contents of the body field inserted into the mail and sends the mail. Note that the form does not check to see if the body is empty.

CFPOP (Advanced)

The CFPOP tag allows ColdFusion to receive and manipulate mail in POP3 mailboxes. You can use this tag to create your own mail client in the browser if your administrator has enabled the mail features of the ColdFusion server.

The CFPOP tag has many attributes and features. For a full explanation of the CFPOP tag, consult the ColdFusion documentation that was installed with your ColdFusion server.

CFHTTP and CFHTTPPARAM (Advanced)

CFHTTPPARAM is a required tag for a CFHTTP to set the name and type of parameter passed with a POST operation.

For more information on the CFHTTP and CFHTTPPARAM tags consult the ColdFusion documentation that was installed with your ColdFusion server.

CFLDAP (Advanced)

CFLDAP provides an interface to a Lightweight Directory Access Protocol (LDAP) server. The tag also allows you to search, add, edit, and delete data.

For more information on the CFLDAP tag, consult the ColdFusion documentation that was installed with your ColdFusion server.

CFFTP (Advanced)

CFFTP controls FTP operations between the ColdFusion server and FTP sites. The CFFTP tag does not move files from the browser to the ColdFusion server. To move files from a browser to the server, use the CFFILE tag.

For more information on the CFFTP tag, consult the ColdFusion documentation that was installed with your ColdFusion server.

CFSEARCH (Advanced)

CFSEARCH searches Verity collections using either the ColdFusion or K2Server, depending on which search engine the collection is registered by.

For more information on the CFSEARCH tag, consult the ColdFusion documentation that was installed with your ColdFusion server.

CFINDEX (Advanced)

CFINDEX populates a Verity search engine collection with a list of documents from the file system or from the results of a CFQUERY.

For more information on the CFINDEX tag, consult the ColdFusion documentation that was installed with your ColdFusion server.

CFMODULE (Advanced)

CFMODULE invokes a custom tag that is installed on your server.

For more information on the CFMODULE tag, consult the ColdFusion documentation that was installed with your ColdFusion server.

CFOBJECT (Advanced)

CFOBJECT creates a ColdFusion object of a specific type, component, COM object, CORBA object, Java object, or web service object.

For more information on the CFOBJECT tag, consult the ColdFusion documentation that was installed with your ColdFusion server.

CFCHART (Advanced)

The CFCHART tag generates and displays a chart from a specific set of data. It is used with the CFCHARTDATA and CFCHARTSERIES tags to provide data to chart and the format of the chart. For more information on the CFCHART tag, consult the ColdFusion documentation that was installed with your ColdFusion server.

More Tags (Advanced)

There are more ColdFusion tags available than are displayed in the insert bar for CFML. When you access the More Tags object a dialog box opens that lets you pick any ColdFusion tag to insert and to add whatever attributes are available for that tag. You would use this object if you know ColdFusion well and you want to insert a tag for which there is no specific object.

[ LiB ]