From 30ea10cfb81a2f0f58114e5e2ec09e0b15a13c40 Mon Sep 17 00:00:00 2001 From: Matt Colyer Date: Mon, 14 Oct 2013 12:30:08 -0700 Subject: [PATCH 01/10] :memo: Elaborate on how to create a theme --- docs/creating-a-theme.md | 115 ++++++++++++++++++++------------------- 1 file changed, 60 insertions(+), 55 deletions(-) diff --git a/docs/creating-a-theme.md b/docs/creating-a-theme.md index 3fa872934..5f6be8d1f 100644 --- a/docs/creating-a-theme.md +++ b/docs/creating-a-theme.md @@ -6,71 +6,76 @@ ## Overview -* Explain the difference between ui themes and syntax themes +Atom is built using web technologies, the interface is rendered using HTML and +it's styled via [LESS] (a superset of CSS). Don't worry if you haven't +heard of LESS before, it's just like CSS but with a few handy extensions. + +Since CSS is the basis of the theming system, we can load multiple themes within +Atom and it behaves just like a website. Themes loaded first are overridden by +themes which are loaded later (the order is controlled from within the Settings +pane). + +This flexibility is helpful for users which prefer a light interface with a dark +syntax theme. Atom only has interface and syntax themes currently but it's easy +see how one might want to create their own language specific syntax theme for +very specific styling. ## Getting Started -* What do I need to install? - * Atom - to edit text - * Git - to track and distribute your themes -* What do I need to know? - * CSS/LESS - as that's what themes are written in - * Devtools - so you can find the selector you're looking for. -* Is there an example I can start from? - * Yes, you can clone https://github.com/atom/solarized-dark-syntax +To create your own theme you'll need a few things: -# Create a minimal syntax theme +* A working install of [Atom], so you can work on your new theme. +* A working install of [git] to track changes. +* A [GitHub] account, so you can distribute your themes. -```bash -cd ~/.atom/packages -mkdir my-theme -cd my-theme -git init -mkdir stylesheets -apm init --theme -cat > index.less < stylesheets/base.less < stylesheets/overrides.less < Date: Mon, 14 Oct 2013 14:40:18 -0700 Subject: [PATCH 02/10] :memo: Update customizing atom guide --- docs/customizing-atom.md | 128 +++++++++++++++++++++------------------ 1 file changed, 68 insertions(+), 60 deletions(-) diff --git a/docs/customizing-atom.md b/docs/customizing-atom.md index d905463f5..c3dd217dd 100644 --- a/docs/customizing-atom.md +++ b/docs/customizing-atom.md @@ -2,57 +2,26 @@ "title": "Customizing Atom" }}} -# Configuration Settings +# Customizing Atom -## Your .atom Directory +To change a setting, configure a theme, or install a package just open the +Settings pane in the current window by pressing `cmd+,`. -When you install Atom, an _.atom_ directory is created in your home directory. -If you press `cmd-,`, 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. +## Changing The Theme -Atom loads configuration settings from the `config.cson` file in your _~/.atom_ -directory, which contains CoffeeScript-style JSON: +Because Atom themes are based on CSS, it's possible (and encouraged) to have +multiple themes active at the same time. Atom comes with both light and dark +interface themes as well as several syntax themes (you can also [create your +own][create-theme]). -```coffeescript -core: - hideGitIgnoredFiles: true -editor: - fontSize: 18 -``` +To change the active themes just open the Settings pane (`cmd-,`) and select the +`Themes` tab. You can install non-bundled themes by going to the `Available +Themes` section on the `Packages` tab within the Settings panel. -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. +## Installing Packages -## 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. +You can install non-bundled packages by going to the `Available Packages` section +on the `Packages` tab within the Settings panel (`cmd-,`). ## Customizing Key Bindings @@ -66,7 +35,7 @@ built-in keymaps: 'enter': 'editor:newline' ".select-list .editor.mini": - 'enter': 'core:confirm', + 'enter': 'core:confirm' ``` This keymap defines the meaning of `enter` in two different contexts. In a @@ -80,32 +49,68 @@ 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 +## Advanced Configuration -Atom comes bundled with two themes `atom-dark-*` and `atom-light-*`. +Atom loads configuration settings from the `config.cson` file in your _~/.atom_ +directory, which contains CoffeeScript-style JSON: -Because Atom themes are based on CSS, it's possible to have multiple themes -active at the same time. +```coffeescript +core: + hideGitIgnoredFiles: true +editor: + fontSize: 18 +``` -For example, you'll usually select a theme for the UI and another theme for -syntax highlighting. You can change themes from the preferences pane. +The configuration itself is grouped by the package name or one of the two core +namespaces: `core` and `editor`. -You install new themes by placing them in the _~/.atom/themes_ directory. A -theme can be a single LESS file or a directory containing multiple LESS files. +### Configuration Key Reference -## Installing Packages +- `core` + - `autosave`: Save a buffer when its view loses focus + - `disabledPackages`: An array of package names to disable + - `excludeVcsIgnoredPaths`: Don't search within files specified by _.gitignore_ + - `hideGitIgnoredFiles`: Whether files in the _.gitignore_ should be hidden + - `ignoredNames`: File names to ignore across all of Atom (not fully implemented) + - `projectHome`: The directory where projects are assumed to be located + - `themes`: An array of theme names to load, in cascading order +- `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 + - `normalizeIndentOnPaste`: Enable/disable conversion of pasted tabs to spaces + - `preferredLineLength`: Identifies the length of a line (defaults to `80`) + - `showInvisibles`: Whether to render placeholders for invisible characters (defaults to `false`) + - `showIndentGuide`: Show/hide indent indicators within the editor + - `showLineNumbers`: Show/hide line numbers within the gutter + - `softWrap`: Enable/disable soft wrapping of text within the editor + - `softWrapAtPreferredLineLength`: Enable/disable soft line wrapping at `preferredLineLength` + - `tabLength`: Number of spaces within a tab (defaults to `2`) +- `fuzzyFinder` + - `ignoredNames`: Files to ignore *only* in the fuzzy-finder +- `whitespace` + - `ensureSingleTrailingNewline`: Whether to reduce multiple newlines to one at the end of files + - `removeTrailingWhitespace`: Enable/disable striping of whitespace at the end of lines (defaults to `true`) +- `wrapGuide` + - `columns`: Array of hashes with a `pattern` and `column` key to match the + the path of the current editor to a column position. -FIXME: Rewrite for the new dialog. - -## Quick Personal Hacks +### 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). +If customizations become extensive, consider [creating a +package][create-a-package]. ### user.less @@ -123,3 +128,6 @@ contains the cursor, you could add the following style to _user.less_: color: @highlight-color; } ``` + +[create-a-package]: creating-packages.md +[create-theme]: creating-a-theme.md From 4b566d1ce3965dfa5e61a395738061587a5c927e Mon Sep 17 00:00:00 2001 From: Matt Colyer Date: Mon, 14 Oct 2013 17:00:16 -0700 Subject: [PATCH 03/10] :memo: Cleanup markdown --- docs/creating-a-package.md | 256 ++++++++++++++++++---------------- docs/creating-a-theme.md | 22 ++- docs/customizing-atom.md | 12 +- docs/getting-started.md | 31 ++-- docs/index.md | 20 ++- docs/internals/view-system.md | 13 +- docs/template.jst | 151 -------------------- 7 files changed, 182 insertions(+), 323 deletions(-) delete mode 100644 docs/template.jst diff --git a/docs/creating-a-package.md b/docs/creating-a-package.md index f95bbd669..2c89bb2dc 100644 --- a/docs/creating-a-package.md +++ b/docs/creating-a-package.md @@ -1,12 +1,8 @@ -{{{ -"title": "Creating a Package" -}}} - # 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. +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 @@ -26,8 +22,8 @@ my-package/ ## Publishing -Atom bundles a command line utility called [apm](http://github.com/atom/apm) -which can be used to publish Atom packages to the public registry. +Atom bundles a command line utility called [apm][apm] which can be used to +publish Atom packages to the public registry. Once your package is written and ready for distribution you can run the following to publish your package: @@ -37,40 +33,40 @@ cd my-package apm publish minor ``` -This will update your `package.json` to have a new minor `version`, commit -the change, create a new [Git tag](http://git-scm.com/book/en/Git-Basics-Tagging), -and then upload the package to the registry. +This will update your `package.json` to have a new minor `version`, commit the +change, create a new [Git tag][git-tag], and then upload the package to the +registry. Run `apm help publish` to see all the available options and `apm help` to see all the other available commands. ## package.json -Similar to [npm packages][npm], 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. +Similar to [npm packages][npm], 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. +In addition to the regular [npm package.json keys][npm-keys] available, Atom +package.json files have their own additions. - `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. +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. +key mappings your package needs to load. If not specified, mappings in the +_keymaps_ directory are added alphabetically. - `menus`(**Optional**): an Array of Strings identifying the order of the menu mappings your package needs to load. If not specified, mappings in the _keymap_ 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. +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. +trigger your package's activation. You can delay the loading of your package +until one of these events is trigged. ## Source Code @@ -135,8 +131,8 @@ 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/atom/atom/) -for examples of Atom's API in action. +See [wrap-guide][wrap-guide] for examples of Atom's API in +action. ## Stylesheets @@ -144,19 +140,22 @@ 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. +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. +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. +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. +See the [main keymaps documentation][keymaps] for more +information on how keymaps work. ## Menus @@ -168,14 +167,15 @@ By default, all menus are loaded in alphabetical order. An optional `menus` array in your _package.json_ can specify which menus to load and in what order. +FIXME: Describe how to create an application menu item. + Context menus are created by determining which element was selected and then adding all of the menu items whose selectors match that element (in the order which they were loaded). The process is then repeated for the elements until reaching the top of the dom tree. NOTE: Currently you can only specify items to be added to the context -menu, the menu which appears when you right click. There are plans to -add support for adding to global menu. +menu, the menu which appears when you right click. ``` 'context-menu': @@ -203,24 +203,26 @@ be `.cson` or `.json` files. Here's an example: """ ``` -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`. +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. +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 an object representing what to do with each matching group. +`captures`. `match` is a regular expression identifying the pattern to +highlight, while `captures` is an object representing what to do with each +matching group. For example: @@ -245,14 +247,14 @@ To capture a single group, simply use the `name` key instead: } ``` -This indicates that Markdown header lines (`#`, `##`, `###`) should be applied with -the `markup.heading.gfm` token. +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). +[section 12.4 of the TextMate Manual][tm-tokens]. -Your grammar should also include a `filetypes` array, which is a list of file extensions -your grammar supports: +Your grammar should also include a `filetypes` array, which is a list of file +extensions your grammar supports: ```coffeescript 'fileTypes': [ @@ -279,12 +281,15 @@ You can also use the `atom` protocol URLs in themes. ## Writing Tests -Your package **should** have tests, and if they're placed in the _spec_ directory, -they can be run by Atom. +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 -execute the tests, so you can assume that any DSL available there is available -to your package as well. +Under the hood, [Jasmine] is being used to execute the tests, so you can +assume that any DSL available there is available to your package as well. + +## Running tests + +FIXME: Describe `apm test` # Full Example @@ -292,13 +297,13 @@ 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 `cmd-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_. +"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 `cmd-r` to reload Atom, then hit `cmd-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! +Now, _changer_ is going to have a default set of folders and files created for +us. Hit `cmd-r` to reload Atom, then hit `cmd-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: @@ -311,9 +316,9 @@ 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`. +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: @@ -325,10 +330,11 @@ _keymaps/changer.cson_ can easily become this: 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. +`.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: @@ -337,15 +343,17 @@ takes a command name and executes a function in the code. For example: 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. +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?! +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. +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! @@ -363,7 +371,8 @@ Let's bring in jQuery: $ = require 'jquery' ``` -Now, we can query the tree to get us a list of every file that _wasn't_ modified: +Now, we can query the tree to get us a list of every file that _wasn't_ +modified: ```coffeescript magic: -> @@ -393,9 +402,9 @@ ol.entries .hide-me { } ``` -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: +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: -> @@ -412,11 +421,11 @@ magic: -> 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. +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][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: @@ -429,9 +438,9 @@ modified times. Let's start by carving out a `div` to hold the filenames: @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. +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: @@ -442,8 +451,8 @@ 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: +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 @@ -454,12 +463,12 @@ else ``` 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. +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: @@ -474,8 +483,8 @@ 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. +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: @@ -501,14 +510,14 @@ $('ol.entries li.file.modified span.name').each (i, el) -> 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. +`modifiedFiles` is an array containing a list of our modified files. We're also +using the node.js [`path` library][path] 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`: +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 @@ -522,11 +531,11 @@ else 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: +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 @@ -543,14 +552,27 @@ else # Included Libraries -In addition to core node.js modules, all packages can `require` the following popular -libraries into their packages: +FIXME: Describe `require 'atom' -* [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'`) +In addition to core node.js modules, all packages can `require` the following +popular libraries into their packages: + +* [SpacePen] (as `require 'space-pen'`) +* [jQuery] (as `require 'jquery'`) +* [Underscore] (as `require 'underscore'`) Additional libraries can be found by browsing Atom's _node_modules_ folder. [npm]: http://en.wikipedia.org/wiki/Npm_(software) +[npm-keys]: https://npmjs.org/doc/json.html +[apm]: https://github.com/atom/apm +[git-tag]: http://git-scm.com/book/en/Git-Basics-Tagging +[wrap-guide]: https://github.com/atom/wrap-guide/ +[keymaps]: internals/keymaps.md +[tm-tokens]: http://manual.macromates.com/en/language_grammars.html +[spacepen]: https://github.com/nathansobo/space-pen +[path]: http://nodejs.org/docs/latest/api/path.html +[jquery]: http://jquery.com/ +[underscore]: http://underscorejs.org/ +[jasmine]: https://github.com/pivotal/jasmine diff --git a/docs/creating-a-theme.md b/docs/creating-a-theme.md index 5f6be8d1f..ea33fcbaf 100644 --- a/docs/creating-a-theme.md +++ b/docs/creating-a-theme.md @@ -1,7 +1,3 @@ -{{{ -"title": "Creating a Theme" -}}} - # Creating a Theme ## Overview @@ -47,12 +43,12 @@ a few things before starting: 1. Open `package.json` and update the relevant parts. 1. Open `stylesheets/colors.less` to change the various colors variables which have been already been defined. - 1. Open `stylesheets/base.less` and modify the various syntax CSS selectors that - have been already been defined. - 1. When you're ready update the `README.md` and include an example screenshot of - your new theme in action. -1. Open a terminal, find your new theme's directory, initialize the git repository - and push it to repository on GitHub. + 1. Open `stylesheets/base.less` and modify the various syntax CSS selectors + that have been already been defined. + 1. When you're ready update the `README.md` and include an example screenshot + of your new theme in action. +1. Open a terminal, find your new theme's directory, initialize the git + repository and push it to repository on GitHub. 1. Once you're ready for others to use your theme run `apm publish` from within that directory to make it available to other Atom users. @@ -72,10 +68,10 @@ to make but you aren't sure how to reference an element. That's when the devtools become really useful, just open them up (`cmd+alt+i`), switch to the `Elements` tab and inspect the element you're interested in. -[LESS]: http://lesscss.org/ +[less]: http://lesscss.org/ [git]: http://git-scm.com/ -[Atom]: https://atom.io/ -[GitHub]: https://github.com/ +[atom]: https://atom.io/ +[github]: https://github.com/ [less-tutorial]: https://speakerdeck.com/danmatthews/less-css [devtools-tutorial]: https://developers.google.com/chrome-developer-tools/docs/elements [ui-variables]: https://github.com/atom/atom-dark-ui/blob/master/stylesheets/ui-variables.less diff --git a/docs/customizing-atom.md b/docs/customizing-atom.md index c3dd217dd..2c1aade16 100644 --- a/docs/customizing-atom.md +++ b/docs/customizing-atom.md @@ -1,7 +1,3 @@ -{{{ -"title": "Customizing Atom" -}}} - # Customizing Atom To change a setting, configure a theme, or install a package just open the @@ -20,8 +16,8 @@ Themes` section on the `Packages` tab within the Settings panel. ## Installing Packages -You can install non-bundled packages by going to the `Available Packages` section -on the `Packages` tab within the Settings panel (`cmd-,`). +You can install non-bundled packages by going to the `Available Packages` +section on the `Packages` tab within the Settings panel (`cmd-,`). ## Customizing Key Bindings @@ -118,8 +114,8 @@ 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.less_ 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.less_: +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.less_: ```less @highlight-color: pink; diff --git a/docs/getting-started.md b/docs/getting-started.md index d2796daf3..cadb7c664 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,7 +1,3 @@ -{{{ -"title": "Getting Started" -}}} - # Getting Started Welcome to Atom! This guide provides a quick introduction so you can be @@ -15,18 +11,17 @@ can always hit `cmd-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 learn about adding or changing a -binding for a command, refer to the [key bindings](#customizing-key-bindings) -section below. +binding for a command, refer to the [key bindings][key-bindings] section below. -![Command Palette](https://f.cloud.github.com/assets/1424/1091618/ee7c3554-166a-11e3-9955-aaa61bb5509c.png) +![Command Palette] ## The Basics ### Working With Files -Atom windows are scoped to the directory in which they're opened from. So if -you launch Atom from the command line, everything will be relative to the -current directory. This means that the tree view on the left will only show files +Atom windows are scoped to the directory in which they're opened from. So if you +launch Atom from the command line, everything will be relative to the current +directory. This means that the tree view on the left will only show files contained within that directory. This can be a useful way to organize multiple projects, as each project will be @@ -62,12 +57,13 @@ FIXME: Describe https://github.com/atom/find-and-replace #### Navigating By Symbols If you want to jump to a method, the `cmd-j` binding opens a list of all symbols -in the current file. `cmd-.` jumps to the tag for the word currently under the cursor. +in the current file. `cmd-.` jumps to the tag for the word currently under the +cursor. To search for symbols across your project use `cmd-shift-j`, but you'll need to make sure you have a tags file generated for the project 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). +language. Here is [a good example][ctags]. ### Split Panes @@ -102,7 +98,10 @@ To install a package, open the configuration panel and select the packages tab. FIXME: Needs more details. -[configuring]: customizing-atom.html -[theming]: creating-a-theme.html -[extending]: creating-a-package.html -[customization]: customizing-atom.html +[configuring]: customizing-atom.md +[theming]: creating-a-theme.md +[extending]: creating-a-package.md +[customization]: customizing-atom.md +[key-bindings]: #customizing-key-bindings +[command palette]: https://f.cloud.github.com/assets/1424/1091618/ee7c3554-166a-11e3-9955-aaa61bb5509c.png +[ctags]: https://github.com/kevinsawicki/dotfiles/blob/master/.ctags diff --git a/docs/index.md b/docs/index.md index 08b8e6835..44c607b2d 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,16 +1,12 @@ -{{{ -"title": "Guides" -}}} - ## Guides -* [Getting Started](getting-started.html) -* [Customizing Atom](customizing-atom.html) -* [Creating a Package](creating-a-package.html) -* [Creating a Theme](creating-a-theme.html) +* [Getting Started](getting-started.md) +* [Customizing Atom](customizing-atom.md) +* [Creating a Package](creating-a-package.md) +* [Creating a Theme](creating-a-theme.md) ### Advanced Topics -* [Configuration](internals/configuration.html) -* [Keymaps](internals/keymaps.html) -* [Serialization](internals/serialization.html) -* [View System](internals/view-system.html) +* [Configuration](internals/configuration.md) +* [Keymaps](internals/keymaps.md) +* [Serialization](internals/serialization.md) +* [View System](internals/view-system.md) diff --git a/docs/internals/view-system.md b/docs/internals/view-system.md index 7ee336489..00c6d8212 100644 --- a/docs/internals/view-system.md +++ b/docs/internals/view-system.md @@ -2,9 +2,8 @@ ### SpacePen Basics -Atom's view system is built around the [SpacePen](http://github.com/nathansobo/space-pen) -view framework. SpacePen view objects inherit from the jQuery prototype, and -wrap DOM nodes +Atom's view system is built around the [SpacePen] view framework. SpacePen +view objects inherit from the jQuery prototype, and wrap DOM nodes View objects are actually jQuery wrappers around DOM fragments, supporting all the typical jQuery traversal and manipulation methods. In addition, view objects @@ -28,8 +27,7 @@ editorView = editorElement.view() editorView.setCursorBufferPosition([1, 2]) ``` -Refer to the [SpacePen](http://github.com/nathansobo/space-pen) documentation -for more details. +Refer to the [SpacePen] documentation for more details. ### RootView @@ -38,7 +36,7 @@ singleton instance of the `RootView` view class. The root view fills the entire window, and contains every other view. If you open Atom's inspector with `alt-cmd-i`, you can see the internal structure of `RootView`: -![RootView in the inspector](https://f.cloud.github.com/assets/1424/1091631/1932c2d6-166b-11e3-8adf-9690fe82d3b8.png) +![RootView in the inspector][rootview-inspector] #### Panes @@ -62,3 +60,6 @@ rootView.horizontal.prepend(new MyView) # place a view below the panes (or use .prepend() to place it above) rootView.vertical.append(new MyOtherView) ``` + +[spacepen]: http://github.com/nathansobo/space-pen +[rootview-inspector]: https://f.cloud.github.com/assets/1424/1091631/1932c2d6-166b-11e3-8adf-9690fe82d3b8.png diff --git a/docs/template.jst b/docs/template.jst deleted file mode 100644 index 50a1d4005..000000000 --- a/docs/template.jst +++ /dev/null @@ -1,151 +0,0 @@ - - - - - - - - - - - - Atom - <%= title %> - - - -
-
-
- - Atom Documentation -
-
- -
-
-
- -
- <%= content %> -
- - From 541d25787b933196d0112a4ba35db388d3bb2228 Mon Sep 17 00:00:00 2001 From: Matt Colyer Date: Tue, 15 Oct 2013 15:13:38 -0700 Subject: [PATCH 04/10] :memo: Clean up the getting started guide --- docs/getting-started.md | 29 ++++++++++++----------------- 1 file changed, 12 insertions(+), 17 deletions(-) diff --git a/docs/getting-started.md b/docs/getting-started.md index cadb7c664..169ab3161 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -2,16 +2,17 @@ Welcome to Atom! This guide provides a quick introduction so you can be productive as quickly as possible. There are also guides which cover -[configuring][configuring], [theming][theming], and [extending][extending] Atom. +[configuring], [theming], and [extending] Atom. ## The Command Palette If there's one key-command you must remember in Atom, it should be `cmd-p`. You can always hit `cmd-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 learn about adding or changing a -binding for a command, refer to the [key bindings][key-bindings] section below. +currently focused interface 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 learn about adding or +changing a binding for a command, refer to the [key bindings][key-bindings] +section below. ![Command Palette] @@ -52,7 +53,8 @@ To delete a file, select it in the tree view and hit `delete`. #### Find and Replace -FIXME: Describe https://github.com/atom/find-and-replace +To search within a buffer use `cmd-f`. To search the entire project use +`cmd-shift-f`. To find and replace within the current buffer use `cmd-alt-f`. #### Navigating By Symbols @@ -67,7 +69,7 @@ language. Here is [a good example][ctags]. ### Split Panes -You can split any editor pane horizontally or vertically by using `ctrl-\` or +You can split any editor pane horizontally or vertically by using `ctrl-w s` or `ctrl-w v`. Once you have a split pane, you can move focus between them with `ctrl-tab` or `ctrl-w w`. To close a pane, close all tabs inside it. @@ -75,8 +77,7 @@ You can split any editor pane horizontally or vertically by using `ctrl-\` or You can fold everything with `ctrl-{` and unfold everything with `ctrl-}`. Or, you can fold / unfold by a single level with `ctrl-[` and -`ctrl-]`. The user interaction around folds is still a bit rough, but we're -planning to improve it soon. +`ctrl-]`. ### Soft-Wrap @@ -87,17 +88,11 @@ command. ## Configuration If you press `cmd-,`, a configuration panel will appear in the currently focused -pane. This will serve as the primary interface for adjusting configuration -settings, adding and changing key bindings, tweaking styles, etc. +pane. This serves as the primary interface for adjusting settings, installing +packages and changing themes. For more advanced configuration see the [customization guide][customization]. -## Installing Packages - -To install a package, open the configuration panel and select the packages tab. - -FIXME: Needs more details. - [configuring]: customizing-atom.md [theming]: creating-a-theme.md [extending]: creating-a-package.md From fc4750bcd5d10f72ee675d40e3cb462eacd962b7 Mon Sep 17 00:00:00 2001 From: Matt Colyer Date: Tue, 15 Oct 2013 15:20:33 -0700 Subject: [PATCH 05/10] :memo: Clarify a few points about themes --- docs/creating-a-theme.md | 32 +++++++++++++++----------------- 1 file changed, 15 insertions(+), 17 deletions(-) diff --git a/docs/creating-a-theme.md b/docs/creating-a-theme.md index ea33fcbaf..6cfeac62e 100644 --- a/docs/creating-a-theme.md +++ b/docs/creating-a-theme.md @@ -1,20 +1,18 @@ # Creating a Theme -## Overview - -Atom is built using web technologies, the interface is rendered using HTML and -it's styled via [LESS] (a superset of CSS). Don't worry if you haven't -heard of LESS before, it's just like CSS but with a few handy extensions. +Atom's interface is rendered using HTML and it's styled via [LESS] (a superset +of CSS). Don't worry if you haven't heard of LESS before, it's just like CSS but +with a few handy extensions. Since CSS is the basis of the theming system, we can load multiple themes within -Atom and it behaves just like a website. Themes loaded first are overridden by +Atom and they behaves just as they would on a website. Themes loaded first are overridden by themes which are loaded later (the order is controlled from within the Settings pane). This flexibility is helpful for users which prefer a light interface with a dark -syntax theme. Atom only has interface and syntax themes currently but it's easy -see how one might want to create their own language specific syntax theme for -very specific styling. +syntax theme. Atom currently has interface and syntax themes but it's easy see +how one might want to create their own language specific syntax theme for very +specific styling. ## Getting Started @@ -22,15 +20,15 @@ To create your own theme you'll need a few things: * A working install of [Atom], so you can work on your new theme. * A working install of [git] to track changes. -* A [GitHub] account, so you can distribute your themes. +* And a [GitHub] account, so you can distribute your themes. Themes are pretty straight forward but it's still helpful to be familiar with a few things before starting: -* LESS is a superset of CSS but it's got some really handy features like - variables. If you aren't familiar with it's syntax take a few minutes +* LESS is a superset of CSS but it has some really handy features like + variables. If you aren't familiar with its syntax take a few minutes to [familiarize yourself][less-tutorial]. -* Atom uses Chrome at it's core, so you can use Chrome devtools to +* Atom uses Chrome at its core, so you can use Chrome devtools to inspect the current state of the interface. Checkout Google's [extensive tutorial][devtools-tutorial] for a short introduction. @@ -49,8 +47,8 @@ a few things before starting: of your new theme in action. 1. Open a terminal, find your new theme's directory, initialize the git repository and push it to repository on GitHub. -1. Once you're ready for others to use your theme run `apm publish` from within - that directory to make it available to other Atom users. +1. Once you're ready for others to use your theme, run `apm publish` from within + that directory to make it available. ## Interface Themes @@ -65,8 +63,8 @@ target elements within the editor. Once you've got the basics down you'll find that there will be changes you want to make but you aren't sure how to reference an element. That's when the -devtools become really useful, just open them up (`cmd+alt+i`), switch to the -`Elements` tab and inspect the element you're interested in. +devtools become really useful. To open them use `cmd+alt+i` and switch to the +`Elements` tab to inspect the element you're interested in. [less]: http://lesscss.org/ [git]: http://git-scm.com/ From 26039653b269b756a886e63fb83e2680655fd2c8 Mon Sep 17 00:00:00 2001 From: Matt Colyer Date: Tue, 15 Oct 2013 16:50:15 -0700 Subject: [PATCH 06/10] Mark core.ignoredNames as complete --- docs/customizing-atom.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/customizing-atom.md b/docs/customizing-atom.md index 2c1aade16..a2e7fecb8 100644 --- a/docs/customizing-atom.md +++ b/docs/customizing-atom.md @@ -67,7 +67,7 @@ namespaces: `core` and `editor`. - `disabledPackages`: An array of package names to disable - `excludeVcsIgnoredPaths`: Don't search within files specified by _.gitignore_ - `hideGitIgnoredFiles`: Whether files in the _.gitignore_ should be hidden - - `ignoredNames`: File names to ignore across all of Atom (not fully implemented) + - `ignoredNames`: File names to ignore across all of Atom - `projectHome`: The directory where projects are assumed to be located - `themes`: An array of theme names to load, in cascading order - `editor` From 3f8eb361c0aa46eefd61f5ad442649d1a310f9c0 Mon Sep 17 00:00:00 2001 From: Matt Colyer Date: Tue, 15 Oct 2013 17:34:19 -0700 Subject: [PATCH 07/10] :memo: Cleanup/Correct Creating a package guide --- docs/creating-a-package.md | 197 +++++++++++++++++++++++-------------- 1 file changed, 123 insertions(+), 74 deletions(-) diff --git a/docs/creating-a-package.md b/docs/creating-a-package.md index 2c89bb2dc..3175abce0 100644 --- a/docs/creating-a-package.md +++ b/docs/creating-a-package.md @@ -1,8 +1,8 @@ # 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. +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 @@ -10,36 +10,17 @@ have all of these directories): ```text my-package/ - lib/ - stylesheets/ - keymaps/ - snippets/ grammars/ + keymaps/ + lib/ + menus/ spec/ - package.json + snippets/ + stylesheets/ index.coffee + package.json ``` -## Publishing - -Atom bundles a command line utility called [apm][apm] which can be used to -publish Atom packages to the public registry. - -Once your package is written and ready for distribution you can run the -following to publish your package: - -```sh -cd my-package -apm publish minor -``` - -This will update your `package.json` to have a new minor `version`, commit the -change, create a new [Git tag][git-tag], and then upload the package to the -registry. - -Run `apm help publish` to see all the available options and `apm help` to see -all the other available commands. - ## package.json Similar to [npm packages][npm], Atom packages can contain a _package.json_ file @@ -123,22 +104,21 @@ module.exports = 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. +Beyond this simple contract, your package has access to Atom's API. 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 [wrap-guide][wrap-guide] for examples of Atom's API in -action. +Check out [wrap-guide] for a simple example of Atom's package 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. +your package is activated. Stylesheets can be written as CSS or [LESS] (but LESS +is recommended). An optional `stylesheets` array in your _package.json_ can list the stylesheets by name to specify a loading order; otherwise, stylesheets are loaded @@ -146,38 +126,61 @@ 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. +```coffeescript +'.tree-view-scroller': + 'ctrl-V': 'changer:magic' +``` -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. +It's recommended that you provide key bindings for commonly used actions for +your extension, especially if you're also adding a new command. -See the [main keymaps documentation][keymaps] for more -information on how keymaps work. +Keymaps are placed in the _keymaps_ subdirectory. 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][keymaps] for more detailed information on +how keymaps work. ## Menus -Menus are placed in the _menus_ subdirectory. It's useful to specify a -context menu items if if commands are linked to a specific part of the -interface, say for example adding a file in the tree-view. +Menus are placed in the _menus_ subdirectory. By default, all menus are loaded +in alphabetical order. An optional `menus` array in your _package.json_ can +specify which menus to load and in what order. -By default, all menus are loaded in alphabetical order. An optional -`menus` array in your _package.json_ can specify which menus to load -and in what order. - -FIXME: Describe how to create an application menu item. - -Context menus are created by determining which element was selected and -then adding all of the menu items whose selectors match that element (in -the order which they were loaded). The process is then repeated for the -elements until reaching the top of the dom tree. - -NOTE: Currently you can only specify items to be added to the context -menu, the menu which appears when you right click. +### Application Menu +```coffee-script +'menu': [ + { + 'label': 'Packages' + 'submenu': [ + { + 'label': 'My Package' + 'submenu': [ + { + 'label': 'Toggle' + 'command': 'my-package:toggle' + } + ] + } + ] + } +] ``` + +It's recommended that you create an application menu item for common actions +with your package that aren't tied to a specific element. + +To add your own item to the application menu simply create a top level `menu` +key in any menu configuration file in _menus_ (since the above is [CSON] it +should end with `.cson`) + +The menu templates you specify are merged with all other templates provided +by other packages in the order which they were loaded. + +### Context Menu + +```coffee-script 'context-menu': '.tree-view': 'Add file': 'tree-view:add-file' @@ -185,10 +188,25 @@ menu, the menu which appears when you right click. 'Inspect Element': 'core:inspect' ``` +It's recommended to specify a context menu item for commands that are linked to +specific parts of the interface, like adding a file in the tree-view. + +To add your own item to the application menu simply create a top level +`context-menu` key in any menu configuration file in _menus_ (since the above is +[CSON] it should end with `.cson`) + +Context menus are created by determining which element was selected and +then adding all of the menu items whose selectors match that element (in +the order which they were loaded). The process is then repeated for the +elements until reaching the top of the DOM tree. + +In the example above, the `Add file` item will only appear when the focused item +or one of its parents has the `tree-view` class applied to it. + ## Snippets -An extension can supply language snippets in the _snippets_ directory. These can -be `.cson` or `.json` files. Here's an example: +An extension can supply language snippets in the _snippets_ directory which +allows the user to enter repetitive text quickly. ```coffeescript ".source.coffee .specs": @@ -287,18 +305,48 @@ directory, they can be run by Atom. Under the hood, [Jasmine] is being used to execute the tests, so you can assume that any DSL available there is available to your package as well. +**FIXME: Explain the following** + +* jasmine +* jasmine-focused +* `spec/fixtures` and global.project +* setTimeout +* whatever else is different in spec-helper + ## Running tests -FIXME: Describe `apm test` +Once you've got your test suite written, the recommended way to run it is `apm +test`. `apm test` prints its output to the console and returns the proper status +code depending on whether tests passed or failed. + +## Publishing + +Atom bundles a command line utility called [apm] which can be used to publish +Atom packages to the public registry. + +Once your package is written and ready for distribution you can run the +following to publish your package: + +```sh +cd my-package +apm publish minor +``` + +This will update your `package.json` to have a new minor `version`, commit the +change, create a new [Git tag][git-tag], and then upload the package to the +registry. + +Run `apm help publish` to see all the available options and `apm help` to see +all the other available commands. + # Full Example 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 `cmd-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_. +To get started hit `cmd-p`, and start typing "Package Generator." to generate +the package. Once you select the package generator command, 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 `cmd-r` to reload Atom, then hit `cmd-p` and start typing "Changer." @@ -317,7 +365,7 @@ 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 +key binding 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: @@ -357,7 +405,7 @@ editor. Hitting the key binding on the tree now works! -## Working with styles +## 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. @@ -368,7 +416,7 @@ some of the bundled libraries Atom provides by default](#included-libraries). Let's bring in jQuery: ```coffeescript -$ = require 'jquery' +{$} = require 'atom' ``` Now, we can query the tree to get us a list of every file that _wasn't_ @@ -425,7 +473,7 @@ 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][space-pen], which we'll touch upon only briefly here. +[SpacePen], 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: @@ -464,7 +512,7 @@ else 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 +toggled on and off more freely, it might be better to draw the interface 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 @@ -563,7 +611,6 @@ popular libraries into their packages: Additional libraries can be found by browsing Atom's _node_modules_ folder. - [npm]: http://en.wikipedia.org/wiki/Npm_(software) [npm-keys]: https://npmjs.org/doc/json.html [apm]: https://github.com/atom/apm @@ -576,3 +623,5 @@ Additional libraries can be found by browsing Atom's _node_modules_ folder. [jquery]: http://jquery.com/ [underscore]: http://underscorejs.org/ [jasmine]: https://github.com/pivotal/jasmine +[cson]: https://github.com/atom/season +[less]: http://lesscss.org From 492d7bc69a07f94f85df3f6182f691258219a994 Mon Sep 17 00:00:00 2001 From: Matt Colyer Date: Wed, 16 Oct 2013 11:52:00 -0700 Subject: [PATCH 08/10] :memo: Give package styling recommendations --- docs/creating-a-package.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/creating-a-package.md b/docs/creating-a-package.md index 3175abce0..da544466d 100644 --- a/docs/creating-a-package.md +++ b/docs/creating-a-package.md @@ -120,6 +120,15 @@ 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] (but LESS is recommended). +Ideally you will not need much in the way of styling. We've provided a standard +set of components. You can view all components by using the command palette +(`cmd-p`) and searching for "styleguide" or just `cmd+ctrl+D`. + +If you do need styling, we try to keep only structural styles in the package +stylesheets. Colors and sizing should be taken from the active theme's +[ui-variables.less][ui-variables]. If you follow this guideline, your package +will look good out of the box with any theme! + An optional `stylesheets` array in your _package.json_ can list the stylesheets by name to specify a loading order; otherwise, stylesheets are loaded alphabetically. @@ -625,3 +634,4 @@ Additional libraries can be found by browsing Atom's _node_modules_ folder. [jasmine]: https://github.com/pivotal/jasmine [cson]: https://github.com/atom/season [less]: http://lesscss.org +[ui-variables]: https://github.com/atom/atom-dark-ui/blob/master/stylesheets/ui-variables.less From f7a30845f8120177f64332b58f8b7935cde1ffba Mon Sep 17 00:00:00 2001 From: Matt Colyer Date: Wed, 16 Oct 2013 12:08:53 -0700 Subject: [PATCH 09/10] Update keybinding --- docs/creating-a-package.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/creating-a-package.md b/docs/creating-a-package.md index da544466d..96b70c301 100644 --- a/docs/creating-a-package.md +++ b/docs/creating-a-package.md @@ -122,7 +122,7 @@ is recommended). Ideally you will not need much in the way of styling. We've provided a standard set of components. You can view all components by using the command palette -(`cmd-p`) and searching for "styleguide" or just `cmd+ctrl+D`. +(`cmd-p`) and searching for "styleguide" or just `cmd+ctrl+G`. If you do need styling, we try to keep only structural styles in the package stylesheets. Colors and sizing should be taken from the active theme's From dbef7a26ce1d3b4252897e339e5f4f6bee78b488 Mon Sep 17 00:00:00 2001 From: Matt Colyer Date: Wed, 16 Oct 2013 12:09:27 -0700 Subject: [PATCH 10/10] :memo: Describe apm linking when creating a theme --- docs/creating-a-theme.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/creating-a-theme.md b/docs/creating-a-theme.md index 6cfeac62e..b0ff04ebb 100644 --- a/docs/creating-a-theme.md +++ b/docs/creating-a-theme.md @@ -45,10 +45,11 @@ a few things before starting: that have been already been defined. 1. When you're ready update the `README.md` and include an example screenshot of your new theme in action. -1. Open a terminal, find your new theme's directory, initialize the git - repository and push it to repository on GitHub. -1. Once you're ready for others to use your theme, run `apm publish` from within - that directory to make it available. +1. Open a terminal to your new theme directory + 1. Run `apm link` to install it locally. + 1. Reload Atom (`cmd-r`) and your theme should now be applied. + 1. To publish, initialize a git repository, push to GitHub, and run + `apm publish`. ## Interface Themes