mirror of
https://github.com/pulsar-edit/pulsar.git
synced 2025-01-07 23:59:22 +03:00
Start leveling up extension docs
This commit is contained in:
Garen Torikian
Garen Torikian & Nathan Sobo
parent
4b993b99cd
commit
8d7fd982e1
@ -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.
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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 },
|
||||
|
||||
138
docs/configuring-atom.md
Normal file
138
docs/configuring-atom.md
Normal file
@ -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;
|
||||
}
|
||||
```
|
||||
@ -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.
|
||||
|
||||
|
||||
|
||||
## 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.
|
||||
|
||||
@ -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
|
||||
|
||||
154
docs/packages/authoring-packages.md
Normal file
154
docs/packages/authoring-packages.md
Normal file
@ -0,0 +1,154 @@
|
||||
# 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.
|
||||
@ -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/
|
||||
0
docs/packages/creating_a_package.md
Normal file
0
docs/packages/creating_a_package.md
Normal file
5
docs/packages/package_json.md
Normal file
5
docs/packages/package_json.md
Normal file
@ -0,0 +1,5 @@
|
||||
# package.json format
|
||||
|
||||
stylesheets
|
||||
keymaps
|
||||
snippets
|
||||
Loading…
Reference in New Issue
Block a user