Home > Products >

Documentation

cf_noteSpace

notes and comments on every page on your site
Copyright 2004 ESWsoftware
Visit us at www.eswsoftware.com

Version:	1.1a (Release notes)
Date:	20041002
Required:	Adobe ColdFusion 5.0 or greater, or BlueDragon 6.1 or greater See System requirements for more detail
Recent changes:	20041002 * fixed CF5 locking issue 20040924 * added BlueDragon support.

What is it?
What's new in version 1.1?
Installation
Usage
The tag
Tag attributes

1. What is it?

cf_noteSpace lets visitors to your site comment on your pages. Simply add the cf_noteSpace custom tag to any page where you want to allow commenting, or add the tag to the display template you use for all your pages. You could even add the tag to your OnRequestEnd.cfm file to allow site-wide commenting.

This tag is particularly useful for web sites that are in development. Use cf_noteSpace to get feedback from your client on individual pages. The tag is also useful on documentation sites. Give your users an easy way to comment on or ask about specific pages of documentation.

By default, the tag allows anybody to comment. However, you can control who gets to make, read, or delete comments.

2. What's new in version 1.1?

BlueDragon Server support (see http://www.newatlanta.com/bluedragon/ )

NOTE: If you are already running cf_noteSpace 1.0 on your server, you will need to reset your cached language resource bundle after installation. Do this by viewing your page in a web browser as usual, but add the following variable to your page's URL: resetResourceBundle=true. For example, if your page is index.cfm then you'll need to visit the URL: index.cfm?resetResourceBundle=true . You only need to perform this procedure once.

3. Installation

If you are not familiar with installation of custom tags, please read this brief article first: Installing and using custom tags. It will save you time and frustration. You may also like to try the Installation Wizard which will provide a custom recommendation for your environment.

Install the notespace.cfm and resourcebundle.cfm files, along with the notespace and shared folders in your server's custom tags folder or another preferred location. We recommend the following location: C:\CFusionMX\CustomTags\ESWsoftware\ .

The comments folder may be located anywhere on your server. cf_noteSpace will use this folder to store comments. The default location is the folder containing your notespace.cfm custom tag. Place it here for now, alongside the notespace and shared folders.

Copy the resources folder to a web-accessible location on your web site. Make sure the supplied image test.gif is found in the resources folder. Open your browser and type in the URL of the resources folder on your web site. Add /test.gif on the end. If a large green check mark appears along with a message, then you have typed the address correctly. If not, keep trying.

Once you see the message, strip the http:// and your domain name off the beginning of the URL but leave a leading slash. Strip the test.gif off the end but leave a trailing slash. What remains is the correct value for your resourcePath attribute!

It is important that the resourcePath attribute is set correctly so that the style sheets are used. If your comment form appears plain and unstyled then either this path is incorrect or you have specified a non-existent skin.

4. Usage

To enable commenting on an individual page, add the following tag just before the page's closing body element:

<cf_noteSpace  
  resourcePath="[web_path]"
>

Where [web_path] is the value of the resourcePath attribute you determined above.

If you are developing a Fusebox site or other site where the URL of the page includes the query string then you'll need to set the thisPage attribute to the URL of the current page. For example: thisPage="/index.cfm?fuseaction=article&id=34

To add commenting to your entire site, add the cf_noteSpace tag to your OnRequestEnd.cfm file in the root of your site. For OnRequestEnd.cfm to be processed, you'll need an Application.cfm file too. For more information about Application.cfm and OnRequestEnd.cfm, see Developing ColdFusion MX Applications with CFML: Mapping an application. Note that this technique, while effective, will most likely generate invalid HTML markup by placing the comments after your closing html element. If you are concerned about this, try adding the custom tag to your page template instead.

Several other features are available. Add the email attribute so that you may be emailed when a comment is posted. If your site supports logged in users, set the administrator attribute to a variable that contains yes whenever a user is logged in who is permitted to administer the comments or no otherwise. To block anonymous comments, set anonymous to no, and set the userId attribute to a variable representing the logged in user. If this is anything but an empty string, cf_noteSpace will allow commenting.

5. The tag

<cf_noteSpace
  administrator="Yes" or "No"        [DEFAULT: "No"]
  anonymous="Yes" or "No"            [DEFAULT: "Yes"]
  email="email_address"      
  enabled="Yes" or "No"              [DEFAULT: "Yes"]
  locale="locale"                    [DEFAULT: getLocale()]
  resourcePath="web_path"            [DEFAULT: "/resources/"]   
  skin="skin"                        [DEFAULT: "glacier"]
  storagePath="file_path"            [DEFAULT: "#getDirectoryFromPath(getCurrentTemplatePath())#comments/"]
  thisPage="URL"                     [DEFAULT: "http://#cgi.server_name#:#cgi.server_port##cgi.script_name#?"]
  userId="user_id"
>

6. Tag attributes

administrator="Yes" or "No" [DEFAULT: "No"]: If yes then administrator functions are available: Comments may be deleted and a list of all pages with comments may be viewed. Generally, this attribute would be set to a variable that changed depending on who is logged in. For example: administrator="#isAdministator#"
anonymous="Yes" or "No" [DEFAULT: "Yes"]: If yes then anybody may add a comment. Otherwise, commenting is allowed only if the userId attribute is set.
email="email_address": If supplied, an email will be sent to this address whenever a comment is posted.
enabled="Yes" or "No" [DEFAULT: "Yes"]: This is simply a quick way of disabling the cf_noteSpace application.
locale="locale" [DEFAULT: getLocale()]: The locale is used to select the appropriate language resource bundle. It is recommended that you use the ColdFusion function, setLocale() to set your page's locale, and ignore this attribute. For example, add <cfset setLocale("English (United States)")> to your Application.cfm file.
resourcePath="web_path" [DEFAULT: "/resources/"]: The resourcePath is the web path to client resources such as style sheets, images, and JavaScript. See section 2 above to set this correctly.
skin="skin" [DEFAULT: "glacier"]: The skin controls the visual appearance of this application. cf_noteSpace currently comes with only one skin, although you can add your own.
storagePath="file_path" [DEFAULT: "#getDirectoryFromPath(getCurrentTemplatePath())#comments/"]: This is the absolute file path to the folder where comments will be stored. Comments are stored in XML files, one file for each page.
thisPage="URL" [DEFAULT: "http://#cgi.server_name#:#cgi.server_port##cgi.script_name#?"]: This is the web path of the current page. This is used to uniquely identify each page, and also to ensure that the form buttons work. See the notes above on the format of this URL, but remember that cf_noteSpace will attempt to add variables to the end of the URL, so you will need a ? in there.
userId="user_id": If you have set the attribute anonymous="no" then this attribute must be set to allow comments. cf_noteSpace will accept any value that is not an empty string. If you have set anonymous="yes" you may still want to set this attribute as a convenience to logged-in users. The userId does not need to identify a user uniquely. If you use an email address as the user ID in your application, you may want to consider setting the cf_noteSpace userId attribute to just the first section before the "@" in order to protect the user against email address harvesting bots.