ColdFusion in Context: Posting Notice

Suppose you want to tell your patrons that your site will go down for maintenance for two hours, or that you're running a special on hair cream, or that your database is temporarily down. How do you readily go about doing that? This tip will explore multiple ways to add such a notice to your home page.

This home page displays the result of a database query, inserts code from an included file, reads text from a text file, and displays the contents of an application variable. You wouldn't use all of these techniques in a real application, but you can look them over and choose what you like. To do this, build a home page, create an appropriate database table, and build routines to write your messages. For this demo, name the home page homepage.cfm (a bland, but memorable filename).

Read the Database

Displaying data from a database is easy. Just bear in mind that if the database is off-line, you can't read a message from the database that tells you the database is off-line. (Got that? [grin]) Provide a default message to replace the one from the database if your database access fails, and use a cftry-catch combination to display this default if it's needed. Begin homepage.cfm with the following code. 

DON'T USE ALL THESE TECHNIQUES AT ONCE!
<hr>
Database Query...
<p>
<cftry>
<cfquery name="Seenotice" datasource="context">
select * from Notice
</cfquery>
<cfif Seenotice.recordcount>
  <cfoutput query="Seenotice">#Notice#</cfoutput>
<cfelse>
  [The database has no message yet.]
</cfif>
<cfcatch type="any">
THE DATABASE IS UNDERGOING MAINTENANCE.<br>
Regretfully, we ask you to try back later.
</cfcatch>
</cftry>

Include a ColdFusion Template

It's easy to include a ColdFusion template. Further, for most pages in your application, you should always be able to assume that the page exists. However, because a message page won't exist until you write your first message, this particular page might not be there initially. Again, the try-catch combination comes to the rescue; it will trap the error and display a default if the page is missing. Notice, by the way, that the file extension for a template does not have to be .cfm; the file just has to be in a directory tree the Web server can use. Add this code to homepage.cfm. 

<hr>
Include a File...
<p>
<cftry>
<cfinclude template="notecfm.unk">
<cfcatch type="any">
[There is no message include file yet.]
</cfcatch>
</cftry>

Read a File

An advantage of reading a file over including a template is that the file doesn't have to come from a directory under the Web server's control. Again, the file extension doesn't have to be anything the operating system knows how to handle by default but can be obscure if you wish. Add this code to homepage.cfm. 

<hr>
Read a File with CFFILE...
<p>
<cfset Fullname="c:\doc\notehtm.unk">
<cfif fileExists("#Fullname#")>
  <cffile action="read" file="#Fullname#" variable="NoteText">
  <cfoutput>#NoteText#</cfoutput>
<cfelse>
  [There is no message text file yet.]
</cfif>

Read an Application Variable

In theory, reading an application variable is faster than the previous methods of getting data from storage to the screen; because, you usually avoid a file hit with this method. However, if you're being careful, reading an application variable is a tiny bit harder than getting information from a database. Name the application if you haven't already done this globally for your system. Lock the application and copy the variable you need to a local variable (so you can release the lock quickly). If the application variable doesn't exist, set the local variable to "oops" to warn the following code that the application variable is missing. If the application variable is missing, try to load it from a text file (since the text file won't go away) and using an exclusive lock (because you don't want multiple folks trying to set it at once). Eventually, display the local variable's contents. Add this code to homepage.cfm. 

<hr>
Display an Application Variable...
<p>
<!--- Add the next line if the application 
hasn't been defined elsewhere --->
<cfapplication name="Notice" sessionmanagement="no">

<cflock name="NoticeRead" timeout="30" type="readonly">
<cfparam name="application.notice" default="oops">
<cfset Appnotice=application.notice>
</cflock>
<cfif Appnotice is "oops">
  <cfif fileExists("noticeapp.txt")>
    <cffile action="read" file="noticeapp.txt" 
    variable="NoteApp">
    <cfset Appnotice=NoteApp>
    <cflock name="NoticeSet" timeout="30" type="exclusive">
    <cfset application.notice=NoteApp>
    </cflock>
    <cfoutput>#NoteApp#</cfoutput>
  <cfelse>
    [There is no message file to load the variable,
    hence no application message.]
  </cfif>
<cfelse>
  <cfoutput>#Appnotice#</cfoutput>
</cfif>

Run an Empty Test

Browse homepage.cfm. The database portion should gently tell you the database is unavailable. The other portions should explain that there's no message yet. If this is not the behavior you get, debug before proceeding; because, this code won't work the same way once you've defined messages. Temporarily comment out the the try-catch combinations if you're uncertain what's going on. They hide error messages useful for debugging.

Make a Table

Create a table named Notice containing a field named Notice; a memo field type or its equivalent would be appropriate. Then browse homepage.cfm again. This time, the database portion should say that no message is available.

Interact with a Database

This code will let you maintain a message in the database. Call this code noticedb.cfm. The code to only permit a specific IP address to run this code is commented out for this demo; uncomment it to keep outside users from changing your home page. Using IP address 127.0.0.1 would restrict this to local access only. If you don't have a fixed remote IP address to use in place of 127.0.0.1, you'll want to create a mini-application with login code so you can run this routine remotely.

Read the notice from the database. If no notice exists, insert an almost empty notice - a null string would fail - and then add a row to the read query and populate the appropriate column (cell) so the form won't break: use a combination of queryAddRow and querySetCell to do this. If the form has been submitted, and the message isn't blank, change the database to match the form. When you code the textarea tag to accept your message, set wrap to physical so it preserves line breaks you might happen to use in your message. Once you've created this code, try it out; then browse homepage.cfm to see the result. 

<!--- Uncomment to block remote users
 <cfif cgi.remote_addr is not "127.0.0.1">
  <cflocation url="http://www.cftipsplus.com">
</cfif>
--->

<cfquery name="Chknotice" datasource="context">
select * from Notice
</cfquery>

<cfif not Chknotice.recordcount>
  <cfquery name="Blanknotice" datasource="context">
  insert into Notice (Notice)
  values (' ')
  </cfquery>
  <cfset dummy=QueryAddRow(Chknotice)>
</cfif>

<cfif isDefined("form.Doit") and len(trim(form.Notice))>
  <cfquery name="setnotice" datasource="context">
  update Notice set
  Notice = '#trim(form.Notice)#'
  </cfquery>
  <cfset dummy=querySetCell(ChkNotice, "Notice", trim(form.Notice))>
</cfif>

<form name="Setnotice" method="post" action="noticedb.cfm">
<textarea name="Notice" wrap="physical" rows="5" cols="60">
<cfoutput>#trim(Chknotice.Notice)#</cfoutput></textarea>
<input type="Submit" name="Doit" value="Change">
</form>

Interactively Write a Template

This code - call it noticein.cfm - will let you modify a template that's always included in the home page. As in the previous code, this code begins with lines you can uncomment and modify to restrict this routine to authorized users. If you want the included file to reside in the same directory as this script, add the filename to the getDirectoryFromPath function as shown. (It returns the full directory path of the script that invoked this function.) Otherwise, just replace Fullname with the full path and name of the template you want to use. If the form has been submitted and the message in the form isn't blank, write the form message to the file. If the file exists, read it into a variable for the form. Otherwise, create an almost empty variable for the form. (ColdFusion doesn't like completely empty templates.) When you're done, use the code to create a message, then read it from homepage.cfm. 

<!--- Uncomment to block remote users
 <cfif cgi.remote_addr is not "127.0.0.1">
  <cflocation url="http://www.cftipsplus.com">
</cfif>
--->
<cfset Fullname="#getDirectoryFromPath(cf_template_path)#"&"notecfm.unk">
<cfif isDefined("form.Doit") and len(trim(form.Notice))>
  <cffile action="write" file="#Fullname#" output="#form.Notice#" addnewline="Yes">
</cfif>
<cfif fileExists("#Fullname#")>
  <cffile action="read" file="#Fullname#" variable="NoteText">
<cfelse>
  [There is no message text file yet.]
</cfif>
<cfparam name="NoteText" default=" ">

<form name="Setnotice" method="post" action="noticein.cfm">
<textarea name="Notice" wrap="physical" rows="5" cols="60">
<cfoutput>#trim(NoteText)#</cfoutput></textarea>
<input type="Submit" name="Doit" value="Change">
</form>

Interactively Write a File

This code - call it noticefi.cfm - will let you modify a file in or out of a server directory. It includes lines you can uncomment if you want the file to be in the current directory. Otherwise, it's just like the code above: it lets you modify a file. Once you've created this code, try it out; then browse homepage.cfm to see the result. 

<!--- Uncomment to block remote users
 <cfif cgi.remote_addr is not "127.0.0.1">
  <cflocation url="http://www.cftipsplus.com">
</cfif>
--->
<cfset Fullname="C:\doc\notehtm.unk">
<!--- <cfset Fullname="#getDirectoryFromPath(cf_template_path)#"&"notehtm.unk">
--->

<cfif isDefined("form.Doit") and len(trim(form.Notice))>
  <cffile action="write" file="#Fullname#" output="#form.Notice#" addnewline="Yes">
</cfif>
<cfif fileExists("#Fullname#")>
  <cffile action="read" file="#Fullname#" variable="NoteText">
<cfelse>
  [There is no message text file yet.]
</cfif>
<cfparam name="NoteText" default=" ">

<form name="Setnotice" method="post" action="noticefi.cfm">
<textarea name="Notice" wrap="physical" rows="5" cols="60">
<cfoutput>#trim(NoteText)#</cfoutput></textarea>
<input type="Submit" name="Doit" value="Change">
</form>

Interactively, Indirectly Set an Application Variable

This code - call it noticeap.cfm - will let you modify a file and then set an application variable equal to the contents of the file. It does this when the form has been submitted and the message field has more than just spaces. The reason it gets a file involved is that application memory gets wiped out whenever the server is rebooted. The file will retain the message; memory won't. If the file exists, this code then reads the file into the form for modification. (If the file doesn't exist, the code provides an appropriate caution.) Once you've created this code, try it out; then browse homepage.cfm to see the result. 

<!--- Uncomment to block remote users
 <cfif cgi.remote_addr is not "127.0.0.1">
  <cflocation url="http://www.cftipsplus.com">
</cfif>
--->
<cfset Fullname="C:\doc\noteapp.unk">
<!--- <cfset Fullname="#getDirectoryFromPath(cf_template_path)#"&"noteapp.unk">
--->

<cfif isDefined("form.Doit") and len(trim(form.Notice))>
  <cffile action="write" file="#Fullname#" output="#form.Notice#" addnewline="Yes">
  <!--- Add the next line if the application 
  hasn't been defined elsewhere --->
  <cfapplication name="Notice" sessionmanagement="no">
  <cflock name="NoticeWrite" timeout="30" type="exclusive">
  <cfset application.notice=form.Notice>
  </cflock>
</cfif>
<cfif fileExists("#Fullname#")>
  <cffile action="read" file="#Fullname#" variable="NoteText">
<cfelse>
  [There is no message text file yet.]
</cfif>
<cfparam name="NoteText" default=" ">

<form name="Setnotice" method="post" action="noticeap.cfm">
<textarea name="Notice" wrap="physical" rows="5" cols="60">
<cfoutput>#trim(NoteText)#</cfoutput></textarea>
<input type="Submit" name="Doit" value="Change">
</form>

Go to Manual

You could change that included file (or the home page itself) manually. However, that leaves much room for error if you're in a hurry, and access to do the task might be a problem. Because you shouldn't use ColdFusion RDS on a production server, you'd need physical access or shared drives to change the home page manually.

See the Possibilities

Notice that these methods are not created equal. Only one of these methods readily lets the user know that the database is off line. Only one of these methods allows you to use ColdFusion code in your message. On the other hand, all of them allow you to use HTML. I think using a combination of methods is best. Pick your favorite methods, use them in your applications, and share your lessons learned so we can make fresh mistakes [grin]. =Marty=
[Actual file paths vary from what you see here to match the real server used in this demonstration.]