| All right. You've set up ColdFusion Server according to the instructions in the Appendix, and it is time to put what we have learned so far to some use. We will now take a look at a few common ColdFusion tags and functions and then tie everything together in our first ColdFusion template. The <CFSET> Tag One of the most commonly used ColdFusion tags is <CFSET>. This tag is used to assign a value to a variable. Variables will be covered in depth in Step 2, but for now, just think of a variable as a container that holds whatever value you assign to it. The variable also is given a name so that you can recall its value whenever it's needed. The <CFSET> tag has no attributes other than the name of the variable being set. <CFSET ZodiacSign = "Scorpio"> In this example, we have created a variable called ZodiacSign and assigned it a value of Scorpio. Whenever we want to use the value Scorpio again in our application, we simply call the variable by its name, ZodiacSign. Using the <CFSET> tag will only set the value of a variable; it will not display that value when the page is published. To display the value, you need to use another tag you have already seen called <CFOUTPUT>. The <CFOUTPUT> Tag The <CFOUTPUT> tag is another tag that gets a lot of use. This tag has two major functions: to output database query information and to output the value of ColdFusion variables and functions. Using <CFOUTPUT> with database queries will be covered in Step 3, "Databases and SQL." For now, let's just have a look at outputting the value of a variable. <CFOUPUT> Hey babe, what's your sign? I'm a <B>#ZodiacSign#</B> </CFOUTPUT> The <CFOUTPUT> tag is a container tag and therefore requires opening and closing tags. The content between these tags is referred to as a <CFOUTPUT> block. Within this <CFOUTPUT> block, you can put any ColdFusion variables you would like to output as HTML. Notice in the preceding example that we also have included HTML bold (<B>) tags within the <CFOUTPUT> block. Any normal text or HTML tags within the output block will be ignored by ColdFusion Server and returned to the client's browser for processing. If ColdFusion Server ignores normal text in an output block, how does it know what to process? Why, it looks for the special # characters, of course. These "pound signs," as they are referred to, are the signal to ColdFusion Server that some processing needs to be done. In our example, we put the variable name ZodiacSign between the two pound signs to isolate it from the normal text and to indicate to ColdFusion that we would like the value of the ZodiacSign variablein this case, the word Scorpioinstead of the actual string ZodiacSign. The Now() Function Let's take a look at a couple of functions that will come in handy in your ColdFusion coding. As you might guess, the Now() function returns the current date and time down to the second. Because the World Wide Web is, well, worldwide, what date and time does the Now() function retrieve? It gets its date and time information from the computer running ColdFusion Server, not the client's browser. The Now() function can be very handy for recording when events happen throughout your web application. It can be used for tracking such things as the following: When users log on and log off the system Changes to database records Time elapsed since a user's last visit
The Now() function needs no parameters and can be used in several ways: As the value for a variable, as in <CFSET TheCurrentTime=Now()> Directly, inside a <CFOUTPUT> block (as shown in the code following this list) As the argument for another function
For example, the following line of code <CFOUTPUT>The time is #Now()#</CFOUTPUT> will return The time is {ts '2002-01-24 15:38:55'} The DateFormat() Function Although the Now() function can be very useful, the output it returns is not the prettiest thing in the world. Enter the DateFormat() function. This function enables you to use any date/time object and format the output to your liking. The DateFormat() function takes two parameters: a required date/time object and an optional output mask. The date/time object can be a variable, a string, or another date function, such as Now(). When using multiple parameters, they must be separated with commas. When using a single parameter, a comma is not used. #DateFormat(Date [, mask ])# NOTE When using a string, such as 12/10/02, as a parameter for the DateFormat() function, the string must be enclosed in quotation marks. For example, DateFormat("12/10/02").
The mask parameter enables you to change the display format of a date/time object. The mask can contain up to three sections representing the day, month, and year, and you can use as many or as few of them as you like. Table 1.1 contains possible mask combinations. The mask must be enclosed in quotation marks and can contain other characters, such as commas and hyphens. Table 1.1. DateFormat() Output Mask Parameters| Mask | Description |
|---|
| D | Numeric day of the month with no leading zero for single-digit days (4 December, for example). | | DD | Numeric day of the month with a leading zero for single-digit days (04 December, for example). | | DDD | Three-letter abbreviation for the day of the week (Mon for Monday, for example). | | DDDD | Complete name of the day of the week (Monday, for example). | | M | Numeric value for the month with no leading zero for single-digit months (3 for March, for example). | | MM | Numeric value for the month with a leading zero for single-digit months (03 for March, for example). | | MMM | Three-letter abbreviation for the month (Mar for March, for example) | | MMMM | Full name of the month (March, for example) | | Y | Last two digits of the year; however, no leading zero is displayed for values below 10. For example, the year 2009 would be displayed as 9, and the year 2011 would be displayed as 11. | | YY | Last two digits of the year with a leading 0 for values below 10. | | YYYY | Full four-digit year value. |
Listing 1.1 shows several uses of the DateFormat() function. Listing 1.1 DateFormat.cfm <HTML> <HEAD> <TITLE> The Date Format Function </TITLE> </HEAD> <BODY> <H2>DateFormat() Examples:</H2> <CFSET MyDateVariable = Now()> <CFOUTPUT> #MyDateVariable#<BR> #DateFormat(MyDateVariable)#<BR> #DateFormat("12/10/02")#<BR> #DateFormat("12/10/02","DDDD, DD MMMM - YYYY")#<BR> #DateFormat("12/10/02","MMMM")# </CFOUTPUT> </BODY> </HTML> Figure 1.10 shows the output that would result from the code in Listing 1.1. Figure 1.10. DateFormat.cfm browser display.  ColdFusion Comments If you have ever tried to modify or debug someone else's code, you know how important commenting your code can be. Providing comments throughout your code is an absolute must. Not only does it help other developers who might work on the files after you, it also serves to refresh your own memory when you return to work on code months or perhaps even years later. Comments help your development because they can do the following: Speed development in a team environment Reduce debugging and troubleshooting time Make code more readable Lead to better organization of code
It's good practice to provide descriptive comments wherever you think they might be necessary. The following are some good guidelines for when to provide comments: When creating a new file. Add documentation such as the filename, purpose of the file, author, and creation and modification dates. When variables are created. When testing for certain conditions. When including other code.
The syntax and purpose of ColdFusion comments are similar to that of HTML comments, except that ColdFusion comments use three dashes as opposed to the two dashes used in HTML comments. The major difference between the two comment types is that, as with all ColdFusion code, the ColdFusion Server will strip ColdFusion comments out, and they will not be returned to the client's browser. This means that if a user chooses to view the source code of a ColdFusion page loaded in his browser, he would not see any of the ColdFusion comments. This enables developers to leave very descriptive information within their files (for themselves and other developers) without worrying about disclosing sensitive information to a user who might choose to view the source code of downloaded pages. Listing 1.2 shows the previous example with comments added. Listing 1.2 DateFormat2.cfm <!--- File: DateFormat2.cfm Description: This file illustrates the use of ColdFusion comments Author: Barry Moore Created: 25-Jan-02 ---> <HTML> <HEAD> <TITLE> The Date Format Function </TITLE> </HEAD> <BODY> <!-- This is an HTML comment. It will show up if you view source --> <!--- This is a ColdFusion comment it will NOT show up in the source ---> <H2> DateFormat() Examples:</H2> <!--- Create a variable using the Now() function ---> <CFSET MyDateVariable = Now()> <!--- Output dates using various formats ---> <CFOUTPUT> <!--- display the date variables value without formatting ---> #MyDateVariable#<BR> <!--- DateFormat() function using a variable and no mask ---> #DateFormat(MyDateVariable)#<BR> <!--- DateFormat() function using a string and no mask ---> #DateFormat("12/10/02")#<BR> <!--- DateFormat() function using a string and full mask ---> #DateFormat("12/10/02","dddd, dd mmmm - yyyy")#<BR> <!--- DateFormat() function using a month only mask ---> #DateFormat("12/10/02","mmmm")# </CFOUTPUT> </BODY> </HTML> Figure 1.11 shows what would appear if you asked to see the source code from your browser. Figure 1.11. Browser source code for DateFormat2.cfm.  Give Your ColdFusion Templates a Good Pounding You might have noticed that when we used the Now() function inside a <CFOUTPUT> block, we used pound signs. <CFOUTPUT> The time is: #Now()#</CFOUTPUT> However, when we used Now() to set the value of a variable with <CFSET>, we did not use pound signs. <CFSET MyDateVariable = Now()> The proper use of pound signs is an issue that can confuse people who are new (and not so new) to ColdFusion, so let's get it correct from the start. Pound signs are used to identify ColdFusion variables and functions within a string of text. In this <CFOUTPUT> example, we wanted to distinguish the Now() function from the string of surrounding text, so we used the pound signs. Because ColdFusion Server treats a <CFOUTPUT> block as a string, pound signs are always required with <CFOUTPUT>. Easy. What about within a tag, like in the <CFSET> example? Because the Now() function appears on its own and not within a string of text, no pound signs are required. Let's take a look at a few more examples. Example 1: <CFSET Message1= "The time is Now()"> Because the Now() function appears within a string (inside the quotation marks), pound signs are required, and this example is incorrect. If displayed, the value of the Message1 variable would be The time is Now(). Example 2: <CFSET Message2 = "The time is #Now()#"> This is correct. The pound signs separate the Now() function from the rest of the string, and the Message2 variable, if displayed, would output something like The time is {ts '2002-01-26 23:43:46'}. Example 3: <CFSET Message3 = "the time is:" & Now()> This also is correct. The Now() function is not part of the text string (it is outside the quotation marks), so no pound signs are required. In this case, however, we need to use the ampersand to concatenate, or join, the value of the Now() function to the end of the string. The Message3 variable, if displayed, would output something similar to The time is: {ts '2002-01-26 23:43:46'}. One last thing. What if you want to actually use the pound sign itself within a string of text inside a <CFOUTPUT> block? This is commonly the case with hexadecimal color values. <CFOUTPUT> Welcome back<FONT COLOR="#FF0000">#FirstName#</FONT> </CFOUTPUT> This code would cause an error because ColdFusion Server looks for pound signs in pairs. It reads the pound sign in front of the color value and expects to find another matching one but does not. To use a single pound sign, you must do what is referred to as escaping the pound sign. You escape the pound sign by putting another pound sign in front of the one you want to use. <CFOUTPUT> Welcome back<FONT COLOR="##FF0000">#FirstName#</FONT> </CFOUTPUT> In this last example, ColdFusion Server will now see the pair of empty ##s, treat them as a single, text character pound sign, and continue to process the template. |
|
