BackUp LevelNext

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:

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.