This package provides CFML syntax highlighting as well as function and tag completions. It also has a number of other features, please see below for more information.

You can install this package via Package Control. Please restart Sublime Text after installation.

Manual installation is also possible by downloading the repository and placing it in a folder within your Sublime packages folder. (See below for more information.)

Please ensure that you are running at least build 3083 of Sublime Text 3, as some of the features of the package will not work otherwise. If you are on build 3092+ the package will use the new sublime-syntax syntax highlighting.

This package was developed from the following packages:

• https://github.com/SublimeText/ColdFusion
• https://github.com/sublimehq/Packages (especially the HTML and JavaScript syntaxes)
• https://github.com/Benvie/JavaScriptNext.tmLanguage

The current CFScript syntax is based on Will Bond's (@wbond) JavaScript syntax rewrite:

• https://github.com/sublimehq/Packages/blob/master/JavaScript/JavaScript.sublime-syntax

Special thanks to @foundeo and cfdocs.org, from which this package gets its function and tag data. Also, thanks to @mjhagen who helped me get this package off the ground.

• Completions
• Inline Documentation
• A Note about Settings
• Default Key Bindings
• CFC Indexing and Dot Paths
• Custom Tags
• Custom Coloring for CFML Tags
• Controller/View Toggle
• CommandBox
• TestBox
• Framework One
• Manual Installation

Completions are included for tags and tag attributes, as well for built-in functions and member functions. Completions are also available for Application.cfc settings and methods.

F1 is mapped to an inline documentation command that provides an inline documentation popup based on the cursor position.

You can always override the default key binding in your user key bindings file.

If the documentation command is run when the cursor is within a built-in function or tag it will load the cfdocs.org documentation for that function or tag. Thus, having the cursor anywhere within dateFormat(myDate, "yyyy-mm-dd") and pressing F1 (by default) will trigger a popup displaying the documentation for dateFormat. Similarly, having the cursor anywhere within <cfinclude template="myOtherTemplate.cfm"> and pressing F1 will trigger the display of the documention for cfinclude. Inline documentation is also available for Application.cfc settings and methods.

If you have a copy of the cfdocs.org GitHub repository on your file system, there is a package setting, "cfdocs_path", which can be set to the data directory of that repository (e.g. "cfdocs_path": "C:/github/cfdocs/data/en/"). If this is set, the cfdocs.org documentation will be loaded from the file system instead of being fetched via HTTP request. (See below for more information on package settings.)

There are several settings files that you should be aware of, as they control much of the functionality of the package. It is important to know how to access them. There are two ways to access each file, the first being through the menus, and the second being via the command palette, which you open with CTRL+SHIFT+P on Windows (CMD+SHIFT+P on a Mac).

Package Settings

You can access the default package settings from the menu under Package Settings -> CFML -> Package Settings - Default or via the command palette: CFML: Package Settings - Default. To override any of these settings, use the user package settings file. This can be accessed under the menu Package Settings -> CFML -> Package Settings - User or via the command palette: CFML: Package Settings - User.

Project Settings

Some settings are also (or only) able to be set on a per project basis. These settings control the behavior of the package for a given project. You can access and edit project files from the menu under Project -> Edit Project or via the command palette: Project: Edit Project. (These will only be accessible after you have saved a project: Project -> Save Project As or Project: Save As.)

Bindings

The default keyboard and mouse binding files are available in the menu under Package Settings -> CFML -> Key Bindings - Default and Package Settings -> CFML -> Mouse Bindings - Default. Or via the command palette at CFML: Key Bindings - Default and CFML: Mouse Bindings - Default. The user key and mouse binding files are available in the same locations.

In tag attributes, script strings, and between cfoutput tags, pressing # when text is selected will wrap the currently selected text #selected#.

CTRL+ALT+D will output a <cfdump> tag or writeDump()/dump() function in CFML script, wrapping any currently selected text.

CTRL+SHIFT+O will output a <cfoutput> tag or writeOutput() function in CFML script, wrapping any currently selected text.

CTRL+ALT+A will output a <cfabort> tag or abort; in CFML script.

If Sublime Text's auto_close_tags setting is true, when a closing tag's / has been pressed, the closing tag will be completed. There are two package settings that control which CFML and HTML tags should not be closed: cfml_non_closing_tags and html_non_closing_tags.

If the package setting cfml_auto_insert_closing_tag is set to true (by default it is false), when > is pressed in a tag, the corresponding closing tag will be automatically inserted after the cursor position. The package setting cfml_non_closing_tags controls which CFML tags will not get a closing tag auto inserted.

The package setting cfml_between_tag_pair controls the behavior of the editor when ENTER is pressed while the cursor is between a CFML tag pair (e.g. <cfoutput>|</cfoutput>). By default only a single new line is inserted. This can be changed to have an extra new line auto inserted between the tag pair (with an optional indent), and the cursor placed there. See the default package settings file for more information.

There are two settings that are set on a per project basis in a project file, cfc_folders and mappings. Here is an example (a real project file will have other settings in it as well):

{
    "mappings": [
        {"mapping": "/framework", "path": "C:/myprojects/projectname/framework"},
        {"mapping": "/model", "path": "C:/myprojects/projectname/app/model"}
    ],
    "cfc_folders": [
        {
            "path": "C:/myprojects/projectname/app/model",
            "variable_names": ["{cfc}", "{cfc}{cfc_folder_singularized}"],
            "accessors": false
        }
    ]
}

The specified mappings are used to resolve file paths to dot paths when right clicking on a CFC file in the sidebar and selecting Copy CFC Dotted Path. If more than one mapping matches, you will be given a choice, and if none match, it will fall back to using the base folder of the project as a dot path root. The mappings are also used to resolve dot paths specified in the extends attribute in a component, the createObject function, and when using the new operator to instantiate a component (e.g. new dot.path.to.component()). If the F1 command is used when the cursor is in any of these, you will get a popup with the file path for the component (plus more information about the component if it is one that has been indexed). You can click on the file path to jump to the component file. You can also CTRL+ALT+Left Click (CMD+ALT+Left Click on a Mac) on any of these to jump straight to the component file without going through the popup. In addition, these same commands will work in any quoted string that is used as a function call argument if it contains a dot path that can be resolved.

You can see the structure of this mouse binding in the Mouse Bindings - Default file. Use the Mouse Bindings - User file to create your own.

Important: mouse bindings are global throughout Sublime Text, so use caution to ensure you don't override a default Sublime Text mouse binding (such as CTRL+Left Click which adds a new cursor at the position clicked).

The cfc_folders array contains objects with one required key: path. Folders specified here are recursively searched for CFC files and those files are indexed. The variable_names setting is an array of strings, where each string specifies a variable name to associate each indexed CFC with. The names are determined via substitution as follows:

Any other text in the string will be left in place - this allows for specifying a prefix or suffix to use in the variable names. Then, if that variable name is typed in your code and followed with a ., method completions from the corresponding CFC will be offered. You can also use the F1 documentation command on these variable names as well as their methods calls to view documention regarding the CFC and its methods. (Note: the F1 command also works on property names, if they match a cfc variable name, to work with DI frameworks like DI/1 that inject beans into properties of the same name.) In addition, you can use CTRL+ALT+Left Click to jump to the CFC or to the specific method in the CFC.

By default, implicit accessors are included in the completions.The accessors key, if present and set to false, will remove implicit property accessors from the completions offered (explicit accessors will always be included).

These two settings work together, such that when a base CFC as well as another CFC that extends it are both indexed, and a mapping is specified such that the dot path in the extends can be resolved, the documentation and completions for the child CFC will include properties and methods from the base CFC. In addition, the dot paths of all indexed CFCs will be offered as completions in the extends attribute, the createObject function (where the type is component), as well as when using new to instantiate a CFC.

Support is offered on a per project basis for custom tags as used with a <cfimport> tag and a custom tag prefix. Here is an example project file (other settings have been removed):

{
    "custom_tag_folders":
    [
        {
            "path": "C:/myprojects/projectname/customtags/page",
            "prefix": "page"
        }
    ]
}

Once this is done, page will be offered as a custom tag prefix completion, and then after entering <page: a list of tags in the custom tag folder will be offered. After a tag has been entered, completions for every attributes scope variable found in that custom tag file will be offered.

You can use the F1 documentation command to get some minimal documentation about that custom tag, and CTRL+ALT+Left Click can be used to jump to the custom tag file.

The indexer will search for thistag.executionmode is/eq/== "end"/'end' (case insensitive) or <cfcase value="end"/'end'> (case insensitive) in custom tag files in order to determine whether or not to auto close the custom tag.

Unless you are using a specialized color scheme, CFML and HTML tags will receive the same coloring. This can make it a bit harder to distinguish between the two types of tags when embedding CFML tags in HTML. This package has a command you can run from the command palette that will inject custom colors for CFML tags into your current color scheme (or remove them if they are already there). Press CTRL+SHIFT+P to bring up the command palette (CMD+SHIFT+P on a Mac) and run CFML: Toggle Color Scheme Styles. You can edit the styles that will be injected via the user settings for this package.

Caveat: This feature works by either overriding or modifying your active color scheme file. Because of this, it may not work well with other packages that also modify the active color scheme in some way. Also, if the package containing your active color scheme is updated, it is likely that you will need to toggle the custom tag coloring off and then on again to pick up any changes.

CFML MVC frameworks typically have the convention that a controllers and a views folder are contained in the same parent directory, and that controller names and methods correspond to view folder and file names. CTRL+F1 (CMD+F1 on a Mac) is mapped to a toggle command that will jump the editor back and forth between a view file and the controller method that corresponds to it. The settings which determine which folder names are regarded as controller and view folders are contained in the package settings file. By default, controllers and handlers are treated as controller folders, and views as the views folder. Alternate folder names can be specifed in the user package settings file.

CommandBox (https://www.ortussolutions.com/products/commandbox) has been added as the default CFML build system. This simply means that running the build command (F7 on Windows) on a CFML file will run box ${filename} as a shell command in the directory of the file and output the result in a pane within Sublime Text (it can also be selected from the build system menu available via CTRL+SHIFT+B). For this to work, CommandBox needs to be installed, and the CommandBox box binary needs to be available system wide, so that box can be run in any directory (see https://ortus.gitbooks.io/commandbox-documentation/content/setup/installation.html).

TestBox (https://www.ortussolutions.com/products/testbox) completions and inline documentation are available for BaseSpec components. They are enabled by default, but can be disabled globally by adding "testbox_enabled": false to your CFML user package settings, or on a per project basis by adding the same setting to a project settings file. The completions and documentation are offered in any CFC that is contained under a folder named tests (alternate folders can be specified in the settings), as well as in any CFC that extends testbox.system.BaseSpec.

There are three build system variants for running TestBox tests from within Sublime Text. The first is for running all of a project's tests, which can be used no matter what project files are open, so long as the active file is a CFML one. The next variant is for running all of the tests in the directory of the currently active file, while the last variant runs the tests in the currently active test CFC only. CTRL+SHIFT+B calls up the build system menu, from which these options can be selected. Once one of the variants has been run, CTRL+B can used to run the last selected option again, without having to go through the menu.

Several settings need to be set in a project in order for these build systems to function. The first setting is testbox_runner_url, which should be the URL to a TestBox runner which runs tests and returns results in JSON. This needs to be setup so that a dot delimited directory of tests to run can be appended to it. An example URL that does this might be the following: http://localhost:8888/testbox/system/Testbox.cfc?method=runremote&reporter=json&directory=. The second setting is testbox_default_directory, which is the dot delimited directory that will be appended to the testbox_runner_url when the build variant for running all of a project's tests is selected. The last setting is testbox_tests_root, which is the root directory path that is used to determine the dot delimited path to a test directory when running the tests in a particular folder or file. (This could be the path to your project's webroot if your tests are contained under the webroot, but might not be if mappings are used.)

Results are displayed in a results pane. If there are errors or failures you can step backwards and forwards through the file stack traces via F4 and SHIFT+F4. As each file is selected, Sublime Text opens that file and jumps to the line indicated. You can also double click on any file, and Sublime Text will open it for you. Since the path to your files might look different to Sublime Text and the CFML application server (for example, if the server is running on a virtual machine), there is one more setting that maps the path as it appears to the server to the path as it appears to Sublime Text. Use testbox_results.server_root and testbox_results.sublime_root to specify the respective root paths to your project, so that Sublime Text can accurately open the files in stack traces.

All of the settings for TestBox can be seen in the default package settings.

Framework One (https://github.com/framework-one/fw1) function completions and variables.framework setting completions are available. They are disabled by default, but can be enabled globally by adding "fw1_enabled": true to your CFML user package settings, or on a per project basis by adding the same setting to a project settings file. (Project based settings will override global settings. The default package settings for Framework One can be viewed in the CFML default package settings file.) The completions are offered in Application.cfc as well as in Framework One controller, view and layout files. (The folder names can be specified in the settings.) In controllers, Framework One method completions are offered after typing framework. and fw..

Locate your Sublime Text 3 packages directory. This can be easily done by opening the command palette in Sublime Text (CTRL+SHIFT+P on Windows, CMD+SHIFT+P on a Mac), and running Preferences: Browse Packages.

On Windows it will typically be something like this: C:\Users\Username\AppData\Roaming\Sublime Text 3\Packages\

On a Mac it will be something like this: /Users/Username/Library/Application Support/Sublime Text 3/Packages/

Open Terminal or Command Prompt and cd into your packages directory, then run:

git clone https://github.com/jcberquist/sublimetext-cfml.git ./CFML

The specified ./CFML subdirectory is optional and if it is not included the package will be cloned into sublimetext-cfml.

That's it, restart Sublime Text 3 - if you want to update the code to match this repo, simply run the following inside the folder where you installed the package:

git pull origin master

Use the Download ZIP option to download a zip of the repository to your computer. Unzip this, and copy the repository folder into your Sublime Text packages directory. You can leave the folder name as is, or rename it (e.g. to CFML).