mirror of
https://github.com/Foundry376/Mailspring.git
synced 2025-02-26 00:54:04 +08:00
refactor(cruft): remove old Atom docs and other cruft
Summary: Getting rid of things that I'm pretty sure we don't need. Lmk if you see anything to the otherwise. Test Plan: edgehill --test Reviewers: bengotow Reviewed By: bengotow Differential Revision: https://phab.nylas.com/D1799
This commit is contained in:
Evan Morikawa
parent
90dbd9f6ac
commit
2442e0d6b6
69 changed files with 27 additions and 4014 deletions
1
.npmrc
1
.npmrc
|
|
@ -1 +0,0 @@
|
|||
cache = ~/.atom/.npm
|
||||
17
.pairs
17
.pairs
|
|
@ -1,17 +0,0 @@
|
|||
pairs:
|
||||
ns: Nathan Sobo; nathan
|
||||
cj: Corey Johnson; cj
|
||||
dg: David Graham; dgraham
|
||||
ks: Kevin Sawicki; kevin
|
||||
jc: Jerry Cheung; jerry
|
||||
bl: Brian Lopez; brian
|
||||
jp: Justin Palmer; justin
|
||||
gt: Garen Torikian; garen
|
||||
mc: Matt Colyer; mcolyer
|
||||
bo: Ben Ogle; benogle
|
||||
jr: Jason Rudolph; jasonrudolph
|
||||
jl: Jessica Lord; jlord
|
||||
dh: Daniel Hengeveld; danielh
|
||||
email:
|
||||
domain: github.com
|
||||
#global: true
|
||||
|
|
@ -1 +0,0 @@
|
|||
2.7.6
|
||||
130
CONTRIBUTING.md
130
CONTRIBUTING.md
|
|
@ -1,130 +0,0 @@
|
|||
# Contributing to Atom
|
||||
|
||||
:+1::tada: First off, thanks for taking the time to contribute! :tada::+1:
|
||||
|
||||
The following is a set of guidelines for contributing to Atom and its packages,
|
||||
which are hosted in the [Atom Organization](https://github.com/atom) on GitHub.
|
||||
If you're unsure which package is causing your problem or if you're having an
|
||||
issue with Atom core, please open an issue on the [main atom repository](https://github.com/atom/atom/issues).
|
||||
These are just guidelines, not rules, use your best judgement and feel free to
|
||||
propose changes to this document in a pull request.
|
||||
|
||||
## Submitting Issues
|
||||
|
||||
* Check the [debugging guide](https://atom.io/docs/latest/debugging) for tips
|
||||
on debugging. You might be able to find the cause of the problem and fix
|
||||
things yourself.
|
||||
* Include the version of Atom you are using and the OS.
|
||||
* Include screenshots and animated GIFs whenever possible; they are immensely
|
||||
helpful.
|
||||
* Include the behavior you expected and other places you've seen that behavior
|
||||
such as Emacs, vi, Xcode, etc.
|
||||
* Check the dev tools (`alt-cmd-i`) for errors to include. If the dev tools
|
||||
are open _before_ the error is triggered, a full stack trace for the error
|
||||
will be logged. If you can reproduce the error, use this approach to get the
|
||||
full stack trace and include it in the issue.
|
||||
* On Mac, check Console.app for stack traces to include if reporting a crash.
|
||||
* Perform a cursory search to see if a similar issue has already been submitted.
|
||||
* Please setup a [profile picture](https://help.github.com/articles/how-do-i-set-up-my-profile-picture)
|
||||
to make yourself recognizable and so we can all get to know each other better.
|
||||
|
||||
### Package Repositories
|
||||
|
||||
This is the repository for the core Atom editor only. Atom comes bundled with
|
||||
many packages and themes that are stored in other repos under the
|
||||
[Atom organization](https://github.com/atom) such as
|
||||
[tabs](https://github.com/atom/tabs),
|
||||
[find-and-replace](https://github.com/atom/find-and-replace),
|
||||
[language-javascript](https://github.com/atom/language-javascript), and
|
||||
[atom-light-ui](https://github.com/atom/atom-light-ui).
|
||||
|
||||
For more information on how to work with Atom's official packages, see
|
||||
[Contributing to Atom Packages](https://atom.io/docs/latest/contributing-to-packages.html)
|
||||
|
||||
## Pull Requests
|
||||
|
||||
* Include screenshots and animated GIFs in your pull request whenever possible.
|
||||
* Follow the [CoffeeScript](#coffeescript-styleguide),
|
||||
[JavaScript](https://github.com/styleguide/javascript),
|
||||
and [CSS](https://github.com/styleguide/css) styleguides.
|
||||
* Include thoughtfully-worded, well-structured
|
||||
[Jasmine](http://jasmine.github.io/) specs.
|
||||
* Document new code based on the
|
||||
[Documentation Styleguide](#documentation-styleguide)
|
||||
* End files with a newline.
|
||||
* Place requires in the following order:
|
||||
* Built in Node Modules (such as `path`)
|
||||
* Built in Atom and Atom Shell Modules (such as `atom`, `shell`)
|
||||
* Local Modules (using relative paths)
|
||||
* Place class properties in the following order:
|
||||
* Class methods and properties (methods starting with a `@`)
|
||||
* Instance methods and properties
|
||||
* Avoid platform-dependent code:
|
||||
* Use `require('atom').fs.getHomeDirectory()` to get the home directory.
|
||||
* Use `path.join()` to concatenate filenames.
|
||||
* Use `os.tmpdir()` rather than `/tmp` when you need to reference the
|
||||
temporary directory.
|
||||
* Using a plain `return` when returning explicitly at the end of a function.
|
||||
* Not `return null`, `return undefined`, `null`, or `undefined`
|
||||
|
||||
## Git Commit Messages
|
||||
|
||||
* Use the present tense ("Add feature" not "Added feature")
|
||||
* Use the imperative mood ("Move cursor to..." not "Moves cursor to...")
|
||||
* Limit the first line to 72 characters or less
|
||||
* Reference issues and pull requests liberally
|
||||
* Consider starting the commit message with an applicable emoji:
|
||||
* :art: `:art:` when improving the format/structure of the code
|
||||
* :racehorse: `:racehorse:` when improving performance
|
||||
* :non-potable_water: `:non-potable_water:` when plugging memory leaks
|
||||
* :memo: `:memo:` when writing docs
|
||||
* :penguin: `:penguin:` when fixing something on Linux
|
||||
* :apple: `:apple:` when fixing something on Mac OS
|
||||
* :checkered_flag: `:checkered_flag:` when fixing something on Windows
|
||||
* :bug: `:bug:` when fixing a bug
|
||||
* :fire: `:fire:` when removing code or files
|
||||
* :green_heart: `:green_heart:` when fixing the CI build
|
||||
* :white_check_mark: `:white_check_mark:` when adding tests
|
||||
* :lock: `:lock:` when dealing with security
|
||||
* :arrow_up: `:arrow_up:` when upgrading dependencies
|
||||
* :arrow_down: `:arrow_down:` when downgrading dependencies
|
||||
* :shirt: `:shirt:` when removing linter warnings
|
||||
|
||||
## CoffeeScript Styleguide
|
||||
|
||||
* Set parameter defaults without spaces around the equal sign
|
||||
* `clear = (count=1) ->` instead of `clear = (count = 1) ->`
|
||||
* Use parentheses if it improves code clarity.
|
||||
* Prefer alphabetic keywords to symbolic keywords:
|
||||
* `a is b` instead of `a == b`
|
||||
* Avoid spaces inside the curly-braces of hash literals:
|
||||
* `{a: 1, b: 2}` instead of `{ a: 1, b: 2 }`
|
||||
* Include a single line of whitespace between methods.
|
||||
* Capitalize initialisms and acronyms in names, except for the first word, which
|
||||
should be lower-case:
|
||||
* `getURI` instead of `getUri`
|
||||
* `uriToOpen` instead of `URIToOpen`
|
||||
|
||||
## Documentation Styleguide
|
||||
|
||||
* Use [AtomDoc](https://github.com/atom/atomdoc).
|
||||
* Use [Markdown](https://daringfireball.net/projects/markdown).
|
||||
* Reference methods and classes in markdown with the custom `{}` notation:
|
||||
* Reference classes with `{ClassName}`
|
||||
* Reference instance methods with `{ClassName::methodName}`
|
||||
* Reference class methods with `{ClassName.methodName}`
|
||||
|
||||
### Example
|
||||
|
||||
```coffee
|
||||
# Public: Disable the package with the given name.
|
||||
#
|
||||
# * `name` The {String} name of the package to disable.
|
||||
# * `options` (optional) The {Object} with disable options (default: {}):
|
||||
# * `trackTime` A {Boolean}, `true` to track the amount of time taken.
|
||||
# * `ignoreErrors` A {Boolean}, `true` to catch and ignore errors thrown.
|
||||
# * `callback` The {Function} to call after the package has been disabled.
|
||||
#
|
||||
# Returns `undefined`.
|
||||
disablePackage: (name, options, callback) ->
|
||||
```
|
||||
22
Dockerfile
22
Dockerfile
|
|
@ -1,22 +0,0 @@
|
|||
# VERSION: 0.1
|
||||
# DESCRIPTION: Image to build Atom and create a .rpm file
|
||||
|
||||
# Base docker image
|
||||
FROM fedora:20
|
||||
|
||||
# Install dependencies
|
||||
RUN yum install -y \
|
||||
make \
|
||||
gcc \
|
||||
gcc-c++ \
|
||||
glibc-devel \
|
||||
git-core \
|
||||
libgnome-keyring-devel \
|
||||
rpmdevtools
|
||||
|
||||
# Install node
|
||||
RUN curl -sL https://rpm.nodesource.com/setup | bash -
|
||||
RUN yum install -y nodejs
|
||||
|
||||
ADD . /atom
|
||||
WORKDIR /atom
|
||||
21
LICENSE.md
21
LICENSE.md
|
|
@ -1,20 +1 @@
|
|||
Copyright (c) 2014 GitHub Inc.
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining
|
||||
a copy of this software and associated documentation files (the
|
||||
"Software"), to deal in the Software without restriction, including
|
||||
without limitation the rights to use, copy, modify, merge, publish,
|
||||
distribute, sublicense, and/or sell copies of the Software, and to
|
||||
permit persons to whom the Software is furnished to do so, subject to
|
||||
the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be
|
||||
included in all copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
||||
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
||||
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
|
||||
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
|
||||
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
|
||||
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
|
||||
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
||||
Proprietary softare of Nylas Inc.
|
||||
|
|
|
|||
|
|
@ -303,9 +303,9 @@ module.exports = (grunt) ->
|
|||
appDirectory: shellAppDir
|
||||
outputDirectory: path.join(buildDir, 'installer')
|
||||
authors: 'Nylas Inc.'
|
||||
loadingGif: path.resolve(__dirname, '..', 'resources', 'win', 'loading.gif')
|
||||
loadingGif: path.resolve(__dirname, 'resources', 'win', 'loading.gif')
|
||||
iconUrl: 'https://raw.githubusercontent.com/atom/atom/master/resources/win/atom.ico'
|
||||
setupIcon: path.resolve(__dirname, '..', 'resources', 'win', 'nylas.ico')
|
||||
setupIcon: path.resolve(__dirname, 'resources', 'win', 'nylas.ico')
|
||||
|
||||
shell:
|
||||
'kill-atom':
|
||||
|
|
|
|||
|
Before Width: | Height: | Size: 13 KiB After Width: | Height: | Size: 13 KiB |
|
Before Width: | Height: | Size: 1.2 KiB After Width: | Height: | Size: 1.2 KiB |
|
Before Width: | Height: | Size: 33 KiB After Width: | Height: | Size: 33 KiB |
|
Before Width: | Height: | Size: 2.2 KiB After Width: | Height: | Size: 2.2 KiB |
|
Before Width: | Height: | Size: 200 KiB After Width: | Height: | Size: 200 KiB |
|
Before Width: | Height: | Size: 5.1 KiB After Width: | Height: | Size: 5.1 KiB |
|
Before Width: | Height: | Size: 200 KiB After Width: | Height: | Size: 200 KiB |
|
Before Width: | Height: | Size: 19 KiB After Width: | Height: | Size: 19 KiB |
|
Before Width: | Height: | Size: 196 KiB After Width: | Height: | Size: 196 KiB |
|
Before Width: | Height: | Size: 58 KiB After Width: | Height: | Size: 58 KiB |
|
|
@ -40,7 +40,7 @@ module.exports = (grunt) ->
|
|||
cp 'atom.sh', path.resolve(appDir, '..', 'new-app', 'atom.sh')
|
||||
|
||||
cp 'package.json', path.join(appDir, 'package.json')
|
||||
cp path.join('resources', 'nylas.png'), path.join(appDir, 'nylas.png')
|
||||
cp path.join('build', 'resources', 'nylas.png'), path.join(appDir, 'nylas.png')
|
||||
|
||||
packageNames = []
|
||||
packageDirectories = []
|
||||
|
|
@ -48,7 +48,6 @@ module.exports = (grunt) ->
|
|||
'benchmark'
|
||||
'dot-nylas'
|
||||
'vendor'
|
||||
'resources'
|
||||
]
|
||||
|
||||
{devDependencies} = grunt.file.readJSON('package.json')
|
||||
|
|
@ -84,10 +83,11 @@ module.exports = (grunt) ->
|
|||
path.join('build', 'Release', 'obj.target')
|
||||
path.join('build', 'Release', 'obj')
|
||||
path.join('build', 'Release', '.deps')
|
||||
path.join('build', 'resources')
|
||||
path.join('build', 'resources', 'linux')
|
||||
path.join('build', 'resources', 'mac')
|
||||
path.join('build', 'resources', 'win')
|
||||
path.join('vendor', 'apm')
|
||||
path.join('resources', 'linux')
|
||||
path.join('resources', 'mac')
|
||||
path.join('resources', 'win')
|
||||
|
||||
# These are only require in dev mode when the grammar isn't precompiled
|
||||
path.join('snippets', 'node_modules', 'loophole')
|
||||
|
|
@ -170,18 +170,18 @@ module.exports = (grunt) ->
|
|||
fs.symlinkSync(path.join('..', '..', 'bin', 'apm'), path.resolve(appDir, '..', 'new-app', 'apm', 'node_modules', '.bin', 'apm'))
|
||||
|
||||
if process.platform is 'darwin'
|
||||
grunt.file.recurse path.join('resources', 'mac'), (sourcePath, rootDirectory, subDirectory='', filename) ->
|
||||
grunt.file.recurse path.join('build', 'resources', 'mac'), (sourcePath, rootDirectory, subDirectory='', filename) ->
|
||||
unless /.+\.plist/.test(sourcePath)
|
||||
grunt.file.copy(sourcePath, path.resolve(appDir, '..', subDirectory, filename))
|
||||
|
||||
if process.platform is 'win32'
|
||||
cp path.join('resources', 'win', 'atom.cmd'), path.join(shellAppDir, 'resources', 'cli', 'atom.cmd')
|
||||
cp path.join('resources', 'win', 'atom.sh'), path.join(shellAppDir, 'resources', 'cli', 'atom.sh')
|
||||
cp path.join('resources', 'win', 'atom.js'), path.join(shellAppDir, 'resources', 'cli', 'atom.js')
|
||||
cp path.join('resources', 'win', 'apm.sh'), path.join(shellAppDir, 'resources', 'cli', 'apm.sh')
|
||||
cp path.join('build', 'resources', 'win', 'atom.cmd'), path.join(shellAppDir, 'resources', 'cli', 'atom.cmd')
|
||||
cp path.join('build', 'resources', 'win', 'atom.sh'), path.join(shellAppDir, 'resources', 'cli', 'atom.sh')
|
||||
cp path.join('build', 'resources', 'win', 'atom.js'), path.join(shellAppDir, 'resources', 'cli', 'atom.js')
|
||||
cp path.join('build', 'resources', 'win', 'apm.sh'), path.join(shellAppDir, 'resources', 'cli', 'apm.sh')
|
||||
|
||||
if process.platform is 'linux'
|
||||
cp path.join('resources', 'linux', 'icons'), path.join(buildDir, 'icons')
|
||||
cp path.join('build', 'resources', 'linux', 'icons'), path.join(buildDir, 'icons')
|
||||
|
||||
dependencies = ['compile', 'generate-license:save', 'generate-module-cache', 'compile-packages-slug']
|
||||
dependencies.push('copy-info-plist') if process.platform is 'darwin'
|
||||
|
|
|
|||
|
|
@ -9,5 +9,5 @@ module.exports = (grunt) ->
|
|||
helperPlistPath = path.join(contentsDir, 'Frameworks/Atom Helper.app/Contents/Info.plist')
|
||||
|
||||
# Copy custom plist files
|
||||
cp 'resources/mac/nylas-Info.plist', plistPath
|
||||
cp 'resources/mac/helper-Info.plist', helperPlistPath
|
||||
cp 'build/resources/mac/nylas-Info.plist', plistPath
|
||||
cp 'build/resources/mac/helper-Info.plist', helperPlistPath
|
||||
|
|
|
|||
|
|
@ -31,7 +31,7 @@ module.exports = (grunt) ->
|
|||
binDir = path.join(installDir, 'bin')
|
||||
shareDir = path.join(installDir, 'share', 'nylas')
|
||||
|
||||
iconName = path.join(shareDir,'resources', 'app', 'resources', 'nylas.png')
|
||||
iconName = path.join(shareDir, 'resources', 'app', 'resources', 'nylas.png')
|
||||
|
||||
mkdir binDir
|
||||
# Note that `atom.sh` can't be renamed `nylas.sh` because `apm`
|
||||
|
|
@ -44,7 +44,7 @@ module.exports = (grunt) ->
|
|||
# Create nylas.desktop if installation not in temporary folder
|
||||
tmpDir = if process.env.TMPDIR? then process.env.TMPDIR else '/tmp'
|
||||
if installDir.indexOf(tmpDir) isnt 0
|
||||
desktopFile = path.join('resources', 'linux', 'nylas.desktop.in')
|
||||
desktopFile = path.join('build', 'resources', 'linux', 'nylas.desktop.in')
|
||||
desktopInstallFile = path.join(installDir, 'share', 'applications', 'nylas.desktop')
|
||||
|
||||
{description} = grunt.file.readJSON('package.json')
|
||||
|
|
|
|||
|
|
@ -38,9 +38,9 @@ module.exports = (grunt) ->
|
|||
iconName = 'nylas'
|
||||
getInstalledSize buildDir, (error, installedSize) ->
|
||||
data = {name, version, description, section, arch, maintainer, installDir, iconName, installedSize}
|
||||
controlFilePath = fillTemplate(path.join('resources', 'linux', 'debian', 'control'), data)
|
||||
desktopFilePath = fillTemplate(path.join('resources', 'linux', 'nylas.desktop'), data)
|
||||
icon = path.join('resources', 'nylas.png')
|
||||
controlFilePath = fillTemplate(path.join('build', 'resources', 'linux', 'debian', 'control'), data)
|
||||
desktopFilePath = fillTemplate(path.join('build', 'resources', 'linux', 'nylas.desktop'), data)
|
||||
icon = path.join('build', 'resources', 'nylas.png')
|
||||
|
||||
cmd = path.join('script', 'mkdeb')
|
||||
args = [version, arch, controlFilePath, desktopFilePath, icon, buildDir]
|
||||
|
|
|
|||
|
|
@ -35,7 +35,7 @@ module.exports = (grunt) ->
|
|||
cmd: dmgExecutable
|
||||
args: [
|
||||
"--volname", "Nylas Installer",
|
||||
"--volicon", path.join("resources", "nylas.png"),
|
||||
"--volicon", path.join("build", "resources", "nylas.png"),
|
||||
"--window-pos", "200", "120",
|
||||
"--window-size", "800", "400",
|
||||
"--icon-size", "100",
|
||||
|
|
|
|||
|
|
@ -35,8 +35,8 @@ module.exports = (grunt) ->
|
|||
iconName = path.join(shareDir, 'resources', 'app', 'resources', 'nylas.png')
|
||||
|
||||
data = {name, version, description, installDir, iconName}
|
||||
specFilePath = fillTemplate(path.join('resources', 'linux', 'redhat', 'nylas.spec'), data)
|
||||
desktopFilePath = fillTemplate(path.join('resources', 'linux', 'nylas.desktop'), data)
|
||||
specFilePath = fillTemplate(path.join('build', 'resources', 'linux', 'redhat', 'nylas.spec'), data)
|
||||
desktopFilePath = fillTemplate(path.join('build', 'resources', 'linux', 'nylas.desktop'), data)
|
||||
|
||||
cmd = path.join('script', 'mkrpm')
|
||||
args = [specFilePath, desktopFilePath, buildDir]
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@ module.exports = (grunt) ->
|
|||
|
||||
shellAppDir = grunt.config.get('atom.shellAppDir')
|
||||
shellExePath = path.join(shellAppDir, 'edgehill.exe')
|
||||
iconPath = path.resolve('resources', 'win', 'edgehill.ico')
|
||||
iconPath = path.resolve('build', 'resources', 'win', 'edgehill.ico')
|
||||
|
||||
rcedit = require('rcedit')
|
||||
rcedit(shellExePath, {'icon': iconPath}, done)
|
||||
|
|
|
|||
|
|
@ -1,5 +0,0 @@
|
|||
# Welcome to the Atom Docs
|
||||
|
||||
|
||||
|
||||
TODO: Write when docs move to a dedicated repo.
|
||||
|
|
@ -1,58 +0,0 @@
|
|||
## Configuration API
|
||||
|
||||
### Reading Config Settings
|
||||
|
||||
If you are writing a package that you want to make configurable, you'll need to
|
||||
read config settings via the `atom.config` global. You can read the current
|
||||
value of a namespaced config key with `atom.config.get`:
|
||||
|
||||
```coffeescript
|
||||
# read a value with `config.get`
|
||||
@showInvisibles() if atom.config.get "editor.showInvisibles"
|
||||
```
|
||||
|
||||
Or you can subscribe via `atom.config.observe` to track changes from any view
|
||||
object.
|
||||
|
||||
```coffeescript
|
||||
{View} = require 'space-pen'
|
||||
|
||||
class MyView extends View
|
||||
attached: ->
|
||||
@fontSizeObserveSubscription =
|
||||
atom.config.observe 'editor.fontSize', (newValue, {previous}) =>
|
||||
@adjustFontSize()
|
||||
|
||||
detached: ->
|
||||
@fontSizeObserveSubscription.dispose()
|
||||
```
|
||||
|
||||
The `atom.config.observe` method will call the given callback immediately with
|
||||
the current value for the specified key path, and it will also call it in the
|
||||
future whenever the value of that key path changes. If you only want to invoke
|
||||
the callback when the next time the value changes, use `atom.config.onDidChange`
|
||||
instead.
|
||||
|
||||
Subscription methods return *disposable* subscription objects. Note in the
|
||||
example above how we save the subscription to the `@fontSizeObserveSubscription`
|
||||
instance variable and dispose of it when the view is detached. To group multiple
|
||||
subscriptions together, you can add them all to a
|
||||
[`CompositeDisposable`][composite-disposable] that you dispose when the view is
|
||||
detached.
|
||||
|
||||
### Writing Config Settings
|
||||
|
||||
The `atom.config` database is populated on startup from `~/.atom/config.cson`,
|
||||
but you can programmatically write to it with `atom.config.set`:
|
||||
|
||||
```coffeescript
|
||||
# basic key update
|
||||
atom.config.set("core.showInvisibles", true)
|
||||
```
|
||||
|
||||
If you're exposing package configuration via specific key paths, you'll want to
|
||||
associate them with a schema in your package's main module. Read more about
|
||||
schemas in the [config API docs][config-api].
|
||||
|
||||
[composite-disposable]: https://atom.io/docs/api/latest/CompositeDisposable
|
||||
[config-api]: https://atom.io/docs/api/latest/Config
|
||||
|
|
@ -1,175 +0,0 @@
|
|||
# Keymaps In-Depth
|
||||
|
||||
## Structure of a Keymap File
|
||||
|
||||
Keymap files are encoded as JSON or CSON files containing nested hashes. They
|
||||
work much like style sheets, but instead of applying style properties to elements
|
||||
matching the selector, they specify the meaning of keystrokes on elements
|
||||
matching the selector. Here is an example of some bindings that apply when
|
||||
keystrokes pass through `atom-text-editor` elements:
|
||||
|
||||
```coffee
|
||||
'atom-text-editor':
|
||||
'cmd-delete': 'editor:delete-to-beginning-of-line'
|
||||
'alt-backspace': 'editor:delete-to-beginning-of-word'
|
||||
'ctrl-A': 'editor:select-to-first-character-of-line'
|
||||
'ctrl-shift-e': 'editor:select-to-end-of-line'
|
||||
'cmd-left': 'editor:move-to-first-character-of-line'
|
||||
|
||||
'atom-text-editor:not([mini])'
|
||||
'cmd-alt-[': 'editor:fold-current-row'
|
||||
'cmd-alt-]': 'editor:unfold-current-row'
|
||||
```
|
||||
|
||||
Beneath the first selector are several bindings, mapping specific *keystroke
|
||||
patterns* to *commands*. When an element with the `atom-text-editor` class is focused and
|
||||
`cmd-delete` is pressed, an custom DOM event called
|
||||
`editor:delete-to-beginning-of-line` is emitted on the `atom-text-editor` element.
|
||||
|
||||
The second selector group also targets editors, but only if they don't have the
|
||||
`mini` attribute. In this example, the commands for code folding don't really
|
||||
make sense on mini-editors, so the selector restricts them to regular editors.
|
||||
|
||||
### Keystroke Patterns
|
||||
|
||||
Keystroke patterns express one or more keystrokes combined with optional
|
||||
modifier keys. For example: `ctrl-w v`, or `cmd-shift-up`. A keystroke is
|
||||
composed of the following symbols, separated by a `-`. A multi-keystroke pattern
|
||||
can be expressed as keystroke patterns separated by spaces.
|
||||
|
||||
|
||||
| Type | Examples
|
||||
| --------------------|----------------------------
|
||||
| Character literals | `a` `4` `$`
|
||||
| Modifier keys | `cmd` `ctrl` `alt` `shift`
|
||||
| Special keys | `enter` `escape` `backspace` `delete` `tab` `home` `end` `pageup` `pagedown` `left` `right` `up` `down`
|
||||
|
||||
### Commands
|
||||
|
||||
Commands are custom DOM events that are triggered when a keystroke matches a
|
||||
binding. This allows user interface code to listen for named commands without
|
||||
specifying the specific keybinding that triggers it. For example, the following
|
||||
code creates a command to insert the current date in an editor:
|
||||
|
||||
```coffee
|
||||
atom.commands.add 'atom-text-editor',
|
||||
'user:insert-date': (event) ->
|
||||
editor = @getModel()
|
||||
editor.insertText(new Date().toLocaleString())
|
||||
```
|
||||
|
||||
`atom.commands` refers to the global {CommandRegistry} instance where all commands
|
||||
are set and consequently picked up by the command palette.
|
||||
|
||||
When you are looking to bind new keys, it is often useful to use the command
|
||||
palette (`ctrl-shift-p`) to discover what commands are being listened for in a
|
||||
given focus context. Commands are "humanized" following a simple algorithm, so a
|
||||
command like `editor:fold-current-row` would appear as "Editor: Fold Current
|
||||
Row".
|
||||
|
||||
### "Composed" Commands
|
||||
|
||||
A common question is, "How do I make a single keybinding execute two or more
|
||||
commands?" There isn't any direct support for this in Atom, but it can be
|
||||
achieved by creating a custom command that performs the multiple actions
|
||||
you desire and then creating a keybinding for that command. For example, let's
|
||||
say I want to create a "composed" command that performs a Select Line followed
|
||||
by Cut. You could add the following to your `init.coffee`:
|
||||
|
||||
```coffee
|
||||
atom.commands.add 'atom-text-editor', 'custom:cut-line', ->
|
||||
editor = atom.workspace.getActiveTextEditor()
|
||||
editor.selectLinesContainingCursors()
|
||||
editor.cutSelectedText()
|
||||
```
|
||||
|
||||
Then let's say we want to map this custom command to `alt-ctrl-z`, you could
|
||||
add the following to your keymap:
|
||||
|
||||
```coffee
|
||||
'atom-text-editor':
|
||||
'alt-ctrl-z': 'custom:cut-line'
|
||||
```
|
||||
|
||||
### Specificity and Cascade Order
|
||||
|
||||
As is the case with CSS applying styles, when multiple bindings match for a
|
||||
single element, the conflict is resolved by choosing the most *specific*
|
||||
selector. If two matching selectors have the same specificity, the binding
|
||||
for the selector appearing later in the cascade takes precedence.
|
||||
|
||||
Currently, there's no way to specify selector ordering within a single keymap,
|
||||
because JSON objects do not preserve order. We eventually plan to introduce a
|
||||
custom CSS-like file format for keymaps that allows for ordering within a single
|
||||
file. For now, we've opted to handle cases where selector ordering is critical
|
||||
by breaking the keymap into two separate files, such as `snippets-1.cson` and
|
||||
`snippets-2.cson`.
|
||||
|
||||
## Removing Bindings
|
||||
|
||||
When the keymap system encounters a binding with the `unset!` directive as its
|
||||
command, it will treat the current element as if it had no key bindings matching
|
||||
the current keystroke sequence and continue searching from its parent. If you
|
||||
want to remove a binding from a keymap you don't control, such as keymaps in
|
||||
Atom core or in packages, use the `unset!` directive.
|
||||
|
||||
For example, the following code removes the keybinding for `a` in the Tree View,
|
||||
which is normally used to trigger the `tree-view:add-file` command:
|
||||
|
||||
```coffee
|
||||
'.tree-view':
|
||||
'a': 'unset!'
|
||||
```
|
||||
|
||||
|
||||
|
||||
## Forcing Chromium's Native Keystroke Handling
|
||||
|
||||
EDIT: This has been overridden in the Edgehill project. By default, Chromium's
|
||||
native keystroke handling for Copy, Paste, Select-All, etc. is enabled. To except
|
||||
yourself from these behaviors, apply the `.override-key-bindings` class to an element.
|
||||
|
||||
If you want to force the native browser behavior for a given keystroke, use the
|
||||
`native!` directive as the command of a binding. This can be useful to enable
|
||||
the correct behavior in native input elements, for example. If you apply the
|
||||
`.native-key-bindings` class to an element, all the keystrokes typically handled
|
||||
by the browser will be assigned the `native!` directive.
|
||||
|
||||
## Overloading Key Bindings
|
||||
|
||||
Occasionally, it makes sense to layer multiple actions on top of the same key
|
||||
binding. An example of this is the snippets package. Snippets are inserted by
|
||||
typing a snippet prefix such as `for` and then pressing `tab`. Every time `tab`
|
||||
is pressed, we want to execute code attempting to expand a snippet if one exists
|
||||
for the text preceding the cursor. If a snippet *doesn't* exist, we want `tab`
|
||||
to actually insert whitespace.
|
||||
|
||||
To achieve this, the snippets package makes use of the `.abortKeyBinding()`
|
||||
method on the event object representing the `snippets:expand` command.
|
||||
|
||||
```coffee-script
|
||||
# pseudo-code
|
||||
editor.command 'snippets:expand', (e) =>
|
||||
if @cursorFollowsValidPrefix()
|
||||
@expandSnippet()
|
||||
else
|
||||
e.abortKeyBinding()
|
||||
```
|
||||
|
||||
When the event handler observes that the cursor does not follow a valid prefix,
|
||||
it calls `e.abortKeyBinding()`, telling the keymap system to continue searching
|
||||
for another matching binding.
|
||||
|
||||
## Step-by-Step: How Keydown Events are Mapped to Commands
|
||||
|
||||
* A keydown event occurs on a *focused* element.
|
||||
* Starting at the focused element, the keymap walks upward towards the root of
|
||||
the document, searching for the most specific CSS selector that matches the
|
||||
current DOM element and also contains a keystroke pattern matching the keydown
|
||||
event.
|
||||
* When a matching keystroke pattern is found, the search is terminated and the
|
||||
pattern's corresponding command is triggered on the current element.
|
||||
* If `.abortKeyBinding()` is called on the triggered event object, the search
|
||||
is resumed, triggering a binding on the next-most-specific CSS selector for
|
||||
the same element or continuing upward to parent elements.
|
||||
* If no bindings are found, the event is handled by Chromium normally.
|
||||
|
|
@ -1,24 +0,0 @@
|
|||
## Developing Node Modules
|
||||
|
||||
Atom contains a number of packages that are Node modules instead of Atom packages. If you want to
|
||||
make changes to the Node modules, for instance `atom-keymap`, you have to link them into the
|
||||
development environment differently than you would a normal Atom package.
|
||||
|
||||
### Linking a Node Module Into Your Atom Dev Environment
|
||||
|
||||
Here are the steps to run a local version of a node module *not an apm* within Atom. We're using
|
||||
`atom-keymap` as an example:
|
||||
|
||||
```bash
|
||||
$ git clone https://github.com/atom/atom-keymap.git
|
||||
$ cd atom-keymap
|
||||
$ npm install
|
||||
$ npm link
|
||||
$ apm rebuild # This is the special step, it makes the npm work with Atom's version of Node
|
||||
$ cd WHERE-YOU-CLONED-ATOM
|
||||
$ npm link atom-keymap
|
||||
$ atom # Should work!
|
||||
```
|
||||
|
||||
After this, you'll have to `npm install` and `apm rebuild` when you make a change to the node
|
||||
module's code.
|
||||
|
|
@ -1,87 +0,0 @@
|
|||
# Scoped Settings, Scopes and Scope Descriptors
|
||||
|
||||
Atom supports language-specific settings. You can soft wrap only Markdown files, or set the tab length to 4 in Python files.
|
||||
|
||||
Language-specific settings are a subset of something more general we call "scoped settings". Scoped settings allow targeting down to a specific syntax token type. For example, you could conceivably set a setting to target only Ruby comments, only code inside Markdown files, or even only JavaScript function names.
|
||||
|
||||
## Scope names in syntax tokens
|
||||
|
||||
Each token in the editor has a collection of scope names. For example, the aformentioned JavaScript function name might have the scope names `function` and `name`. An open paren might have the scope names `punctuation`, `parameters`, `begin`.
|
||||
|
||||
Scope names work just like CSS classes. In fact, in the editor, scope names are attached to a token's DOM node as CSS classes.
|
||||
|
||||
Take this piece of JavaScript:
|
||||
|
||||
```js
|
||||
function functionName() {
|
||||
console.log('Log it out');
|
||||
}
|
||||
```
|
||||
|
||||
In the dev tools, the first line's markup looks like this.
|
||||
|
||||
|
||||
|
||||
All the class names on the spans are scope names. Any scope name can be used to target a setting's value.
|
||||
|
||||
## Scope Selectors
|
||||
|
||||
Scope selectors allow you to target specific tokens just like a CSS selector targets specific nodes in the DOM. Some examples:
|
||||
|
||||
```coffee
|
||||
'.source.js' # selects all javascript tokens
|
||||
'.source.js .function.name' # selects all javascript function names
|
||||
'.function.name' # selects all function names in any language
|
||||
```
|
||||
|
||||
[Config::set][config-set] accepts a `scopeSelector`. If you'd like to set a setting for JavaScript function names, you can give it the js function name `scopeSelector`:
|
||||
|
||||
```coffee
|
||||
atom.config.set('.source.js .function.name', 'my-package.my-setting', 'special value')
|
||||
```
|
||||
|
||||
## Scope Descriptors
|
||||
|
||||
A scope descriptor is an [Object][scope-descriptor] that wraps an `Array` of
|
||||
`String`s. The Array describes a path from the root of the syntax tree to a
|
||||
token including _all_ scope names for the entire path.
|
||||
|
||||
In our JavaScript example above, a scope descriptor for the function name token would be:
|
||||
|
||||
```coffee
|
||||
['source.js', 'meta.function.js', 'entity.name.function.js']
|
||||
```
|
||||
|
||||
[Config::get][config-get] accepts a `scopeDescriptor`. You can get the value for your setting scoped to JavaScript function names via:
|
||||
|
||||
```coffee
|
||||
scopeDescriptor = ['source.js', 'meta.function.js', 'entity.name.function.js']
|
||||
value = atom.config.get(scopeDescriptor, 'my-package.my-setting')
|
||||
```
|
||||
|
||||
But, you do not need to generate scope descriptors by hand. There are a couple methods available to get the scope descriptor from the editor:
|
||||
|
||||
* [Editor::getRootScopeDescriptor][editor-getRootScopeDescriptor] to get the language's descriptor. eg. `[".source.js"]`
|
||||
* [Editor::scopeDescriptorForBufferPosition][editor-scopeDescriptorForBufferPosition] to get the descriptor at a specific position in the buffer.
|
||||
* [Cursor::getScopeDescriptor][cursor-getScopeDescriptor] to get a cursor's descriptor based on position. eg. if the cursor were in the name of the method in our example it would return `["source.js", "meta.function.js", "entity.name.function.js"]`
|
||||
|
||||
Let's revisit our example using these methods:
|
||||
|
||||
```coffee
|
||||
editor = atom.workspace.getActiveTextEditor()
|
||||
cursor = editor.getLastCursor()
|
||||
valueAtCursor = atom.config.get(cursor.getScopeDescriptor(), 'my-package.my-setting')
|
||||
valueForLanguage = atom.config.get(editor.getRootScopeDescriptor(), 'my-package.my-setting')
|
||||
```
|
||||
|
||||
|
||||
[config]:https://atom.io/docs/api/latest/Config
|
||||
[config-get]:https://atom.io/docs/api/latest/Config#instance-get
|
||||
[config-set]:https://atom.io/docs/api/latest/Config#instance-set
|
||||
[config-observe]:https://atom.io/docs/api/latest/Config#instance-observe
|
||||
|
||||
[editor-getRootScopeDescriptor]:https://atom.io/docs/api/latest/TextEditor#instance-getRootScopeDescriptor
|
||||
[editor-scopeDescriptorForBufferPosition]:https://atom.io/docs/api/latest/TextEditor#instance-scopeDescriptorForBufferPosition
|
||||
|
||||
[cursor-getScopeDescriptor]:https://atom.io/docs/api/latest/Cursor#instance-getScopeDescriptor
|
||||
[scope-descriptor]:https://atom.io/docs/api/latest/ScopeDescriptor
|
||||
|
|
@ -1,75 +0,0 @@
|
|||
## Serialization in Atom
|
||||
|
||||
When a window is refreshed or restored from a previous session, the view and its
|
||||
associated objects are *deserialized* from a JSON representation that was stored
|
||||
during the window's previous shutdown. For your own views and objects to be
|
||||
compatible with refreshing, you'll need to make them play nicely with the
|
||||
serializing and deserializing.
|
||||
|
||||
### Package Serialization Hook
|
||||
|
||||
Your package's main module can optionally include a `serialize` method, which
|
||||
will be called before your package is deactivated. You should return JSON, which
|
||||
will be handed back to you as an argument to `activate` next time it is called.
|
||||
In the following example, the package keeps an instance of `MyObject` in the
|
||||
same state across refreshes.
|
||||
|
||||
```coffee-script
|
||||
module.exports =
|
||||
activate: (state) ->
|
||||
@myObject =
|
||||
if state
|
||||
atom.deserializers.deserialize(state)
|
||||
else
|
||||
new MyObject("Hello")
|
||||
|
||||
serialize: ->
|
||||
@myObject.serialize()
|
||||
```
|
||||
|
||||
### Serialization Methods
|
||||
|
||||
```coffee-script
|
||||
class MyObject
|
||||
atom.deserializers.add(this)
|
||||
|
||||
@deserialize: ({data}) -> new MyObject(data)
|
||||
constructor: (@data) ->
|
||||
serialize: -> { deserializer: 'MyObject', data: @data }
|
||||
```
|
||||
|
||||
#### .serialize()
|
||||
Objects that you want to serialize should implement `.serialize()`. This method
|
||||
should return a serializable object, and it must contain a key named
|
||||
`deserializer` whose value is the name of a registered deserializer that can
|
||||
convert the rest of the data to an object. It's usually just the name of the
|
||||
class itself.
|
||||
|
||||
#### @deserialize(data)
|
||||
The other side of the coin is the `deserialize` method, which is usually a
|
||||
class-level method on the same class that implements `serialize`. This method's
|
||||
job is to convert a state object returned from a previous call `serialize` back
|
||||
into a genuine object.
|
||||
|
||||
#### atom.deserializers.add(klass)
|
||||
You need to call the `atom.deserializers.add` method with your class in
|
||||
order to make it available to the deserialization system. Now you can call the
|
||||
global `deserialize` method with state returned from `serialize`, and your
|
||||
class's `deserialize` method will be selected automatically.
|
||||
|
||||
### Versioning
|
||||
|
||||
```coffee-script
|
||||
class MyObject
|
||||
atom.deserializers.add(this)
|
||||
|
||||
@version: 2
|
||||
@deserialize: (state) -> ...
|
||||
serialize: -> { version: @constructor.version, ... }
|
||||
```
|
||||
|
||||
Your serializable class can optionally have a class-level `@version` property
|
||||
and include a `version` key in its serialized state. When deserializing, Atom
|
||||
will only attempt to call deserialize if the two versions match, and otherwise
|
||||
return undefined. We plan on implementing a migration system in the future, but
|
||||
this at least protects you from improperly deserializing old state.
|
||||
|
|
@ -1,288 +0,0 @@
|
|||
# Atom.io package and update API
|
||||
|
||||
This guide describes the web API used by [apm](https://github.com/atom/apm) and
|
||||
Atom. The vast majority of use cases are met by the `apm` command-line tool,
|
||||
which does other useful things like incrementing your version in `package.json`
|
||||
and making sure you have pushed your git tag. In fact, Atom itself shells out to
|
||||
`apm` rather than hitting the API directly. If you're curious about how Atom
|
||||
uses `apm`, see the [PackageManager class](https://github.com/atom/settings-view/blob/master/lib/package-manager.coffee)
|
||||
in the `settings-view` package.
|
||||
|
||||
*This API should be considered pre-release and is subject to change (though significant breaking changes are unlikely).*
|
||||
|
||||
### Authorization
|
||||
|
||||
For calls to the API that require authentication, provide a valid token from your
|
||||
[Atom.io account page](https://atom.io/account) in the `Authorization` header.
|
||||
|
||||
### Media type
|
||||
|
||||
All requests that take parameters require `application/json`.
|
||||
|
||||
# API Resources
|
||||
|
||||
## Packages
|
||||
|
||||
### Listing packages
|
||||
|
||||
#### GET /api/packages
|
||||
|
||||
Parameters:
|
||||
|
||||
- **page** (optional)
|
||||
- **sort** (optional) - One of `downloads`, `created_at`, `updated_at`, `stars`. Defaults to `downloads`
|
||||
- **direction** (optional) - `asc` or `desc`. Defaults to `desc`. `stars` can only be ordered `desc`
|
||||
|
||||
Returns a list of all packages in the following format:
|
||||
```json
|
||||
[
|
||||
{
|
||||
"releases": {
|
||||
"latest": "0.6.0"
|
||||
},
|
||||
"name": "thedaniel-test-package",
|
||||
"repository": {
|
||||
"type": "git",
|
||||
"url": "https://github.com/thedaniel/test-package"
|
||||
}
|
||||
},
|
||||
...
|
||||
]
|
||||
```
|
||||
|
||||
Results are paginated 30 at a time, and links to the next and last pages are
|
||||
provided in the `Link` header:
|
||||
|
||||
```
|
||||
Link: <https://www.atom.io/api/packages?page=1>; rel="self",
|
||||
<https://www.atom.io/api/packages?page=41>; rel="last",
|
||||
<https://www.atom.io/api/packages?page=2>; rel="next"
|
||||
```
|
||||
|
||||
By default, results are sorted by download count, descending.
|
||||
|
||||
### Searching packages
|
||||
|
||||
#### GET /api/packages/search
|
||||
|
||||
Parameters:
|
||||
|
||||
- **q** (required) - Search query
|
||||
- **page** (optional)
|
||||
- **sort** (optional) - One of `downloads`, `created_at`, `updated_at`, `stars`. Defaults to the relevance of the search query.
|
||||
- **direction** (optional) - `asc` or `desc`. Defaults to `desc`.
|
||||
|
||||
Returns results in the same format as [listing packages](#listing-packages).
|
||||
|
||||
### Showing package details
|
||||
|
||||
#### GET /api/packages/:package_name
|
||||
|
||||
Returns package details and versions for a single package
|
||||
|
||||
Parameters:
|
||||
|
||||
- **engine** (optional) - Only show packages with versions compatible with this
|
||||
Atom version. Must be valid [SemVer](http://semver.org).
|
||||
|
||||
Returns:
|
||||
|
||||
```json
|
||||
{
|
||||
"releases": {
|
||||
"latest": "0.6.0"
|
||||
},
|
||||
"name": "thedaniel-test-package",
|
||||
"repository": {
|
||||
"type": "git",
|
||||
"url": "https://github.com/thedaniel/test-package"
|
||||
},
|
||||
"versions": [
|
||||
(see single version output below)
|
||||
...,
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Creating a package
|
||||
|
||||
#### POST /api/packages
|
||||
|
||||
Create a new package; requires authentication.
|
||||
|
||||
The name and version will be fetched from the `package.json`
|
||||
file in the specified repository. The authenticating user *must* have access
|
||||
to the indicated repository.
|
||||
|
||||
When a package is created, a release hook is registered with GitHub for package
|
||||
version creation.
|
||||
|
||||
Parameters:
|
||||
|
||||
- **repository** - String. The repository containing the plugin, in the form "owner/repo"
|
||||
|
||||
Returns:
|
||||
|
||||
- **201** - Successfully created, returns created package.
|
||||
- **400** - Repository is inaccessible, nonexistent, not an atom package. Possible
|
||||
error messages include:
|
||||
- That repo does not exist, isn't an atom package, or atombot does not have access
|
||||
- The package.json at owner/repo isn't valid
|
||||
- **409** - A package by that name already exists
|
||||
|
||||
### Deleting a package
|
||||
|
||||
#### DELETE /api/packages/:package_name
|
||||
|
||||
Delete a package; requires authentication.
|
||||
|
||||
Returns:
|
||||
|
||||
- **204** - Success
|
||||
- **400** - Repository is inaccessible
|
||||
- **401** - Unauthorized
|
||||
|
||||
### Renaming a package
|
||||
|
||||
Packages are renamed by publishing a new version with the name changed in `package.json`
|
||||
See [Creating a new package version](#creating-a-new-package-version) for details.
|
||||
|
||||
Requests made to the previous name will forward to the new name.
|
||||
|
||||
### Package Versions
|
||||
|
||||
#### GET /api/packages/:package_name/versions/:version_name
|
||||
|
||||
Returns `package.json` with `dist` key added for e.g. tarball download:
|
||||
|
||||
```json
|
||||
{
|
||||
"bugs": {
|
||||
"url": "https://github.com/thedaniel/test-package/issues"
|
||||
},
|
||||
"dependencies": {
|
||||
"async": "~0.2.6",
|
||||
"pegjs": "~0.7.0",
|
||||
"season": "~0.13.0"
|
||||
},
|
||||
"description": "Expand snippets matching the current prefix with `tab`.",
|
||||
"dist": {
|
||||
"tarball": "https://codeload.github.com/..."
|
||||
},
|
||||
"engines": {
|
||||
"atom": "*"
|
||||
},
|
||||
"main": "./lib/snippets",
|
||||
"name": "thedaniel-test-package",
|
||||
"publishConfig": {
|
||||
"registry": "https://...",
|
||||
},
|
||||
"repository": {
|
||||
"type": "git",
|
||||
"url": "https://github.com/thedaniel/test-package.git"
|
||||
},
|
||||
"version": "0.6.0"
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
### Creating a new package version
|
||||
|
||||
#### POST /api/packages/:package_name/versions
|
||||
|
||||
Creates a new package version from a git tag; requires authentication. If `rename`
|
||||
is not `true`, the `name` field in `package.json` *must* match the current package
|
||||
name.
|
||||
|
||||
#### Parameters
|
||||
|
||||
- **tag** - A git tag for the version you'd like to create. It's important to note
|
||||
that the version name will not be taken from the tag, but from the `version`
|
||||
key in the `package.json` file at that ref. The authenticating user *must* have
|
||||
access to the package repository.
|
||||
- **rename** - Boolean indicating whether this version contains a new name for the package.
|
||||
|
||||
#### Returns
|
||||
|
||||
- **201** - Successfully created. Returns created version.
|
||||
- **400** - Git tag not found / Repository inaccessible / package.json invalid
|
||||
- **409** - Version exists
|
||||
|
||||
### Deleting a version
|
||||
|
||||
#### DELETE /api/packages/:package_name/versions/:version_name
|
||||
|
||||
Deletes a package version; requires authentication.
|
||||
|
||||
Note that a version cannot be republished with a different tag if it is deleted.
|
||||
If you need to delete the latest version of a package for e.g. security reasons,
|
||||
you'll need to increment the version when republishing.
|
||||
|
||||
Returns 204 No Content
|
||||
|
||||
|
||||
## Stars
|
||||
|
||||
### Listing user stars
|
||||
|
||||
#### GET /api/users/:login/stars
|
||||
|
||||
List a user's starred packages.
|
||||
|
||||
Return value is similar to **GET /api/packages**
|
||||
|
||||
#### GET /api/stars
|
||||
|
||||
List the authenticated user's starred packages; requires authentication.
|
||||
|
||||
Return value is similar to **GET /api/packages**
|
||||
|
||||
### Starring a package
|
||||
|
||||
#### POST /api/packages/:name/star
|
||||
|
||||
Star a package; requires authentication.
|
||||
|
||||
Returns a package.
|
||||
|
||||
### Unstarring a package
|
||||
|
||||
#### DELETE /api/packages/:name/star
|
||||
|
||||
Unstar a package; requires authentication.
|
||||
|
||||
Returns 204 No Content.
|
||||
|
||||
### Listing a package's stargazers
|
||||
|
||||
#### GET /api/packages/:name/stargazers
|
||||
|
||||
List the users that have starred a package.
|
||||
|
||||
Returns a list of user objects:
|
||||
|
||||
```json
|
||||
[
|
||||
{"login":"aperson"},
|
||||
{"login":"anotherperson"},
|
||||
]
|
||||
```
|
||||
|
||||
## Atom updates
|
||||
|
||||
### Listing Atom updates
|
||||
|
||||
#### GET /api/updates
|
||||
|
||||
Atom update feed, following the format expected by [Squirrel](https://github.com/Squirrel/).
|
||||
|
||||
Returns:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "0.96.0",
|
||||
"notes": "[HTML release notes]",
|
||||
"pub_date": "2014-05-19T15:52:06.000Z",
|
||||
"url": "https://www.atom.io/api/updates/download"
|
||||
}
|
||||
```
|
||||
|
|
@ -1,22 +0,0 @@
|
|||
# FreeBSD
|
||||
|
||||
FreeBSD -RELEASE 64-bit is the recommended platform.
|
||||
|
||||
## Requirements
|
||||
|
||||
* FreeBSD
|
||||
* `pkg install node`
|
||||
* `pkg install npm`
|
||||
* `pkg install libgnome-keyring`
|
||||
* `npm config set python /usr/local/bin/python2 -g` to ensure that gyp uses Python 2
|
||||
|
||||
## Instructions
|
||||
|
||||
```sh
|
||||
git clone https://github.com/nylas/edgehill
|
||||
cd edgehill
|
||||
script/build # Creates application at $TMPDIR/nylas-build/Nylas
|
||||
sudo script/grunt install # Installs command to /usr/local/bin/nylas
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
|
@ -1,159 +0,0 @@
|
|||
# Linux
|
||||
|
||||
Ubuntu LTS 12.04 64-bit is the recommended platform.
|
||||
|
||||
## Requirements
|
||||
|
||||
* OS with 64-bit or 32-bit architecture
|
||||
* C++ toolchain
|
||||
* [Git](http://git-scm.com/)
|
||||
* [Node.js](http://nodejs.org/download/) v0.10.x
|
||||
* [npm](https://www.npmjs.com/) v1.4.x (bundled with Node.js)
|
||||
* `npm -v` to check the version.
|
||||
* `npm config set python /usr/bin/python2 -g` to ensure that gyp uses python2.
|
||||
* You might need to run this command as `sudo`, depending on how you have set up [npm](https://github.com/joyent/node/wiki/Installing-Node.js-via-package-manager#ubuntu-mint-elementary-os).
|
||||
* development headers for [GNOME Keyring](https://wiki.gnome.org/Projects/GnomeKeyring)
|
||||
|
||||
### Ubuntu / Debian
|
||||
|
||||
* `sudo apt-get install build-essential git libgnome-keyring-dev fakeroot`
|
||||
* Instructions for [Node.js](https://github.com/joyent/node/wiki/Installing-Node.js-via-package-manager#ubuntu-mint-elementary-os).
|
||||
|
||||
### Fedora / CentOS / RHEL
|
||||
|
||||
* `sudo yum --assumeyes install make gcc gcc-c++ glibc-devel git-core libgnome-keyring-devel rpmdevtools`
|
||||
* Instructions for [Node.js](https://github.com/joyent/node/wiki/Installing-Node.js-via-package-manager#fedora).
|
||||
|
||||
### Arch
|
||||
|
||||
* `sudo pacman -S gconf base-devel git nodejs libgnome-keyring python2`
|
||||
* `export PYTHON=/usr/bin/python2` before building Atom.
|
||||
|
||||
### Slackware
|
||||
|
||||
* `sbopkg -k -i node -i atom`
|
||||
|
||||
### openSUSE
|
||||
|
||||
* `sudo zypper install nodejs make gcc gcc-c++ glibc-devel git-core libgnome-keyring-devel rpmdevtools`
|
||||
|
||||
## Instructions
|
||||
|
||||
If you have problems with permissions don't forget to prefix with `sudo`
|
||||
|
||||
1. Clone the Nylas Mail repository:
|
||||
|
||||
```sh
|
||||
git clone https://github.com/nylas/edgehill
|
||||
cd edgehill
|
||||
```
|
||||
|
||||
2. Checkout the latest Nylas Mail release:
|
||||
|
||||
```sh
|
||||
git fetch -p
|
||||
git checkout $(git describe --tags `git rev-list --tags --max-count=1`)
|
||||
```
|
||||
|
||||
3. Build Nylas Mail:
|
||||
|
||||
```sh
|
||||
script/build
|
||||
```
|
||||
|
||||
This will create the Nylas Mail application at `$TMPDIR/nylas-build/Nylas`.
|
||||
|
||||
4. Install the `edgehill` and `apm` commands to `/usr/local/bin` by executing:
|
||||
|
||||
```sh
|
||||
sudo script/grunt install
|
||||
```
|
||||
|
||||
To use the newly installed Nylas Mail, quit and restart all running Nylas Mail instances.
|
||||
|
||||
5. *Optionally*, you may generate distributable packages of Nylas Mail at `$TMPDIR/nylas-build`. Currenty, `.deb` and `.rpm` package types are supported. To create a `.deb` package run:
|
||||
|
||||
```sh
|
||||
script/grunt mkdeb
|
||||
```
|
||||
|
||||
To create an `.rpm` package run
|
||||
|
||||
```sh
|
||||
script/grunt mkrpm
|
||||
```
|
||||
|
||||
## Advanced Options
|
||||
|
||||
### Custom install directory
|
||||
|
||||
```sh
|
||||
sudo script/grunt install --install-dir /install/edgehill/here
|
||||
```
|
||||
|
||||
### Custom build directory
|
||||
|
||||
```sh
|
||||
script/build --build-dir /build/edgehill/here
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### TypeError: Unable to watch path
|
||||
|
||||
If you get following error with a big traceback right after Nylas Mail starts:
|
||||
|
||||
```
|
||||
TypeError: Unable to watch path
|
||||
```
|
||||
|
||||
you have to increase number of watched files by inotify. For testing if
|
||||
this is the reason for this error you can issue
|
||||
|
||||
```sh
|
||||
sudo sysctl fs.inotify.max_user_watches=32768
|
||||
```
|
||||
|
||||
and restart Nylas Mail. If Nylas Mail now works fine, you can make this setting permanent:
|
||||
|
||||
```sh
|
||||
echo 32768 | sudo tee -a /proc/sys/fs/inotify/max_user_watches
|
||||
```
|
||||
|
||||
See also https://github.com/atom/atom/issues/2082.
|
||||
|
||||
### /usr/bin/env: node: No such file or directory
|
||||
|
||||
If you get this notice when attempting to `script/build`, you either do not
|
||||
have Node.js installed, or node isn't identified as Node.js on your machine.
|
||||
If it's the latter, entering `sudo ln -s /usr/bin/nodejs /usr/bin/node` into
|
||||
your terminal may fix the issue.
|
||||
|
||||
#### You can also use Alternatives
|
||||
|
||||
On some variants (mostly Debian based distros) it's preferable for you to use
|
||||
Alternatives so that changes to the binary paths can be fixed or altered easily:
|
||||
|
||||
```sh
|
||||
sudo update-alternatives --install /usr/bin/node node /usr/bin/nodejs 1 --slave /usr/bin/js js /usr/bin/nodejs
|
||||
```
|
||||
|
||||
### AttributeError: 'module' object has no attribute 'script_main'
|
||||
|
||||
If you get following error with a big traceback while building Nylas Mail:
|
||||
|
||||
```
|
||||
sys.exit(gyp.script_main()) AttributeError: 'module' object has no attribute 'script_main' gyp ERR!
|
||||
```
|
||||
|
||||
you need to uninstall the system version of gyp.
|
||||
|
||||
On Fedora you would do the following:
|
||||
|
||||
```sh
|
||||
sudo yum remove gyp
|
||||
```
|
||||
|
||||
### Linux build error reports in atom/atom
|
||||
* Use [this search](https://github.com/atom/atom/search?q=label%3Abuild-error+label%3Alinux&type=Issues)
|
||||
to get a list of reports about build errors on Linux.
|
||||
|
|
@ -1,20 +0,0 @@
|
|||
# OS X
|
||||
|
||||
## Requirements
|
||||
|
||||
* OS X 10.8 or later
|
||||
* [node.js](http://nodejs.org/download/) v0.10.x
|
||||
* Command Line Tools for [Xcode](https://developer.apple.com/xcode/downloads/) (run `xcode-select --install` to install)
|
||||
|
||||
## Instructions
|
||||
|
||||
```sh
|
||||
git clone git@github.com:nylas/edgehill.git
|
||||
cd edgehill
|
||||
script/build # Creates application at /Applications/Edgehill.app
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### OSX build error reports in atom/atom
|
||||
* Use [this search](https://github.com/atom/atom/search?q=label%3Abuild-error+label%3Aos-x&type=Issues) to get a list of reports about build errors on OSX.
|
||||
|
|
@ -1,89 +0,0 @@
|
|||
# Windows
|
||||
|
||||
## Requirements
|
||||
|
||||
### On Windows 7
|
||||
* [Visual C++ 2010 Express](http://www.visualstudio.com/en-us/downloads/download-visual-studio-vs#DownloadFamilies_4)
|
||||
* [Visual Studio 2010 Service Pack 1](http://www.microsoft.com/en-us/download/details.aspx?id=23691)
|
||||
* [node.js](http://nodejs.org/download/) v0.10.x
|
||||
* For 64-bit builds of node and native modules you **must** have the
|
||||
[Windows 7 64-bit SDK](http://www.microsoft.com/en-us/download/details.aspx?id=8279).
|
||||
You may also need the [compiler update for the Windows SDK 7.1](http://www.microsoft.com/en-us/download/details.aspx?id=4422)
|
||||
* [Python](https://www.python.org/downloads/) v2.7.
|
||||
* The python.exe must be available at `%SystemDrive%\Python27\python.exe`.
|
||||
If it is installed elsewhere, you can create a symbolic link to the
|
||||
directory containing the python.exe using:
|
||||
`mklink /d %SystemDrive%\Python27 D:\elsewhere\Python27`
|
||||
* [GitHub for Windows](http://windows.github.com/)
|
||||
|
||||
### On Windows 8
|
||||
* [Visual Studio Express 2013 for Windows Desktop](http://www.visualstudio.com/en-us/downloads/download-visual-studio-vs#DownloadFamilies_2)
|
||||
* [node.js](http://nodejs.org/download/) v0.10.x
|
||||
* [Python](https://www.python.org/downloads/) v2.7.x (required by [node-gyp](https://github.com/TooTallNate/node-gyp))
|
||||
* [GitHub for Windows](http://windows.github.com/)
|
||||
|
||||
## Instructions
|
||||
|
||||
```bat
|
||||
# Use the `Git Shell` app which was installed by GitHub for Windows. Also Make
|
||||
# sure you have logged into the GitHub for Windows GUI App.
|
||||
cd C:\
|
||||
git clone https://github.com/nylas/edgehill/
|
||||
cd edgehill
|
||||
script/build # Creates application in the `Program Files` directory
|
||||
```
|
||||
|
||||
## Why do I have to use GitHub for Windows?
|
||||
|
||||
You don't. You can use your existing Git! GitHub for Windows's Git Shell is just
|
||||
easier to set up.
|
||||
|
||||
If you _prefer_ using your existing Git installation, make sure git's cmd directory is in your PATH env variable (e.g. `C:\Program Files (x86)\Git\cmd`) before you open your powershell or command window.
|
||||
Note that you may have to open your command window as administrator. For powershell that doesn't seem to always be the case, though.
|
||||
|
||||
If none of this works, do install Github for Windows and use its Git shell. Makes life easier.
|
||||
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Errors
|
||||
* `node is not recognized`
|
||||
|
||||
* If you just installed node you need to restart your computer before node is
|
||||
available on your Path.
|
||||
|
||||
|
||||
* `script/build` outputs only the Node and Python versions before returning
|
||||
|
||||
* Try moving the repository to `C:\atom`. Most likely, the path is too long.
|
||||
See [issue #2200](https://github.com/atom/atom/issues/2200).
|
||||
|
||||
* `error MSB4025: The project file could not be loaded. Invalid character in the given encoding.`
|
||||
|
||||
* These can occur because your home directory (`%USERPROFILE%`) has non-ASCII
|
||||
characters in it. This is a bug in [gyp](https://code.google.com/p/gyp/)
|
||||
which is used to build native node modules and there is no known workaround.
|
||||
* https://github.com/TooTallNate/node-gyp/issues/297
|
||||
* https://code.google.com/p/gyp/issues/detail?id=393
|
||||
|
||||
* `script/build` stops at installing runas with 'Failed at the runas@0.5.4 install script.'
|
||||
|
||||
See the next item.
|
||||
|
||||
* `error MSB8020: The build tools for Visual Studio 2010 (Platform Toolset = 'v100') cannot be found.`
|
||||
|
||||
* If you're building atom with Visual Studio 2013 try executing the following
|
||||
command in your Git shell and then re-run `script/build`:
|
||||
|
||||
```
|
||||
$env:GYP_MSVS_VERSION=2013
|
||||
```
|
||||
|
||||
* Other `node-gyp` errors on first build attempt, even though the right node and python versions are installed.
|
||||
* Do try the build command one more time, as experience shows it often works on second try in many of these cases.
|
||||
|
||||
|
||||
### Windows build error reports in atom/atom
|
||||
* If all fails, use [this search](https://github.com/atom/atom/search?q=label%3Abuild-error+label%3Awindows&type=Issues) to get a list of reports about build errors on Windows, and see if yours has already been reported.
|
||||
|
||||
* If it hasn't, please open a new issue with your Windows version 32/64bit and a print/screenshot of your build output, incl. the node and python versions.
|
||||
|
|
@ -1,54 +0,0 @@
|
|||
# Contributing to Official Atom Packages
|
||||
|
||||
If you think you know which package is causing the issue you are reporting, feel
|
||||
free to open up the issue in that specific repository instead. When in doubt
|
||||
just open the issue here but be aware that it may get closed here and reopened
|
||||
in the proper package's repository.
|
||||
|
||||
## Hacking on Packages
|
||||
|
||||
### Cloning
|
||||
|
||||
The first step is creating your own clone.
|
||||
|
||||
For example, if you want to make changes to the `tree-view` package, fork the repo on your github account, then clone it:
|
||||
|
||||
```
|
||||
> git clone git@github.com:your-username/tree-view.git
|
||||
```
|
||||
|
||||
Next install all the dependencies:
|
||||
|
||||
```
|
||||
> cd tree-view
|
||||
> apm install
|
||||
Installing modules ✓
|
||||
```
|
||||
|
||||
Now you can link it to development mode so when you run an Atom window with `atom --dev`, you will use your fork instead of the built in package:
|
||||
|
||||
```
|
||||
> apm link -d
|
||||
```
|
||||
|
||||
### Running in Development Mode
|
||||
|
||||
Editing a package in Atom is a bit of a circular experience: you're using Atom
|
||||
to modify itself. What happens if you temporarily break something? You don't
|
||||
want the version of Atom you're using to edit to become useless in the process.
|
||||
For this reason, you'll only want to load packages in **development mode** while
|
||||
you are working on them. You'll perform your editing in **stable mode**, only
|
||||
switching to development mode to test your changes.
|
||||
|
||||
To open a development mode window, use the "Application: Open Dev" command,
|
||||
which is normally bound to `cmd-shift-o`. You can also run dev mode from the
|
||||
command line with `atom --dev`.
|
||||
|
||||
To load your package in development mode, create a symlink to it in
|
||||
`~/.atom/dev/packages`. This occurs automatically when you clone the package
|
||||
with `apm develop`. You can also run `apm link --dev` and `apm unlink --dev`
|
||||
from the package directory to create and remove dev-mode symlinks.
|
||||
|
||||
### Installing Dependencies
|
||||
|
||||
You'll want to keep dependencies up to date by running `apm update` after pulling any upstream changes.
|
||||
|
|
@ -1 +0,0 @@
|
|||
../CONTRIBUTING.md
|
||||
|
|
@ -1,52 +0,0 @@
|
|||
## Converting a TextMate Bundle
|
||||
|
||||
This guide will show you how to convert a [TextMate][TextMate] bundle to an
|
||||
Atom package.
|
||||
|
||||
Converting a TextMate bundle will allow you to use its editor preferences,
|
||||
snippets, and colorization inside Atom.
|
||||
|
||||
### Install apm
|
||||
|
||||
The `apm` command line utility that ships with Atom supports converting
|
||||
a TextMate bundle to an Atom package.
|
||||
|
||||
Check that you have `apm` installed by running the following command in your
|
||||
terminal:
|
||||
|
||||
```sh
|
||||
apm help init
|
||||
```
|
||||
|
||||
You should see a message print out with details about the `apm init` command.
|
||||
|
||||
If you do not, launch Atom and run the _Atom > Install Shell Commands_ menu
|
||||
to install the `apm` and `atom` commands.
|
||||
|
||||
### Convert the Package
|
||||
|
||||
Let's convert the TextMate bundle for the [R][R] programming language. You can find other existing TextMate bundles [here][TextMateOrg].
|
||||
|
||||
You can convert the R bundle with the following command:
|
||||
|
||||
```sh
|
||||
apm init --package ~/.atom/packages/language-r --convert https://github.com/textmate/r.tmbundle
|
||||
```
|
||||
|
||||
You can now browse to `~/.atom/packages/language-r` to see the converted bundle.
|
||||
|
||||
:tada: Your new package is now ready to use, launch Atom and open a `.r` file in
|
||||
the editor to see it in action!
|
||||
|
||||
### Further Reading
|
||||
|
||||
* Check out [Publishing a Package](publishing-a-package.html) for more information
|
||||
on publishing the package you just created to [atom.io][atomio].
|
||||
|
||||
[atomio]: https://atom.io
|
||||
[CSS]: https://en.wikipedia.org/wiki/Cascading_Style_Sheets
|
||||
[Less]: http://lesscss.org
|
||||
[plist]: https://en.wikipedia.org/wiki/Property_list
|
||||
[R]: https://en.wikipedia.org/wiki/R_(programming_language)
|
||||
[TextMate]: http://macromates.com
|
||||
[TextMateOrg]: https://github.com/textmate
|
||||
|
|
@ -1,68 +0,0 @@
|
|||
## Converting a TextMate Theme
|
||||
|
||||
This guide will show you how to convert a [TextMate][TextMate] theme to an Atom
|
||||
theme.
|
||||
|
||||
### Differences
|
||||
|
||||
TextMate themes use [plist][plist] files while Atom themes use [CSS][CSS] or
|
||||
[Less][Less] to style the UI and syntax in the editor.
|
||||
|
||||
The utility that converts the theme first parses the theme's plist file and
|
||||
then creates comparable CSS rules and properties that will style Atom similarly.
|
||||
|
||||
### Install apm
|
||||
|
||||
The `apm` command line utility that ships with Atom supports converting
|
||||
a TextMate theme to an Atom theme.
|
||||
|
||||
Check that you have `apm` installed by running the following command in your
|
||||
terminal:
|
||||
|
||||
```sh
|
||||
apm help init
|
||||
```
|
||||
|
||||
You should see a message print out with details about the `apm init` command.
|
||||
|
||||
If you do not, launch Atom and run the _Atom > Install Shell Commands_ menu
|
||||
to install the `apm` and `atom` commands.
|
||||
|
||||
You can now run `apm help init` to see all the options for initializing new
|
||||
packages and themes.
|
||||
|
||||
### Convert the Theme
|
||||
|
||||
Download the theme you wish to convert, you can browse existing TextMate themes
|
||||
[here][TextMateThemes].
|
||||
|
||||
Now, let's say you've downloaded the theme to `~/Downloads/MyTheme.tmTheme`,
|
||||
you can convert the theme with the following command:
|
||||
|
||||
```sh
|
||||
apm init --theme ~/.atom/packages/my-theme --convert ~/Downloads/MyTheme.tmTheme
|
||||
```
|
||||
|
||||
You can browse to `~/.atom/packages/my-theme` to see the converted theme.
|
||||
|
||||
### Activate the Theme
|
||||
|
||||
Now that your theme is installed to `~/.atom/packages` you can enable it
|
||||
by launching Atom and selecting the _Atom > Preferences..._ menu.
|
||||
|
||||
Select the _Themes_ link on the left side and choose _My Theme_ from the
|
||||
__Syntax Theme__ dropdown menu to enable your new theme.
|
||||
|
||||
:tada: Your theme is now enabled, open an editor to see it in action!
|
||||
|
||||
### Further Reading
|
||||
|
||||
* Check out [Publishing a Package](publishing-a-package.html) for more information
|
||||
on publishing the theme you just created to [atom.io][atomio].
|
||||
|
||||
[atomio]: https://atom.io
|
||||
[CSS]: https://en.wikipedia.org/wiki/Cascading_Style_Sheets
|
||||
[Less]: http://lesscss.org
|
||||
[plist]: https://en.wikipedia.org/wiki/Property_list
|
||||
[TextMate]: http://macromates.com
|
||||
[TextMateThemes]: http://wiki.macromates.com/Themes/UserSubmittedThemes
|
||||
|
|
@ -1,515 +0,0 @@
|
|||
# Creating Packages
|
||||
|
||||
Packages are at the core of Atom. Nearly everything outside of the main editor
|
||||
is handled by a package. That includes "core" pieces like the [file tree][file-tree],
|
||||
[status bar][status-bar], [syntax highlighting][cs-syntax], and more.
|
||||
|
||||
A package can contain a variety of different resource types to change Atom's
|
||||
behavior. The basic package layout is as follows:
|
||||
|
||||
```text
|
||||
my-package/
|
||||
grammars/
|
||||
keymaps/
|
||||
lib/
|
||||
menus/
|
||||
spec/
|
||||
snippets/
|
||||
styles/
|
||||
index.coffee
|
||||
package.json
|
||||
```
|
||||
|
||||
Not every package will have (or need) all of these directories.
|
||||
|
||||
We have [a tutorial on creating your first package][first-package].
|
||||
|
||||
There are also guides for converting [TextMate bundles][convert-bundle] and
|
||||
[TextMate themes][convert-theme] so they work in Atom.
|
||||
|
||||
## package.json
|
||||
|
||||
Similar to [npm packages][npm], Atom packages 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][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.
|
||||
- `styles` (**Optional**): an Array of Strings identifying the order of the
|
||||
style sheets your package needs to load. If not specified, style sheets in the
|
||||
_styles_ 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.
|
||||
- `menus`(**Optional**): an Array of Strings identifying the order of
|
||||
the menu mappings your package needs to load. If not specified, mappings
|
||||
in the _menus_ 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.
|
||||
- `activationCommands` (**Optional**): an Array of Strings identifying commands that
|
||||
trigger your package's activation. You can delay the loading of your package
|
||||
until one of these events is triggered.
|
||||
- `providedServices` (**Optional**): an Object describing the services that your
|
||||
package provides, which can be used by other packages. The keys of this object
|
||||
are the names of the services, and the values are Objects with the following
|
||||
keys:
|
||||
- `description` (**Optional**) a String describing the service
|
||||
- `versions` (**Required**) an Object whose keys are Semver version strings,
|
||||
and whose values are names of methods in your package's top-level module
|
||||
that return a value implementing the service.
|
||||
- `consumedServices` (**Optional**): an Object describing the services that your
|
||||
package uses, which can be provided by other packages. The keys of this object
|
||||
are the names of the services, and the values are Objects with the following
|
||||
keys:
|
||||
- `versions` (**Required**) an Object whose keys are Semver version ranges
|
||||
and whose values are names of methods in your package's top-level module
|
||||
that are called with values implementing the service.
|
||||
|
||||
## 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(state)`: This **required** method is called when your
|
||||
package is activated. It is passed the state data from the last time the window
|
||||
was serialized if 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, or when your package is being updated or disabled. If your package is
|
||||
watching any files, holding external resources, providing commands or subscribing
|
||||
to events, release them here.
|
||||
|
||||
### Simple Package Code
|
||||
|
||||
Your directory would look like this:
|
||||
|
||||
```text
|
||||
my-package/
|
||||
package.json
|
||||
index.coffee
|
||||
lib/
|
||||
my-package.coffee
|
||||
```
|
||||
|
||||
`index.coffee` might be:
|
||||
```coffeescript
|
||||
module.exports = require "./lib/my-package"
|
||||
```
|
||||
|
||||
`my-package/my-package.coffee` might start:
|
||||
```coffeescript
|
||||
module.exports =
|
||||
activate: (state) -> # ...
|
||||
deactivate: -> # ...
|
||||
serialize: -> # ...
|
||||
```
|
||||
|
||||
Beyond this simple contract, your package has access to [Atom's API][api]. Be aware
|
||||
that the Atom 1.0 API is mostly frozen. Refer to the API documentation for what
|
||||
is public. That said, 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.
|
||||
|
||||
## Style Sheets
|
||||
|
||||
Style sheets for your package should be placed in the _styles_ directory.
|
||||
Any style sheets in this directory will be loaded and attached to the DOM when
|
||||
your package is activated. Style sheets can be written as CSS or [Less], but
|
||||
Less is recommended.
|
||||
|
||||
Ideally, you won't need much in the way of styling. We've provided a standard
|
||||
set of components which define both the colors and UI elements for any package
|
||||
that fits into Atom seamlessly. You can view all of Atom's UI components by
|
||||
opening the styleguide: open the command palette (`cmd-shift-P`) and search for
|
||||
_styleguide_, or just type `cmd-ctrl-shift-G`.
|
||||
|
||||
If you _do_ need special styling, try to keep only structural styles in the
|
||||
package style sheets. If you _must_ specify colors and sizing, these should be
|
||||
taken from the active theme's [ui-variables.less][ui-variables]. For more
|
||||
information, see the [theme variables docs][theme-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 style sheets
|
||||
by name to specify a loading order; otherwise, style sheets are loaded
|
||||
alphabetically.
|
||||
|
||||
## Keymaps
|
||||
|
||||
It's recommended that you provide key bindings for commonly used actions for
|
||||
your extension, especially if you're also adding a new command:
|
||||
|
||||
```coffeescript
|
||||
'.tree-view-scroller':
|
||||
'ctrl-V': 'changer:magic'
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
|
||||
Keybindings are executed by determining which element the keypress occurred on.
|
||||
In the example above, `changer:magic` command is executed when pressing `ctrl-V`
|
||||
on the `.tree-view-scroller` element.
|
||||
|
||||
See the [main keymaps documentation][keymaps] for more detailed information on
|
||||
how keymaps work.
|
||||
|
||||
## Menus
|
||||
|
||||
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.
|
||||
|
||||
### Application Menu
|
||||
|
||||
It's recommended that you create an application menu item for common actions
|
||||
with your package that aren't tied to a specific element:
|
||||
|
||||
```coffeescript
|
||||
'menu': [
|
||||
{
|
||||
'label': 'Packages'
|
||||
'submenu': [
|
||||
{
|
||||
'label': 'My Package'
|
||||
'submenu': [
|
||||
{
|
||||
'label': 'Toggle'
|
||||
'command': 'my-package:toggle'
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
To add your own item to the application menu, simply create a top level `menu`
|
||||
key in any menu configuration file in _menus_. This can be a JSON or [CSON]
|
||||
file.
|
||||
|
||||
The menu templates you specify are merged with all other templates provided
|
||||
by other packages in the order which they were loaded.
|
||||
|
||||
### Context Menu
|
||||
|
||||
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:
|
||||
|
||||
```coffeescript
|
||||
'context-menu':
|
||||
'.tree-view': [
|
||||
{label: 'Add file', command: 'tree-view:add-file'}
|
||||
]
|
||||
'atom-workspace': [
|
||||
{label: 'Inspect Element', command: 'core:inspect'}
|
||||
]
|
||||
```
|
||||
|
||||
To add your own item to the application menu simply create a top level
|
||||
`context-menu` key in any menu configuration file in _menus_. This can be a
|
||||
JSON or [CSON] file.
|
||||
|
||||
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.
|
||||
|
||||
You can also add separators and submenus to your context menus. To add a
|
||||
submenu, provide a `submenu` key instead of a command. To add a separator, add
|
||||
an item with a single `type: 'separator'` key/value pair.
|
||||
|
||||
```coffeescript
|
||||
'context-menu':
|
||||
'atom-workspace': [
|
||||
{
|
||||
label: 'Text'
|
||||
submenu: [
|
||||
{label: 'Inspect Element', command: 'core:inspect'}
|
||||
{type: 'separator'}
|
||||
{label: 'Selector All', command: 'core:select-all'}
|
||||
{type: 'separator'}
|
||||
{label: 'Deleted Selected Text', command: 'core:delete'}
|
||||
]
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
## Snippets
|
||||
|
||||
An extension can supply language snippets in the _snippets_ directory which
|
||||
allows the user to enter repetitive text quickly:
|
||||
|
||||
```coffeescript
|
||||
".source.coffee .specs":
|
||||
"Expect":
|
||||
prefix: "ex"
|
||||
body: "expect($1).to$2"
|
||||
"Describe":
|
||||
prefix: "de"
|
||||
body: """
|
||||
describe "${1:description}", ->
|
||||
${2:body}
|
||||
"""
|
||||
```
|
||||
|
||||
A snippets file contains scope selectors at its top level (`.source.coffee
|
||||
.spec`). Each scope selector contains a hash of snippets keyed by their name
|
||||
(`Expect`, `Describe`). Each snippet also specifies a `prefix` and a `body` key.
|
||||
The `prefix` represents the first few letters to type before hitting the `tab`
|
||||
key to autocomplete. The `body` defines the autofilled text. You can use
|
||||
placeholders like `$1`, `$2`, to indicate regions in the body the user can
|
||||
navigate to every time they hit `tab`.
|
||||
|
||||
All files in the directory are automatically loaded, unless the _package.json_
|
||||
supplies a `snippets` key. As with all scoped items, snippets loaded later take
|
||||
precedence over earlier snippets when two snippets match a scope with the same
|
||||
specificity.
|
||||
|
||||
## Language Grammars
|
||||
|
||||
If you're developing a new language grammar, you'll want to place your file in
|
||||
the _grammars_ directory. Each grammar is a pairing of two keys, `match` and
|
||||
`captures`. `match` is a regular expression identifying the pattern to
|
||||
highlight, while `captures` is an object representing what to do with each
|
||||
matching group.
|
||||
|
||||
For example:
|
||||
|
||||
|
||||
```coffeescript
|
||||
{
|
||||
'match': '(?:^|\\s)(__[^_]+__)'
|
||||
'captures':
|
||||
'1': 'name': 'markup.bold.gfm'
|
||||
}
|
||||
```
|
||||
|
||||
This indicates that the first matching capture (`(__[^_]+__)`) should have the
|
||||
`markup.bold.gfm` token applied to it.
|
||||
|
||||
To capture a single group, simply use the `name` key instead:
|
||||
|
||||
```coffeescript
|
||||
{
|
||||
'match': '^#{1,6}\\s+.+$'
|
||||
'name': 'markup.heading.gfm'
|
||||
}
|
||||
```
|
||||
|
||||
This indicates that Markdown header lines (`#`, `##`, `###`) should be applied
|
||||
with the `markup.heading.gfm` token.
|
||||
|
||||
More information about the significance of these tokens can be found in
|
||||
[section 12.4 of the TextMate Manual][tm-tokens].
|
||||
|
||||
Your grammar should also include a `filetypes` array, which is a list of file
|
||||
extensions your grammar supports:
|
||||
|
||||
```coffeescript
|
||||
'fileTypes': [
|
||||
'markdown'
|
||||
'md'
|
||||
'mkd'
|
||||
'mkdown'
|
||||
'ron'
|
||||
]
|
||||
```
|
||||
|
||||
## Adding Configuration Settings
|
||||
|
||||
You can support config settings in your package that are editable in the
|
||||
settings view. Specify a `config` key in your package main:
|
||||
|
||||
```coffeescript
|
||||
module.exports =
|
||||
# Your config schema!
|
||||
config:
|
||||
someInt:
|
||||
type: 'integer'
|
||||
default: 23
|
||||
minimum: 1
|
||||
activate: (state) -> # ...
|
||||
# ...
|
||||
```
|
||||
|
||||
To define the configuration, we use [json schema][json-schema] which allows you
|
||||
to indicate the type your value should be, its default, etc.
|
||||
|
||||
See the [Config API Docs](https://atom.io/docs/api/latest/Config) for more
|
||||
details specifying your configuration.
|
||||
|
||||
## Interacting With Other Packages Via Services
|
||||
|
||||
Atom packages can interact with each other through versioned APIs called
|
||||
*services*. To provide a service, in your `package.json`, specify one or more
|
||||
version numbers, each paired with the name of a method on your package's main module:
|
||||
|
||||
```json
|
||||
{
|
||||
"providedServices": {
|
||||
"my-service": {
|
||||
"description": "Does a useful thing",
|
||||
"versions": {
|
||||
"1.2.3": "provideMyServiceV1",
|
||||
"2.3.4": "provideMyServiceV2",
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
In your package's main module, implement the methods named above. These methods
|
||||
will be called any time a package is activated that consumes their corresponding
|
||||
service. They should return a value that implements the service's API.
|
||||
|
||||
|
||||
```coffeescript
|
||||
module.exports =
|
||||
activate: -> # ...
|
||||
|
||||
provideMyServiceV1: ->
|
||||
adaptToLegacyAPI(myService)
|
||||
|
||||
provideMyServiceV2: ->
|
||||
myService
|
||||
```
|
||||
|
||||
Similarly, to consume a service, specify one or more [version *ranges*][version-ranges],
|
||||
each paired with the name of a method on the package's main module:
|
||||
|
||||
```json
|
||||
{
|
||||
"consumedServices": {
|
||||
"another-service": {
|
||||
"versions": {
|
||||
"^1.2.3": "consumeAnotherServiceV1",
|
||||
">=2.3.4 <2.5": "consumeAnotherServiceV2",
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
These methods will be called any time a package is activated that *provides* their
|
||||
corresponding service. They will receive the service object as an argument. You
|
||||
will usually need to perform some kind of cleanup in the event that the package
|
||||
providing the service is deactivated. To do this, return a `Disposable` from
|
||||
your service-consuming method:
|
||||
|
||||
```coffeescript
|
||||
{Disposable} = require 'atom'
|
||||
|
||||
module.exports =
|
||||
activate: -> # ...
|
||||
|
||||
consumeAnotherServiceV1: (service) ->
|
||||
useService(adaptServiceFromLegacyAPI(service))
|
||||
new Disposable -> stopUsingService(service)
|
||||
|
||||
consumeAnotherServiceV2: (service) ->
|
||||
useService(service)
|
||||
new Disposable -> stopUsingService(service)
|
||||
```
|
||||
|
||||
## Bundle External Resources
|
||||
|
||||
It's common to ship external resources like images and fonts in the package, to
|
||||
make it easy to reference the resources in HTML or CSS, you can use the `atom`
|
||||
protocol URLs to load resources in the package.
|
||||
|
||||
The URLs should be in the format of
|
||||
`atom://package-name/relative-path-to-package-of-resource`, for example, the
|
||||
`atom://image-view/images/transparent-background.gif` would be equivalent to
|
||||
`~/.atom/packages/image-view/images/transparent-background.gif`.
|
||||
|
||||
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.
|
||||
|
||||
Under the hood, [Jasmine] executes your tests, so you can assume that any DSL
|
||||
available there is also available to your package.
|
||||
|
||||
## Running Tests
|
||||
|
||||
Once you've got your test suite written, you can run it by pressing
|
||||
`cmd-alt-ctrl-p` or via the _Developer > Run Package Specs_ menu.
|
||||
|
||||
You can also use the `apm test` command to run them from the command line. It
|
||||
prints the test output and results to the console and returns the proper status
|
||||
code depending on whether the 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.
|
||||
|
||||
[api]: https://atom.io/docs/api/latest
|
||||
[file-tree]: https://github.com/atom/tree-view
|
||||
[status-bar]: https://github.com/atom/status-bar
|
||||
[cs-syntax]: https://github.com/atom/language-coffee-script
|
||||
[npm]: https://en.wikipedia.org/wiki/Npm_(software)
|
||||
[npm-keys]: https://docs.npmjs.com/files/package.json
|
||||
[git-tag]: http://git-scm.com/book/en/Git-Basics-Tagging
|
||||
[wrap-guide]: https://github.com/atom/wrap-guide/
|
||||
[keymaps]: advanced/keymaps.md
|
||||
[theme-variables]: theme-variables.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]: http://jasmine.github.io
|
||||
[cson]: https://github.com/atom/season
|
||||
[Less]: http://lesscss.org
|
||||
[ui-variables]: https://github.com/atom/atom-dark-ui/blob/master/styles/ui-variables.less
|
||||
[first-package]: your-first-package.html
|
||||
[convert-bundle]: converting-a-text-mate-bundle.html
|
||||
[convert-theme]: converting-a-text-mate-theme.html
|
||||
[json-schema]: http://json-schema.org/
|
||||
[version-ranges]: https://docs.npmjs.com/misc/semver#ranges
|
||||
|
|
@ -1,148 +0,0 @@
|
|||
# Creating a Theme
|
||||
|
||||
Atom's interface is rendered using HTML, and it's styled via [Less] which is 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 supports two types of themes: _UI_ and _syntax_. UI themes style
|
||||
elements such as the tree view, the tabs, drop-down lists, and the status bar.
|
||||
Syntax themes style the code inside the editor.
|
||||
|
||||
Themes can be installed and changed from the settings view which you can open
|
||||
by selecting the _Atom > Preferences..._ menu and navigating to the _Install_
|
||||
section and the _Themes_ section on the left hand side.
|
||||
|
||||
## Getting Started
|
||||
|
||||
Themes are pretty straightforward but it's still helpful to be familiar with
|
||||
a few things before starting:
|
||||
|
||||
* 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].
|
||||
* You may also want to review the concept of a _[package.json]_, too. This file
|
||||
is used to help distribute your theme to Atom users.
|
||||
* Your theme's _package.json_ must contain a `"theme"` key with a value
|
||||
of `"ui"` or `"syntax"` for Atom to recognize and load it as a theme.
|
||||
* You can find existing themes to install or fork on
|
||||
[atom.io][atomio-themes].
|
||||
|
||||
## Creating a Syntax Theme
|
||||
|
||||
Let's create your first theme.
|
||||
|
||||
To get started, hit `cmd-shift-P`, and start typing "Generate Syntax Theme" to
|
||||
generate a new theme package. Select "Generate Syntax Theme," and you'll be
|
||||
asked for the path where your theme will be created. Let's call ours
|
||||
_motif-syntax_. __Tip:__ syntax themes should end with _-syntax_.
|
||||
|
||||
Atom will pop open a new window, showing the _motif-syntax_ theme, with a
|
||||
default set of folders and files created for us. If you open the settings view
|
||||
(`cmd-,`) and navigate to the _Themes_ section on the left, you'll see the
|
||||
_Motif_ theme listed in the _Syntax Theme_ drop-down. Select it from the menu to
|
||||
activate it, now when you open an editor you should see that your new
|
||||
_motif-syntax_ theme in action.
|
||||
|
||||
Open up _styles/colors.less_ to change the various colors variables which
|
||||
have been already been defined. For example, turn `@red` into `#f4c2c1`.
|
||||
|
||||
Then open _styles/base.less_ and modify the various selectors that have
|
||||
been already been defined. These selectors style different parts of code in the
|
||||
editor such as comments, strings and the line numbers in the gutter.
|
||||
|
||||
As an example, let's make the `.gutter` `background-color` into `@red`.
|
||||
|
||||
Reload Atom by pressing `cmd-alt-ctrl-l` to see the changes you made reflected
|
||||
in your Atom window. Pretty neat!
|
||||
|
||||
__Tip:__ You can avoid reloading to see changes you make by opening an atom
|
||||
window in dev mode. To open a Dev Mode Atom window run `atom --dev .` in the
|
||||
terminal, use `cmd-shift-o` or use the _View > Developer > Open in Dev Mode_
|
||||
menu. When you edit your theme, changes will instantly be reflected!
|
||||
|
||||
> Note: It's advised to _not_ specify a `font-family` in your syntax theme because it will override the Font Family field in Atom's settings. If you still like to recommend a font that goes well with your theme, we recommend you do so in your README.
|
||||
|
||||
## Creating an Interface Theme
|
||||
|
||||
Interface themes **must** provide a `ui-variables.less` file which contains all
|
||||
of the variables provided by the [core themes][ui-variables].
|
||||
|
||||
To create an interface UI theme, do the following:
|
||||
|
||||
1. Fork one of the following repositories:
|
||||
* [atom-dark-ui]
|
||||
* [atom-light-ui]
|
||||
2. Clone the forked repository to the local filesystem
|
||||
3. Open a terminal in the forked theme's directory
|
||||
4. Open your new theme in a Dev Mode Atom window run `atom --dev .` in the
|
||||
terminal or use the _View > Developer > Open in Dev Mode_ menu
|
||||
5. Change the name of the theme in the theme's `package.json` file
|
||||
6. Name your theme end with a `-ui`. i.e. `super-white-ui`
|
||||
7. Run `apm link` to symlink your repository to `~/.atom/packages`
|
||||
8. Reload Atom using `cmd-alt-ctrl-L`
|
||||
9. Enable the theme via _UI Theme_ drop-down in the _Themes_ section of the
|
||||
settings view
|
||||
10. Make changes! Since you opened the theme in a Dev Mode window, changes will
|
||||
be instantly reflected in the editor without having to reload.
|
||||
|
||||
## Development workflow
|
||||
|
||||
There are a few of tools to help make theme development faster and easier.
|
||||
|
||||
### Live Reload
|
||||
|
||||
Reloading by hitting `cmd-alt-ctrl-L` after you make changes to your theme is
|
||||
less than ideal. Atom supports [live updating][livereload] of styles on Dev Mode
|
||||
Atom windows.
|
||||
|
||||
To enable a Dev Mode window:
|
||||
|
||||
1. Open your theme directory in a dev window by either going to the
|
||||
__View > Developer > Open in Dev Mode__ menu or by hitting the `cmd-shift-o`
|
||||
shortcut
|
||||
2. Make a change to your theme file and save it. Your change should be
|
||||
immediately applied!
|
||||
|
||||
If you'd like to reload all the styles at any time, you can use the shortcut
|
||||
`cmd-ctrl-shift-r`.
|
||||
|
||||
### Developer Tools
|
||||
|
||||
Atom is based on the Chrome browser, and supports Chrome's Developer Tools. You
|
||||
can open them by selecting the _View > Toggle Developer Tools_ menu, or by
|
||||
using the `cmd-alt-i` shortcut.
|
||||
|
||||
The dev tools allow you to inspect elements and take a look at their CSS
|
||||
properties.
|
||||
|
||||
![devtools-img]
|
||||
|
||||
Check out Google's [extensive tutorial][devtools-tutorial] for a short
|
||||
introduction.
|
||||
|
||||
### Atom Styleguide
|
||||
|
||||
If you are creating an interface theme, you'll want a way to see how your theme
|
||||
changes affect all the components in the system. The [styleguide] is a page that
|
||||
renders every component Atom supports.
|
||||
|
||||
To open the styleguide, open the command palette (`cmd-shift-P`) and search for
|
||||
_styleguide_, or use the shortcut `cmd-ctrl-shift-g`.
|
||||
|
||||
![styleguide-img]
|
||||
|
||||
[atomio-themes]: https://atom.io/themes
|
||||
[Less]: http://lesscss.org/
|
||||
[git]: http://git-scm.com/
|
||||
[atom]: https://atom.io/
|
||||
[package.json]: ./creating-a-package.html#package-json
|
||||
[less-tutorial]: https://speakerdeck.com/danmatthews/less-css
|
||||
[devtools-tutorial]: https://developer.chrome.com/devtools/docs/dom-and-styles
|
||||
[ui-variables]: ./theme-variables.html
|
||||
[livereload]: https://github.com/atom/dev-live-reload
|
||||
[styleguide]: https://github.com/atom/styleguide
|
||||
[atom-dark-ui]: https://github.com/atom/atom-dark-ui
|
||||
[atom-light-ui]: https://github.com/atom/atom-light-ui
|
||||
[styleguide-img]: https://f.cloud.github.com/assets/69169/1347390/2d431d98-36af-11e3-8f8e-3f4ce1e67adb.png
|
||||
[devtools-img]: https://f.cloud.github.com/assets/69169/1347391/2d51f91c-36af-11e3-806f-f7b334af43e9.png
|
||||
[themesettings-img]: https://f.cloud.github.com/assets/69169/1347569/3150bd0c-36b2-11e3-9d69-423503acfe3f.png
|
||||
|
|
@ -1,185 +0,0 @@
|
|||
# Customizing Atom
|
||||
|
||||
To change a setting, configure a theme, or install a package just open the
|
||||
Settings view in the current window by pressing `cmd-,`.
|
||||
|
||||
## Changing The Theme
|
||||
|
||||
Atom comes with both light and dark UI themes as well as several syntax themes.
|
||||
You are also encouraged to [create or fork][create-theme] your own theme.
|
||||
|
||||
To change the active theme just open the Settings view (`cmd-,`) and select the
|
||||
`Themes` section from the left hand side. You will see a drop-down menu to
|
||||
change the active _Syntax_ and _UI_ themes.
|
||||
|
||||
You can also install more themes from here by browsing the featured themes or
|
||||
searching for a specific theme.
|
||||
|
||||
## Installing Packages
|
||||
|
||||
You can install non-bundled packages by going to the `Packages` section on left
|
||||
hand side of the Settings view (`cmd-,`). You will see several featured packages
|
||||
and you can also search for packages from here. The packages listed here have
|
||||
been published to [atom.io](http://atom.io/packages) which is the official
|
||||
registry for Atom packages.
|
||||
|
||||
You can also install packages from the command line using `apm`.
|
||||
|
||||
Check that you have `apm` installed by running the following command in your
|
||||
terminal:
|
||||
|
||||
```sh
|
||||
apm help install
|
||||
```
|
||||
|
||||
You should see a message print out with details about the `apm install` command.
|
||||
|
||||
If you do not, launch Atom and run the _Atom > Install Shell Commands_ menu
|
||||
to install the `apm` and `atom` commands.
|
||||
|
||||
You can also install packages by using the `apm install` command:
|
||||
|
||||
* `apm install <package_name>` to install the latest version.
|
||||
|
||||
* `apm install <package_name>@<package_version>` to install a specific version.
|
||||
|
||||
For example `apm install emmet@0.1.5` installs the `0.1.5` release of the
|
||||
[Emmet](https://github.com/atom/emmet) package into `~/.atom/packages`.
|
||||
|
||||
You can also use `apm` to find new packages to install:
|
||||
|
||||
* `apm search coffee` to search for CoffeeScript packages.
|
||||
|
||||
* `apm view emmet` to see more information about a specific package.
|
||||
|
||||
## Customizing Key Bindings
|
||||
|
||||
Atom keymaps work similarly to style sheets. Just as style sheets 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
|
||||
'atom-text-editor':
|
||||
'enter': 'editor:newline'
|
||||
|
||||
'atom-text-editor[mini] input':
|
||||
'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, `~/.atom/keymap.cson` is loaded when Atom is started. It will always
|
||||
be loaded last, giving you the chance to override bindings that are defined by
|
||||
Atom's core keymaps or third-party packages.
|
||||
|
||||
You can open this file in an editor from the _Atom > Open Your Keymap_ menu.
|
||||
|
||||
You'll want to know all the commands available to you. Open the Settings panel
|
||||
(`cmd-,`) and select the _Keybindings_ tab. It will show you all the keybindings
|
||||
currently in use.
|
||||
|
||||
## Advanced Configuration
|
||||
|
||||
Atom loads configuration settings from the `config.cson` file in your _~/.atom_
|
||||
directory, which contains [CoffeeScript-style JSON][CSON] (CSON):
|
||||
|
||||
```coffee
|
||||
'core':
|
||||
'excludeVcsIgnoredPaths': true
|
||||
'editor':
|
||||
'fontSize': 18
|
||||
```
|
||||
|
||||
The configuration itself is grouped by the package name or one of the two core
|
||||
namespaces: `core` and `editor`.
|
||||
|
||||
You can open this file in an editor from the _Atom > Open Your Config_ menu.
|
||||
|
||||
### Configuration Key Reference
|
||||
|
||||
- `core`
|
||||
- `disabledPackages`: An array of package names to disable
|
||||
- `excludeVcsIgnoredPaths`: Don't search within files specified by _.gitignore_
|
||||
- `followSymlinks`: Follow symlinks when searching and scanning root directory
|
||||
- `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`
|
||||
- `autoIndent`: Enable/disable basic auto-indent (defaults to `true`)
|
||||
- `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`)
|
||||
- `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`)
|
||||
- `wrap-guide`
|
||||
- `columns`: Array of hashes with a `pattern` and `column` key to match the
|
||||
the path of the current editor to a column position.
|
||||
|
||||
### Quick Personal Hacks
|
||||
|
||||
### init.coffee
|
||||
|
||||
When Atom finishes loading, it will evaluate _init.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.
|
||||
If customizations become extensive, consider [creating a package][creating-a-package].
|
||||
|
||||
You can open this file in an editor from the _Atom > Open Your Init Script_
|
||||
menu.
|
||||
|
||||
For example, if you have the Audio Beep configuration setting enabled, you
|
||||
could add the following code to your _~/.atom/init.coffee_ file to have Atom
|
||||
greet you with an audio beep every time it loads:
|
||||
|
||||
```coffee
|
||||
atom.beep()
|
||||
```
|
||||
|
||||
This file can also be named _init.js_ and contain JavaScript code.
|
||||
|
||||
### styles.less
|
||||
|
||||
If you want to apply quick-and-dirty personal styling changes without creating
|
||||
an entire theme that you intend to publish, you can add styles to the
|
||||
_styles.less_ file in your _~/.atom_ directory.
|
||||
|
||||
You can open this file in an editor from the _Atom > Open Your Stylesheet_ menu.
|
||||
|
||||
For example, to change the color of the cursor, you could add the following
|
||||
rule to your _~/.atom/styles.less_ file:
|
||||
|
||||
```less
|
||||
atom-text-editor::shadow .cursor {
|
||||
border-color: pink;
|
||||
}
|
||||
```
|
||||
|
||||
Unfamiliar with Less? Read more about it [here][Less].
|
||||
|
||||
This file can also be named _styles.css_ and contain CSS.
|
||||
|
||||
[creating-a-package]: creating-a-package.md
|
||||
[create-theme]: creating-a-theme.md
|
||||
[Less]: http://www.lesscss.org
|
||||
[CSON]: https://github.com/atom/season
|
||||
[CoffeeScript]: http://coffeescript.org/
|
||||
|
|
@ -1,133 +0,0 @@
|
|||
# Debugging
|
||||
|
||||
Atom provides several tools to help you understand unexpected behavior and debug problems. This guide describes some of those tools and a few approaches to help you debug and provide more helpful information when [submitting issues]:
|
||||
|
||||
* [Update to the latest version](#update-to-the-latest-version)
|
||||
* [Check for linked packages](#check-for-linked-packages)
|
||||
* [Check Atom and package settings](#check-atom-and-package-settings)
|
||||
* [Check the keybindings](#check-the-keybindings)
|
||||
* [Check if the problem shows up in safe mode](#check-if-the-problem-shows-up-in-safe-mode)
|
||||
* [Check your config files](#check-your-config-files)
|
||||
* [Check for errors in the developer tools](#check-for-errors-in-the-developer-tools)
|
||||
|
||||
## Update to the latest version
|
||||
|
||||
You might be running into an issue which was already fixed in a more recent version of Atom than the one you're using.
|
||||
|
||||
If you're building Atom from source, pull down the latest version of master and [re-build][building atom].
|
||||
|
||||
If you're using released version, check which version of Atom you're using:
|
||||
|
||||
```shell
|
||||
$ atom --version
|
||||
0.99.0
|
||||
```
|
||||
|
||||
Head on over to the [list of releases][atom releases] and see if there's a more recent release. You can update to the most recent release by downloading Atom from the releases page, or with the in-app auto-updater. The in-app auto-updater checks for and downloads a new version after you restart Atom, or if you use the Atom > Check for Update menu option.
|
||||
|
||||
## Check for linked packages
|
||||
|
||||
If you develop or contribute to Atom packages, there may be left-over packages linked to your `~/.atom/packages` or `~/.atom/dev/packages` directories. You can use:
|
||||
|
||||
```shell
|
||||
$ apm links
|
||||
```
|
||||
|
||||
to list all linked development packages. You can remove the links using the `apm unlink` command. See `apm unlink --help` for details.
|
||||
|
||||
## Check Atom and package settings
|
||||
|
||||
In some cases, unexpected behavior might be caused by misconfigured or unconfigured settings in Atom or in one of the packages.
|
||||
|
||||
Open Atom's Settings View with `cmd-,` or the Atom > Preferences menu option.
|
||||
|
||||
![Settings View]
|
||||
|
||||
Check Atom's settings in the Settings pane, there's a description of each configuration option [here][customizing guide]. For example, if you want Atom to use hard tabs (real tabs) and not soft tabs (spaces), disable the "Soft Tabs" option.
|
||||
|
||||
Since Atom ships with a set of packages and you can install additional packages yourself, check the list of packages and their settings. For example, if you'd like to get rid of the vertical line in the middle of the editor, disable the [Wrap Guide package]. And if you don't like it when Atom strips trailing whitespace or ensures that there's a single trailing newline in the file, you can configure that in the [Whitespace packages'][whitespace package] settings.
|
||||
|
||||
![Package Settings]
|
||||
|
||||
## Check the keybindings
|
||||
|
||||
If a command is not executing when you hit a keystroke or the wrong command is executing, there might be an issue with the keybindings for that keystroke. Atom ships with the [Keybinding resolver][keybinding resolver package], a neat package which helps you understand which keybindings are executed.
|
||||
|
||||
Show the keybinding resolver with <code>cmd-.</code> or with "Key Binding Resolver: Show" from the Command palette. With the keybinding resolver shown, hit a keystroke:
|
||||
|
||||
![Keybinding Resolver]
|
||||
|
||||
The keybinding resolver shows you a list of keybindings that exist for the keystroke, where each item in the list has the following:
|
||||
* the command for the keybinding,
|
||||
* the CSS selector used to define the context in which the keybinding is valid, and
|
||||
* the file in which the keybinding is defined.
|
||||
|
||||
Of all the keybinding that are listed (grey color), at most one keybinding is matched and executed (green color). If the command you wanted to trigger isn't listed, then a keybinding for that command hasn't been defined. More keybindings are provided by [packages] and you can [define your own keybindings][customizing keybindings].
|
||||
|
||||
If multiple keybindings are matched, Atom determines which keybinding will be executed based on the [specificity of the selectors and the order in which they were loaded][specificity and order]. If the command you wanted to trigger is listed in the Keybinding resolver, but wasn't the one that was executed, this is normally explained by one of two causes:
|
||||
* the keystroke was not used in the context defined by the keybinding's selector. For example, you can't trigger the "Tree View: Add File" command if the Tree View is not focused, or
|
||||
* there is another keybinding that took precedence. This often happens when you install a package which defines keybinding that conflict with existing keybindings. If the package's keybindings have selectors with higher specificity or were loaded later, they'll have priority over existing ones.
|
||||
|
||||
Atom loads core Atom keybindings and package keybindings first, and user-defined keybindings after last. Since user-defined keybindings are loaded last, you can use your `keymap.cson` file to tweak the keybindings and sort out problems like these. For example, you can remove keybindings with [the `unset!` directive][unset directive].
|
||||
|
||||
If you notice that a package's keybindings are taking precedence over core Atom keybindings, it might be a good idea to report the issue on the package's GitHub repository.
|
||||
|
||||
## Check if the problem shows up in safe mode
|
||||
|
||||
A large part of Atom's functionality comes from packages you can install. In some cases, these packages might be causing unexpected behavior, problems, or performance issues.
|
||||
|
||||
To determine if a package you installed is causing problems, start Atom from the terminal in safe mode:
|
||||
|
||||
```
|
||||
$ atom --safe
|
||||
```
|
||||
|
||||
This starts Atom, but does not load packages from `~/.atom/packages` or `~/.atom/dev/packages`. If you can no longer reproduce the problem in safe mode, it's likely it was caused by one of the packages.
|
||||
|
||||
To figure out which package is causing trouble, start Atom normally again and open Settings (`cmd-,`). Since Settings allow you to disable each installed package, you can disable packages one by one until you can no longer reproduce the issue. Restart (`cmd-q`) or reload (`cmd-ctrl-alt-l`) Atom after you disable each package to make sure it's completely gone.
|
||||
|
||||
When you find the problematic package, you can disable or uninstall the package, and consider creating an issue on the package's GitHub repository.
|
||||
|
||||
## Check your config files
|
||||
|
||||
You might have defined some custom functionality or styles in Atom's [Init script or Stylesheet]. In some situations, these personal hacks might be causing problems so try clearing those files and restarting Atom.
|
||||
|
||||
## Check for errors in the developer tools
|
||||
|
||||
When an error is thrown in Atom, the developer tools are automatically shown with the error logged in the Console tab. However, if the dev tools are open before the error is triggered, a full stack trace for the error will be logged:
|
||||
|
||||
![devtools error]
|
||||
|
||||
If you can reproduce the error, use this approach to get the full stack trace. The stack trace might point to a problem in your [Init script][init script or stylesheet] or a specific package you installed, which you can then disable and report an issue on its GitHub repository.
|
||||
|
||||
## Check that you have a build toolchain installed
|
||||
|
||||
If you are having issues installing a package using `apm install`, this could be
|
||||
because the package has dependencies on libraries that contain native code
|
||||
and so you will need to have a C++ compiler and Python installed to be able to
|
||||
install it.
|
||||
|
||||
You can run `apm install --check` to see if [apm][apm] can build native code on
|
||||
your machine.
|
||||
|
||||
Check out the pre-requisites in the [build instructions][build-instructions] for
|
||||
your platform for more details.
|
||||
|
||||
[apm]: https://github.com/atom/apm
|
||||
[build-instructions]: https://github.com/atom/atom/tree/master/docs/build-instructions
|
||||
[submitting issues]: https://github.com/atom/atom/blob/master/CONTRIBUTING.md#submitting-issues
|
||||
[building atom]: https://github.com/atom/atom#building
|
||||
[atom releases]: https://github.com/atom/atom/releases
|
||||
[customizing guide]: https://atom.io/docs/latest/customizing-atom#configuration-key-reference
|
||||
[settings view]: https://f.cloud.github.com/assets/671378/2241795/ba4827d8-9ce4-11e3-93a8-6666ee100917.png
|
||||
[package settings]: https://cloud.githubusercontent.com/assets/38924/3173588/7e5f6b0c-ebe8-11e3-9ec3-e8d140967e79.png
|
||||
[wrap guide package]: https://atom.io/packages/wrap-guide
|
||||
[whitespace package]: https://atom.io/packages/whitespace
|
||||
[keybinding resolver package]: https://atom.io/packages/keybinding-resolver
|
||||
[keybinding resolver]: https://f.cloud.github.com/assets/671378/2241702/5dd5a102-9cde-11e3-9e3f-1d999930492f.png
|
||||
[customizing keybindings]: https://atom.io/docs/latest/customizing-atom#customizing-key-bindings
|
||||
[packages]: https://atom.io/packages
|
||||
[specificity and order]: https://atom.io/docs/latest/advanced/keymaps#specificity-and-cascade-order
|
||||
[unset directive]: https://atom.io/docs/latest/advanced/keymaps#removing-bindings
|
||||
[init script or stylesheet]: https://atom.io/docs/latest/customizing-atom#quick-personal-hacks
|
||||
[devtools error]: https://cloud.githubusercontent.com/assets/38924/3177710/11b4e510-ec13-11e3-96db-a2e8a7891773.png
|
||||
|
|
@ -1,109 +0,0 @@
|
|||
# Getting Started
|
||||
|
||||
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], [theming], and [extending] Atom.
|
||||
|
||||
## The Command Palette
|
||||
|
||||
If there's one key-command you remember in Atom, it should be `cmd-shift-P`. You
|
||||
can always press `cmd-shift-P` to bring up a list of commands (and key bindings)
|
||||
that are relevant to the currently focused interface element. This is a great
|
||||
way to explore the system and learn key bindings interactively. For information
|
||||
about adding or changing a key binding refer to the [customizing key
|
||||
bindings][key-bindings] section.
|
||||
|
||||
![Command Palette]
|
||||
|
||||
## The Basics
|
||||
|
||||
### Working With Files
|
||||
|
||||
Atom windows are scoped to a single directory on disk. If you launch Atom from
|
||||
the command line via the `atom` command and don't specify a path, Atom opens a
|
||||
window for the current working directory. The current window's directory will be
|
||||
visible as the root of the tree view on the left, and also serve as the context
|
||||
for all file-related operations.
|
||||
|
||||
#### Finding Files
|
||||
|
||||
The fastest way to find a file is to use the fuzzy finder. Press `cmd-t` and
|
||||
begin typing the name of the file you're looking for. If you are looking for a
|
||||
file that is already open press `cmd-b` to bring up a searchable list of open
|
||||
files. If you are using Git you can use `cmd-shift-b` to search the list of
|
||||
files modified and untracked in your project's repository.
|
||||
|
||||
You can also use the tree view to navigate to a file. To open and focus the
|
||||
tree view, press `ctrl-0`. The tree view can be toggled open and closed with
|
||||
`cmd-\`.
|
||||
|
||||
#### Adding, Moving, Deleting Files
|
||||
|
||||
You can add, move, and delete files and folders by right-clicking them in the
|
||||
tree view and selecting the desired operation from the context menu. You can
|
||||
also perform these operations from the keyboard by selecting a file or folder
|
||||
and using `a` to add, `m` to move, and `delete` to delete.
|
||||
|
||||
### Searching
|
||||
|
||||
#### Find and Replace
|
||||
|
||||
To search within a buffer use `cmd-f`. To search the entire project use
|
||||
`cmd-shift-f`.
|
||||
|
||||
#### Navigating By Symbols
|
||||
|
||||
To jump to a symbol such as a method definition, press `cmd-r`. This opens a
|
||||
list of all symbols in the current file, which you can fuzzy filter similarly to
|
||||
`cmd-t`.
|
||||
|
||||
To search for symbols across your project, use `cmd-shift-r`. First you'll need
|
||||
to make sure you have `tags` (or `TAGS`) file generated for your project.
|
||||
This can be done by installing [ctags](http://ctags.sourceforge.net/) and
|
||||
running a command such as `ctags -R src/` from the command line in your
|
||||
project's root directory. Using [Homebrew](http://brew.sh/)? Just run
|
||||
`brew install ctags`.
|
||||
|
||||
You can customize how tags are generated by creating your own `.ctags` file
|
||||
in your home directory (`~/.ctags`). Here is [a good example][ctags] to start
|
||||
from.
|
||||
|
||||
### Split Panes
|
||||
|
||||
You can split any editor pane horizontally or vertically by using `cmd-k right`
|
||||
or `cmd-k down`. Once you have a split pane, you can move focus between them
|
||||
with `cmd-k cmd-right` or `cmd-k cmd-down`. To close a pane, close all its
|
||||
editors with `cmd-w`, then press `cmd-w` one more time to close the pane. You
|
||||
can configure panes to auto-close when empty in the Settings view.
|
||||
|
||||
### Folding
|
||||
|
||||
You can fold blocks of code by clicking the arrows that appear when you hover
|
||||
your mouse cursor over the gutter. You can also fold and unfold from the
|
||||
keyboard with `alt-cmd-[` and `alt-cmd-]`. To fold everything, use
|
||||
`alt-cmd-shift-{` and to unfold everything use `alt-cmd-shift-}`. You can also
|
||||
fold at a specific indentation level with `cmd-k cmd-N` where N is the
|
||||
indentation depth.
|
||||
|
||||
### Soft-Wrap
|
||||
|
||||
If you want to toggle soft wrap, trigger the command from the command palette.
|
||||
Press `cmd-shift-P` to open the palette, then type "wrap" to find the correct
|
||||
command. By default, lines will wrap based on the size of the editor. If you
|
||||
prefer to wrap at a specific line length, toggle "Wrap at preferred line length"
|
||||
in preferences.
|
||||
|
||||
## Configuration
|
||||
|
||||
Press `cmd-,` to open the Settings view. This is the place to change settings,
|
||||
install packages, and change the theme.
|
||||
|
||||
For more advanced configuration see the [customization guide][customization].
|
||||
|
||||
[configuring]: customizing-atom.md
|
||||
[theming]: creating-a-theme.md
|
||||
[extending]: creating-a-package.md
|
||||
[customization]: customizing-atom.md
|
||||
[key-bindings]: customizing-atom.md#customizing-key-bindings
|
||||
[command palette]: https://f.cloud.github.com/assets/1424/1091618/ee7c3554-166a-11e3-9955-aaa61bb5509c.png
|
||||
[ctags]: https://github.com/atom/symbols-view/blob/master/lib/.ctags
|
||||
|
|
@ -1,29 +0,0 @@
|
|||
## Guides
|
||||
|
||||
* [Getting Started](getting-started.md)
|
||||
* [Customizing Atom](customizing-atom.md)
|
||||
* [Creating a Package](creating-a-package.md)
|
||||
* [Creating a Theme](creating-a-theme.md)
|
||||
* [Publishing a Package](publishing-a-package.md)
|
||||
* [Writing Specs](writing-specs.md)
|
||||
* [Converting a TextMate Bundle](converting-a-text-mate-bundle.md)
|
||||
* [Converting a TextMate Theme](converting-a-text-mate-theme.md)
|
||||
* [Contributing](contributing.md)
|
||||
* [Contributing to Core Packages](contributing-to-packages.md)
|
||||
* [Debugging](debugging.md)
|
||||
* [Your First Package](your-first-package.md)
|
||||
|
||||
### Advanced Topics
|
||||
|
||||
* [Configuration](advanced/configuration.md)
|
||||
* [Developing Node Modules](advanced/node-modules.md)
|
||||
* [Keymaps](advanced/keymaps.md)
|
||||
* [Serialization](advanced/serialization.md)
|
||||
* [Scopes and Scope Descriptors](advanced/scopes-and-scope-descriptors.md)
|
||||
* [Theme Variables](theme-variables.md)
|
||||
* [apm REST API](apm-rest-api.md)
|
||||
|
||||
### Upgrading to 1.0 APIs
|
||||
|
||||
* [Upgrading Your UI Theme Or Package Selectors](upgrading/upgrading-your-ui-theme.md)
|
||||
* [Upgrading Your Syntax Theme](upgrading/upgrading-your-syntax-theme.md)
|
||||
|
|
@ -1,114 +0,0 @@
|
|||
## Publishing a Package
|
||||
|
||||
This guide will show you how to publish a package or theme to the
|
||||
[atom.io][atomio] package registry.
|
||||
|
||||
Publishing a package allows other people to install it and use it in Atom. It
|
||||
is a great way to share what you've made and get feedback and contributions from
|
||||
others.
|
||||
|
||||
This guide assumes your package's name is `my-package` but you should pick a
|
||||
better name.
|
||||
|
||||
### Install apm
|
||||
|
||||
The `apm` command line utility that ships with Atom supports publishing packages
|
||||
to the atom.io registry.
|
||||
|
||||
Check that you have `apm` installed by running the following command in your
|
||||
terminal:
|
||||
|
||||
```sh
|
||||
apm help publish
|
||||
```
|
||||
|
||||
You should see a message print out with details about the `apm publish` command.
|
||||
|
||||
If you do not, launch Atom and run the _Atom > Install Shell Commands_ menu
|
||||
to install the `apm` and `atom` commands.
|
||||
|
||||
### Prepare Your Package
|
||||
|
||||
If you've followed the steps in the [your first package][your-first-package]
|
||||
doc then you should be ready to publish and you can skip to the next step.
|
||||
|
||||
If not, there are a few things you should check before publishing:
|
||||
|
||||
* Your *package.json* file has `name`, `description`, and `repository` fields.
|
||||
* Your *package.json* file has a `version` field with a value of `"0.0.0"`.
|
||||
* Your *package.json* file has an `engines` field that contains an entry
|
||||
for Atom such as: `"engines": {"atom": ">=0.50.0"}`.
|
||||
* Your package has a `README.md` file at the root.
|
||||
* Your package is in a Git repository that has been pushed to
|
||||
[GitHub][github]. Follow [this guide][repo-guide] if your package isn't
|
||||
already on GitHub.
|
||||
|
||||
### Publish Your Package
|
||||
|
||||
Before you publish a package it is a good idea to check ahead of time if
|
||||
a package with the same name has already been published to atom.io. You can do
|
||||
that by visiting `https://atom.io/packages/my-package` to see if the package
|
||||
already exists. If it does, update your package's name to something that is
|
||||
available before proceeding.
|
||||
|
||||
Now let's review what the `apm publish` command does:
|
||||
|
||||
1. Registers the package name on atom.io if it is being published for the
|
||||
first time.
|
||||
2. Updates the `version` field in the *package.json* file and commits it.
|
||||
3. Creates a new [Git tag][git-tag] for the version being published.
|
||||
4. Pushes the tag and current branch up to GitHub.
|
||||
5. Updates atom.io with the new version being published.
|
||||
|
||||
Now run the following commands to publish your package:
|
||||
|
||||
```sh
|
||||
cd ~/github/my-package
|
||||
apm publish minor
|
||||
```
|
||||
|
||||
If this is the first package you are publishing, the `apm publish` command may
|
||||
prompt you for your GitHub username and password. This is required to publish
|
||||
and you only need to enter this information the first time you publish. The
|
||||
credentials are stored securely in your [keychain][keychain] once you login.
|
||||
|
||||
:tada: Your package is now published and available on atom.io. Head on over to
|
||||
`https://atom.io/packages/my-package` to see your package's page.
|
||||
|
||||
With `apm publish`, you can bump the version and publish by using
|
||||
```sh
|
||||
apm publish <version-type>
|
||||
```
|
||||
where `<version-type>` can be `major`, `minor` and `patch`.
|
||||
|
||||
The `major` option to the publish command tells apm to increment the first
|
||||
digit of the version before publishing so the published version will be `1.0.0`
|
||||
and the Git tag created will be `v1.0.0`.
|
||||
|
||||
The `minor` option to the publish command tells apm to increment the second
|
||||
digit of the version before publishing so the published version will be `0.1.0`
|
||||
and the Git tag created will be `v0.1.0`.
|
||||
|
||||
The `patch` option to the publish command tells apm to increment the third
|
||||
digit of the version before publishing so the published version will be `0.0.1`
|
||||
and the Git tag created will be `v0.0.1`.
|
||||
|
||||
Use `major` when you make a huge change, like a rewrite, or a large change to the functionality or interface.
|
||||
Use `minor` when adding or removing a feature.
|
||||
Use `patch` when you make a small change like a bug fix that does not add or remove features.
|
||||
|
||||
### Further Reading
|
||||
|
||||
* Check out [semantic versioning][semver] to learn more about versioning your
|
||||
package releases.
|
||||
* Consult the [Atom.io package API docs][apm-rest-api] to learn more about how
|
||||
`apm` works.
|
||||
|
||||
[atomio]: https://atom.io
|
||||
[github]: https://github.com
|
||||
[git-tag]: http://git-scm.com/book/en/Git-Basics-Tagging
|
||||
[keychain]: https://en.wikipedia.org/wiki/Keychain_(Apple)
|
||||
[repo-guide]: http://guides.github.com/overviews/desktop
|
||||
[semver]: http://semver.org
|
||||
[your-first-package]: your-first-package.html
|
||||
[apm-rest-api]: apm-rest-api.md
|
||||
|
|
@ -1,150 +0,0 @@
|
|||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
|
||||
<link href="//netdna.bootstrapcdn.com/bootstrap/3.0.0/css/bootstrap.min.css" rel="stylesheet">
|
||||
<link rel="stylesheet" href="//netdna.bootstrapcdn.com/bootstrap/3.0.0/css/bootstrap-theme.min.css">
|
||||
<!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries -->
|
||||
<!--[if lt IE 9]>
|
||||
<script src="../../assets/js/html5shiv.js"></script>
|
||||
<script src="../../assets/js/respond.min.js"></script>
|
||||
<![endif]-->
|
||||
|
||||
<title>Atom - <%= title %></title>
|
||||
<style>
|
||||
/*github.com style (c) Vasily Polovnyov <vast@whiteants.net>*/
|
||||
pre code {
|
||||
display: block; padding: 0.5em;
|
||||
color: #333;
|
||||
background: #f8f8ff
|
||||
}
|
||||
pre .comment,
|
||||
pre .template_comment,
|
||||
pre .diff .header,
|
||||
pre .javadoc {
|
||||
color: #998;
|
||||
font-style: italic
|
||||
}
|
||||
pre .keyword,
|
||||
pre .css .rule .keyword,
|
||||
pre .winutils,
|
||||
pre .javascript .title,
|
||||
pre .nginx .title,
|
||||
pre .subst,
|
||||
pre .request,
|
||||
pre .status {
|
||||
color: #333;
|
||||
font-weight: bold
|
||||
}
|
||||
pre .number,
|
||||
pre .hexcolor,
|
||||
pre .ruby .constant {
|
||||
color: #099;
|
||||
}
|
||||
pre .string,
|
||||
pre .tag .value,
|
||||
pre .phpdoc,
|
||||
pre .tex .formula {
|
||||
color: #d14
|
||||
}
|
||||
pre .title,
|
||||
pre .id {
|
||||
color: #900;
|
||||
font-weight: bold
|
||||
}
|
||||
pre .javascript .title,
|
||||
pre .lisp .title,
|
||||
pre .clojure .title,
|
||||
pre .subst {
|
||||
font-weight: normal
|
||||
}
|
||||
pre .class .title,
|
||||
pre .haskell .type,
|
||||
pre .vhdl .literal,
|
||||
pre .tex .command {
|
||||
color: #458;
|
||||
font-weight: bold
|
||||
}
|
||||
pre .tag,
|
||||
pre .tag .title,
|
||||
pre .rules .property,
|
||||
pre .django .tag .keyword {
|
||||
color: #000080;
|
||||
font-weight: normal
|
||||
}
|
||||
pre .attribute,
|
||||
pre .variable,
|
||||
pre .lisp .body {
|
||||
color: #008080
|
||||
}
|
||||
pre .regexp {
|
||||
color: #009926
|
||||
}
|
||||
pre .class {
|
||||
color: #458;
|
||||
font-weight: bold
|
||||
}
|
||||
pre .symbol,
|
||||
pre .ruby .symbol .string,
|
||||
pre .lisp .keyword,
|
||||
pre .tex .special,
|
||||
pre .prompt {
|
||||
color: #990073
|
||||
}
|
||||
pre .built_in,
|
||||
pre .lisp .title,
|
||||
pre .clojure .built_in {
|
||||
color: #0086b3
|
||||
}
|
||||
pre .preprocessor,
|
||||
pre .pi,
|
||||
pre .doctype,
|
||||
pre .shebang,
|
||||
pre .cdata {
|
||||
color: #999;
|
||||
font-weight: bold
|
||||
}
|
||||
pre .deletion {
|
||||
background: #fdd
|
||||
}
|
||||
pre .addition {
|
||||
background: #dfd
|
||||
}
|
||||
pre .diff .change {
|
||||
background: #0086b3
|
||||
}
|
||||
pre .chunk {
|
||||
color: #aaa
|
||||
}
|
||||
|
||||
body {
|
||||
padding-top: 50px;
|
||||
}
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div class="navbar navbar-inverse navbar-fixed-top">
|
||||
<div class="container">
|
||||
<div class="navbar-header">
|
||||
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse">
|
||||
<span class="icon-bar"></span>
|
||||
<span class="icon-bar"></span>
|
||||
<span class="icon-bar"></span>
|
||||
</button>
|
||||
<a class="navbar-brand" href="/<%= tag %>/index.html">Atom Documentation</a>
|
||||
</div>
|
||||
<div class="collapse navbar-collapse">
|
||||
<ul class="nav navbar-nav">
|
||||
<li><a href="/docs/api/<%= tag %>/api/index.html">API</a></li>
|
||||
</ul>
|
||||
</div><!--/.nav-collapse -->
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="container">
|
||||
<%= content %>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
|
|
@ -1,118 +0,0 @@
|
|||
# Style variables
|
||||
|
||||
EDGEHILL NOTE: THIS FILE IS NOT UP TO DATE.
|
||||
|
||||
Atom's UI provides a set of variables you can use in your own themes and packages.
|
||||
|
||||
## Use in Themes
|
||||
|
||||
Each custom theme must specify a `ui-variables.less` file with all of the
|
||||
following variables defined. The top-most theme specified in the theme settings
|
||||
will be loaded and available for import.
|
||||
|
||||
## Use in Packages
|
||||
|
||||
In any of your package's `.less` files, you can access the theme variables
|
||||
by importing the `ui-variables` file from Atom.
|
||||
|
||||
Your package should generally only specify structural styling, and these should
|
||||
come from [the style guide][styleguide]. Your package shouldn't specify colors,
|
||||
padding sizes, or anything in absolute pixels. You should instead use the theme
|
||||
variables. If you follow this guideline, your package will look good out of the
|
||||
box with any theme!
|
||||
|
||||
Here's an example `.less` file that a package can define using theme variables:
|
||||
|
||||
```css
|
||||
@import "ui-variables";
|
||||
|
||||
.my-selector {
|
||||
background-color: @base-background-color;
|
||||
padding: @component-padding;
|
||||
}
|
||||
```
|
||||
|
||||
## Variables
|
||||
|
||||
### Text colors
|
||||
|
||||
* `@text-color`
|
||||
* `@text-color-subtle`
|
||||
* `@text-color-highlight`
|
||||
* `@text-color-selected`
|
||||
* `@text-color-info` - A blue
|
||||
* `@text-color-success`- A green
|
||||
* `@text-color-warning`- An orange or yellow
|
||||
* `@text-color-error` - A red
|
||||
|
||||
### Background colors
|
||||
|
||||
* `@background-color-info` - A blue
|
||||
* `@background-color-success` - A green
|
||||
* `@background-color-warning` - An orange or yellow
|
||||
* `@background-color-error` - A red
|
||||
* `@background-color-highlight`
|
||||
* `@background-color-selected`
|
||||
* `@app-background-color` - The app's background under all the editor components
|
||||
|
||||
### Component colors
|
||||
|
||||
* `@base-background-color` -
|
||||
* `@base-border-color` -
|
||||
|
||||
* `@pane-item-background-color` -
|
||||
* `@pane-item-border-color` -
|
||||
|
||||
* `@input-background-color` -
|
||||
* `@input-border-color` -
|
||||
|
||||
* `@tool-panel-background-color` -
|
||||
* `@tool-panel-border-color` -
|
||||
|
||||
* `@inset-panel-background-color` -
|
||||
* `@inset-panel-border-color` -
|
||||
|
||||
* `@panel-heading-background-color` -
|
||||
* `@panel-heading-border-color` -
|
||||
|
||||
* `@overlay-background-color` -
|
||||
* `@overlay-border-color` -
|
||||
|
||||
* `@button-background-color` -
|
||||
* `@button-background-color-hover` -
|
||||
* `@button-background-color-selected` -
|
||||
* `@button-border-color` -
|
||||
|
||||
* `@tab-bar-background-color` -
|
||||
* `@tab-bar-border-color` -
|
||||
* `@tab-background-color` -
|
||||
* `@tab-background-color-active` -
|
||||
* `@tab-border-color` -
|
||||
|
||||
* `@tree-view-background-color` -
|
||||
* `@tree-view-border-color` -
|
||||
|
||||
* `@ui-site-color-1` -
|
||||
* `@ui-site-color-2` -
|
||||
* `@ui-site-color-3` -
|
||||
* `@ui-site-color-4` -
|
||||
* `@ui-site-color-5` -
|
||||
|
||||
### Component sizes
|
||||
|
||||
* `@disclosure-arrow-size` -
|
||||
|
||||
* `@component-padding` -
|
||||
* `@component-icon-padding` -
|
||||
* `@component-icon-size` -
|
||||
* `@component-line-height` -
|
||||
* `@component-border-radius` -
|
||||
|
||||
* `@tab-height` -
|
||||
|
||||
### Fonts
|
||||
|
||||
* `@font-size` -
|
||||
* `@font-family` -
|
||||
|
||||
[styleguide]: https://github.com/atom/styleguide
|
||||
|
|
@ -1,625 +0,0 @@
|
|||
# Upgrading your package to 1.0 APIs
|
||||
|
||||
Atom is rapidly approaching 1.0. Much of the effort leading up to the 1.0 has been cleaning up APIs in an attempt to future proof, and make a more pleasant experience developing packages.
|
||||
|
||||
This document will guide you through the large bits of upgrading your package to work with 1.0 APIs.
|
||||
|
||||
## TL;DR
|
||||
|
||||
We've set deprecation messages and errors in strategic places to help make sure you don't miss anything. You should be able to get 95% of the way to an updated package just by fixing errors and deprecations. There are a couple of things you can do to get the full effect of all the errors and deprecations.
|
||||
|
||||
### Use atom-space-pen-views
|
||||
|
||||
If you use any class from `require 'atom'` with a `$` or `View` in the name, add the `atom-space-pen-views` module to your package's `package.json` file's dependencies:
|
||||
|
||||
```js
|
||||
{
|
||||
"dependencies": {
|
||||
"atom-space-pen-views": "^2.0.3"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Then run `apm install` in your package directory.
|
||||
|
||||
### Require views from atom-space-pen-views
|
||||
|
||||
Anywhere you are requiring one of the following from `atom` you need to require them from `atom-space-pen-views` instead.
|
||||
|
||||
```coffee
|
||||
# require these from 'atom-space-pen-views' rather than 'atom'
|
||||
$
|
||||
$$
|
||||
$$$
|
||||
View
|
||||
TextEditorView
|
||||
ScrollView
|
||||
SelectListView
|
||||
```
|
||||
|
||||
So this:
|
||||
|
||||
```coffee
|
||||
# Old way
|
||||
{$, TextEditorView, View, GitRepository} = require 'atom'
|
||||
```
|
||||
|
||||
Would be replaced by this:
|
||||
|
||||
```coffee
|
||||
# New way
|
||||
{GitRepository} = require 'atom'
|
||||
{$, TextEditorView, View} = require 'atom-space-pen-views'
|
||||
```
|
||||
|
||||
### Run specs and test your package
|
||||
|
||||
You wrote specs, right!? Here's where they shine. Run them with `cmd-shift-P`, and search for `run package specs`. It will show all the deprecation messages and errors.
|
||||
|
||||
### Update the engines field in package.json
|
||||
|
||||
When you are deprecation free and all done converting, upgrade the `engines` field in your package.json:
|
||||
|
||||
```json
|
||||
{
|
||||
"engines": {
|
||||
"atom": ">=0.174.0, <2.0.0"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Examples
|
||||
|
||||
We have upgraded all the core packages. Please see [this issue](https://github.com/atom/atom/issues/4011) for a link to all the upgrade PRs.
|
||||
|
||||
## Deprecations
|
||||
|
||||
All of the methods in Atom core that have changes will emit deprecation messages when called. These messages are shown in two places: your **package specs**, and in **Deprecation Cop**.
|
||||
|
||||
### Specs
|
||||
|
||||
Just run your specs, and all the deprecations will be displayed in yellow.
|
||||
|
||||
|
||||
|
||||
### Deprecation Cop
|
||||
|
||||
Run an atom window in dev mode (`atom -d`) with your package loaded, and open Deprecation Cop (search for `deprecation` in the command palette). Deprecated methods will be appear in Deprecation Cop only after they have been called.
|
||||
|
||||
|
||||
|
||||
When deprecation cop is open, and deprecated methods are called, a `Refresh` button will appear in the top right of the Deprecation Cop interface. So exercise your package, then come back to Deprecation Cop and click the `Refresh` button.
|
||||
|
||||
## Upgrading your Views
|
||||
|
||||
Previous to 1.0, views were baked into Atom core. These views were based on jQuery and `space-pen`. They looked something like this:
|
||||
|
||||
```coffee
|
||||
# The old way: getting views from atom
|
||||
{$, TextEditorView, View} = require 'atom'
|
||||
|
||||
module.exports =
|
||||
class SomeView extends View
|
||||
@content: ->
|
||||
@div class: 'find-and-replace', =>
|
||||
@div class: 'block', =>
|
||||
@subview 'myEditor', new TextEditorView(mini: true)
|
||||
#...
|
||||
```
|
||||
|
||||
### The New
|
||||
|
||||
`require 'atom'` no longer provides view helpers or jQuery. Atom core is now 'view agnostic'. The preexisting view system is available from a new npm package: `atom-space-pen-views`.
|
||||
|
||||
`atom-space-pen-views` now provides jQuery, `space-pen` views, and Atom specific views:
|
||||
|
||||
|
||||
```coffee
|
||||
# These are now provided by atom-space-pen-views
|
||||
$
|
||||
$$
|
||||
$$$
|
||||
View
|
||||
TextEditorView
|
||||
ScrollView
|
||||
SelectListView
|
||||
```
|
||||
|
||||
### Adding the module dependencies
|
||||
|
||||
To use the new views, you need to specify the `atom-space-pen-views` module in your package's `package.json` file's dependencies:
|
||||
|
||||
```js
|
||||
{
|
||||
"dependencies": {
|
||||
"atom-space-pen-views": "^2.0.3"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`space-pen` bundles jQuery. If you do not need `space-pen` or any of the views, you can require jQuery directly.
|
||||
|
||||
```js
|
||||
{
|
||||
"dependencies": {
|
||||
"jquery": "^2"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Converting your views
|
||||
|
||||
Sometimes it is as simple as converting the requires at the top of each view page. I assume you read the 'TL;DR' section and have updated all of your requires.
|
||||
|
||||
### Upgrading classes extending any space-pen View
|
||||
|
||||
#### `afterAttach` and `beforeRemove` updated
|
||||
|
||||
The `afterAttach` and `beforeRemove` hooks have been replaced with
|
||||
`attached` and `detached` and the semantics have changed.
|
||||
|
||||
`afterAttach` was called whenever the node was attached to another DOM node, even if that parent node wasn't present in the DOM. `afterAttach` also was called with a boolean indicating whether or not the element and its parents were on the DOM. Now the `attached` hook is _only_ called when the node and all of its parents are actually on the DOM, and is not called with a boolean.
|
||||
|
||||
`beforeRemove` was only called when `$.fn.remove` was called, which was typically used when the node was completely removed from the DOM. The new `detached` hook is called whenever the DOM node is _detached_, which could happen if the node is being detached for reattachment later. In short, if `beforeRemove` is called the node is never coming back. With `detached` it might be attached again later.
|
||||
|
||||
```coffee
|
||||
# Old way
|
||||
{View} = require 'atom'
|
||||
class MyView extends View
|
||||
afterAttach: (onDom) ->
|
||||
#...
|
||||
|
||||
beforeRemove: ->
|
||||
#...
|
||||
```
|
||||
|
||||
```coffee
|
||||
# New way
|
||||
{View} = require 'atom-space-pen-views'
|
||||
class MyView extends View
|
||||
attached: ->
|
||||
# Always called with the equivalent of @afterAttach(true)!
|
||||
#...
|
||||
|
||||
detached: ->
|
||||
#...
|
||||
```
|
||||
|
||||
#### `subscribe` and `subscribeToCommand` methods removed
|
||||
|
||||
The `subscribe` and `subscribeToCommand` methods have been removed. See the Eventing and Disposables section for more info.
|
||||
|
||||
### Upgrading to the new TextEditorView
|
||||
|
||||
All of the atom-specific methods available on the `TextEditorView` have been moved to the `TextEditor`, available via `TextEditorView::getModel`. See the [`TextEditorView` docs][TextEditorView] and [`TextEditor` docs][TextEditor] for more info.
|
||||
|
||||
### Upgrading classes extending ScrollView
|
||||
|
||||
The `ScrollView` has very minor changes.
|
||||
|
||||
You can no longer use `@off` to remove default behavior for `core:move-up`, `core:move-down`, etc.
|
||||
|
||||
```coffee
|
||||
# Old way to turn off default behavior
|
||||
class ResultsView extends ScrollView
|
||||
initialize: (@model) ->
|
||||
super()
|
||||
# turn off default scrolling behavior from ScrollView
|
||||
@off 'core:move-up'
|
||||
@off 'core:move-down'
|
||||
@off 'core:move-left'
|
||||
@off 'core:move-right'
|
||||
```
|
||||
|
||||
```coffee
|
||||
# New way to turn off default behavior
|
||||
class ResultsView extends ScrollView
|
||||
initialize: (@model) ->
|
||||
disposable = super()
|
||||
# turn off default scrolling behavior from ScrollView
|
||||
disposable.dispose()
|
||||
```
|
||||
|
||||
* Check out [an example](https://github.com/atom/find-and-replace/pull/311/files#diff-9) from find-and-replace.
|
||||
* See the [docs][ScrollView] for all the options.
|
||||
|
||||
### Upgrading classes extending SelectListView
|
||||
|
||||
Your SelectListView might look something like this:
|
||||
|
||||
```coffee
|
||||
# Old!
|
||||
class CommandPaletteView extends SelectListView
|
||||
initialize: ->
|
||||
super()
|
||||
@addClass('command-palette overlay from-top')
|
||||
atom.workspaceView.command 'command-palette:toggle', => @toggle()
|
||||
|
||||
confirmed: ({name, jQuery}) ->
|
||||
@cancel()
|
||||
# do something with the result
|
||||
|
||||
toggle: ->
|
||||
if @hasParent()
|
||||
@cancel()
|
||||
else
|
||||
@attach()
|
||||
|
||||
attach: ->
|
||||
@storeFocusedElement()
|
||||
|
||||
items = [] # TODO: build items
|
||||
@setItems(items)
|
||||
|
||||
atom.workspaceView.append(this)
|
||||
@focusFilterEditor()
|
||||
|
||||
confirmed: ({name, jQuery}) ->
|
||||
@cancel()
|
||||
```
|
||||
|
||||
This attaches and detaches itself from the dom when toggled, canceling magically detaches it from the DOM, and it uses the classes `overlay` and `from-top`.
|
||||
|
||||
The new SelectListView no longer automatically detaches itself from the DOM when cancelled. It's up to you to implement whatever cancel beahavior you want. Using the new APIs to mimic the sematics of the old class, it should look like this:
|
||||
|
||||
```coffee
|
||||
# New!
|
||||
class CommandPaletteView extends SelectListView
|
||||
initialize: ->
|
||||
super()
|
||||
# no more need for the `overlay` and `from-top` classes
|
||||
@addClass('command-palette')
|
||||
atom.commands.add 'atom-workspace', 'command-palette:toggle', => @toggle()
|
||||
|
||||
# You need to implement the `cancelled` method and hide.
|
||||
cancelled: ->
|
||||
@hide()
|
||||
|
||||
confirmed: ({name, jQuery}) ->
|
||||
@cancel()
|
||||
# do something with the result
|
||||
|
||||
toggle: ->
|
||||
# Toggling now checks panel visibility,
|
||||
# and hides / shows rather than attaching to / detaching from the DOM.
|
||||
if @panel?.isVisible()
|
||||
@cancel()
|
||||
else
|
||||
@show()
|
||||
|
||||
show: ->
|
||||
# Now you will add your select list as a modal panel to the workspace
|
||||
@panel ?= atom.workspace.addModalPanel(item: this)
|
||||
@panel.show()
|
||||
|
||||
@storeFocusedElement()
|
||||
|
||||
items = [] # TODO: build items
|
||||
@setItems(items)
|
||||
|
||||
@focusFilterEditor()
|
||||
|
||||
hide: ->
|
||||
@panel?.hide()
|
||||
```
|
||||
|
||||
* And check out the [conversion of CommandPaletteView][selectlistview-example] as a real-world example.
|
||||
* See the [SelectListView docs][SelectListView] for all options.
|
||||
|
||||
## Using the model layer rather than the view layer
|
||||
|
||||
The API no longer exposes any specialized view objects or view classes. `atom.workspaceView`, and all the view classes: `WorkspaceView`, `EditorView`, `PaneView`, etc. have been globally deprecated.
|
||||
|
||||
Nearly all of the atom-specific actions performed by the old view objects can now be managed via the model layer. For example, here's adding a panel to the interface using the `atom.workspace` model instead of the `workspaceView`:
|
||||
|
||||
```coffee
|
||||
# Old!
|
||||
div = document.createElement('div')
|
||||
atom.workspaceView.appendToTop(div)
|
||||
```
|
||||
|
||||
```coffee
|
||||
# New!
|
||||
div = document.createElement('div')
|
||||
atom.workspace.addTopPanel(item: div)
|
||||
```
|
||||
|
||||
For actions that still require the view, such as dispatching commands or munging css classes, you'll access the view via the `atom.views.getView()` method. This will return a subclass of `HTMLElement` rather than a jQuery object or an instance of a deprecated view class (e.g. `WorkspaceView`).
|
||||
|
||||
```coffee
|
||||
# Old!
|
||||
workspaceView = atom.workspaceView
|
||||
editorView = workspaceView.getActiveEditorView()
|
||||
paneView = editorView.getPaneView()
|
||||
```
|
||||
|
||||
```coffee
|
||||
# New!
|
||||
# Generally, just use the models
|
||||
workspace = atom.workspace
|
||||
editor = workspace.getActiveTextEditor()
|
||||
pane = editor.getPane()
|
||||
|
||||
# If you need views, get them with `getView`
|
||||
workspaceElement = atom.views.getView(atom.workspace)
|
||||
editorElement = atom.views.getView(editor)
|
||||
paneElement = atom.views.getView(pane)
|
||||
```
|
||||
|
||||
## Updating Specs
|
||||
|
||||
`atom.workspaceView`, the `WorkspaceView` class and the `EditorView` class have been deprecated. These two objects are used heavily throughout specs, mostly to dispatch events and commands. This section will explain how to remove them while still retaining the ability to dispatch events and commands.
|
||||
|
||||
### Removing WorkspaceView references
|
||||
|
||||
`WorkspaceView` has been deprecated. Everything you could do on the view, you can now do on the `Workspace` model.
|
||||
|
||||
Requiring `WorkspaceView` from `atom` and accessing any methods on it will throw a deprecation warning. Many specs lean heavily on `WorkspaceView` to trigger commands and fetch `EditorView` objects.
|
||||
|
||||
Your specs might contain something like this:
|
||||
|
||||
```coffee
|
||||
# Old!
|
||||
{WorkspaceView} = require 'atom'
|
||||
describe 'FindView', ->
|
||||
beforeEach ->
|
||||
atom.workspaceView = new WorkspaceView()
|
||||
```
|
||||
|
||||
Instead, we will use the `atom.views.getView()` method. This will return a plain `HTMLElement`, not a `WorkspaceView` or jQuery object.
|
||||
|
||||
```coffee
|
||||
# New!
|
||||
describe 'FindView', ->
|
||||
workspaceElement = null
|
||||
beforeEach ->
|
||||
workspaceElement = atom.views.getView(atom.workspace)
|
||||
```
|
||||
|
||||
### Attaching the workspace to the DOM
|
||||
|
||||
The workspace needs to be attached to the DOM in some cases. For example, view hooks only work (`attached()` on `View`, `attachedCallback()` on custom elements) when there is a descendant attached to the DOM.
|
||||
|
||||
You might see this in your specs:
|
||||
|
||||
```coffee
|
||||
# Old!
|
||||
atom.workspaceView.attachToDom()
|
||||
```
|
||||
|
||||
Change it to:
|
||||
|
||||
```coffee
|
||||
# New!
|
||||
jasmine.attachToDOM(workspaceElement)
|
||||
```
|
||||
|
||||
### Removing EditorView references
|
||||
|
||||
Like `WorkspaceView`, `EditorView` has been deprecated. Everything you needed to do on the view you are now able to do on the `TextEditor` model.
|
||||
|
||||
In many cases, you will not even need to get the editor's view anymore. Any of those instances should be updated to use the `TextEditor` instance instead. You should really only need the editor's view when you plan on triggering a command on the view in a spec.
|
||||
|
||||
Your specs might contain something like this:
|
||||
|
||||
```coffee
|
||||
# Old!
|
||||
describe 'Something', ->
|
||||
[editorView] = []
|
||||
beforeEach ->
|
||||
editorView = atom.workspaceView.getActiveView()
|
||||
```
|
||||
|
||||
We're going to use `atom.views.getView()` again to get the editor element. As in the case of the `workspaceElement`, `getView` will return a subclass of `HTMLElement` rather than an `EditorView` or jQuery object.
|
||||
|
||||
```coffee
|
||||
# New!
|
||||
describe 'Something', ->
|
||||
[editor, editorElement] = []
|
||||
beforeEach ->
|
||||
editor = atom.workspace.getActiveTextEditor()
|
||||
editorElement = atom.views.getView(editor)
|
||||
```
|
||||
|
||||
### Dispatching commands
|
||||
|
||||
Since the `editorElement` objects are no longer `jQuery` objects, they no longer support `trigger()`. Additionally, Atom has a new command dispatcher, `atom.commands`, that we use rather than commandeering jQuery's `trigger` method.
|
||||
|
||||
From this:
|
||||
|
||||
```coffee
|
||||
# Old!
|
||||
workspaceView.trigger 'a-package:toggle'
|
||||
editorView.trigger 'find-and-replace:show'
|
||||
```
|
||||
|
||||
To this:
|
||||
|
||||
```coffee
|
||||
# New!
|
||||
atom.commands.dispatch workspaceElement, 'a-package:toggle'
|
||||
atom.commands.dispatch editorElement, 'find-and-replace:show'
|
||||
```
|
||||
|
||||
## Eventing and Disposables
|
||||
|
||||
A couple large things changed with respect to events:
|
||||
|
||||
1. All model events are now exposed as event subscription methods that return [`Disposable`][disposable] objects
|
||||
1. The `subscribe()` method is no longer available on `space-pen` `View` objects
|
||||
1. An Emitter is now provided from `require 'atom'`
|
||||
|
||||
### Consuming Events
|
||||
|
||||
All events from the Atom API are now methods that return a [`Disposable`][disposable] object, on which you can call `dispose()` to unsubscribe.
|
||||
|
||||
```coffee
|
||||
# Old!
|
||||
editor.on 'changed', ->
|
||||
```
|
||||
|
||||
```coffee
|
||||
# New!
|
||||
disposable = editor.onDidChange ->
|
||||
|
||||
# You can unsubscribe at some point in the future via `dispose()`
|
||||
disposable.dispose()
|
||||
```
|
||||
|
||||
Deprecation warnings will guide you toward the correct methods.
|
||||
|
||||
#### Using a CompositeDisposable
|
||||
|
||||
You can group multiple disposables into a single disposable with a `CompositeDisposable`.
|
||||
|
||||
```coffee
|
||||
{CompositeDisposable} = require 'atom'
|
||||
|
||||
class Something
|
||||
constructor: ->
|
||||
editor = atom.workspace.getActiveTextEditor()
|
||||
@disposables = new CompositeDisposable
|
||||
@disposables.add editor.onDidChange ->
|
||||
@disposables.add editor.onDidChangePath ->
|
||||
|
||||
destroy: ->
|
||||
@disposables.dispose()
|
||||
```
|
||||
|
||||
### Removing View::subscribe and Subscriber::subscribe calls
|
||||
|
||||
There were a couple permutations of `subscribe()`. In these examples, a `CompositeDisposable` is used as it will commonly be useful where conversion is necessary.
|
||||
|
||||
#### subscribe(unsubscribable)
|
||||
|
||||
This one is very straight forward.
|
||||
|
||||
```coffee
|
||||
# Old!
|
||||
@subscribe editor.on 'changed', ->
|
||||
```
|
||||
|
||||
```coffee
|
||||
# New!
|
||||
disposables = new CompositeDisposable
|
||||
disposables.add editor.onDidChange ->
|
||||
```
|
||||
|
||||
#### subscribe(modelObject, event, method)
|
||||
|
||||
When the modelObject is an Atom model object, the change is very simple. Just use the correct event method, and add it to your CompositeDisposable.
|
||||
|
||||
```coffee
|
||||
# Old!
|
||||
@subscribe editor, 'changed', ->
|
||||
```
|
||||
|
||||
```coffee
|
||||
# New!
|
||||
disposables = new CompositeDisposable
|
||||
disposables.add editor.onDidChange ->
|
||||
```
|
||||
|
||||
#### subscribe(jQueryObject, selector(optional), event, method)
|
||||
|
||||
Things are a little more complicated when subscribing to a DOM or jQuery element. Atom no longer provides helpers for subscribing to elements. You can use jQuery or the native DOM APIs, whichever you prefer.
|
||||
|
||||
```coffee
|
||||
# Old!
|
||||
@subscribe $(window), 'focus', ->
|
||||
```
|
||||
|
||||
```coffee
|
||||
# New!
|
||||
{Disposable, CompositeDisposable} = require 'atom'
|
||||
disposables = new CompositeDisposable
|
||||
|
||||
# New with jQuery
|
||||
focusCallback = ->
|
||||
$(window).on 'focus', focusCallback
|
||||
disposables.add new Disposable ->
|
||||
$(window).off 'focus', focusCallback
|
||||
|
||||
# New with native APIs
|
||||
focusCallback = ->
|
||||
window.addEventListener 'focus', focusCallback
|
||||
disposables.add new Disposable ->
|
||||
window.removeEventListener 'focus', focusCallback
|
||||
```
|
||||
|
||||
### Providing Events: Using the Emitter
|
||||
|
||||
You no longer need to require `emissary` to get an emitter. We now provide an `Emitter` class from `require 'atom'`. We have a specific pattern for use of the `Emitter`. Rather than mixing it in, we instantiate a member variable, and create explicit subscription methods. For more information see the [`Emitter` docs][emitter].
|
||||
|
||||
```coffee
|
||||
# New!
|
||||
{Emitter} = require 'atom'
|
||||
|
||||
class Something
|
||||
constructor: ->
|
||||
@emitter = new Emitter
|
||||
|
||||
destroy: ->
|
||||
@emitter.dispose()
|
||||
|
||||
onDidChange: (callback) ->
|
||||
@emitter.on 'did-change', callback
|
||||
|
||||
methodThatFiresAChange: ->
|
||||
@emitter.emit 'did-change', {data: 2}
|
||||
|
||||
# Using the evented class
|
||||
something = new Something
|
||||
something.onDidChange (eventObject) ->
|
||||
console.log eventObject.data # => 2
|
||||
something.methodThatFiresAChange()
|
||||
```
|
||||
|
||||
## Subscribing To Commands
|
||||
|
||||
`$.fn.command` and `View::subscribeToCommand` are no longer available. Now we use `atom.commands.add`, and collect the results in a `CompositeDisposable`. See [the docs][commands-add] for more info.
|
||||
|
||||
```coffee
|
||||
# Old!
|
||||
atom.workspaceView.command 'core:close core:cancel', ->
|
||||
|
||||
# When inside a View class, you might see this
|
||||
@subscribeToCommand 'core:close core:cancel', ->
|
||||
```
|
||||
|
||||
```coffee
|
||||
# New!
|
||||
@disposables.add atom.commands.add 'atom-workspace',
|
||||
'core:close': ->
|
||||
'core:cancel': ->
|
||||
|
||||
# You can register commands directly on individual DOM elements in addition to
|
||||
# using selectors. When in a View class, you should have a `@element` object
|
||||
# available. `@element` is a plain HTMLElement object
|
||||
@disposables.add atom.commands.add @element,
|
||||
'core:close': ->
|
||||
'core:cancel': ->
|
||||
```
|
||||
|
||||
## Upgrading your stylesheet's selectors
|
||||
|
||||
Many selectors have changed, and we have introduced the [Shadow DOM][shadowdom] to the editor. See [Upgrading Your Package Selectors guide][upgrading-selectors] for more information in upgrading your package stylesheets.
|
||||
|
||||
## Help us improve this guide!
|
||||
|
||||
Did you hit something painful that wasn't in here? Want to reword some bit of it? Find something incorrect? Please edit [this file][guide], and send a pull request. Contributions are greatly appreciated.
|
||||
|
||||
|
||||
|
||||
|
||||
[texteditorview]:https://github.com/atom/atom-space-pen-views#texteditorview
|
||||
[scrollview]:https://github.com/atom/atom-space-pen-views#scrollview
|
||||
[selectlistview]:https://github.com/atom/atom-space-pen-views#selectlistview
|
||||
[selectlistview-example]:https://github.com/atom/command-palette/pull/19/files
|
||||
[emitter]:https://atom.io/docs/api/latest/Emitter
|
||||
[texteditor]:https://atom.io/docs/api/latest/TextEditor
|
||||
[disposable]:https://atom.io/docs/api/latest/Disposable
|
||||
[commands-add]:https://atom.io/docs/api/latest/CommandRegistry#instance-add
|
||||
[upgrading-selectors]:upgrading-your-ui-theme
|
||||
[shadowdom]:http://blog.atom.io/2014/11/18/avoiding-style-pollution-with-the-shadow-dom.html
|
||||
[guide]:https://github.com/atom/atom/blob/master/docs/upgrading/upgrading-your-package.md
|
||||
|
|
@ -1,24 +0,0 @@
|
|||
# Upgrading Your Syntax Theme
|
||||
|
||||
Text editor content is now rendered in the shadow DOM, which shields it from being styled by global style sheets to protect against accidental style pollution. For more background on the shadow DOM, check out the [Shadow DOM 101][shadow-dom-101] on HTML 5 Rocks.
|
||||
|
||||
Syntax themes are specifically intended to style only text editor content, so they are automatically loaded directly into the text editor's shadow DOM when it is enabled. This happens automatically when the the theme's `package.json` contains a `theme: "syntax"` declaration, so you don't need to change anything to target the appropriate context.
|
||||
|
||||
When theme style sheets are loaded into the text editor's shadow DOM, selectors intended to target the editor from the *outside* no longer make sense. Styles targeting the `.editor` and `.editor-colors` classes instead need to target the `:host` pseudo-element, which matches against the containing `atom-text-editor` node. Check out the [Shadow DOM 201][host-pseudo-element] article for more information about the `:host` pseudo-element.
|
||||
|
||||
Here's an example from Atom's light syntax theme. Note that the `atom-text-editor` selector intended to target the editor from the outside has been retained to allow the theme to keep working during the transition phase when it is possible to disable the shadow DOM.
|
||||
|
||||
```css
|
||||
atom-text-editor, :host { /* :host added */
|
||||
background-color: @syntax-background-color;
|
||||
color: @syntax-text-color;
|
||||
|
||||
.invisible-character {
|
||||
color: @syntax-invisible-character-color;
|
||||
}
|
||||
/* more nested selectors... */
|
||||
}
|
||||
```
|
||||
|
||||
[shadow-dom-101]: http://www.html5rocks.com/en/tutorials/webcomponents/shadowdom
|
||||
[host-pseudo-element]: http://www.html5rocks.com/en/tutorials/webcomponents/shadowdom-201#toc-style-host
|
||||
|
|
@ -1,137 +0,0 @@
|
|||
# Upgrading Your UI Theme Or Package Selectors
|
||||
|
||||
In addition to changes in Atom's scripting API, we'll also be making some breaking changes to Atom's DOM structure, requiring style sheets and keymaps in both packages and themes to be updated.
|
||||
|
||||
## Deprecation Cop
|
||||
|
||||
Deprecation cop will list usages of deprecated selector patterns to guide you. You can access it via the command palette (`cmd-shift-p`, then search for `Deprecation`). It breaks the deprecations down by package:
|
||||
|
||||
|
||||
|
||||
## Custom Tags
|
||||
|
||||
Rather than adding classes to standard HTML elements to indicate their role, Atom now uses custom element names. For example, `<div class="workspace">` has now been replaced with `<atom-workspace>`. Selectors should be updated accordingly. Note that tag names have lower specificity than classes in CSS, so you'll need to take care in converting things.
|
||||
|
||||
Old Selector | New Selector
|
||||
--------------------|--------------------------------
|
||||
`.editor` | `atom-text-editor`
|
||||
`.editor.mini` | `atom-text-editor[mini]`
|
||||
`.workspace` | `atom-workspace`
|
||||
`.horizontal` | `atom-workspace-axis.horizontal`
|
||||
`.vertical` | `atom-workspace-axis.vertical`
|
||||
`.pane-container` | `atom-pane-conatiner`
|
||||
`.pane` | `atom-pane`
|
||||
`.tool-panel` | `atom-panel`
|
||||
`.panel-top` | `atom-panel.top`
|
||||
`.panel-bottom` | `atom-panel.bottom`
|
||||
`.panel-left` | `atom-panel.left`
|
||||
`.panel-right` | `atom-panel.right`
|
||||
`.overlay` | `atom-panel.modal`
|
||||
|
||||
## Supporting the Shadow DOM
|
||||
|
||||
Text editor content is now rendered in the shadow DOM, which shields it from being styled by global style sheets to protect against accidental style pollution. For more background on the shadow DOM, check out the [Shadow DOM 101][shadow-dom-101] on HTML 5 Rocks. If you need to style text editor content in a UI theme, you'll need to circumvent this protection for any rules that target the text editor's content. Some examples of the kinds of UI theme styles needing to be updated:
|
||||
|
||||
* Highlight decorations
|
||||
* Gutter decorations
|
||||
* Line decorations
|
||||
* Scrollbar styling
|
||||
* Anything targeting a child selector of `.editor`
|
||||
|
||||
During a transition phase, it will be possible to enable or disable the text editor's shadow DOM in the settings, so themes will need to be compatible with both approaches.
|
||||
|
||||
### Shadow DOM Selectors
|
||||
|
||||
Chromium provides two tools for bypassing shadow boundaries, the `::shadow` pseudo-element and the `/deep/` combinator. For an in-depth explanation of styling the shadow DOM, see the [Shadow DOM 201][shadow-dom-201] article on HTML 5 Rocks.
|
||||
|
||||
#### ::shadow
|
||||
|
||||
The `::shadow` pseudo-element allows you to bypass a single shadow root. For example, say you want to update a highlight decoration for a linter package. Initially, the style looks as follows:
|
||||
|
||||
```css
|
||||
// Without shadow DOM support
|
||||
atom-text-editor .highlight.my-linter {
|
||||
background: hotpink;
|
||||
}
|
||||
```
|
||||
|
||||
In order for this style to apply with the shadow DOM enabled, you will need to add a second selector with the `::shadow` pseudo-element. You should leave the original selector in place so your theme continues to work with the shadow DOM disabled during the transition period.
|
||||
|
||||
```css
|
||||
// With shadow DOM support
|
||||
atom-text-editor .highlight.my-linter,
|
||||
atom-text-editor::shadow .highlight.my-linter {
|
||||
background: hotpink;
|
||||
}
|
||||
```
|
||||
|
||||
Check out the [find-and-replace][find-and-replace] package for another example of using `::shadow` to pierce the shadow DOM.
|
||||
|
||||
#### /deep/
|
||||
|
||||
The `/deep/` combinator overrides *all* shadow boundaries, making it useful for rules you want to apply globally such as scrollbar styling. Here's a snippet containing scrollbar styling for the Atom Dark UI theme before shadow DOM support:
|
||||
|
||||
```css
|
||||
// Without shadow DOM support
|
||||
.scrollbars-visible-always {
|
||||
::-webkit-scrollbar {
|
||||
width: 8px;
|
||||
height: 8px;
|
||||
}
|
||||
|
||||
::-webkit-scrollbar-track,
|
||||
::-webkit-scrollbar-corner {
|
||||
background: @scrollbar-background-color;
|
||||
}
|
||||
|
||||
::-webkit-scrollbar-thumb {
|
||||
background: @scrollbar-color;
|
||||
border-radius: 5px;
|
||||
box-shadow: 0 0 1px black inset;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
To style scrollbars even inside of the shadow DOM, each rule needs to be prefixed with `/deep/`. We use `/deep/` instead of `::shadow` because we don't care about the selector of the host element in this case. We just want our styling to apply everywhere.
|
||||
|
||||
```css
|
||||
// With shadow DOM support using /deep/
|
||||
.scrollbars-visible-always {
|
||||
/deep/ ::-webkit-scrollbar {
|
||||
width: 8px;
|
||||
height: 8px;
|
||||
}
|
||||
|
||||
/deep/ ::-webkit-scrollbar-track,
|
||||
/deep/ ::-webkit-scrollbar-corner {
|
||||
background: @scrollbar-background-color;
|
||||
}
|
||||
|
||||
/deep/ ::-webkit-scrollbar-thumb {
|
||||
background: @scrollbar-color;
|
||||
border-radius: 5px;
|
||||
box-shadow: 0 0 1px black inset;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Context-Targeted Style Sheets
|
||||
|
||||
The selector features discussed above allow you to target shadow DOM content with specific selectors, but Atom also allows you to target a specific shadow DOM context with an entire style sheet. The context into which a style sheet is loaded is based on the file name. If you want to load a style sheet into the editor, name it with the `.atom-text-editor.less` or `.atom-text-editor.css` extensions.
|
||||
|
||||
```
|
||||
my-ui-theme/
|
||||
styles/
|
||||
index.less # loaded globally
|
||||
index.atom-text-editor.less # loaded in the text editor shadow DOM
|
||||
```
|
||||
|
||||
Check out this [style sheet](https://github.com/atom/decoration-example/blob/master/styles/decoration-example.atom-text-editor.less) from the decoration-example package for an example of context-targeting.
|
||||
|
||||
Inside a context-targeted style sheet, there's no need to use the `::shadow` or `/deep/` expressions. If you want to refer to the element containing the shadow root, you can use the `::host` pseudo-element.
|
||||
|
||||
During the transition phase, style sheets targeting the `atom-text-editor` context will *also* be loaded globally. Make sure you update your selectors in a way that maintains compatibility with the shadow DOM being disabled. That means if you use a `::host` pseudo element, you should also include the same style rule matches against `atom-text-editor`.
|
||||
|
||||
[shadow-dom-101]: http://www.html5rocks.com/en/tutorials/webcomponents/shadowdom
|
||||
[shadow-dom-201]: http://www.html5rocks.com/en/tutorials/webcomponents/shadowdom-201#toc-style-cat-hat
|
||||
[find-and-replace]: https://github.com/atom/find-and-replace/blob/95351f261bc384960a69b66bf12eae8002da63f9/styles/find-and-replace.less#L10
|
||||
|
|
@ -1,136 +0,0 @@
|
|||
# Writing specs
|
||||
|
||||
Atom uses [Jasmine](http://jasmine.github.io/1.3/introduction.html) as its spec framework. Any new functionality should have specs to guard against regressions.
|
||||
|
||||
## Create a new spec
|
||||
|
||||
[Atom specs](https://github.com/atom/atom/tree/master/spec) and [package specs](https://github.com/atom/markdown-preview/tree/master/spec) are added to their respective `spec` directory. The example below creates a spec for Atom core.
|
||||
|
||||
0. Create a spec file
|
||||
|
||||
Spec files **must** end with `-spec` so add `sample-spec.coffee` to `atom/spec`.
|
||||
|
||||
0. Add one or more `describe` methods
|
||||
|
||||
The `describe` method takes two arguments, a description and a function. If the description explains a behavior it typically begins with `when`; if it is more like a unit test it begins with the method name.
|
||||
|
||||
```coffee
|
||||
describe "when a test is written", ->
|
||||
# contents
|
||||
```
|
||||
|
||||
or
|
||||
|
||||
```coffee
|
||||
describe "Editor::moveUp", ->
|
||||
# contents
|
||||
```
|
||||
|
||||
0. Add one or more `it` method
|
||||
|
||||
The `it` method also takes two arguments, a description and a function. Try and make the description flow with the `it` method. For example, a description of `this should work` doesn't read well as `it this should work`. But a description of `should work` sounds great as `it should work`.
|
||||
|
||||
```coffee
|
||||
describe "when a test is written", ->
|
||||
it "has some expectations that should pass", ->
|
||||
# Expectations
|
||||
```
|
||||
|
||||
0. Add one or more expectations
|
||||
|
||||
The best way to learn about expectations is to read the [jasmine documentation](http://jasmine.github.io/1.3/introduction.html#section-Expectations) about them. Below is a simple example.
|
||||
|
||||
```coffee
|
||||
describe "when a test is written", ->
|
||||
it "has some expectations that should pass", ->
|
||||
expect("apples").toEqual("apples")
|
||||
expect("oranges").not.toEqual("apples")
|
||||
```
|
||||
|
||||
## Asynchronous specs
|
||||
|
||||
Writing Asynchronous specs can be tricky at first. Some examples.
|
||||
|
||||
0. Promises
|
||||
|
||||
Working with promises is rather easy in Atom. You can use our `waitsForPromise` function.
|
||||
|
||||
```coffee
|
||||
describe "when we open a file", ->
|
||||
it "should be opened in an editor", ->
|
||||
waitsForPromise ->
|
||||
atom.workspace.open('c.coffee').then (editor) ->
|
||||
expect(editor.getPath()).toContain 'c.coffee'
|
||||
```
|
||||
|
||||
This method can be used in the `describe`, `it`, `beforeEach` and `afterEach` functions.
|
||||
|
||||
```coffee
|
||||
describe "when we open a file", ->
|
||||
beforeEach ->
|
||||
waitsForPromise ->
|
||||
atom.workspace.open 'c.coffee'
|
||||
|
||||
it "should be opened in an editor", ->
|
||||
expect(atom.workspace.getActiveTextEditor().getPath()).toContain 'c.coffee'
|
||||
|
||||
```
|
||||
|
||||
If you need to wait for multiple promises use a new `waitsForPromise` function for each promise. (Caution: Without `beforeEach` this example will fail!)
|
||||
|
||||
```coffee
|
||||
describe "waiting for the packages to load", ->
|
||||
|
||||
beforeEach ->
|
||||
waitsForPromise ->
|
||||
atom.workspace.open('sample.js')
|
||||
waitsForPromise ->
|
||||
atom.packages.activatePackage('tabs')
|
||||
waitsForPromise ->
|
||||
atom.packages.activatePackage('tree-view')
|
||||
|
||||
it 'should have waited long enough', ->
|
||||
expect(atom.packages.isPackageActive('tabs')).toBe true
|
||||
expect(atom.packages.isPackageActive('tree-view')).toBe true
|
||||
```
|
||||
|
||||
0. Asynchronous functions with callbacks
|
||||
|
||||
Specs for asynchronous functions can be done using the `waitsFor` and `runs` functions. A simple example.
|
||||
|
||||
```coffee
|
||||
describe "fs.readdir(path, cb)", ->
|
||||
it "is async", ->
|
||||
spy = jasmine.createSpy('fs.readdirSpy')
|
||||
|
||||
fs.readdir('/tmp/example', spy)
|
||||
waitsFor ->
|
||||
spy.callCount > 0
|
||||
runs ->
|
||||
exp = [null, ['example.coffee']]
|
||||
expect(spy.mostRecentCall.args).toEqual exp
|
||||
expect(spy).toHaveBeenCalledWith(null, ['example.coffee'])
|
||||
```
|
||||
|
||||
For a more detailed documentation on asynchronous tests please visit the [jasmine documentation](http://jasmine.github.io/1.3/introduction.html#section-Asynchronous_Support).
|
||||
|
||||
|
||||
## Running specs
|
||||
|
||||
Most of the time you'll want to run specs by triggering the `application:run-package-specs` command. This command is not only to run package specs, it is also for Atom core specs. This will run all the specs in the current project's spec directory. If you want to run the Atom core specs and **all** the default package specs trigger the `window:run-all-specs` command.
|
||||
|
||||
To run a limited subset of specs use the `fdescribe` or `fit` methods. You can use those to focus a single spec or several specs. In the example above, focusing an individual spec looks like this:
|
||||
|
||||
```coffee
|
||||
describe "when a test is written", ->
|
||||
fit "has some expectations that should pass", ->
|
||||
expect("apples").toEqual("apples")
|
||||
expect("oranges").not.toEqual("apples")
|
||||
```
|
||||
|
||||
### Running on CI
|
||||
|
||||
It is now easy to run the specs in a CI environment like Travis and AppVeyor. See the
|
||||
[Travis CI For Your Packages](http://blog.atom.io/2014/04/25/ci-for-your-packages.html)
|
||||
and [AppVeyor CI For Your Packages](http://blog.atom.io/2014/07/28/windows-ci-for-your-packages.html)
|
||||
posts for more details.
|
||||
|
|
@ -1,158 +0,0 @@
|
|||
# Create Your First Package
|
||||
|
||||
This tutorial will guide you though creating a simple command that replaces the
|
||||
selected text with [ascii art](https://en.wikipedia.org/wiki/ASCII_art). When you
|
||||
run our new command with the word "cool" selected, it will be replaced with:
|
||||
|
||||
```
|
||||
___
|
||||
/\_ \
|
||||
___ ___ ___\//\ \
|
||||
/'___\ / __`\ / __`\\ \ \
|
||||
/\ \__//\ \L\ \/\ \L\ \\_\ \_
|
||||
\ \____\ \____/\ \____//\____\
|
||||
\/____/\/___/ \/___/ \/____/
|
||||
```
|
||||
|
||||
The final package can be viewed at
|
||||
[https://github.com/atom/ascii-art](https://github.com/atom/ascii-art).
|
||||
|
||||
To begin, press `cmd-shift-P` to bring up the [Command
|
||||
Palette](https://github.com/atom/command-palette). Type "generate package" and
|
||||
select the "Package Generator: Generate Package" command. Now we need to name
|
||||
the package. Try to avoid naming your package with the *atom-* prefix, for
|
||||
example we are going to call this package _ascii-art_.
|
||||
|
||||
Atom will open a new window with the contents of our new _ascii-art_ package
|
||||
displayed in the Tree View. Because this window is opened **after** the package
|
||||
is created, the ASCII Art package will be loaded and available in our new
|
||||
window. To verify this, toggle the Command Palette (`cmd-shift-P`) and type
|
||||
"ASCII Art". You'll see a new `ASCII Art: Toggle` command. When triggered, this
|
||||
command displays a default message.
|
||||
|
||||
Now let's edit the package files to make our ASCII Art package do something
|
||||
interesting. Since this package doesn't need any UI, we can remove all
|
||||
view-related code. Start by opening up _lib/ascii-art.coffee_. Remove all view
|
||||
code, so the `module.exports` section looks like this:
|
||||
|
||||
```coffeescript
|
||||
module.exports =
|
||||
activate: ->
|
||||
```
|
||||
|
||||
## Create a Command
|
||||
|
||||
Now let's add a command. We recommend that you namespace your commands with the
|
||||
package name followed by a `:`, so we'll call our command `ascii-art:convert`.
|
||||
Register the command in _lib/ascii-art.coffee_:
|
||||
|
||||
```coffeescript
|
||||
module.exports =
|
||||
activate: ->
|
||||
atom.commands.add 'atom-workspace', "ascii-art:convert", => @convert()
|
||||
|
||||
convert: ->
|
||||
# This assumes the active pane item is an editor
|
||||
editor = atom.workspace.getActivePaneItem()
|
||||
editor.insertText('Hello, World!')
|
||||
```
|
||||
|
||||
The `atom.commands.add` method takes a selector, command name, and a callback.
|
||||
The callback executes when the command is triggered on an element matching the
|
||||
selector. In this case, when the command is triggered the callback will call the
|
||||
`convert` method and insert 'Hello, World!'.
|
||||
|
||||
## Reload the Package
|
||||
|
||||
Before we can trigger `ascii-art:convert`, we need to load the latest code for
|
||||
our package by reloading the window. Run the command `window:reload` from the
|
||||
command palette or by pressing `ctrl-alt-cmd-l`.
|
||||
|
||||
## Trigger the Command
|
||||
|
||||
Now open the command panel and search for the `ascii-art:convert` command. But
|
||||
it's not there! To fix this, open _package.json_ and find the property called
|
||||
`activationCommands`. Activation Events speed up load time by allowing Atom to
|
||||
delay a package's activation until it's needed. So remove the existing command
|
||||
and add `ascii-art:convert` to the `activationCommands` array:
|
||||
|
||||
```json
|
||||
"activationCommands": ["ascii-art:convert"],
|
||||
```
|
||||
|
||||
First, reload the window by running the command `window:reload`. Now when you
|
||||
run the `ascii-art:convert` command it will output 'Hello, World!'
|
||||
|
||||
## Add a Key Binding
|
||||
|
||||
Now let's add a key binding to trigger the `ascii-art:convert` command. Open
|
||||
_keymaps/ascii-art.cson_ and add a key binding linking `ctrl-alt-a` to the
|
||||
`ascii-art:convert` command. You can delete the pre-existing key binding since
|
||||
you don't need it anymore. When finished, the file will have this:
|
||||
|
||||
```coffeescript
|
||||
'atom-text-editor':
|
||||
'ctrl-alt-a': 'ascii-art:convert'
|
||||
```
|
||||
|
||||
Notice `atom-text-editor` on the first line. Just like CSS, keymap selectors
|
||||
*scope* key bindings so they only apply to specific elements. In this case, our
|
||||
binding is only active for elements matching the `atom-text-editor` selector. If
|
||||
the Tree View has focus, pressing `ctrl-alt-a` won't trigger the
|
||||
`ascii-art:convert` command. But if the editor has focus, the
|
||||
`ascii-art:convert` method *will* be triggered. More information on key bindings
|
||||
can be found in the [keymaps](advanced/keymaps.html) documentation.
|
||||
|
||||
Now reload the window and verify that the key binding works! You can also verify
|
||||
that it **doesn't** work when the Tree View is focused.
|
||||
|
||||
## Add the ASCII Art
|
||||
|
||||
Now we need to convert the selected text to ASCII art. To do this we will use
|
||||
the [figlet](https://npmjs.org/package/figlet) [node](http://nodejs.org/) module
|
||||
from [npm](https://npmjs.org/). Open _package.json_ and add the latest version of
|
||||
figlet to the dependencies:
|
||||
|
||||
```json
|
||||
"dependencies": {
|
||||
"figlet": "1.0.8"
|
||||
}
|
||||
```
|
||||
|
||||
After saving the file, run the command 'update-package-dependencies:update' from
|
||||
the Command Palette. This will install the package's node module dependencies,
|
||||
only figlet in this case. You will need to run
|
||||
'update-package-dependencies:update' whenever you update the dependencies field
|
||||
in your _package.json_ file.
|
||||
|
||||
Now require the figlet node module in _lib/ascii-art.coffee_ and instead of
|
||||
inserting 'Hello, World!' convert the selected text to ASCII art.
|
||||
|
||||
```coffeescript
|
||||
convert: ->
|
||||
# This assumes the active pane item is an editor
|
||||
editor = atom.workspace.getActivePaneItem()
|
||||
selection = editor.getLastSelection()
|
||||
|
||||
figlet = require 'figlet'
|
||||
figlet selection.getText(), {font: "Larry 3D 2"}, (error, asciiArt) ->
|
||||
if error
|
||||
console.error(error)
|
||||
else
|
||||
selection.insertText("\n#{asciiArt}\n")
|
||||
```
|
||||
|
||||
Select some text in an editor window and hit `ctrl-alt-a`. :tada: You're now an
|
||||
ASCII art professional!
|
||||
|
||||
## Further reading
|
||||
|
||||
* [Getting your project on GitHub guide](http://guides.github.com/overviews/desktop)
|
||||
|
||||
* [Writing specs](writing-specs.md) for your package
|
||||
|
||||
* [Creating a package guide](creating-a-package.html) for more information
|
||||
on the mechanics of packages
|
||||
|
||||
* [Publishing a package guide](publishing-a-package.html) for more information
|
||||
on publishing your package to [atom.io](https://atom.io)
|
||||
|
|
@ -1,14 +0,0 @@
|
|||
# Your init script
|
||||
#
|
||||
# Atom will evaluate this file each time a new window is opened. It is run
|
||||
# after packages are loaded/activated and after the previous editor state
|
||||
# has been restored.
|
||||
#
|
||||
# An example hack to make opened Markdown files always be soft wrapped:
|
||||
#
|
||||
# path = require 'path'
|
||||
#
|
||||
# atom.workspaceView.eachEditorView (editorView) ->
|
||||
# editor = editorView.getEditor()
|
||||
# if path.extname(editor.getPath()) is '.md'
|
||||
# editor.setSoftWrapped(true)
|
||||
|
|
@ -1,25 +0,0 @@
|
|||
/*
|
||||
* Your Stylesheet
|
||||
*
|
||||
* This stylesheet is loaded when Atom starts up and is reloaded automatically
|
||||
* when it is changed.
|
||||
*
|
||||
* If you are unfamiliar with LESS, you can read more about it here:
|
||||
* http://www.lesscss.org
|
||||
*/
|
||||
|
||||
.tree-view {
|
||||
|
||||
}
|
||||
|
||||
// style the background and foreground colors on the atom-text-editor-element
|
||||
// itself
|
||||
atom-text-editor {
|
||||
|
||||
}
|
||||
|
||||
// To style other content in the text editor's shadow DOM, use the ::shadow
|
||||
// expression
|
||||
atom-text-editor::shadow .cursor {
|
||||
|
||||
}
|
||||
|
|
@ -37,7 +37,7 @@ cp "$TARGET/usr/share/nylas/resources/LICENSE.md" "$TARGET/usr/share/doc/nylas/c
|
|||
|
||||
# Add lintian overrides
|
||||
mkdir -m $FILE_MODE -p "$TARGET/usr/share/lintian/overrides"
|
||||
cp "$ROOT/resources/linux/debian/lintian-overrides" "$TARGET/usr/share/lintian/overrides/nylas"
|
||||
cp "$ROOT/build/resources/linux/debian/lintian-overrides" "$TARGET/usr/share/lintian/overrides/nylas"
|
||||
|
||||
# Remove executable bit from .node files
|
||||
find "$TARGET" -type f -name "*.node" -exec chmod a-x {} \;
|
||||
|
|
|
|||
|
|
@ -10,7 +10,7 @@ module.exports =
|
|||
class AtomWindow
|
||||
_.extend @prototype, EventEmitter.prototype
|
||||
|
||||
@iconPath: path.resolve(__dirname, '..', '..', 'resources', 'nylas.png')
|
||||
@iconPath: path.resolve(__dirname, '..', '..', 'build', 'resources', 'nylas.png')
|
||||
@includeShellLoadTime: true
|
||||
|
||||
browserWindow: null
|
||||
|
|
|
|||
Loading…
Reference in a new issue