ColdFusion Builder Extensions

About 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

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

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.

Syntax

*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:

  <event> <ide version="2.0" > .... </ide> </event>

   

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

  <eventinfo projectname="mg1" projectlocation="C:/Documents and Settings/sandeepp/runtime-EclipseApplication/mg1" eventtype="onprojectcreate"> <server name="local1" hostname="localhost" port="8501" wwwroot="C:\ColdFusion9\wwwroot"/> </eventinfo>

   

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:

  <action name="generate CFC" handlerid="cfcgenerator" showResponse="yes" />

• In the CFM handler, do the following:

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

   <cfheader name="Content-Type" value="text/xml">

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

   <cfoutput> <response> <ide> <dialog > <input name="location" Label="Enter Location" type="dir" /> </dialog> </ide> </response> </cfoutput>

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:

   <cfheader name="Content-Type" value="text/xml">

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

   <cfoutput> <response showresponse="true"> <ide url="http://localhost:8500/local/Dynamic%20UI%20Test/handlers/main.swf" > <dialog width="455" height="470" /> </ide> </response> </cfoutput>

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

1. Install or import the extension which contributes the view.
2. Open Show View dialog box (Window > Show View > Other).
3. Double-click ColdFusion in the folder list.
4. Select the view (that is contributed) and then click OK.

The view appears and calls the corresponding Handler CFM file.

Use Handlers (for dynamic views)

In the CFM handler,

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

   <cfheader name="Content-Type" value="text/xml">

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

   <cfoutput> <response showresponse="true"> <ide url="URL"> <view id="ID" title="title" icon="icon_path" /> </ide> </response> </cfoutput>

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

Step 1: Get ideeventinfo XML

Step 2: Get callback URL from ideeventinfo XML

Step 3: Create XML to send command to ColdFusion Builder

Step 4: Execute callback command and get response

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

1. In the Extensions view, click  and select the Archive file to install.

   Note: If the extension that you are installing is shipped with ColdFusion Builder, the Archive file is available in the Extensions directory within the ColdFusion Builder installation.

    

2. The Extension Install wizard guides you through the installation.
3. Select the Server. If no server is configured, click Add Server to add a new server. For information about adding a server, see Adding ColdFusion servers.You can install the same extension on different servers. For example, CF9 local server and CF8 local server. However, at any given point, only the server that the extension uses is active.
4. Enter the path to the ColdFusion web root (if the path is not automatically populated when selecting the server). For example, _C:\ColdFusion9_wwwroot\
5. Select a folder within the web root to install the extension. The archive file is extracted to the install location.
6. Click Install.

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.

  Note: It is useful to import extensions when you use existing extensions to develop new extensions.

   

• 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

Use ColdFusion Builder Extension Creator to create and package extensions

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.

1. In the Navigator view, right-click the project in which you want to create the extension, and select Adobe Extension Builder > New.
2. Enter or browse to a location to store the extension. Select Create Folder With Extension Name to store the extension files in a folder with the same name as the extension.
3. Select the Extension Details tab to enter the extension name and details. You can also specify any license agreement text that must appear on installing the extension.

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.
  1. You can associate handlers with an action. Handlers display the code generation operations that are fetched from the server. Specify the Handler ID and Handler name, and select Show Response to display the server response. Then, click Save.
  2. Before a handler is called, you can get user inputs. To do so, click Add Input.
  3. Specify the input variable name, label for the input dialog box, tooltip, and the input variable type.
  4. You can also specify the pattern against which the user input is validated, and the error message that appears when the validation fails.
  5. Select Required to specify the input field as required, and select Checked to have the check box selected, by default. Then, click Save.
• 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.

1. To specify a new handler, click Add Handler, and enter the necessary details.
2. Select Generates Response to get user inputs before calling the handler.
3. Specify the title of the input dialog box, and the height and width in pixels. Then, click Save Handler.

Create an extension installation wizard

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

1. Specify the height and width of the wizard in pixels. You can also associate a handler with the wizard. Then, click Save.
2. Specify a title for the wizard, and click Save.
3. Specify the input variable name, label for the input dialog box, tooltip, and the input variable type. You can also specify the pattern against which the user input is validated, and the error message that appears when the validation fails.

Package the extension

1. In the Navigator view, right-click the ide_config.xml file and the Handler folder that contains all the Handler CFM files, and select Adobe Extension Builder > Package. The files are added to a ZIP file.
2. Browse to a location to store the ZIP file.

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:

  <codeassistcontribution>  <functions>  <function name="linkTo" variableName="event" componentName="component_name" handlerId="CodeAssistHandler">  <parameter index="1" />  </function>  </functions>  </codeassistcontribution>

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

  <codeassistcontribution>  <variables>  <variable name="event" componentName="component_name" handlerId="CodeAssistHandler">  <parameter index="1" />  </variable>  </variables>  </codeassistcontribution>

  Attribute	Description
  name	Name of the function that has to be listed.
  variableName	Name of the variable. If specified, then the handler is called only if the name of the variable on which the function is called matches the variable name.For variables, when you specify variablename. ,in the editor, Code Assist presents the contribution for that variable.
  componentName	If specified, the type of the variable on which the function is called matches the component name you specify.
  handlerID	ID of the associated handler.
  index	Specifies parameter indexes for which the handler can provide Code Assist. If not present, then the handler is called for all parameters in the function.

   

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

   <codeassist_response>  <proposal display="display_value" insert="insert_this_value" inquotes="true/false"/>  </codeassist_response>

   Attribute	Description
   display	The value you specify appears in the proposal window.
   insert	If that proposal is selected, then the value you specify is inserted in the editor.
   inquotes	If set to true, then the text inserted in the editor is enclosed in double quotes.

    

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

Additional resources

• How to contribute to code assist from extensions ColdFusion Builder engineering team member Sandeep Paliwal provides answers to the frequently asked questions about contributing to Code Assist using extensions.

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

1. In the Project View, right-click the project and then select Properties > ColdFusion Project.
2. In the Start Page Setting, select the option available in the Use Extension list.
3. Click OK.

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