Developing extensions

Configuration file
Understanding ColdFusion Builder and handler communication

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.

Element	Description
`name`	The name of the extension.
`author`	The author's name.
`version`	The file version.
`email`	Specifies the e-mail address.
`description`	A brief description of the application. The description can be in plain text or you specify a path to an HTML file, which contains the application description. If you specify a path to an HTML file, store the HTML file in the Install directory within the extension.
`license`	License agreement displayed when installing the extension. The license agreement can be displayed in plain text or you specify a path to an HTML file, which contains the license agreement. If you specify a path to an HTML file, store the HTML file in the Install directory within the extension.

Example

<application> 
    <name>ORM CFC Generator</name> 
    <author>Adobe</author> 
    <version>1.0</version> 
    <email>user@xyz.com</email> 
    <description>ORM CFC code Generator</description> 
    <license>license.html</license> 
</application>

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

<application> 
<name>Name of the ColdFusion Builder extension</name> 
<install> 
<wizard height="" width="" handlerid="handlerID" > 
<page title="Wizard page title" > 
<input name="Input" ... /> 
<input name="Input" ... /> 
</page> 
</wizard> 
</install> 
</application>

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.

<application> 
<name>ORM CFC Generator</name> 
<install> 
<wizard height="" width="" handlerid="postinstallhandler" > 
<page title="Install settings" > 
<input name="Mapping" ... /> 
<input name="Datasource" ... /> 
</page> 
</wizard> 
</install> 
</application>

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.

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

<handlers> 
    <handler id ="cfm" type="cfm" filename="filename" /> 
</handlers>

Attribute

Description

Handler ID

type

Specifies the handler type.

The handler type you can specify is "CFM"

filename

The name of the CFM file

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

Example

<handlers> 
    <handler id="cfcgenerator" type="CFM" 
    filename="ormCFCGenerator.cfm" /> 
    <handler id="gridgenerator" type="CFM" 
    filename="cfgridGenerator.cfm" /> 
</handlers>

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

<events> 
    <event 
    type="onprojectcreate" 
    handlerid="handler id" /> 
</events>

Attribute

Description

type

Specifies the event for which the handler runs.

You can specify the event type="onprojectcreate"

handlerid

Specifies the handler ID to pass.

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

Example

<events> 
    <event type="onprojectcreate" 
    handlerid="projectCreationHandler" /> 
    </events>

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

<menucontributions> 
    <contribution target="rdsview|projectview|outlineview"> 
    <menu name="name of the menu item"> 
    <action name="action name"> 
    </action> 
    </menu> 
    </contribution> 
</menucontributions>

contribution

Attribute	Description
`target`	The target view can be any of the following: rdsview projectview outlineview editor

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

action

Attribute	Description
`name`	Specifies the name of the action.
`handlerid`	Specifies the ID of the associated handler.
`showresponse`	A Boolean that value that specifies if the HTML response that the handler receives must be shown to the user: `yes` `no` The default value is `false`.

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

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.

<menu name="ORM Code Generator"> 
<filters> 
<filter type="file" pattern="modelGlue.xml" /> 
<filters> 
</menu>

Specifying filters for the Navigator View

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

Syntax

<filter type="folder|project|file" 
pattern="regular expression to match folder, project, or filename" />

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:

<menu name="ORM Code Generator"> 
<filters> 
<filter type="folder" /> 
<filters> 
</menu>

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

<menu name="menu name"> 
<filters> 
<filter type="node name" />

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:

<menu name="ORM Code Generator"> 
<filters> 
<filter type="cffunction" />

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:

<dialog height="400" width="600" title="title" image="path to the image file"> 
<input name="Mapping" ... /> 
<input name="Datasource" ... /> 
</dialog>

Attribute	Description
`height`	Specifies the height of the dialog.
`width`	Specifies the width of the dialog.
`title`	Specifies the title for the dialog.
`image`	Specifies the path to the image that appears in the title bar. The path that you specify must be relative to the Extension folder.

Syntax

<action name="action name"> 
    <input name="input variable name" 
    label="label for the input dialog box" 
    tooltip="tool tip" 
    type="dir|string|boolean|file|password|list"/> 
</action>

Attribute	Description
`name`	Input variable name
`label`	The label of the input dialog box
`tooltip`	The tool tip that appears when the user moves the mouse over the input dialog box.
`type`	The input variable can be any of the following data types: dir string Boolean file password list projectdir projectfile
`required`	Specifies the input field as required. When you specify an input field as required, the OK button is not enabled until the user enters a value in the required field.
`pattern`	Specifies the regular expression against which user input is validated. For a validation error, you can specify the error message that must appear. You use the `errormessage` attribute to specify the error message.
`errormessage`	The error message that appears when validation fails for a given pattern.
`helpmessage`	The Help tip that appears in the title area of the dialog for a given input field.
`default`	Specifies a default value for a given input type. You cannot specify a default value for Boolean input types. For lists, the default value is pre-selected.
`checked`	A Boolean value that specifies if the check box field is selected or deselected, by default: true - check box is selected (default value). false - check box is deselected

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

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

Datatype	Input type	Syntax
dir	Directory selection field	<input name="input variable name" label="label" tooltip=" tooltip" type="dir"/>
string	Text field	<input name="input variable name" label="label" tooltip=" tooltip" type="string"/>
boolean	Check box	<input name="input variable name" label="label" tooltip=" tooltip" type="boolean"/>
file	File selection field	<input name="input variable name" label="label" tooltip=" tooltip" type="file"/>
password	Password field	<input name="input variable name" label="label" tooltip=" tooltip" type="password"/>
list	List field	<input name="input variable name" label="label" tooltip=" tooltip" type="list"> <option value=”Option1”> <option value=”Option2”> </input>
projectdir	Project directory selection field	<input name="input variable name" label="label" tooltip=" tooltip" type="projectdir"/>
projectfile	Project file selection field	<input name="input variable name" label="label" tooltip=" tooltip" type="projectfile"/>

Example

<menucontributions > 
    <contribution target="rdsview" > 
        <menu name="ORM Code Generator"> 
             <action name="Generate ORM CFC" handlerid="cfm1" > 
                <input name="Location" label="Enter location" 
    tooltip="Location where generated CFCs will be stored" type="dir"/> 
                <input name="generateAppCFC" label="Generate 
    Application CFC" tooltip="Generate Application CFC along with ORM CFC" 
    type="boolean"/> 
                <input name="generateView" label="Generate View" 
                tooltip="Generate View template along with ORM CFC" type="boolean"/> 
            </action> 
            <action name="Generate Ajax Grid" handlerid="cfm2" > 
                <input name="Location" label="Enter location" 
                tooltip="Location where generated View will be stored" type="dir"/> 
            </action> 
        </menu> 
    </contribution> 
    <contribution target="projectview" > 
        <menu name="ORM Code Generator"> 
            <action name="Generate ORM CFC" handlerid="cfm1" /> 
            <action name="Generate Ajax Grid" handlerid="cfm2" /> 
        </menu> 
    </contribution> 
    <contribution target="outlineview" > 
        <menu name="ORM Code Generator"> 
            <action name="Generate ORM CFC" handlerid="cfm1" /> 
            <action name="Generate Ajax Grid" handlerid="cfm2" /> 
        </menu> 
    </contribution> 
</menucontributions>

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.

Keyword	Actual value
projectlocation	Absolute path to the project location
projectname	Name of the project
serverhome	Absolute path to the serve installation location
wwwroot	Server web root

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

<input name="projectname" label="projectname" default="{$projectname}" type="dir"/>

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

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

<cfparam name="ideeventinfo">

<cfset ideData= form.ideEventInfo >

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.

Code	Context	Description
`<rdsview > <database name=""> <table name=""> <fields> <field name="" type="" length="" nullallowed="" primarykey=""/> </fields> </table> </database> </rdsview>`	rdsview	When you click a menu item of the RDS view, the event details are sent to the associated handler.
`<projectview projectname="" projectlocation=""> <resource name="" path="" type="file/folder/project" /> </projectview>`	projectview	When you click a menu item of the Project view, the event details are sent to the associated handler.
`<outlineview projectname="" projectlocation="" > <source filename="" path="" > <node type="function/other"> <function name="" returntype=""> <argument name="" type="" /> </function> </node> </source> </outlineview>`	outlineview	When you click a menu item of the Outline view, the event details are sent to the associated handler.
`<eventinfo projectname="" projectlocation="" eventtype="" > <resource name="" path="" type="file/folder/project" /> </eventinfo>`	on project create	When the specified event occurs, the event details are sent to the associated handler.
`<user> <input name="" value=""/> <input name="" value=""/> <input name="" value=""/> </user>`	input dialog	All user inputs are specified within the user tag. Each input tag within the user tag, contains specific user input. The input name is the same as the input name specified in the IDE_Config.xml file.
<user> <page index="" > <input name="" value="" /> </page> </user>	Install wizard	All user inputs are specified within the user tag and sent to the handler associated with the Install wizard. Each input tag within the user tag contains specific user input. The input name is the same as the input name specified in the IDE_Config.xml file.