AngularJs Sublime Text 2 Bundle

This package provides snippets for all the available AngularJS api calls. The snippets are activated both in HTML and CoffeeScript.

Is this a major perversion of the snippet system? In a way, yes.

Think of it more as a poor mans Intellisense, rather than a series of snippets. The snippets intentionally overlap with one another, so that only a few simple mnemonics require memorization, rather than hundreds.

Using this approach, instead of providing a xyz,TAB style snippet expansion, xyz,TAB will load a context-sensitive Sublime completion overlay where the appropriate snippet can be picked with the arrow keys and an additional TAB. For example, ng,TAB in an HTML tag will show all the available ng-* attributes. This is a little slower approach than the one typically taken with snippets, but decreases the learning curve over the API surface. Note that Sublime appears to have different conditions for showing the completion overlay. Simply typing ng in a CoffeeScript document will show the completion menu, while the TAB is required in HTML. (This is potentially related to other installed packages)

Installation

Automatic

Ensure that you have installed Sublime Package Control following these instructions

Open the Sublime command palette with Ctrl + Shift + P, type / select Package Control: Install Package, then from the package control list, type / select AngularJS (CoffeeScript)

Note that packages are auto-updating, so as new modifications are made they will automatically be installed.

Manual tweaking of Package Control

This is not recommended, but Package control can be pointed directly at this GitHub repository rather than using the registry. Add to Packages\User\Package Control.sublime-settings, under the appropriate keys in the JSON config file.

This file can be opened via the Sublime menu: Preferences -> Package Settings -> Package Control -> Settings -- User

{
  "installed_packages":
  [
    "AngularJS (CoffeeScript)"
  ],
  "package_name_map":
  {
    "Sublime-AngularJS-Coffee-Completions": "AngularJS (CoffeeScript)"
  },
  "repositories":
  [
    "https://github.com/EastPoint/Sublime-AngularJS-Coffee-Completions"
  ]
}

Keybindings

Snippet triggers in Sublime are effectively implicit key bindings, that are always mapped to a series of characters + TAB. Alternatively, they can be found on the Ctrl + Shift + P menu by typing Ang to filter the list.

It is further recommended that a keybinding similar to the following is added to provide single key combo access to all the currently available snippets.

[
  { "keys": ["shift+f3"], "command": "show_overlay",
    "args": {"overlay": "command_palette", "text": "Angular"} }
]

To allow for the $ character to trigger the menu automatically, the following must be added to the Preferences.sublime-settings file. This file can be opened by the Preferences -> Settings -- User menu item.

{
    "auto_complete_triggers":
    [
        {
            "characters": "$",
            "selector": "source.coffee, source.js, source.js.embedded.html"
        }
    ]
}

If you want to disable duplicate $s from showing up in the editor when completing, then you must change the default word_separators to the following, in the same user Preferences.sublime-settings

{
    "word_separators": "./\\()\"'-:,.;<>~!@#%^&*|+=[]{}`~?"
}

NOTE: auto_complete_triggers and word_separators are siblings in the same JSON config object.

CoffeeScript

The bindings have been selected so that they don't interfere with the standard CoffeeScript bindings, namely =, -, cla, log, elif, el, if, ifel, #, forof, forx, fori, forin, req, swi, ter, try or unl

Sublime Bugs

Unfortunately there are a couple of issues with Sublime at the moment preventing it from doing a couple of things that would help us out:

• Filtering within the completions overlay doesn't work right when the $ character is involved.

• There is no way to add names to a completion like you can for a snippet, so the Ctrl + Space overlay only shows identifiers.

• The tab trigger system in Sublime does not support regular expressions. So when dealing with a member function such as scope.$watch, there is no way to reduce the noise in the list when pressing .$. We see all completions starting with $ rather than only those starting with .$, lengthening the list.

• There is no way that I can find to limit the scope of the ng-* attributes to only the HTML tags that they are valid for (i.e. ng-csp only belong on html) The best we can do here is to segregate snippets that are attributes vs tags.

• Sublime doesn't have a convention for optional parameters / blocks in snippets. This is faked by highlighting the block on the first TAB so that it may be deleted, and allowing subsequent TABs to change specific values in the block if the block is kept. However, Sublime still honors the tabs inside the block after it's been deleted. In practical terms, this means it may require extra TAB presses to send the cursor to the next replacement point after an optional block has been deleted.

Please vote up issues 124225 and 124217 if you want to see these issues resolved!

Hopefully a future version of Sublime will address these issues, but for now there are some work-arounds.

The solution at the moment is to provide placeholder snippets for top-level services such as $filter.

A workflow for this would be the following:

`$`, `TAB`
  -> select Angular filter from the menu with `TAB`
  -> `$filter` is inserted into document
  -> `TAB` brings up completions against `$filter`
  -> select specific filter from the menu with `TAB` (such as currency)
  -> `$filter('currency') currency, 'symbol-eg-USD$'` is inserted into document
  and supports `TAB` completion (or chunk deletion)

Tab Triggers

The number of tab triggers is intentionally limited to increase discoverability. As a convention, most parameters have been stubbed with a value that indicates the value that should be replaced. Where functions take multiple possible parameters, the | has been used by convention - i.e. true|false

tl;dr Version

These are the only triggers used - $, .$, ng, for, is, mod, dir, fil, mock, $cookieStore, $filter., $http., $httpBackend., $injector., $interpolate., $location., $log., $provide., $q., $route., $routeProvider., .error, .expect, .other, .success and .when … PHEW

Directive

All HTML based directives are keyed off the ng,TAB binding.

Module

Scope

Controller

Covers both FormController and NgModelController

Resource

Filter

Global API

Http

HttpBackend

Note that .expect and .when are designed to chain, so we don't bind to $httpBackend

Q

Route

Cookie

Location

Log

Mock

Injector

Interpolate

Provide

Other Services

Future Improvements

• It would be nice to provide inline docs through SublimeCodeIntel in a vein similar to the ones provided for jQuery.

• SublimeErl also provides some pretty fancy features which would be nice to integrate

Making Contributions

• When editing .sublime-snippets files, always use real tab characters for indentation on a newline following a crlf/lf. Sublime will automatically insert spaces if your user settings specify spacing for indentation.

• Write CoffeeScript that will pass coffeelint

Thanks

Original inspiration was from the AngularJS tmbundle, which was targeted at JavaScript and a small set of mnemonics for common operations. This is designed to be more comprehensive.