github/atom
1
1
Fork 0
mirror of https://github.com/atom/atom.git synced 2026-01-22 13:28:01 -05:00
Code Issues Packages Projects Releases Wiki Activity

Update configuration docs

Browse Source
This commit is contained in:
Nathan Sobo
2014-01-21 20:56:30 -07:00
parent 8ca8ac5efc
commit 8d193d542b
1 changed files with 27 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files

39
docs/internals/configuration.md
View File

@@ -3,14 +3,15 @@
### Reading Config Settings
If you are writing a package that you want to make configurable, you'll need to
read config settings. You can read a value from `config` with `config.get`:
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 config.get "edtior.showInvisibles"
```
Or you can use `observeConfig` to track changes from a view object.
Or you can use the `::observeConfig` to track changes from any view object.
```coffeescript
class MyView extends View
@@ -19,7 +20,7 @@ class MyView extends View
@adjustFontSize()
```
The `observeConfig` method will call the given callback immediately with the
The `::observeConfig` 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.
@@ -35,26 +36,40 @@ You can add the ability to observe config values to non-view classes by
extending their prototype with the `ConfigObserver` mixin:
```coffeescript
ConfigObserver = require 'config-observer'
_.extend MyClass.prototype, ConfigObserver
{ConfigObserver} = require 'atom'
class MyClass
ConfigObserver.includeInto(this)
constructor: ->
@observeConfig 'editor.showInvisibles', -> # ...
destroy: ->
@unobserveConfig()
```
### Writing Config Settings
As discussed above, the config database is automatically populated from
`config.cson` when Atom is started, but you can programmatically write to it in
the following way:
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
config.set("core.showInvisibles", true)
atom.config.set("core.showInvisibles", true)
```
config.pushAtKeyPath("core.disabledPackages", "wrap-guide")
You should never mutate the value of a config key, because that would circumvent
the notification of observers. You can however use methods like `pushAtKeyPath`,
`unshiftAtKeyPath`, and `removeAtKeyPath` to manipulate mutable config values.
```coffeescript
atom.config.pushAtKeyPath("core.disabledPackages", "wrap-guide")
atom.config.removeAtKeyPath("core.disabledPackages", "terminal")
```
You can also use `setDefaults`, which will assign default values for keys that
are always overridden by values assigned with `set`. Defaults are not written out
to the the `config.json` file to prevent it from becoming cluttered.
are always overridden by values assigned with `set`. Defaults are not written
out to the the `config.json` file to prevent it from becoming cluttered.
```coffeescript
config.setDefaults("editor", fontSize: 18, showInvisibles: true)