Setup

Overview

The AutoCode extension adds some extra functionality to Komodo, that makes it easier to write (and test) code. Its features include:

• Tab-complete on abbreviations
• DocComment generation
• Places integration
• JavaScript console functionality
• Auto-Complete customisation

Download and intallation

Download the AutoCode .xpi from support.activestate.com/node/7280 then install using the following instuctions:

1. Make sure Komodo is open
2. Drag the .xpi file onto Komodo
3. Restart Komodo

Preferences

Ensure that the extension's functionality is enabled by going to Preferences > Editor > AutoCode, and making sure that the relevant checkboxes are checked.

For more information see the section on Komodo installation.

Auto-Abbreviations

Intro

Abbreviations are a standard Komodo feature that allow you to enter a single keyword in the editor pane, then expand that keyword into an editable code, with placeholder regions that you tab through to fill in values.

AutoCode Abbreviations allows you to use the tab key, instead of the default CTRL+T to enter an abbreviation.

Overview

The concept is perhaps easier illustrated with a sequence of images. Firstly, type a keyword corresponding to an abbreviation name, in this case "for":

Then, press tab (as opposed to the more cumbersome default, CTRL+T) to trigger the abbreviation's template:

The template is inserted into the document, and the first place holder is highlighted in each place in the template that it is used. You can alter it by simply typing, or accept the value and tab to the next placeholder.

Snippets folders

In order to expand a keyword, you'll need a named Snippet in your Toolbox's Abbreviations folder. The Snippet name should match the keyword typed, and should sit somewhere within a folder matching the language:

There are some more rules on how Snippets are selected, so see the Komodo help for further information.

Ignoring identifiers following keywords

Occasionally, pressing tab can trigger an insertion when you don't want one, for example, when declaring a variable and then tabbing to place values in columns.

For these cases, AutoCode Preferences allows you to set a list of keywords, for which when a word immediately after is tabbed, the abbreviation will be ignored:

So for example, if you typed...

var func

...and then a Tab character, the ActiveState-provided "func", insertion of the Snippet would be skipped, as the word func came immediately after the ignored keyword var.

However, typing just...

func

...would insert the Snippet as expected.

Note that AutoCode also skips inserting abbreviations if it detects the caret is currently in an inline comment or DocComment block.

DocComment generation

Overview

Komodo uses the JSDoc and PHPDoc syntax to document JavaScript and PHP code, as well as hint param and return types.

With the Auto-Comment checkbox enabled in the preferences, all you need to do comment a function or method is to type /** just above the function declaration...

...then press the TAB key:

The comment will be completed, and placeholders will be entered, allowing you to tab through the values.

Note that a return(s) value is added and automatically highlighted in full, so if there's no return value on your function, you can simply press delete when highlighted, and the entire line will be removed.

Customising formatting

You'll notice that the entries are also nicely formatted into columns. There are more options in the Preferences for this, including fixed-width columns, and padding:

Customising content

To add your own (global) custom text or parameters to class and function comments (such as @author information), locate the relevant Snippets inside AutoCode's own Toolbox...

...then add your own parameters as you wish:

The code therein will be insterted automatically into the appropriate comment types as they are created.

Places integration

Intro

The Places integration is the most powerful feature of AutoCode, and automates the process of inserting file paths, or even complete blocks of code including file paths, project variables, and image widths and heights, into a document.

Note that athough everyday usage of places integration is actually really easy, the level of customisation hides a lot of power, so it's recomended to read through the Places help at least once, just to get a brief understanding of how the various options and rules work together.

The various sections are:

• Overview
• Using snippets to generate code
• Snippet variables
• Grouping file extensions under a common Snippet
• Snippet folders
• Code generation rules
• Default Snippets

Overview

At its simplest level, Places integration enables you to simply ALT+click a file or folder in the Places panel to insert the item's relative or absolute path into the current document:

However, as well as just inserting the path, you can also use the Komodo Snippets system to customize the insertion, to insert full snippets of code that include the URL of the file being inserted. This insertion is based on both the inserted file's type and the document's current language (but can be overridden in other ways).

For example, if you are in an HTML document, and you ALT+click an image file, an HTML img tag will be insterted, including the actual width and height of the image:

Or if in the JavaScript part of the HTML document, ALT+clicking will insert some image-specific JavaScript code:

Or if in a PHP document, you could set up custom PHP code to insert images using your own code:

AutoCode comes with a variety of Snippets already set up for use, but you're more than free to add your own, directly to the AutoCode Toolbox.

Using snippets to generate code

As seen above, all insertions are fully-customisable by the user, as each of them is a standard, physical, Snippet in your Komodo Toolbox. You may edit as you see fit, even adding your own language & file type combinations.

AutoCode uses some basic rules and a standard Snippets folder structure in order to locate the correct Snippet to use:

AutoCode > Places > Root Folder > Sub-Folder (optional) > Language > extension

At the most basic level, when just working in a language such as HTML, and without any special Project settings, the folder structure to insert an image Snippet would be:

AutoCode > Places > Languages > HTML > image

In the actual Snippet panel, that looks like this:

The code inside the actual Snippet itself, with the AutoCode Places path variable being swapped out on insertion, is:

<img src="[[%tabstop:path]]" width="[[%tabstop:width]]" height="[[%tabstop:height]]" />

As you see here, AutoCode Places uses standard Snippet tab stops for the AutoCode Places variables, which is discussed in more detail next.

Snippet variables

AutoCode variables

The path variable is the default variable used for inserting paths into your documents, and is determined by the file's location relative to the document, and your AutoCode Places setting on whether that path should be relative or absolute.

However, the following path variables are available to use within your Snippets:

Variable	Description
file	the full filename, including the extension
filename	the filename only (without the extension)
fileext	the file extension only
path	the full path to (and including) the file (as determined by preferences)
relpath	the relative path to (and including) the file
abspath	the absolute path to (and including) the file from the project root
folderpath	the full path to the folder (as determined by preferences)
relfolderpath	the relative path to the folder
absfolderpath	the absolute path to the folder from the project root
uri	the URI to the file
folderuri	the URI to the folder

Also available are the following special variables:

Variable	Description
varname	any variable you have set in your project's Environment Variables
width	the image height
height	the image height

Variables are inserted into the snippet using the standard Interpolation Shortcuts mechanism, which also allows you to add snippets manually, should you so wish:

[[%tabstop:VARNAME]]

You can use these values in combination with other code, and even other tabstops (including numbered tabstops) to form fairly advanced code insertion (note that variables are case-sensitive):

@font-face {
	font-family: "[[%tabstop:name]]";
	src: url("[[%tabstop1:folderpath]][[%tabstop2:filename]]");
	src: local("☺"),
		url("[[%tabstop1:folderpath]][[%tabstop2:filename]].woff") format("woff"),
		url("[[%tabstop1:folderpath]][[%tabstop2:filename]].otf") format("opentype"),
		url("[[%tabstop1:folderpath]][[%tabstop2:filename]].svg") format("svg");
	}

Project Environment variables

Note that you can also use Project Environment variables to customise paths per project. In the following example, the Project Environment variable EXTENSION NAME has been set up:

Then, in the following Snippet, the tabstop variable EXTENSION NAME has been used, along with the Places variable abspath:

chrome://[[%tabstop:EXTENSION NAME]][[%tabstop:abspath]]

Which looks like this in the Snippets dialog:

This would (in the case of the AutoCode extension project) result in the following path being inserted:

chrome://autocode/absolute/path/to/file.ext

This allows the developer to fully-customise paths or URLs per project. Examine the sample snippets that ship with AutoCode to get an idea, and add your own as you see fit.

Grouping file extensions under a common Snippet

Sometimes, you'll want to treat various file extensions the same, such as image extensions (jpg, png, etc) in HTML.

As such, AutoCode allows you to associate groups of extensions with a single Snippet name. if you look in the AutoCode Preferences you'll find a text box where you can edit these associations, and add your own if you wish:

Note that Snippets matching extensions take precedance over Snippets matching groups when inserting code into a document.

Snippet folders

If you look at the Autocode/Places/Snippets folder, you will see that apart from the Languages sub-folder, there are also 3 other sub-folders:Custom, Documents and Projects. Each of these folders allows the developer another level of granularity when it comes to determining the selection of code snippets.

Languages

The Languages folder is the default folder where AutoCode looks for matching snippets. Simply set up your language-specific snippets underneath this folder.

Projects

The Projects folder is where you can add folders with the names of current Komodo Projects you want to use custom code for. Simply add the project name as a top level folder (or set the Project Environment variable AUTOCODE PROJECT, then use that value as the folder name), then set up your language folders beneath:

AutoCode > Places > Projects > My Project > HTML > image

This can be especially useful when you have projects that require custom paths, but you don't want to edit your default Languages snippets.

Custom

The Custom folder is where you can set up completely custom snippets to be used by AutoCode, which are made available by adding the Project Environment variable AUTOCODE PLACE, then use that value), then set up your language folders beneath.

For example, you may decide to use a particular framework (in this case, Kohana) and want to set up image-specific snippets for one of your Kohana helper classes.

You simply set the Project Environment's AUTOCODE PLACE variable to Kohana:

Create the new image Snippet:

AutoCode > Places > Custom > Kohana > PHP > image

Then edit the code in the snippet and insert using ALT+click:

Documents

The Documents folder allows you to override the the Languages settings with Document-specific settings. This is useful when you're dealing with a document that always inserts file paths in a set format.

For example, the Mozilla .manifest format requires that paths to files be expressed as absolute chrome:// URIs:

chrome://absolute/path/to/file.ext

By specifying a Document Snippet for .manifest files, you can ensure that the format is always the same, no matter what kind of file is ALT+clicked.

In this example, the Snippet AutoCode/Places/Documents/manifest is created, and an absolute URI is set:

Code generation rules

With all these different ways of generating path insertions, it might seem a little confusing. Well, the order of decision-making in order to determine which Snippet to use (or not use) is quite specific, and is outlined below.

Note that the list below is the exact order AutoCode determines which Snippet to use; the first successful match stops the process, and the Snippet is inserted:

Note that whilst the abovelist looks complex, it's not - it's just a specific order so that the more specific overrides the more general.

Defaults and overrides

So, as written above, AutoCode Places nearly always looks to insert a custom path Snippet, however, there are a few times where it doesn't:

Firstly, as soon as a file is ALT+clicked, only the path (and not a Snippet) is inserted if:

• there is a current document selection, or
• the caret is between two matching quotes

Finally, AutoCode Places has a system of defaults, which are sought if none of the extensions or groups match.

In each of the main Places folders, as well as the Language sub-folders, you can optionally place a Snippet named default, which AutoCode Places will fall back to.

The hierarchy of defaults is:

1: Places/<folder>/<language>/default
2: Places/default

For example, the Snippet Languages > HTML > default contains HTML that inserts the file path as a basic link:

<a href="[[%tabstop:path]]" />[[%tabstop:filename]]</a>

The final default is in the main Places folder. You can edit this if you have a different preference perhaps for "double" or 'single' quoted paths:

"[[%tabstop:path]]"

This system allows you to create single Snippets that will cover various eventualities in your code. See the existing examples for a better understanding if you are unclear.

JavaScript Console

Overview

Enabling the JavaScript console in AutoCode allows you to edit and run JavaScript code directly in Komodo.

Operation

With a JavaScript file open (the extension must be .js), you can use the CTRL+Enter (Mac users: Apple+Enter) shortcut key to evaluate the JavaScript currently in the editor window. (Note that you can also execute Windows .bat files by pressing CTRL+Enter).

If the code is valid, it will execute. If not, an error message will pop up, and Komodo will move the cursor to the line of the error.

The following commands are also available when using the Console, which allow you test values and output in the Command Output panel as you develop:

• trace(value): Traces the value to the command output
• inspect(value): Traces a hierarchical representation of the value to the command output. More info about inspect()'s arguments can be found here.
• clear(): Clears the command output

Below you can see the result of an inspect:

AutoComplete

Overview

The simplest functionality in AutoCode allows you to change the height of the AutoComplete dropdown from the default 5 lines.