A plugin to run your Commandbox tasks from within Sublime plus some handy snippets too.

Quickstart

1. Install Via Package Control Commandbox

Installation

via PackageControl

If you have PackageControl installed, you can use it to install the package.

Just type cmd-shift-p/ctrl-shift-p to bring up the command pallete and pick Package Control: Install Package from the dropdown, search and select the CommandBox package there and you're all set.

Manually

You can clone the repo in your /Packages (Preferences -> Browse Packages...) folder and start using/hacking it.

cd ~/path/to/Packages
git clone git://github.com/Ortus-Solutions/sublime-commandbox.git Commandbox

Troubleshooting

If you are having trouble running the plugin in Mac OSX it's possible that your path isn't being reported by your shell. In which case give the plugin SublimeFixMacPath a try. It may resolve our issue.

If you still can't get it to run properly, first make sure your Commandbox tasks run from a terminal (i.e. outside of sublime) and if so then submit an issue.

Usage

Running a Commandbox Command

You may select pre-configured commands from Menu -> Commandbox, including the ability enter a custom command.

Keyboard Shortcuts:

• Ctrl+Shift+B - Run Commandbox Command: A prompt input will open for you to enter your command

• Ctrl+Shift+T - Start the Embedded Server: Your Commandbox cwd is always the root of your Sublime Project so any box.json configuration will be honored

• Ctrl+Shift+P - Stop the Embedded Server

• Alt+P - Show the Commandbox Output Panel ( also available in the View -> Commandbox menu )

• Alt+[Command|Windows]+P - Hide the Commandbox Output Panel ( also available in the View -> Commandbox menu )

Settings

The file Commandbox.sublime-settings is used for configuration, you can change your user settings in Preferences -> Package Settings -> Commandbox -> Settings - User.

The defaults are:

{
    // Override your environment PATH
    "exec_args": {},
    // Use a new tab when showing the results. If it's false it'll use a panel.
    "results_in_new_tab": false,
    // Defines the delay used to autoclose the panel or tab that holds the box results.
    // If false (or 0) it will remain open.
    "results_autoclose_timeout_in_milliseconds": 0,
    // If true it will open the output panel when running Commandbox(silent) only if the task failed
    "show_silent_errors": true,
    // Create the file 'sublime-commandbox.log' to report errors
    "log_errors": true,
    // Syntax file for highlighting the box results
    // Set to false if you don't want any colors (you may need to restart Sublime)
    "syntax": "Packages/Commandbox/syntax/CommandboxResults.tmLanguage",
    // Read from stdout and stderr without blocking (both at the same time)
    "nonblocking": true,
    // Add a custom flag to a particular box command. Format: { "task_name": "flags" }
    // For example: { "concat": "--silent" }
    "flags": {},
    // If `false` the package will run even if no `box.json` is found on the root folders currently open.
    "check_for_boxjson": true,
}

exec_args

You may override your PATH environment variable as follows:

{
    "exec_args": {
        "path": "/bin:/usr/bin:/usr/local/bin"
    }
}

box installed locally

If box is installed locally in the project, you have to specify the path to the box executable. Threfore, adjust the path to /bin:/usr/bin:/usr/local/bin:node_modules/.bin

results_in_new_tab

If set to true, a new tab will be used instead of a panel to output the results.

results_autoclose_timeout_in_milliseconds

Defines the delay used to autoclose the panel or tab that holds the Commandbox results.

show_silent_errors

If true it will open the output panel when running Commandbox (silent) only if the task failed

log_erros

Toggles the creation of sublime-commandbox.log if any error occurs.

syntax

Syntax file for highlighting the box results. You can pick it from from the command panel as Set Syntax: Commandbox results.

Set the setting to false if you don't want any colors (you may need to restart Sublime if you're removing the syntax).

nonblocking

When enabled, the package will read the streams from the task process using two threads, one for stdout and another for stderr. This allows all the output to be piped to Sublime live without having to wait for the task to finish.

If set to false, it will read first from stdout and then from stderr.

Bind Your Own Keyboard Shortcuts

You can use a shortcut for running a specific task like this:

{ "keys": ["KEYS"], "command": "commandbox", "args": { "task_name": "watch" } }

Even though you can run CommandBox from your favorite terminal window, there are a number of nice IDE integrations out there that are designed to allow you to run command line utilities from inside your favorite editor. Here's a few that we're aware of and how to use them. If you have more, please let us know!

Here are suggestions for using VSC (Visual Studio Code) for developing in CFML.

What do you want to do with VSC?

1. Install it?

2. Key Extensions?

3. Working with the shell/terminal

4. Git Extensions?

Installing VSCode

This IDE has it's own domain. ( https://code.visualstudio.com/ ) with downloads for macOS, Windows and Linux on the home page. :+1:

Using The Terminal/Shell

You can approach this different ways. It is pretty nice to have the command prompt running right inside your IDE. Pressing CTRL +` will show and/or hide your terminal. This will let you run Commandbox directly inside your terminal.

Commandbox only

Go to File > Preferences > Settings and search for shell.windows. Hover over the item in DEFAULT SETTINGS and you will see an edit pencil. Click on that and it will copy the values over to USER SETTINGS. (NOTE: You can also set stuff up in WORKSPACE SETTINGS for different projects. Now set the location of commandbox on your system like we did in our system in the example below.

"terminal.integrated.shell.windows": "/path/to/box",

When adding a path, follow the rules for adding platform specific path seperators.

Commandbox and Shells of Choice

Install Shell Launcher and reload the IDE.

• Shell Launcher Easily launch multiple shell configurations in the terminal.

Now open your user settings like is shown in the Commandbox only section just above. Add the following to your USER SETTINGS.

//Shell launcher // A list of shell configurations for Windows "shellLauncher.shells.windows": [ { "shell": "C:\\Windows\\sysnative\\cmd.exe", "label": "cmd" }, { "shell": "/path/to/box", "label": "Commandbox" } ],

Or loading it as desired

If you have commandbox mapped to a path you can of course just call box like you would from any terminal and it will load right up for you. Just use any terminal in VSC that would load box outside VSC and it will run the same.

Key Extensions

You should also install a few extensions. (These extensions can also be added from the built in Extentions item.)

• CFML Language Support

• CFLint Support

• Tag Comment Support

Git Extensions

Additional Extensions ( of course, choose the ones you want and ignore the others )

• Git Lens This will take your git IDE to new levels.

P.S. A couple of other nice plugins.

• TODO Highlight Add TODO, FIXME or other comments to code and find quickly with this extension.

• Project Manager: save folders as projects and easily switch between projects

• Hg: integrated Mercurial source control

• Great Icons Because it is more fun, nuff said!

More information to follow. (Including video guides to show how to get started that may not be as familiar with different parts.)