Implementing CFX Tags  
 
 

The key concept to understand in building custom tags is the use of the tag request object, represented by the C++ class CCFXRequest. This object represents a request made from an application page to a custom tag. A pointer to an instance of a request object is passed to the main procedure of a custom tag. The methods available from the request object allow the custom tag to accomplish its work.

See Chapter 12, The ColdFusion Extension API for reference information about the CFX API.

 
 
  Debugging CFX tags  
 
 

Once a debug session is configured, you can run your custom tag from within the debugger, set breakpoints, single-step, and so on.

 
 
  Windows NT  
 

Custom tags can easily be debugged within the Visual C++ environment. To debug a tag, open the Build Settings dialog and click the Debug tab. Set the Executable for debug session setting to the full path to the ColdFusion Engine (such as, c:\cfusion\bin\cfserver.exe) and set the program arguments setting to -DEBUG.

 
 
  Solaris  
 

You can debug custom tags on Solaris using the dbx debugger. You should shutdown ColdFusion using the stop script.

Set the environment variables, including LD_LIBRARY_PATH and CFHOME as they are set in the start script. You should then be able to run the cfserver executable under the dbx debugger and set break points in your CFX code. You may need to set a break point in main ("stop in main") so dbx loads the symbols for your CFX before you can set breakpoints in your code.

 
 
  Registering CFX tags  
 
 

You must register custom tags in the ColdFusion Administrator before you can use them within application pages. To register or modify the settings for a tag, use the Extensions, CFX Tags page of the ColdFusion Administrator, as described in Managing CFX Tags in this chapter.

Windows NT only. The Visual C++ Custom Tag Wizard automatically registers custom tags so that they can be tested and debugged.

 
 
  Distribution  
 

If you are distributing a custom tag, you may want to automatically register the custom tag during the setup process by writing the registration entries directly into the Registry. The location, key, and value names to write are as follows:

Hive -- HKEY_LOCAL_MACHINE

Key -- SOFTWARE\Allaire\ColdFusion\CurrentVersion\CustomTags\TagName

Values:

  • LibraryPath -- The full path to the DLL (Windows NT) or shared object (Solaris) that implements the custom tag.
  • ProcedureName -- The name of the procedure to call for processing tag requests.
  • Description -- A description of the tag's functionality for browsing by end users.
  • CacheLibrary -- Indicates whether to keep the DLL or shared object loaded in RAM (1 or 0).

You can create a file containing this information by using the Regedit utility to export the registry entry from a machine on which the custom tag is already installed.

You can also use the Regedit utility to import custom tags to the registry (on either Windows NT or Solaris). To do this:

  1. Export the custom tag's registry entry by using the Regedit utility. This creates a file similar to the following:
    REGEDIT4
    
    [HKEY_LOCAL_MACHINE\SOFTWARE\Allaire\ColdFusion\CurrentVersion\ 
    CustomTags\CFX_TEST]
    "LibraryPath"="C:\\cfusion\\cfx\\CFX_TEST\\test.dll"
    "ProcedureName"="ProcessTagRequest"
    "Description"="Sample CFX tag."
    "CacheLibrary"="1"
    
  2. In the install script, import the registry entry by including the following command in the install script:
    regedit importfilename
    


 
 
BackUp LevelNext
 
 

allaire     AllaireDoc@allaire.com
    Copyright © 1998, Allaire Corporation. All rights reserved.