Prerequisite knowledge
Required products 
User Level
Experience with ColdFusion will be needed to apply the techniques covered in this article.
Adobe ColdFusion Builder (2016 release) (Download trial)

Adobe ColdFusion Enterprise Edition (2016 release) (Download trial)

Extensions within Adobe ColdFusion Builder allow developers with ColdFusion and XML knowledge to create installable extensions that interact with the IDE as if they were pre-packaged with it. Not only can the extensions be used on-demand through the menu options, but they can also be tied to actions that occur within the IDE, so you can streamline your entire development process.
An IDE is the primary tool in a developer’s arsenal. Since the first IDE was introduced long ago, there has been a low murmur of grumbling from developers, "it works OK but I wish it did…" For ColdFusion developers, at least, this grumbling is about to be silenced. With the introduction of ColdFusion Builder extensions, which modify functionality to suit anyone’s needs, developers no longer have to wish for functionality that doesn’t exist. Instead, using ColdFusion and XML, they can create it themselves. It’s time to stop wishing and start building.

What's the story with extensions?

Extensions allow developers to add new functionality and tasks to ColdFusion Builder. There are many tasks that developers perform on a daily basis that would be ideal candidates for automation within an IDE. Most of these tasks are either unique to the way in which a developer works or specific to the framework in use. Regardless of what the purpose is, extensions allow you to create the needed functionality and install it easily into ColdFusion Builder.
An extension is packaged as a ZIP file that contains two integral pieces: the IDE_config.xml file and the handlers. The IDE_config.xml file has all the information that ColdFusion Builder needs to add the extension to its various file menus, such as when it should be available and what files should be called in the event that it is selected. The handlers are the ColdFusion files that are run when actions are called from within the extension.
Since extensions are ZIP files, they can be distributed easily and installed in any ColdFusion Builder instance. The installation process couldn’t be easier, especially with the Extension View. To open the Extension View, choose Window > Show View > Other. Under ColdFusion, click on Extensions (See Figure 1). Click Install Extension from Archive File and select the ZIP file that contains the extension (you can also select previously installed extensions and uninstall them or change their active server from this panel). The Extension Install wizard will guide you through the rest of the installation.
Installing a new extension
Figure 1. Installing a new extension in ColdFusion Builder
Since the handler files in an extension can be ColdFusion files, you must select a ColdFusion server on which to install the extension. If you have not already added your ColdFusion server information into ColdFusion Builder, you will have the option to add it at this point. The ColdFusion server can be local or remote, but it is important that you have write privileges on the server.. If you do not have access to a ColdFusion server you will not be able to install an extension.
Note: If you use a remote server, any code or files that are generated will be located on the remote server, not your local machine.

Understanding IDE_config.xml

The IDE_config.xml file is the backbone of an extension. It contains all data related to the extension, including information about the creator, how the extension is displayed in context-menus, and what files are called when certain actions are selected. The root tag of the XML file is the <application> tag, in which all other tags are nested. A skeleton IDE_config.xml file is shown in Figure 2.
 IDE_config.xml file structure
Figure 2. The IDE_config.xml file structure
Application information
The Extension Install wizard screens display information that is relevant to the specific extension being installed, such as its creator, a description, and license terms. For this information to be displayed, the following metadata tags must be nested in the application tag:
  • Name - The name of the extension
  • Author - Either your name or the name of your organization
  • Version - The version of the extension being installed
  • Email - An email address that can be used to contact you if the user has any questions
  • Description - A description of what the extension does. This can be plain text or HTML.
  • License - Details of the license under which the extension is distributed. A user must agree to the license before they can install the extension. This can be plain text or HTML.
<name>Sample Extension</name> <author>Simon Free</author> <version>1.0</version> <email></email> <description>This extension will do something really cool to your code</description> <license>You can write any kind of license agreement you want</license>
This information is displayed on the first screen of the installation process (see Figure 3). Because this is an XML file, it is important to note that any special characters, such as &, used within the description or license tags that could break XML formatting must be wrapped inside of CDATA tags. Also there is no validation carried out on the data, so even if an email address is incorrectly formatted it will still be displayed.
Extension installation wizard
Figure 3. The first screen of the extension installation wizard
Install information
If you need to gather additional information from the user during installation, it is possible to add steps to the installation wizard using install and wizard tags. In the wizard tag you can provide wizard size and handler information. The wizard windows do not resize to fit all the fields in the screen, so you need to provide an appropriate width and height if there is a chance something may get cut off.
The wizard tag may contain multiple page tags. Each page tag represents a screen within the wizard process. The page tag’s one attribute, title, is displayed at the top of the wizard screen. The page tag, in turn, contains input tags, which specify the input boxes that will be displayed in the wizard. You must supply a name for the tag, which will be used by your handler to access the information, as well as a label value. The label is displayed next to the input field and is used to tell the user what information they should supply in the field. Input tags will be covered in more detail later in this article.
<install> <wizard height="400" width="500" handlerid="postinstallhandler" > <page title="Install settings" > <input name="datasource_name" label="Datasource Name" type="string"/> <input name="root_dir" label="Root Directory" type="dir"/> </page> </wizard> </install>
It is important to note that ColdFusion Builder does not store any of the information provided by the user, so it is up to your handler to store any information. Since you cannot guarantee the user has a data source already set up, the best approach is to store the information in a text file. Alternatively, you can communicate with the ColdFusion Administrator CFC to set up a datasource which will store this information.
A context-menu is a pop-up menu that displays after a right-click. When an extension is installed, it is accessible through four different context-menus: RDS view, Project view, Outline view, and the Editor. Within the file you can specify the actions that you want to associate with each menu using the menucontributions tag. This feature will be discussed in more detail in the next section, Context-menus in depth.
In addition to being called via a context-menu, it is also possible for an extension to be called after a given event. Currently, ColdFusion Builder only supports the onprojectcreate event, but there are plans to add more events in later versions. You add an event by nesting an event tag inside the events tag. The event tag has the following available attributes:
  • type - This is the type of event the event is triggered by, which for now is only onprojectcreate.
  • handlerid – This is the name of the handler that will be called when the event occurs.
The ideal use for an onprojectcreate event is to create a basic structure for a newly created project that has all the files and folders you always use in your projects.
<events> <event type="onprojectcreate" handlerid="createStructure" /> </events>
Handlers are ColdFusion files that are run in response to an event or action. For a handler file to be run, it must be referenced by a handler tag. Each handler tag is nested inside the main handlers tag and has a handlerid as an identifier. A handler tag also specifies the handler’s file type and the file name. There are three available attributes for the handler tag:
  • id - This is the handlerid that the other tags reference. The id attribute must be unique and it is case sensitive.
  • type - This is the file type of the handler. For now only CFM is supported.
  • filename - This is the name of the file to be called. All files must be located in the Handlers folder so no path information is needed in this tag.
<handlers> <handler id="postinstallhandler" type="CFM" filename="postinstallhandler.cfm"/> <handler id="fileDetails" type="CFM" filename="fileDetails.cfm"/> </handlers>

Context-menus in depth

In a ColdFusion Builder extension, the menucontributions tag is used to specify the context-menu information. Nested within the menucontributions tag, contribution tags specify different menu contributions for different views. For example, the extension may have one menu option that is only available in RDS view and two other menu options that are only available in Project view. The target attribute of the contribution tag specifies which of the three views it relates to: rdsview, projectview, or editor.
Within the contribution tag you can place multiple menu tags. A menu tag is needed for each option you wish to place in the root of the context-menu. Multiple menu tags can be used to separate different actions if needed. The name attribute of the menu tag is used as the identifier within the context-menu.
The menu tag is purely used as a container tag and has no functionality or actions tied to it. To add menu options to the context-menu, you must use the action tag. The action tag accepts a name, which is displayed in the context-menu, and a handlerid, which refers to one of the handler tags. When the menu item is clicked, the associated handler will be called and the specified ColdFusion file will be run.
Because the functionality provided by the extension may not be relevant in all scenarios, you can apply filters to the menu items so that they are only accessible for specific files. Using the filter tag, you can specify whether the menu item relates to a file, folder, or project. You may also use the pattern attribute of the filter tag to limit its display even further, by providing a regular expression which will be run against the file or folder names. This way, you can use a combination of filters to separate functionality into multiple handlers, instead of sending everything to a single handler, which then must determine how it was invoked.
<menucontributions > <contribution target="projectview"> <menu name="Sample Extension"> <filters> <filter type="file" pattern="^.+\.((cfm)|(cfc))" /> </filters> <action name="Extra File Info" handlerid="fileDetails" showResponse="true" /> </menu> </contribution> </menucontributions>
The action tag has an attribute called showResponse. Setting this attribute to true will enable the creation of a user interface, which will allow the user to interact with the extension and see any success or failure messages. If your extension needs no additional information from the user to run, you can set showResponse to false to suppress the user interface.
When developing your extension, I recommend setting showResponse to true so that you can see any errors that may occur.

Adding an interface

Unless the user interface has been suppressed with showResponse="false" in the action tag, a wizard screen will appear when a user clicks one of the actions in the context-menu. There are three ways to create an interface for an extension.
The first method is to specify input tags inside the action tag in the IDE_config.xml file. These inputs will appear in the order that they are specified. The advantage of this method is that ColdFusion Builder will handle all rendering of the form. Once the form has been filled out the handler will be called.
The second method is to specify a dialog tag inside your handler. Within this tag you then specify the necessary input tags, just like in the first step. The advantage of this method is that you can use ColdFusion to determine which input tags to output and which to skip. Utilizing the dialog tag also has the advantage that you are able to specify a dialogclosehandler which will be fired if the user closes the window rather than clicking on OK.
The third method is to provide a dialog tag and a body tag inside your handler. The dialog tag functions purely as a way to control the height and width of the extension window, and the actual output is placed inside of the body tag. The body tag will render any HTML or text that is placed inside of it and allow you to use CSS to add design elements if you wish. This method may seem the more favorable to most, as it lets them use their HTML skills, but its main drawback is that HTML forms do not work in extensions, so this method can only be used for display only.
When placing input tags inside action tags or dialog tags, you have access to the following attributes:
Input variable name
Text to be displayed next to the input box
The tool tip that appears when the user moves the mouse over the input box
Available input types:
• dir
• string
• Boolean
• file
• password
• list
Specifies whether the input is required
A regular expression used to validate the input
The message displayed if the validation fails
The help message displayed when the label is moused over
The default value
Creates a checkbox that relates a Boolean value
Table 1. Input tag attributes
ColdFusion Builder offers keyword support when providing default values for the input tags. These keywords (see Table 2) are replaced at runtime with the actual values, and will assist in providing an easy-to-use user interface.
Actual value
Absolute path to the project location
Name of the project
Absolute path to the server installation location
Server web root
Table 2. Available keywords

Digging into the data

So far I’ve covered how to set up the extension, but now it is time to talk about the handlers. Handlers are implemented as CFML files in the handlers folder, which are run when users select their associated menu options.
All communication between the handler and ColdFusion Builder is through XML. When a handler is called, XML data is passed to the handler via the form scope. The variable ideEventInfo consists of three pieces of information: The event tag contains all the information sent to the handler; the ide tag contains all event and action information; and the user tag contains any user inputs. The contents of the XML vary depending on the event, which is why it is useful to separate out the different handlers for different event types.
Example handler tags
Figure 4. Example handler tags
Table 3 shows a breakdown of the different pieces of XML that will be available to you.
Target View
  <database name="">
    <table name="">
        <field name="" type="" length="" />
When a menu item from the RDS view is clicked
<projectview projectname="" projectlocation="">
  <resource name="" path="" type="file|folder|project" /></projectview>
When a menu item from the Project view is clicked
<outlineview projectname="" projectlocation="">
  <source filename="" path="">
    <node type="function|other">
      <function name="" returntype="">
        <argument name="" type="" />
      </function>     </node>
When a menu item from the Outline view is clicked
<eventinfo projectname="" projectlocation="" eventtype="" >   <resource name="" path="" type="file|folder|project" />
on project create
The event information supplied to a handler after an event occurs
  <input name="" value="" />
  <input name="" value="" />
input dialog
All user input values where the name relates to the name supplied in the IDE_config.xml file
Table 3. XML data in ideEventInfo
You can use this information as you develop your extension.
Remember that when installing the extension, the user will may have selected a remote server. You’ll need to be careful when you are trying to reference files; a simple file path may not work.


Being able to communicate with the IDE outside of what the user sees in the extension window is very important if you want to create an extension with a high level of usability. For example, if you were to create an extension that created new files in a project, the only way for a user to see the new files would be to refresh the project view. Since most users may not know to do that, you would end up creating an extension with poor usability. The commands tag, when placed in the handler file, allows extensions to call a number of commands, ranging from refreshing projects, to opening files, to inserting text.
Refreshes a specific project
Refreshes a specific folder
Refreshes a specific file
Inserts text either at a specific position or at the beginning and end of selected text
Table 4. Available commands
To implement a call back command, place the commands tag inside the ide tag in the handler.  Inside the commands tag place a command tag, specifying the requested command and then place param tags inside of that to provide any additional information.
<response> <ide> <commands> <command name="[command name]"> <params><param key="" value="" /></params> </command> </commands> </ide> </response>

Debugging and deploying

Debugging your extension is not quite as simple as debugging a web application, because you cannot just refresh a browser to see your changes. Thankfully though, you do not need to uninstall and reinstall the extension whenever you make a change. When an extension is installed, the code is moved to an automatically generated folder off the web server root. You can develop and debug on those files rather than the original files. When you make a change, go back to the screen that you used to install the extension (see Figure 1) and click Reload Extensions. All the changes that you made will now be reloaded, including any made to the IDE_config.xml file. The only changes that you will not be able to see immediately are those pertaining to the installation process. If you choose to make changes related to the installation process, you must uninstall and reinstall your extension to see them.
When developing an extension, you can save some time by using the Import button, rather than the Install button to add your extension. Import allows you to select the folder that has your extension development files in it and will use them to add the extension, rather than requiring you to zip up your files and perform an install. You can then continue to build your extension and reload the extensions whenever you need to test.
When you are happy with your extension and want to share it with others, create a ZIP file that contains the IDE_config.xml file and the handlers folder. Make sure that these two items are in the root of the ZIP file. If you nest them within another folder, the extension installation will fail.

Where to go from here

Hopefully this article has helped you understand the inner workings of ColdFusion Builder beta extensions. Creating the IDE_config.xml file is often the most complex part of creating an extension. Once you have that in place, the development of the various handlers should be relatively easy, as it is done using a language you already know and love. The hardest part of the whole process, however, may be finding inspiration for what to create, and unfortunately that is not something I can help you with. To see what other developers are doing, I recommend visiting the ColdFusion Builder Extensions category on RIA Forge, where there are already a number of submissions that you can examine.