diff --git a/docs/authoring-packages.md b/docs/authoring-packages.md deleted file mode 100644 index 417e3363e..000000000 --- a/docs/authoring-packages.md +++ /dev/null @@ -1,133 +0,0 @@ -# Authoring Packages - -A package can contain a variety of different resource types to change Atom's -behavior. The basic package layout is as follows (not every package will -have all of these directories): - -```text -my-package/ - lib/ - config/ - stylesheets/ - keymaps/ - snippets/ - grammars/ - package.json - index.coffee -``` - -**NOTE:** NPM behavior is partially implemented until we get a working Node.js -API built into Atom. The goal is to make Atom packages be a superset of NPM -packages - -## package.json - -Similar to npm packages, Atom packages can contain a `package.json` file in their -top-level directory. This file contains metadata about the package, such as the -path to its "main" module, library dependencies, and manifests specifying the -order in which its resources should be loaded. - -## Source Code - -If you want to extend Atom's behavior, your package should contain a single -top-level module, which you export from `index.coffee` or another file as -indicated by the `main` key in your `package.json` file. The remainder of your -code should be placed in the `lib` directory, and required from your top-level -file. - -Your package's top-level module is a singleton object that manages the lifecycle -of your extensions to Atom. Even if your package creates ten different views and -appends them to different parts of the DOM, it's all managed from your top-level -object. Your package's top-level module should implement the following methods: - -- `activate(rootView, state)` **Required**: This method is called when your -package is loaded. It is always passed the window's global `rootView`, and is -sometimes passed state data if the window has been reloaded and your module -implements the `serialize` method. - -- `serialize()` **Optional**: This method is called when the window is shutting -down, allowing you to return JSON to represent the state of your component. When -the window is later restored, the data you returned will be passed to your -module's `activate` method so you can restore your view to where the user left -off. - -- `deactivate()` **Optional**: This method is called when the window is shutting -down. If your package is watching any files or holding external resources in any -other way, release them here. If you're just subscribing to things on window -you don't need to worry because that's getting torn down anyway. - -## A Simple Package Layout: - -```text -my-package/ - package.json # optional - index.coffee - lib/ - my-package.coffee -``` - -`index.coffee`: -```coffeescript -module.exports = require "./lib/my-package" -``` - -`my-package/my-package.coffee`: -```coffeescript -module.exports = - activate: (rootView, state) -> # ... - deactivate: -> # ... - serialize: -> # ... -``` - -Beyond this simple contract, your package has full access to Atom's internal -API. Anything we call internally, you can call as well. Be aware that since we -are early in development, APIs are subject to change and we have not yet -established clear boundaries between what is public and what is private. Also, -Please collaborate with us if you need an API that doesn't exist. Our goal is -to build out Atom's API organically based on the needs of package authors like -you. See [Atom's built-in packages](https://github.com/github/atom/tree/master/src/packages) -for examples of Atom's API in action. - -## Stylesheets - -Stylesheets for your package should be placed in the `stylesheets` directory. -Any stylesheets in this directory will be loaded and attached to the DOM when -your package is activated. An optional `stylesheets` key in your `package.json` -can list the stylesheets by name in order to specify a load order; otherwise -stylesheets are loaded alphabetically. - -## Keymaps - -Keymaps are placed in the `keymaps` subdirectory. By default, all keymaps will be -loaded in alphabetical order unless there is a `keymaps` array in `package.json` -specifying which keymaps to load and in what order. It's a good idea to provide -default keymaps for your extension. They can be customized by users later. See -the (main keymaps documentation)[#keymaps] for more information on how keymaps -work. - -## Snippets - -An extension can supply snippets in a `snippets` directory as `.cson` or `.json` -files: - -```coffeescript -".source.coffee .specs": - "Expect": - prefix: "ex" - body: "expect($1).to$2" - "Describe": - prefix: "de" - body: """ - describe "${1:description}", -> - ${2:body} - """ -``` - -A snippets file contains scope selectors at its top level. Each scope selector -contains a hash of snippets keyed by their name. Each snippet specifies a -`prefix` and a `body` key. - -All files in the directory will be automatically loaded, unless the -`package.json` supplies a `snippets` key as a manifest. As with all scoped -items, snippets loaded later take precedence over earlier snippets when two -snippets match a scope with the same specificity. diff --git a/docs/built-in-packages/command-panel.md b/docs/built-in-packages/command-panel.md index 30efa4a9b..d6ebc5725 100644 --- a/docs/built-in-packages/command-panel.md +++ b/docs/built-in-packages/command-panel.md @@ -1,22 +1,26 @@ -## Command Panel +# Command Panel -A partial implementation of the [Sam command language](http://man.cat-v.org/plan_9/1/sam) +The command panel contains a partial implementation of the [Sam command language](http://man.cat-v.org/plan_9/1/sam). +In addition, packages are free to design and define any scoped command. -*Examples* +Pop open the command line by hitting . +You can get a list of commands available to Atom (including any keybindings) by hitting `meta-p`. -`,` selects entire file +## Examples -`1,4` selects lines 1-4 +`,` selects the entire file + +`1,4` selects lines 1-4 in the current file `/pattern` selects the first match after the cursor/selection -`s/pattern/replacement` replace first text matching pattern in current selection +`s/pattern/replacement` replaces the first text matching pattern in current selection -`s/pattern/replacement/g` replace all text matching pattern in current selection +`s/pattern/replacement/g` replaces all text matching pattern in current selection -`,s/pattern/replacement/g` replace all text matching pattern in file +`,s/pattern/replacement/g` replaces all text matching pattern in file -`1,4s/pattern/replacement` replace all text matching pattern in lines 1-4 +`1,4s/pattern/replacement` replaces all text matching pattern in lines 1-4 `x/pattern` selects all matches in the current selections diff --git a/docs/built-in-packages/wrap-guide.md b/docs/built-in-packages/wrap-guide.md index c16b9e2e2..3f0868585 100644 --- a/docs/built-in-packages/wrap-guide.md +++ b/docs/built-in-packages/wrap-guide.md @@ -1,17 +1,16 @@ ## Wrap Guide The `wrap-guide` extension places a vertical line in each editor at a certain -column to guide your formatting so lines do not exceed a certain width. +column to guide your formatting, so lines do not exceed a certain width. -By default the wrap-guide is placed at the 80th column. +By default, the wrap-guide is placed at the 80th column. ### Configuration You can customize where the column is placed using the `wrapGuide.columns` -config option. +config option: -config.cson: -```coffee-cript +```coffeescript "wrap-guide": columns: [ { pattern: "\.mm$", column: 200 }, diff --git a/docs/configuring-atom.md b/docs/configuring-atom.md new file mode 100644 index 000000000..fad41f987 --- /dev/null +++ b/docs/configuring-atom.md @@ -0,0 +1,138 @@ +# Configuration Settings + +## Your .atom Directory + +When you install Atom, an _.atom_ directory is created in your home directory. +If you press `meta-,`, that directory is opened in a new window. For the +time being, this serves as the primary interface for adjusting configuration +settings, adding and changing key bindings, tweaking styles, etc. + +Atom loads configuration settings from the `config.cson` file in your _~/.atom_ +directory, which contains CoffeeScript-style JSON: + +```coffeescript +core: + hideGitIgnoredFiles: true +editor: + fontSize: 18 +``` + +Configuration is broken into namespaces, which are defined by the config hash's +top-level keys. In addition to Atom's core components, each package may define +its own namespace. + +## Glossary of Config Keys + +- `core` + - `disablePackages`: An array of package names to disable + - `hideGitIgnoredFiles`: Whether files in the _.gitignore_ should be hidden + - `ignoredNames`: File names to ignore across all of Atom (not fully implemented) + - `themes`: An array of theme names to load, in cascading order + - `autosave`: Save a buffer when its view loses focus +- `editor` + - `autoIndent`: Enable/disable basic auto-indent (defaults to `true`) + - `autoIndentOnPaste`: Enable/disable auto-indented pasted text (defaults to `false`) + - `nonWordCharacters`: A string of non-word characters to define word boundaries + - `fontSize`: The editor font size + - `fontFamily`: The editor font family + - `invisibles`: Specify characters that Atom renders for invisibles in this hash + - `tab`: Hard tab characters + - `cr`: Carriage return (for Microsoft-style line endings) + - `eol`: `\n` characters + - `space`: Leading and trailing space characters + - `preferredLineLength`: Identifies the length of a line (defaults to `80`) + - `showInvisibles`: Whether to render placeholders for invisible characters (defaults to `false`) +- `fuzzyFinder` + - `ignoredNames`: Files to ignore *only* in the fuzzy-finder +- `whitespace` + - `ensureSingleTrailingNewline`: Whether to reduce multiple newlines to one at the end of files +- `wrapGuide` + - `columns`: Array of hashes with a `pattern` and `column` key to match the + the path of the current editor to a column position. + +## Customizing Key Bindings + +Atom keymaps work similarly to stylesheets. Just as stylesheets use selectors +to apply styles to elements, Atom keymaps use selectors to associate keystrokes +with events in specific contexts. Here's a small example, excerpted from Atom's +built-in keymaps: + +```coffee-script +'.editor': + 'enter': 'editor:newline' + +".select-list .editor.mini": + 'enter': 'core:confirm', +``` + +This keymap defines the meaning of `enter` in two different contexts. In a +normal editor, pressing `enter` emits the `editor:newline` event, which causes +the editor to insert a newline. But if the same keystroke occurs inside of a +select list's mini-editor, it instead emits the `core:confirm` event based on +the binding in the more-specific selector. + +By default, any keymap files in your `~/.atom/keymaps` directory are loaded +in alphabetical order when Atom is started. They will always be loaded last, +giving you the chance to override bindings that are defined by Atom's core +keymaps or third-party packages. + +## Changing The Theme + +Atom comes bundled with two themes `atom-dark-*` and `atom-light-*`. + +Because Atom themes are based on CSS, it's possible to have multiple themes +active at the same time. For example, you'll usually select a theme for the UI +and another theme for syntax highlighting. You can select themes by specifying +them in the `core.themes` array in your `config.cson`: + +```coffee-script +core: + themes: ["atom-light-ui", "atom-light-syntax"] + # or, if the sun is going down: + # themes: ["atom-dark-ui", "atom-dark-syntax"] +``` + +You install new themes by placing them in the _~/.atom/themes_ directory. A +theme can be a CSS file, a directory containing multiple CSS files, or a +TextMate theme (either _.tmTheme_ or _.plist_). + + +## Installing Packages (Partially Implemented) + +To install a package, clone it into the _~/.atom/packages_ directory. Atom will +also load grammars and snippets from TextMate bundles. If you want to disable a +package without removing it from the packages directory, insert its name into +_config.core.disabledPackages_: + +```coffeescript +core: + disabledPackages: [ + "fuzzy-finder", + "tree-view" + ] +``` + +## Quick Personal Hacks + +### user.coffee + +When Atom finishes loading, it will evaluate _user.coffee_ in your _~/.atom_ +directory, giving you a chance to run arbitrary personal CoffeeScript code to +make customizations. You have full access to Atom's API from code in this file. +Please refer to the [Atom Internals Guide](./internals/intro,md) for more information. If your +customizations become extensive, consider [creating a package](./packages/creating_packages.md). + +### user.css + +If you want to apply quick-and-dirty personal styling changes without creating +an entire theme that you intend to distribute, you can add styles to +_user.css_ in your _~/.atom_ directory. + +For example, to change the color of the highlighted line number for the line that +contains the cursor, you could add the following style to _user.css_: + +```css +.editor .line-number.cursor-line { + color: pink; +} +``` diff --git a/docs/getting-started.md b/docs/getting-started.md index 92b31f50e..c9c8f2504 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,32 +1,33 @@ # Getting Started -Welcome to Atom. This documentation is intended to offer a basic introduction -of how to get productive with this editor. Then we'll delve into more details -about configuring, theming, and extending Atom. +Welcome to Atom. This documentation provides a basic introduction to being +productive with this editor. We'll then delve into more details about configuring, +theming, and extending Atom. ## The Command Palette -If there's one key-command you learn in Atom, it should be `meta-p` (`meta` is +If there's one key-command you must remember in Atom, it should be `meta-p` (`meta` is synonymous with the ⌘ key). You can always hit `meta-p` to bring up a list of commands that are relevant to the currently focused UI element. If there is a key binding for a given command, it is also displayed. This is a great way to explore the system and get to know the key commands interactively. If you'd like -to add or change a binding for a command, refer to the [key -bindings](#customizing-key-bindings) section to learn how. +to learn about adding or changing a binding for a command, refer to the [key +bindings](#customizing-key-bindings) section. ![Command Palette](http://f.cl.ly/items/32041o3w471F3C0F0V2O/Screen%20Shot%202013-02-13%20at%207.27.41%20PM.png) ## Basic Key Bindings -Remember you can always use `meta-p` to explore available commands and their + +You can always use `meta-p` to explore available commands and their bindings, but here's a list of a few useful commands. -- `meta-o` : open file/directory -- `meta-n` : new window +- `meta-o` : open a file or directory +- `meta-n` : open new window - `meta-r` : reload the current window -- `meta-alt-ctrl-s` : run specs -- `meta-t` : open fuzzy file finder +- `meta-alt-ctrl-s` : run test specs +- `meta-t` : open file finder to navigate files in your project - `meta-;` : open command prompt -- `meta-f` : open command prompt with `/` +- `meta-f` : open command prompt with `/` for a local file search - `meta-g` : repeat the last local search - `meta-shift-f` : open command prompt with `Xx/` for a project-wide search - `meta-\` : focus/open tree view, or close it when it is focused @@ -52,8 +53,8 @@ issue so you can keep working. The fastest way to find a file in your project is to use the fuzzy finder. Just hit `meta-t` and start typing the name of the file you're looking for. If you -already have the file open and want to jump to it, hit `meta-b` to bring up a -searchable list of open buffers. +already have the file open as a tab and want to jump to it, hit `meta-b` to bring +up a searchable list of open buffers. You can also use the tree view to navigate to a file. To open or move focus to the tree view, hit `meta-\`. You can then navigate to a file and select it with @@ -73,28 +74,32 @@ To delete a file, select it in the tree view and hit `delete`. #### Using the Command Line -Atom has a command line similar to editors Emacs and Vim, which is currently the -only interface for performing searches. Hitting `meta-f` will open the command -line prepopulated with the `/` command, which finds forward in the current -buffer from the location of the cursor. Pressing `meta-g` will repeat the -search. Hitting `meta-shift-f` will open the command line prepopulated with -`Xx/`, which is a composite command that performs a global search. The results -of the search will appear in the operation preview list, which you can focus +Atom has a command line similar to old-school editors such as emacs and vim. Nearly +every command has a key binding which you can discover with `meta-p`. + +The command line is also (currently) the only place you can perform a search. Hitting +`meta-f` opens the command line and prepopulates it with the `/` command. This finds +text in the current buffer, starting at the location of the cursor. Pressing `meta-g` +repeats the search. Hitting `meta-shift-f` opens the command line and prepopulates +it with `Xx/`, which is a composite command that performs a global search. The results +of the search appear in the operation preview list, which you can focus with `meta-:`. -Atom's command language is still under construction and is loosely based on +Atom's command language is still under construction, and is loosely based on the [Sam editor](http://doc.cat-v.org/bell_labs/sam_lang_tutorial/) from the -Plan 9 operating system. It's similar to Ex mode in Vim, but is selection-based +Plan 9 operating system. It's similar to Ex mode in vim, but is selection-based rather than line-based. It allows you to compose commands together in interesting ways. #### Navigating By Symbols If you want to jump to a method, you can use the ctags-based symbols package. -The `meta-j` binding will open a list of all symbols in the current file. The -`meta-shift-j` binding will open a list of all symbols for the current project -based on a tags file. And `meta-.` will jump to the tag for the word currently -under the cursor. Make sure you have a tags file generated for the project for +The `meta-j` binding opens a list of all symbols in the current file. The +`meta-shift-j` binding opens a list of all symbols for the current project +based on a tags file. `meta-.` jumps to the tag for the word currently +under the cursor. + +Make sure you have a tags file generated for the project for the latter of these two bindings to work. Also, if you're editing CoffeeScript, it's a good idea to update your `~/.ctags` file to understand the language. Here is [a good example](https://github.com/kevinsawicki/dotfiles/blob/master/.ctags). @@ -106,8 +111,8 @@ command, as follows: `s/foo/bar/g`. Note that if you have a selection, the replacement will only occur inside the selected text. An empty selection will cause the replacement to occur across the whole buffer. If you want to run the command on the whole buffer even if you have a selection, precede your -substitution with the `,` address, which specifies that the command following it -operate on the whole buffer. +substitution with the `,` address; this indicates that the following command should +run on the whole buffer. ### Split Panes @@ -125,12 +130,12 @@ planning to improve it soon. ### Soft-Wrap If you want to toggle soft wrap, trigger the command from the command palette. -Press `meta-p` to open the palette, then type "wrap" to find the correct +Hit `meta-p` to open the palette, then type "wrap" to find the correct command. ## Your .atom Directory -When you install Atom, a `.atom` directory is created in your home directory. +When you install Atom, an `.atom` directory is created in your home directory. If you press `meta-,`, that directory will be opened in a new window. For the time being, this will serve as the primary interface for adjusting configuration settings, adding and changing key bindings, tweaking styles, etc. diff --git a/docs/manifest.txt b/docs/manifest.txt index 0329df5de..59c29b2cc 100644 --- a/docs/manifest.txt +++ b/docs/manifest.txt @@ -1,10 +1,11 @@ getting-started.md +configuring-atom.md built-in-packages/intro.md built-in-packages/command-panel.md built-in-packages/markdown-preview.md built-in-packages/wrap-guide.md -authoring-themes.md -authoring-packages..md +packages/authoring-packages.md +themes/authoring-themes.md internals/intro.md internals/configuration.md internals/keymaps.md diff --git a/docs/packages/authoring-packages.md b/docs/packages/authoring-packages.md new file mode 100644 index 000000000..6e6c1af7a --- /dev/null +++ b/docs/packages/authoring-packages.md @@ -0,0 +1,211 @@ +# Authoring Packages + +Packages are at the core of Atom. Nearly everything outside of the main editor manipulation +is handled by a package. That includes "core" pieces like the command panel, status bar, +file tree, and more. + +A package can contain a variety of different resource types to change Atom's +behavior. The basic package layout is as follows (though not every package will +have all of these directories): + +```text +my-package/ + lib/ + stylesheets/ + keymaps/ + snippets/ + grammars/ + spec/ + package.json + index.coffee +``` + +**NOTE:** NPM behavior is partially implemented until we get a working Node.js +API built into Atom. The goal is to make Atom packages be a superset of NPM +packages. + +Below, we'll break down each directory. There's also [a tutorial](./creating_a_package.md) +on creating your first package. + +## package.json + +Similar to [npm packages](http://en.wikipedia.org/wiki/Npm_(software)), Atom packages +can contain a _package.json_ file in their top-level directory. This file contains metadata +about the package, such as the path to its "main" module, library dependencies, +and manifests specifying the order in which its resources should be loaded. + +In addition to the regular [npm package.json keys](https://npmjs.org/doc/json.html) +available, Atom package.json files [have their own additions](./package_json.md). + +## Source Code + +If you want to extend Atom's behavior, your package should contain a single +top-level module, which you export from _index.coffee_ (or whichever file is +indicated by the `main` key in your _package.json_ file). The remainder of your +code should be placed in the `lib` directory, and required from your top-level +file. + +Your package's top-level module is a singleton object that manages the lifecycle +of your extensions to Atom. Even if your package creates ten different views and +appends them to different parts of the DOM, it's all managed from your top-level +object. + +Your package's top-level module should implement the following methods: + +- `activate(rootView, state)`: This **required** method is called when your +package is loaded. It is always passed the window's global `rootView`, and is +sometimes passed state data if the window has been reloaded and your module +implements the `serialize` method. Use this to do initialization work when your +package is started (like setting up DOM elements or binding events). + +- `serialize()`: This **optional** method is called when the window is shutting +down, allowing you to return JSON to represent the state of your component. When +the window is later restored, the data you returned is passed to your +module's `activate` method so you can restore your view to where the user left +off. + +- `deactivate()`: This **optional** method is called when the window is shutting +down. If your package is watching any files or holding external resources in any +other way, release them here. If you're just subscribing to things on window, +you don't need to worry because that's getting torn down anyway. + +### Simple Package Code + +```text +my-package/ + package.json # optional + index.coffee + lib/ + my-package.coffee +``` + +`index.coffee`: +```coffeescript +module.exports = require "./lib/my-package" +``` + +`my-package/my-package.coffee`: +```coffeescript +module.exports = + activate: (rootView, state) -> # ... + deactivate: -> # ... + serialize: -> # ... +``` + +Beyond this simple contract, your package has full access to Atom's internal +API. Anything we call internally, you can call as well. Be aware that since we +are early in development, APIs are subject to change and we have not yet +established clear boundaries between what is public and what is private. Also, +please collaborate with us if you need an API that doesn't exist. Our goal is +to build out Atom's API organically based on the needs of package authors like +you. + +See [Atom's built-in packages](https://github.com/github/atom/tree/master/src/packages) +for examples of Atom's API in action. + +## Stylesheets + +Stylesheets for your package should be placed in the _stylesheets_ directory. +Any stylesheets in this directory will be loaded and attached to the DOM when +your package is activated. Stylesheets can be written as CSS or LESS. + +An optional `stylesheets` array in your _package.json_ can list the stylesheets by +name to specify a loading order; otherwise, stylesheets are loaded alphabetically. + +## Keymaps + +Keymaps are placed in the _keymaps_ subdirectory. It's a good idea to provide +default keymaps for your extension, especially if you're also adding a new command. + +By default, all keymaps are loaded in alphabetical order. An optional `keymaps` +array in your _package.json_ can specify which keymaps to load and in what order. + +See the [main keymaps documentation](../internals/keymaps.md) for more information on +how keymaps work. + +## Snippets + +An extension can supply language snippets in the _snippets_ directory. These can +be `.cson` or `.json` files. Here's an example: + +```coffeescript +".source.coffee .specs": + "Expect": + prefix: "ex" + body: "expect($1).to$2" + "Describe": + prefix: "de" + body: """ + describe "${1:description}", -> + ${2:body} + """ +``` + +A snippets file contains scope selectors at its top level (`.source.coffee .spec`). +Each scope selector contains a hash of snippets keyed by their name (`Expect`, `Describe`). +Each snippet also specifies a `prefix` and a `body` key. The `prefix` represents +the first few letters to type before hitting the `tab` key to autocomplete. The +`body` defines the autofilled text. You can use placeholders like `$1`, `$2`, to indicate +regions in the body the user can navigate to every time they hit `tab`. + +All files in the directory are automatically loaded, unless the +_package.json_ supplies a `snippets` key. As with all scoped +items, snippets loaded later take precedence over earlier snippets when two +snippets match a scope with the same specificity. + +## Language Grammars + +If you're developing a new language grammar, you'll want to place your file in +the _grammars_ directory. Each grammar is a pairing of two keys, `match` and +`captures`. `match` is a regular expression identifying the pattern to highlight, +while `captures` is a JSON representing what to do with each matching group. +For example: + + +```json +{ + 'match': '(?:^|\\s)(__[^_]+__)' + 'captures': + '1': 'name': 'markup.bold.gfm' +} +``` + +This indicates that the first matching capture (`(__[^_]+__)`) should have the +`markup.bold.gfm` token applied to it. + +To capture a single group, simply use the `name` key instead: + +```json +{ + 'match': '^#{1,6}\\s+.+$' + 'name': 'markup.heading.gfm' +} +``` + +This indicates that Markdown header lines (`#`, `##`, `###`) should be applied with +the `markup.heading.gfm` token. + +More information about the significance of these tokens can be found in +[section 12.4 of the TextMate Manual](http://manual.macromates.com/en/language_grammars.html). + +Your grammar should also include a `filetypes` array, which is a list of file extensions +your grammar supports: + +``` +'fileTypes': [ + 'markdown' + 'md' + 'mkd' + 'mkdown' + 'ron' +] +``` + +## Writing Tests + +Your package **should** have tests, and if they're placed in the _spec_ directory, +they can be run by Atom. + +Under the hood, [Jasmine](https://github.com/pivotal/jasmine) is being used to run +to execute the tests, so you can assume that any DSL available there is available +to your package as well. diff --git a/docs/packages/creating_a_package.md b/docs/packages/creating_a_package.md new file mode 100644 index 000000000..45e797e7d --- /dev/null +++ b/docs/packages/creating_a_package.md @@ -0,0 +1,254 @@ +# Creating Packages + +Let's take a look at creating our first package. + +Atom has a command you can enter that'll create a package for you: +`package-generator:generate`. Otherwise, you can hit `meta-p`, and start typing +"Package Generator." Once you activate this package, it'll ask you for a name for +your new package. Let's call ours _changer_. + +Now, _changer_ is going to have a default set of folders and files created for us. +Hit `meta-R` to reload Atom, then hit `meta-p` and start typing "Changer." You'll +see a new `Changer:Toggle` command which, if selected, pops up a new message. So +far, so good! + +In order to demonstrate the capabilities of Atom and its API, our Changer plugin +is going to do two things: + +1. It'll show only modified files in the file tree +2. It'll append a new pane to the editor with some information about the modified +files + +Let's get started! + +## Changing Keybindings and Commands + +Since Changer is primarily concerned with the file tree, let's write a keybinding +that works only when the tree is focused. Instead of using the default `toggle`, +our keybinding executes a new command called `magic`. + +_keymaps/changer.cson_ can easily become this: + +```cson +'.tree-view-scroller': + 'ctrl-V': 'changer:magic' +``` + +Notice that the keybinding is called `ctrl-V`--that's actually `ctrl-shift-v`. +You can use capital letters to denote using `shift` for your binding. + +`.tree-view-scroller` represents the parent container for the tree view. Keybindings +only work within the context of where they're entered. For example, hitting `ctrl-V` +anywhere other than tree won't do anything. You can map to `body` if you want +to scope to anywhere in Atom, or just `.editor` for the editor portion. + +To bind keybindings to a command, we'll use the `rootView.command` method. This +takes a command name and executes a function in the code. For example: + +```coffeescript +rootView.command "changer:magic", => @magic() +``` + +It's common practice to namespace your commands with your package name, and separate +it with a colon (`:`). Rename the existing `toggle` method to `magic` to get the +binding to work. + +Reload the editor, click on the tree, hit your keybinding, and...nothing happens! What the heck?! + +Open up the _package.json_ file, and notice the key that says `activationEvents`. +Basically, this tells Atom to not load a package until it hears a certain event. +Let's change the event to `changer:magic` and reload the editor. + +Hitting the key binding on the tree now works! + +## Working with styles + +The next step is to hide elements in the tree that aren't modified. To do that, +we'll first try and get a list of files that have not changed. + +All packages are able to use jQuery in their code. In fact, we have [a list of +some of the bundled libraries Atom provides by default](./included_libraries.md). + +Let's bring in jQuery: + +```coffeescript +$ = require 'jquery' +``` + +Now, we can query the tree to get us a list of every file that _wasn't_ modified: + +```coffeescript +magic: -> + $('ol.entries li').each (i, el) -> + if !$(el).hasClass("modified") + console.log el +``` + +You can access the dev console by hitting `alt-meta-i`. When we execute the +`changer:magic` command, the browser console lists the items that are not being +modified. Let's add a class to each of these elements called `hide-me`: + +```coffeescript +magic: -> + $('ol.entries li').each (i, el) -> + if !$(el).hasClass("modified") + $(el).addClass("hide-me") +``` + +With our newly added class, we can manipulate the visibility of the elements +with a simple stylesheet. Open up _changer.css_ in the _stylesheets_ directory, +and add a single entry: + +```css +ol.entries .hide-me { + display: none; +} +``` + +Refresh atom, and run the `changer` command. You'll see all the non-changed files +disappear from the tree. There are a number of ways you can get the list back; +let's just naively iterate over the same elements and remove the class: + +```coffeescript +magic: -> + $('ol.entries li').each (i, el) -> + if !$(el).hasClass("modified") + if !$(el).hasClass("hide-me") + $(el).addClass("hide-me") + else + $(el).removeClass("hide-me") +``` + +## Creating a New Pane + +The next goal of this package is to append a pane to the Atom editor that lists +some information about the modified files. + +To do that, we're going to first create a new class method called `content`. Every +package that extends from the `View` class can provide an optional class method +called `content`. The `content` method constructs the DOM that your package uses +as its UI. The principals of `content` are built entirely on [SpacePen](https://github.com/nathansobo/space-pen), +which we'll touch upon only briefly here. + +Our display will simply be an unordered list of the file names, and their +modified times. Let's start by carving out a `div` to hold the filenames: + +```coffeescript +@content: -> + @div class: 'modified-files-container', => + @ul class: 'modified-files-list', outlet: 'modifiedFilesList', => + @li 'Test' + @li 'Test2' +``` + +You can add any HTML5 attribute you like. `outlet` names the variable +your package can uses to manipulate the element directly. The fat pipe (`=>`) indicates +that the next set are nested children. + +We'll add one more line to `magic` to make this pane appear: + +```coffeescript +rootView.vertical.append(this) +``` + +If you hit the key command, you'll see a box appear right underneath the editor. +Success! + +Before we populate this, let's apply some logic to toggle the pane off and on, just +like we did with the tree view: + +```coffeescript +# toggles the pane +if @hasParent() + rootView.vertical.children().last().remove() +else + rootView.vertical.append(this) +``` + +There are about a hundred different ways to toggle a pane on and off, and this +might not be the most efficient one. If you know your package needs to be toggled +on and off more freely, it might be better to draw the UI during the initialization, +then immediately call `hide()` on the element to remove it from the view. You can +then swap between `show()` and `hide()`, and instead of forcing Atom to add and remove +the element as we're doing here, it'll just set a CSS property to control your package's +visibility. + +You might have noticed that our two `li` elements aren't showing up. Let's set +a color on them so that they pop. Open up `changer.css` and add this CSS: + +```css +ul.modified-files-list { + color: white; +} +``` + +Refresh Atom, hit the key combo, and see your brilliantly white test list. + +## Calling Node.js Code + +Since Atom is built on top of Node.js, you can call any of its libraries, including +other modules that your package requires. + +We'll iterate through our resulting tree, and construct the path to our modified +file based on its depth in the tree: + +```coffeescript +path = require 'path' + +# ... + +modifiedFiles = [] +# for each single entry... +$('ol.entries li.file.modified span.name').each (i, el) -> + filePath = [] + # ...grab its name... + filePath.unshift($(el).text()) + + # ... then find its parent directories, and grab their names + parents = $(el).parents('.directory.modified') + parents.each (i, el) -> + filePath.unshift($(el).find('div.header span.name').eq(0).text()) + + modifiedFilePath = path.join(project.rootDirectory.path, filePath.join(path.sep)) + modifiedFiles.push modifiedFilePath +``` + +`modifiedFiles` is an array containing a list of our modified files. We're also using +the node.js [`path` library](http://nodejs.org/docs/latest/api/path.html) to get +the proper directory separator for our system. + +Let's remove the two `@li` elements we added in `@content`, so that we can populate +our `modifiedFilesList` with real information. We'll do that by iterating over +`modifiedFiles`, accessing a file's last modified time, and appending it to +`modifiedFilesList`: + +```coffeescript +# toggles the pane +if @hasParent() + rootView.vertical.children().last().remove() +else + for file in modifiedFiles + stat = fs.lstatSync(file) + mtime = stat.mtime + @modifiedFilesList.append("
  • #{file} - Modified at #{mtime}") + rootView.vertical.append(this) +``` + +When you toggle the modified files list, your pane is now populated with the filenames +and modified times of files in your project. You might notice that subsequent calls +to this command reduplicate information. We could provide an elegant way of rechecking +files already in the list, but for this demonstration, we'll just clear the `modifiedFilesList` +each time it's closed: + +```coffeescript +# toggles the pane +if @hasParent() + @modifiedFilesList.empty() + rootView.vertical.children().last().remove() +else + for file in modifiedFiles + stat = fs.lstatSync(file) + mtime = stat.mtime + @modifiedFilesList.append("
  • #{file} - Modified at #{mtime}") + rootView.vertical.append(this) +``` diff --git a/docs/packages/included_libraries.md b/docs/packages/included_libraries.md new file mode 100644 index 000000000..98c76cf49 --- /dev/null +++ b/docs/packages/included_libraries.md @@ -0,0 +1,10 @@ +# Included Libraries + +In addition to core node.js modules, all packages can `require` the following popular +libraries into their packages: + +* [SpacePen](https://github.com/nathansobo/space-pen) (as `require 'space-pen'`) +* [jQuery](http://jquery.com/) (as `require 'jquery'`) +* [Underscore](http://underscorejs.org/) (as `require 'underscore'`) + +Additional libraries can be found by browsing Atom's _node_modules_ folder. diff --git a/docs/packages/package_json.md b/docs/packages/package_json.md new file mode 100644 index 000000000..feffacef8 --- /dev/null +++ b/docs/packages/package_json.md @@ -0,0 +1,18 @@ +# package.json format + +The following keys are available to your package's _package.json_ manifest file: + +- `main` (**Required**): the path to the CoffeeScript file that's the entry point +to your package +- `stylesheets` (**Optional**): an Array of Strings identifying the order of the +stylesheets your package needs to load. If not specified, stylesheets in the _stylesheets_ +directory are added alphabetically. +- `keymaps`(**Optional**): an Array of Strings identifying the order of the +key mappings your package needs to load. If not specified, mappings in the _keymaps_ +directory are added alphabetically. +- `snippets` (**Optional**): an Array of Strings identifying the order of the +snippets your package needs to load. If not specified, snippets in the _snippets_ +directory are added alphabetically. +- `activationEvents` (**Optional**): an Array of Strings identifying events that +trigger your package's activation. You can delay the loading of your package until +one of these events is trigged. diff --git a/docs/authoring-themes.md b/docs/themes/authoring-themes.md similarity index 93% rename from docs/authoring-themes.md rename to docs/themes/authoring-themes.md index a91781cfc..1360bde11 100644 --- a/docs/authoring-themes.md +++ b/docs/themes/authoring-themes.md @@ -1,4 +1,4 @@ -# Authoring A Theme +# Authoring Themes If you understand CSS, you can write an Atom theme easily. Your theme can style Atom's user interface, specify the appearance of syntax-highlighted code, or @@ -9,9 +9,9 @@ translate scope names to CSS classes. To theme Atom's user interface, take a look at the existing light and dark themes for an example. Pressing `alt-meta-i` and inspecting the Atom's markup directly can also be helpful. -The most basic theme is just a `.css` file. More complex themes occupy their own +The most basic theme is just a _.css_ file. More complex themes occupy their own folder, which can contain multiple stylesheets along with an optional -`package.cson` file containing a manifest to control their load-order: +_package.cson_ file containing a manifest to control their load-order: ```text ~/.atom/themes/