Documentation

cf_annotate

Automatic annotations for your web site
Copyright 2005 ESWsoftware
Visit us at www.eswsoftware.com

Version: 1.0 (Release notes)
Date: 20050524
Required: Adobe ColdFusion 5.0 or greater, or
BlueDragon 6.2 or greater
See System requirements for more detail
Recent changes: -

Contents

  1. What is it?
  2. Installation
  3. Usage
  4. Caching
  5. The tag
  6. Tag attributes
Back to top

What is it?

cf_annotate is a simple way to add notes or advertisements to your page content automatically. This custom tag will look for instances of any of a predefined set of keywords in your page content and turn those words into links. When a user points to a linked word, a small box will appear with further information.

Use cf_annotate to:

  • explain foreign words, jargon or acronyms without the visitor needing to leave the page they are reading;
  • link to related content without interrupting the flow of your page;
  • generate revenues by inserting contextual advertising.
Back to top

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 annotate.cfm file in your server's custom tags folder or another preferred location. We recommend the following location: C:\CFusionMX\CustomTags\ESWsoftware\ .

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 you see the links inserted in your page but no popups when you click them, then either this path is incorrect or you have specified a non-existent skin.

Back to top

Usage

To enable annotations on an individual page, wrap the following tag pair around your page's content:
<cf_annotate 
  resourcePath="[web_path]"
  keys="#[keys]"
>
</cf_annotate>

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

[keys] may be a Coldfusion structure, or (ColdFusion MX or BlueDragon only) an XML string, an XML document object, or the absolute path to an XML file. Following are examples of each.

Coldfusion structure

<cfset keys = structNew()>
<cfset keys["XML"] = "<p>Extensible Markup Language, a simple, very flexible text format derived from SGML.</p><p><a href=""http://www.w3.org/XML/"">W3C: Extensible Markup Language home page</a></p>">
<cfset keys["XSL"] = "<p>Extensible Stylesheet Language, a family of recommendations for defining XML document transformation and presentation.</p><p><a href=""http://www.w3.org/Style/XSL/"">W3C: Extensible Stylesheet Language home page</a><br><a href=""http://www.w3.org/TR/xsl/"">W3C: Extensible Stylesheet Language Recommendation</a></p>">
<cfset keys["XSLT"] = "<p>XSL Transformation, a language for transforming XML documents into other XML documents.</p><p><a href=""http://www.w3.org/TR/xslt"">W3C: XSL Transformations Recommendation</a></p>">
<cf_annotate
  keys="#keys#"
>
  <p>XSLT transforms an XML document by applying an Extensible Stylesheet Language (XSL) stylesheet. (When stored in a file, XSL stylesheets typically have the suffix xsl.) ColdFusion provides the XmlTransform function to apply an XSL transformation to an XML document. The function takes an XML document in string format or as an XML document object, and an XSL stylesheet in string format, and returns the transformed document as a string. [<em><a href="http://livedocs.macromedia.com/coldfusion/7/htmldocs/wwhelp/wwhimpl/common/html/wwhelp.htm?context=ColdFusion_Documentation&file=00001520.htm">ColdFusion 7 LiveDocs</a></em>]</p>
</cf_annotate>

XML string

<cfsavecontent variable="keys">
  <keys>
    <key name="XML">
      <![CDATA[
        <p>Extensible Markup Language, a simple, very flexible text format derived from SGML.</p>
        <p><a href="http://www.w3.org/XML/">W3C: Extensible Markup Language home page</a></p>
      ]]>
    </key>
    <key name="XSL">
      <![CDATA[
        <p>Extensible Stylesheet Language, a family of recommendations for defining XML document transformation and presentation.</p>
        <p><a href="http://www.w3.org/Style/XSL/">W3C: Extensible Stylesheet Language home page</a><br><a href="http://www.w3.org/TR/xsl/">W3C: Extensible Stylesheet Language Recommendation</a></p>
      ]]>
    </key>
    <key name="XSLT">
      <![CDATA[
        <p>XSL Transformation, a language for transforming XML documents into other XML documents.</p>
        <p><a href="http://www.w3.org/TR/xslt">W3C: XSL Transformations Recommendation</a></p>
      ]]>
    </key>
  </keys>	
</cfsavecontent>
<cf_annotate
  keys="#keys#"
>
  <p>XSLT transforms an XML document by applying an Extensible Stylesheet Language (XSL) stylesheet. (When stored in a file, XSL stylesheets typically have the suffix xsl.) ColdFusion provides the XmlTransform function to apply an XSL transformation to an XML document. The function takes an XML document in string format or as an XML document object, and an XSL stylesheet in string format, and returns the transformed document as a string. [<em><a href="http://livedocs.macromedia.com/coldfusion/7/htmldocs/wwhelp/wwhimpl/common/html/wwhelp.htm?context=ColdFusion_Documentation&file=00001520.htm">ColdFusion 7 LiveDocs</a></em>]</p>
</cf_annotate>

XML document object

<cfxml variable="keys"><cfinclude template="sample2.xml"></cfxml>

<cf_annotate
  keys="#keys#"
>
  <p>XSLT transforms an XML document by applying an Extensible Stylesheet Language (XSL) stylesheet. (When stored in a file, XSL stylesheets typically have the suffix xsl.) ColdFusion provides the XmlTransform function to apply an XSL transformation to an XML document. The function takes an XML document in string format or as an XML document object, and an XSL stylesheet in string format, and returns the transformed document as a string. [<em><a href="http://livedocs.macromedia.com/coldfusion/7/htmldocs/wwhelp/wwhimpl/common/html/wwhelp.htm?context=ColdFusion_Documentation&file=00001520.htm">ColdFusion 7 LiveDocs</a></em>]</p>
</cf_annotate>

Absolute path to an XML file

<cf_annotate
  keys="#getDirectoryFromPath(getCurrentTemplatePath())#sample2.xml"
>
  <p>XSLT transforms an XML document by applying an Extensible Stylesheet Language (XSL) stylesheet. (When stored in a file, XSL stylesheets typically have the suffix xsl.) ColdFusion provides the XmlTransform function to apply an XSL transformation to an XML document. The function takes an XML document in string format or as an XML document object, and an XSL stylesheet in string format, and returns the transformed document as a string. [<em><a href="http://livedocs.macromedia.com/coldfusion/7/htmldocs/wwhelp/wwhimpl/common/html/wwhelp.htm?context=ColdFusion_Documentation&file=00001520.htm">ColdFusion 7 LiveDocs</a></em>]</p>
</cf_annotate>

Rather than using a tag pair, you may also apply cf_annotate to data stored in a variable. This is useful where the data is written to your page dynamically. For example, you might write something like this:

<cfquery name="page">
  SELECT  body
  FROM    pages
  WHERE   id = #id#
</cfquery>

<cf_annotate
  keys="#keys#"
  string="#page.body#"
  return="annotatedBody"
>

<cfoutput>#annotatedBody#</cfoutput>
Back to top

Caching

For added performance, you may like to cache the markup generated by cf_annotate. When cf_annotate runs, it adds some JavaScript to the HTML head. If you deliver markup generated by cf_annotate from a database or cache, this head markup will be missing. You can insert it manually into your page, or you can call cf_annotate in a special way (outside the cached area):

<cf_annotate
  headOnly="Yes"
  return="annotate"
  skin="quill"
  resourcePath="/resources/"
>
<cfhtmlhead text="#annotate#">

You may like to use ESWsoftware's free cf_cache custom tag. Here's an example where the data being annotated comes from a database:

<cf_cache key="article: #article.id#">
  <cf_annotate
    keys="#keys#"
    string="#article.body#"
    return="annotatedBody"
    resourcePath="/resources/"
  >
  <cfoutput>#annotatedBody#</cfoutput>
</cf_cache>
<cf_annotate
  headOnly="Yes"
  return="htmlHead"
  resourcePath="/resources/"
>
<cfhtmlhead text="#htmlHead#">

As mentioned, instead of calling the cf_annotate tag twice, you could further improve performance by simply copying the generated HTML into your page's head section by hand.

cf_annotate is not designed to be used with large numbers of keys. You may experience performance degradation when you have hundreds or thousands of keys. In cases like these, you should consider performing the annotation step only when the content is modified, storing the annotated content alongside the original content in your database. If performance is still a problem, a different architecture may be required, and cf_annotate may be unsuitable for your purposes.

Back to top

The tag

As a tag pair:

<cf_annotate
  click="Yes" or "No"                [DEFAULT: "No"]
  headOnly="Yes" or "No"             [DEFAULT: "No"]
  keys="keys"                        [REQUIRED]
  resourcePath="web_path"            [DEFAULT: "/resources/"]
  scope="One" or "All"               [DEFAULT: "One"]
  skin="skin"                        [DEFAULT: "windows"]       
  skipKeys="key_list"
  skipTags="Yes" or "No"             [DEFAULT: "Yes"]
  tooltip="tooltip"                  [DEFAULT: "Click for details"]
>
  .
  .
  .
</cf_annotate>

Or as a single tag:

<cf_annotate
  click="Yes" or "No"                [DEFAULT: "No"]
  headOnly="Yes" or "No"             [DEFAULT: "No"]
  keys="keys"                        [REQUIRED]
  resourcePath="web_path"            [DEFAULT: "/resources/"]
  return="variable_name"             [DEFAULT: "annotate"]
  scope="One" or "All"               [DEFAULT: "One"]
  skin="skin"                        [DEFAULT: "windows"]       
  skipKeys="key_list"
  skipTags="Yes" or "No"             [DEFAULT: "Yes"]
  string="string"                    [REQUIRED]
  tooltip="tooltip"                  [DEFAULT: "Click for details"]
>
Back to top

Tag attributes

click="Yes" or "No" [DEFAULT: "No"]
Annotations may appear when you hover over a link or when you click a link. Set this attribute to Yes to click links, or No to hover over links.
headOnly="Yes" or "No" [DEFAULT: "No"]
This attribute is only useful where you are employing caching. Set this attribute to Yes when you are displaying cached cf_annotate output in order to add the required JavaScript to the page head.
keys="keys" [REQUIRED]
A set of keys to match along with the content of each annotation. This attribute may be a structure, an XML string, an XML document object, or the absolute path to an XML document. See the Usage section above for examples of each.
resourcePath="web_path" [DEFAULT: "/resources/"]
The resourcePath is the web path to client resources such as style sheets, images, and JavaScript. See the Installation section above to set this correctly.
return="variable_name" [DEFAULT: "annotate"]
If cf_annotate is called as a single tag, it returns a variable rather than writing its output to screen. Use this attribute to set the variable name.
scope="One" or "All" [DEFAULT: "One"]
Set this attribute to One to annotate just the first of each matching key on a page, or All to annotate all matching keys.
skin="skin" [DEFAULT: "windows"]
The skin controls the visual appearance of this application. cf_annotate currently comes with several skins including buttercup, charcoal, glacier, quill, and windows.
skipKeys="key_list"
If you would like to skip certain keys on this page, supply them as a list to this attribute.
skipTags="Yes" or "No" [DEFAULT: "Yes"]
Set this to Yes to skip HTML or XML tags in your page content as well as certain tag pairs (a, h1, h2, h3, h4 h5, h6, head, label, object, script, select, style, textarea). If ou are working with plain text, setting this attribute to No will improve performance.
string="string" [REQUIRED if cf_annotate is called as a single tag]
If cf_annotate is called as a single tag, this attribute contains the HTML or text that cf_annotate will process.
tooltip="tooltip" [DEFAULT: "Click for details"]
If click is set to Yes then this attribute specifies the "tooltip" that appears when the mouse hovers over the link.

If convenient, you may set default values for cf_annotate attributes in a structure called request.eswsoftware.annotate.defaults . The following attributes may be set in this way: click, headOnly, resourcePath, scope, skin, skipKeys, skipTags, tooltip. For example:

<cfscript>
  request.eswsoftware.annotate.defaults.skin = "glacier";
  request.eswsoftware.annotate.defaults.resourcePath = "/resources/";
  request.eswsoftware.annotate.defaults.click = true;
</cfscript>
<cf_annotate keys="#keys#">
  ...
</cf_annotate>