Dictionaries.. wonderful things. Languages evolve over time, and the extensive range of words and vocabulary inevitably adapts to 'roll with the changes'. Without dictionaries assisting us, we run the risk of becoming reticent with our choice of vocabulary and to an extent our progress with our chosen language.
This can be true for any language, written or spoken.
The CFML Language
Take CFML, for example. As the years have passed and new versions of the programming language have been released, there have been enhancements and additions to each release to improve the language to cater for the requirements in the modern world.
And with every release, an updated reference or dictionary has been released to assist developers and to help us understand at a glance what changes have been made and what we can now do.
Code Assist
ColdFusion Builder ships with code / content assist functionality to assist with code completion and to help with remembering the attributes available for any tag or function - let's face it, there are a lot of them, and we all need prompting from time to time to refresh our memories.
CF Builder comes loaded with a dictionary for MX 7, 8 and of course ColdFusion 9.
You can access the editor to change the current dictionary in use by following these steps:
- Open up Window -> Preferences
- In the tree list, navigate to ColdFusion -> Editor Profiles -> Editor -> Code Assist
You will be presented with the following window and information:
From the drop-down list you can change your selected dictionary to use within the editor for code assistance.
But wait a minute..
What's up?
I'm using an engine which has different tags
Ah, I see. So, you want to use the awesome-ness that is ColdFusion Builder AND adapt the dictionary so that you can use the code assist to help you with the extra tags and functions that you have access to?
Not a problem.
Each dictionary included with ColdFusion Builder is an XML file containing information about each tag and function in the library. As such, you can easily amend an existing dictionary or create your own to suit your requirements.
Create a custom dictionary
Firstly, you'll need to navigate to the location of the dictionaries within your ColdFusion Builder installation, within the plugins directory: \plugins\com.adobe.ide.coldfusion.dictionary_XXX\dictionary
In my case, the directory was called 'plugins\com.adobe.ide.coldfusion.dictionary_1.0.0.271911\dictionary'.
- Create a directory called 'Custom' within the Dictionary directory
- Create an XML file to describe the custom tags and functions
In this example, let's create an XML file to contain some dictionary references for the Railo tags and functions.
The basic structure of the XML file is as follows:
<dictionary>
<tags>
<tag>
<parameter>
</parameter>
</tag>
</tags>
</dictionary>
The root node is the dictionary element, and each tag node holds the description and attributes for the entry, wrapped by the tags node.
Let's add a sample entry for the cfvideoplayer tag.
Custom/railo.xml
<?xml version="1.0" encoding="UTF-8"?>
<dictionary>
<tags>
<!--
cfvideoplayer
preview = "string"
video = "string"
thumbnails = "boolean"
-->
<tag endtagrequired="false" name="cfvideoplayer"
single="true" xmlstyle="false">
<help><![CDATA[
Play a video
]]>
</help>
<parameter name="preview" required="false" type="String">
<help><![CDATA[
The path of the preview image.
]]></help>
<values/>
</parameter>
<parameter name="video" required="false" type="String">
<help><![CDATA[
The path to Movie File (flv/mp4).
]]></help>
<values/>
</parameter>
<parameter name="thumbnails" required="false" type="boolean">
<help><![CDATA[
Use thumbnails in playlist or not.
]]></help>
<values default="false">
<value option="true" />
<value option="false" />
</values>
</parameter>
</tag>
</tags>
</dictionary>
Although not a complete entry for the cfvideoplayer tag, here we have defined the tag in the dictionary and added in three of the attributes available for it.
Ideally, the help nodes should be as complete as possible for every step to assist the user with information on every tag and attribute available.
The concept of adding functions to the dictionary is exactly the same, with the small but hopefully obvious amendment of using a functions node instead of the tags node.
<functions>
<function name="abs" returns="Numeric" >
<help><![CDATA[
Absolute-value function. The absolute value of a number is
the number without its sign.
]]></help>
<parameter name="number" required="true" type="Numeric">
<help><![CDATA[
]]></help>
</parameter>
</function>
</functions>
Setting attribute combinations
The dictionaries also contain extra nodes and elements to assist with code writing.
For any tags that contain attributes dependant on another, you can use the possiblecombinations node, including combinations within.
The following example here is taken from the cfmessagebox entry in the CF9 dictionary. The possiblecombinations node is placed immediately after the final parameter node before the closing tag node.
<possiblecombinations>
<combination attributename="name">
<required>name,type</required>
<optional>callback,labelcancel,labelno,labelok,
labelyes,message,multiline,title</optional>
</combination>
<combination attributename="type">
<required>name,type</required>
<optional>callback,labelcancel,labelno,labelok,
labelyes,message,multiline,title</optional>
</combination>
</possiblecombinations>
Loading the dictionary
So, you've written your custom dictionary to include tags and functions for your CFML engine of choice. You now need to load the dictionary into ColdFusion Builder for use in the editor.
Firstly, the dictionary needs to be included into the dictionaryconfig.xml file. This lives in the same dictionary directory and contains the names and paths to the dictionaries loaded into ColdFusion Builder.
Open this file in your text editor of choice and add the following:
<dictionary_config>
<dictionary id="CF_DICTIONARY">
<version key="ColdFusion9" label="ColdFusion 9">
<grammar location="cf9.xml" />
</version>
<version key="ColdFusion8" label="ColdFusion 8">
<grammar location="cf8.xml" />
</version>
<version key="ColdFusionMX7" label="ColdFusion MX 7">
<grammar location="cfml7.xml" />
</version>
<!--
add the RailoSample dictionary. Set a name
and include the location to the file
-->
<version key="RailoSample" label="Railo Sample">
<grammar location="Custom/railo.xml" />
</version>
</dictionary>
<dictionary id="SQL_DICTIONARY">
<version key="mssql" label="Microsoft(R) SQL Server">
<grammar location="sqlkeywords.txt" />
</version>
</dictionary>
</dictionary_config>
You can see from the config file that ColdFusion Builder also loads in a SQL dictionary for MS SQL. This is worth noting if you wanted to include your own DB dictionary or amend the included file.
Ok, the dictionaryconfig.xml file is now aware of our new custom dictionary. Navigate your way to the Code Assist menu in Preferences once more:
- Open up Window -> Preferences
- In the tree list, navigate to ColdFusion -> Editor Profiles -> Editor -> Code Assist
Directly beneath the drop-down dictionary list, click the 'Reload Dictionaries' button. You may need to restart ColdFusion Builder for it to pick up on the new XML file created in the directory.
Once the dictionary is visible in the list, select your new file and you're ready to start coding in the editor.
You can see that the new dictionary is in use and hinting the tags we have entered in, complete with hint pop ups.
The attributes are also working nicely and providing reminders for us as well.
What does this all mean?
In essence, this means that any CFML developer, regardless of their chosen / preferred engine is able to use ColdFusion Builder to optimise their workflow and enhance their applications.
The ability to create custom dictionaries is incredibly clever and ensures that ALL CFML developers have the same abilities with the development tools on offer.