ColdFusion Builder extensions

You can extend the ColdFusion Builder IDE (Integrated Development Environment) functionality to support various ColdFusion frameworks and code generation requirements. You develop ColdFusion Builder extensions to generate code, design dynamic user interfaces, and perform basic CRUD (Create, Read, Update, and Delete) operations on the database. The ColdFusion Builder extension is a structured component that adds context menus in the ColdFusion Builder IDE and handles events on these menus. You, the ColdFusion developer, can develop a ColdFusion Builder extension yourself or you can install an available extension.

To develop your own ColdFusion Builder extension, you create the configuration file and handler files. You define the context menus and events in the configuration file - IDE_Config.xml. For more information, see Developing extensions.

ColdFusion Builder lets you extend the IDE at various levels including creating user interfaces. For more information, see Creating user interfaces for extensions.

The extensions that are shipped along with ColdFusion Builder are Adobe CFC Generator and AS Class Generator. You can install and integrate these extensions with ColdFusion Builder. For more information, see Using Extensions.

ColdFusion Builder provides the ColdFusion Builder Extension Creator to guide you through the process of creating and packaging extensions. For more information, see Use ColdFusion Builder Extension Creator to create and package extensions.

Developing extensions

To develop a ColdFusion Builder extension, you create the following elements:

• Configuration file (IDE_config.xml)
• Handler files (CFM files)

You can create these elements by writing the code or by using the ColdFusion Builder Extension Creator wizard. For more information about using the ColdFusion Builder Extension Creator wizard, see Use ColdFusion Builder Extension Creator to create and package extensions.

Configuration file

Creating the configuration file (IDE_config.xml) is an important step in developing a ColdFusion Builder extension. You define all the elements of the configuration file within the {{application }}tag.

Specifying metadata elements

You use metadata elements to create an extension and specify information like, extension name, author, version, and extension description.

Use the following elements to specify application metadata in the configuration file.

Example

Adding pages to the ColdFusion Builder Extension Installation wizard

When you define the Configuration file, you can specify code that adds screens to the ColdFusion Builder Extension Install wizard. You can use these screens to get user inputs. Generally, user inputs are required for performing any configuration tasks after installation.

You specify input details using the input tag; for information on how to specify input tags, see Specifying input types. The handler that is specified in the  handlerid  attribute of the  wizardtag  is called with the input details. You can also specify the height and width of the Install wizard using the height and width attributes of the wizard tag. You can specify the title for each page in the wizard using the title attribute of the page tag.

Syntax

Example

In the following example, once the Extension Installation wizard finishes installing the extension, the handler ID, postinstallhandler, is called with the specified input details.

Extending IDE

You can extend the ColdFusion Builder IDE at the following levels:

• Adding context menus: You can add context menus to the following views:
  
  • Resource navigator
  • RDS Data view
  • Outline view
  • CFML Editor
• Handling workspace events: Currently  onprojectcreate  is the only supported event. 
• Create views
• Contribute to Code Assist from extensions

You can specify handlers for the context menus and events to perform CRUD or code generation operations.

Specifying Handlers

ColdFusion Builder supports CFM handlers. In the ColdFusion Builder context, a handler is a file that contains code, which is run in response to an event or an action. You specify handlers within the handlers tag. Use the handlerid attribute to associate the handler with an event or action. Specify all handler details within the handlers tag. For more details on specifying events and actions, see Specifying events and Specifying context-menus. All the handler files must be stored in the Handlers folder.

Syntax

You can specify only alphanumeric characters for the attribute values. Special characters are not allowed.

Example

Specifying events

Use the events tag to specify events. Currently, ColdFusion Builder only supports an event on project creation. The supported event type is onprojectcreate. Pass the required handler ID for the onprojectcreate event. When the event occurs, the handler associated with the handler ID is called.

All applications for which the onprojectcreate event is specified are listed under the list of applications in the Creating a ColdFusion project. When a user selects any of the listed applications, the associated handlers for the selected application are called. The onprojectcreate event is useful in creating a basic project structure for a given ColdFusion Builder extension.

Syntax

You can specify only alphanumeric characters for the attribute values. Special characters are not allowed.

Example

New events added in ColdFusion Builder 2.0.1

onfilechangeineditor: Extension can listen for events when file changes in the editor

Assume that you move to a different document (by clicking the tab on editor) or by opening a document in the editor. It is now possible for the extension to know this. For this, a new event {{onfilechangeineditor, has been introduced. The event can }}be registered as follows:

The information sent in the event message includes the following:

• type: Event type is  onfilechangeineditor
• project_path: Absolute path of the project to which the file (that is opened in the editor) belongs.
• file_path: Absolute path of the file currently opened/switched to in the editor.
• editor_name: Name of the editor that opened the file. For CFML files, the name is Adobe CFML  Editor..

The following is a sample output:

onRDSDataViewSelectionChange: Extension can listen for event when selection changes in the RDS data view

ColdFusion Builder sends different event information messages to the handler, depending on selection in the RDS Data view.For this, a new event, onRDSDataViewSelectionChange has been introduced. The event can be registered as follows:

OnFileSaved: Add event notification when file is saved

When a file is saved in ColdFusion Builder, an event notification is sent to the Handler CFM file. For this, a new event onFileSaved has been introduce . The event can be registered as follows:

The information sent to the Handler includes:

• Specifying callback commands from handlerstype : Event type is onFileSaved
• project_path: Absolute path of the project in which the file that is saved belongs.
• file_path: Absolute path of the file saved.
• editor_name: Name of the editor that opened the file. For CFML files the name is Adobe CFML Editor.

The following is a sample output:

Specifying context-menus

Use the menucontributions tag to specify a context-menu. A context-menu is a pop-up menu that appears on a right-click event.

To specify menu contributions for different views, use the contribution tag. Use the target attribute within the contribution tag to specify the target view where the menu must appear. Use the menu tag within the contribution tag to specify the menu to add. Use the action tag within the menu tag to specify menu items.

Syntax

contribution

menu

action

Specifying menu filters

Menu filters help control where a menu or menu item must appear. You specify menu filters using the filters tag. You can specify different filter types within the filters tag; use the type and pattern attributes to specify where the menu or menu item must appear. If any of the specified filters match, the specified menu or menu item appears.

You can specify filters for both menus and actions. If you specify the filter tag within the menu tag, the filter controls the display of the menu. For example, in the following code, the ORM Code Generator menu appears only if the user right-clicks the modelglue.xml file.

Specifying  filters  for the Navigator View

You can specify filters on the project, folder, or file of the Navigator view.

Syntax

*Example*If you want the ORM Code Generator menu to appear only in the context of a folder, you can use code like the following:

Specifying filters for the Outline View

You can specify filters on different node types of the Outline view. The node name that you specify acts as the filter. In the Outline view, you can also specify filters for files. When you open the file that matches the filter in the CFML editor, the contributed menu appears in the Outline view.

*Example*If you want the ORM Code Generator menu to appear only on the CFfunction node in the Outline view, you can use code like the following:

Specifying input types

Before a handler is called, you can get user inputs using the input tag. The associated handler processes the user inputs. You specify an input tag for every action and the input tag must be within the action tag.

To control the height and width of the input dialogs, you specify the input tag within the dialog tag. For example, you can specify code like the following:

Syntax

Each data type corresponds to an input type as specified in the table below. The syntax for each input type is also specified.

Example

Keyword support

ColdFusion Builder supports keywords that are used to add default values in input dialogs. During runtime, actual values replace the keywords.

The following table lists the supported keywords and the corresponding actual values.

For example, you can specify the projectname keyword as follows:

For information about importing, reloading, packaging, and debugging extensions, see Using the Extensions view.

Support for menu contribution on multiple nodes

In RDS Data View, menu contributions can be added to server, database, and file nodes in addition to table nodes.

If you select server node, then server names are sent to the Handler. The attribute selected, if true, indicates if the server, database, table or field is part of the selection as shown in the following sample response sent to the Handler:

Filters

As menu contributions can be added to multiple nodes in the RDS data view, you can specify filters to specify the node that you choose to be active as shown in the following example.The valid filter types are server, database, table, and field.

Understanding ColdFusion Builder and handler communication

Communication between the handler and ColdFusion Builder IDE is through XML. When an event occurs, ColdFusion Builder sends the event details to the associated handler in XML format. The XML is sent to the handler as a FORM-scope variable named ideEventInfo. To retrieve the XML from the FORM-scope variable, use the cfparam tag in the handler.

Syntax

or

Understanding XML structure

To understand the XML structure, let us review the XML code. Consider the following points before reviewing the code:

• All information sent to the handler is within the event tag.
• All event and action information is within the {{ide }}tag.
• Any user inputs are within the user tag.

The following table describes the XML code. The contents of the XML code vary depending on the event.

ideeventinfo.xml sent to Handler CFM files from ColdFusion Builder has:

• ColdFusion Builder version information provided as follows:

• Server details that include hostname and port number, provided as follows:

Sending messages between extensions

An extension can now send messages to another extension to perform an action or to notify of some event. The extension that receives the message can either take action or ignore the message.

The following scenario explains how this feature is useful:

You can now create extension that can listen to events, for example switching to a different file in the editor or selection change in the RDS data view. Using this feature, if you want, you can update the view content with this information (say about the new selection).

The handler CFM file that receives the event change notification executes a callback command sendMessageToExtension to ColdFusion Builder with the following:

• Message information
• Name of the extension to which the message has to be sent
• The handler CFM file in the extension that has to be executed

The following example asks ColdFusion Builder to send message to New Extension Enhacements in CFB Twister extension and call its handler NewFeaturesTestViewHandler and passes information such as event type and other event related information:

Handler communication

ColdFusion Builder sends the event details to the handler NewFeaturesTestViewHandler as XML (as FORM-scope variable ideEventInfo) as follows:

The information passed inside the extension_message node include the following:

Creating user interfaces for extensions

Create input dialogs

You can create an input dialog either by using a configuration file (IDE_Config.xml) or using CFM pages.

Using the configuration file

You create an input dialog by creating a configuration file (IDE_config.xml) and specifying the necessary details. For more information, see Configuration file.For, example, you can specify code like the following:

Using CFM pages

• In the IDE_config.xml file, specify the showResponse attribute of the Action tag as yes, as follows:

• In the CFM handler, do the following:

1. Specify the content-type value of the  cfheader  tag as text/ xml , as follows:

2. Create the input dialog by constructing the XML as follows:

Create HTML user interfaces

You can create an HTML user interface either by using HTML response or XML response.

Using HTML response

In the IDE_config.xml file, specify the showResponse attribute of the Action tag as yes, as follows:

The HTML content of the CFM page appears in a dialog box. Ajax and Javascript are not supported in the HTML content. If you use links in the HTML content, the URL for the link must be an absolute URL and not a relative URL.

Using XML response

In the CFM handler, do the following:

1. Specify the content-type value of the  cfheader  tag as text/ xml , as follows:

2. Create the HTML user interface by constructing the XML as follows:

The HTML content of the specified URL appears in a dialog box.You can also display HTML user interface through an XML response as follows:

Understanding the structure of XML response

Response

The XML response is defined within the response tag that has the following attributes:

IDE

The IDE tag has the following attributes:

Body

Use the body tag to specify any HTML content. The HTML content within the body tag must be specified in the CDATA section.

Dialog

The dialog tag is used to create input dialogs and has the following attributes:

To control the height and width of the input dialogs, you use the input tag within the dialog tag.

Create views

ColdFusion Builder lets you create views using extensions. You can also specify a view icon and toolbar items for the view you create.

The feature helps you use IDE features concurrently while seeing the data.

Create view in either of the following ways:

• Add contribution to ide_config.xml
• Dynamically from handler response

Add contribution to IDE_config.xml

Specify the details in the configuration file IDE_config.xml as shown in the following code. Adding view contribution to ide_config.xml adds the view to the list of views under ColdFusion category in Show View dialog box (Window > Show View > Other).

Displaying the view

Use Handlers (for dynamic views)

In the CFM handler,

1. Specify the content-type value of the  cfheader  tag (as text/ xml )as follows:

2. Create the view that displays HTML content by constructing the XML as follows:

You can also display HTML content through an XML response as follows:

In ColdFusion Builder 2 and earlier versions, the dynamic views gets added to the sub menu of “Window > Show view” dialog. However, in ColdFusion Builder 3, the dynamic views are shown in the extension view as a drop down item:

Specifying callback commands from handlers

In ColdFusion Builder (the previous release), from the handler CFM files, you can request to run the following commands: refreshproject, refereshfolder, refreshfile, inserttext, and openfile.

Now you can complete all these operations and few others in the execution phase itself (rather than at the end of execution). From the Handler CFM files you can send a call to ColdFusion Builder using the callback URL. ColdFusion Builder provides the callback URL in ideeventinfo XMLas shown here:

In addition to the commands that get context information related to the editor, you can get server-specific information such as data source and table details.

The following table provides the list of commands that help you perform various operations in the execution phase. All commands which request data have command result in XML format. The table has the results returned by each command:

Enhancements to existing callback commands in ColdFusion Builder 2.0.1

The response returned by the callback command  getfunctionsandvariables  now includes variable scope-related information. You can write extension to determine the scope, for example if the variable is var scoped in the function.The following three variables are identified:

• Argument scope
• Var scope
• Tag created variables, for example, the variables created in  cfquery .

You can determine the remaining scopes in the Handler CFM file from the variable name prefix, for example  this or application. The following is a sample  getfunctionsandvariables  output that includes scope-related information:

Example: Execute commands using callback URL

Handling errors while using callback commands

If there is an error while executing commands which return data, command response XML provides the error node with information about the possible cause of error.

Additional resources

• *[ColdFusion Builder 2 Extensions - Understanding
  Callback Commands|http://sandeepp.org/blog/?p=224]* ColdFusion Builder engineering team member Sandeep Paliwal explains the possibilities of callback commands in ColdFusion Builder 2 extensions.

Using the Extensions view

Use the Extensions view to install, uninstall, import, and reload extensions.

If the Extensions view is not already displayed in the workbench, add the Extensions view by selecting Window > Show View > Other. Then, in the Show View dialog box, select ColdFusion > Extensions view.

Install and uninstall extensions

To view a brief description about the installed extension, click the extension name. If you have installed the same extension on more than one server, you can make one of the servers active. To do so, select the server that you want to make active from the Active Server drop-down list.

To uninstall an extension, select the extension in the Extensions view and click  . You can uninstall an extension from the IDE only, or remove the extension from your IDE and computer’s file system at the same time. When an extension is permanently removed from the file system, you cannot undo the command.

Import and reload extensions

Use the Extensions view to import and reload extensions.

• You can import extensions from an existing directory into ColdFusion Builder. Click   in the Extensions view, and select the directory that contains the extension files.

• You reload an extension if you change the configuration file of an installed extension. Configuration file changes are reflected only after you reload the extension. Click  in the Extensions view to reload all the installed extensions.

Debug and package extensions

While loading extensions from the configuration file, any errors are logged to the Eclipse log. To debug the errors, you can view the ColdFusion Builder error log by selecting Window > Show View > Other > General > Error Log. The ColdFusion Builder error log appears in the Error Log view.

To package an extension, add the following contents to a ZIP file:

• Configuration file (IDE_config.xml)
• Handler directory that contains all the Handler CFM files

Ensure that you add the configuration file and handler directory directly under the root of the ZIP file.

The ColdFusion Builder Extension Creator wizard guides you through the process of creating and packaging extensions. The wizard guides you through creating the Configuration file (IDE_Config.xml) and Handler files (CFM), specifying metadata elements, adding context menus, and creating user interfaces.

Specify menu contributions

Select the Menu contributions tab and click Add Menu to specify a context-menu. A context-menu is a pop-up menu that appears on a right-click action.

• Enter the name of the menu and the target view from where the menu must appear. You can specify the target view as the Navigator or Project view, RDS view, Outline view, or the CFML editor. Then, click Save Menu.
• To specify menu items, click Add Action.

• To specify filters that control the display of the menu, click Add Filter. You can specify filters at the project, folder, and file levels.

Specify handlers

Select the Handlers tab to view details about the installed handlers.

Create an extension installation wizard

Select the Install Wizards tab to create an installation wizard that guides you through the extension installation.

Package the extension

Contribute to Code Assist from extensions

You can add proposals to Code Assist from extensions.

1. In the IDE_config.xml, do the following:

• To add proposals to Code Assist for function parameters, add the following code:

• To add proposals to Code Assist on variables, add the following code:

1. In the Handler CFM file, specify the response to add code assist proposal in the following format:

2. Install/import the extension. When you start ColdFusion Builder Code Assist, the functions are displayed in the proposal window.

Extension support for setting Launch Page

You can dynamically generate Start Page URL for framework applications using extensions.

ColdFusion Builder features such as ColdFusion Debugger, Use External Browser, Run as ColdFusion Application use this URL as the Start Page URL.

The generated URL can also have query param added to it.

Add Start Page contribution to IDE_config.xml

Specify the details in the configuration file IDE_config.xml as shown in the following code:

Handler communication

ColdFusion Builder sends the event details to the handler as XML (as FORM-scope variable ideEventInfo) as follows:

This information can be used to generate the URL.

Using extensions to generate Start Page URL

Next time, when you run the application, the handler identified with the ID you specified in IDE_config.xml is called. The information related to the project or the CFM is displayed.

Example