git.r.bdr.sh - rbdr/dotfiles/blob - atom/packages/ex-mode/node_modules/space-pen/README.md

   1 # SpacePen [![Build Status](https://travis-ci.org/atom/space-pen.svg?branch=master)](https://travis-ci.org/atom/space-pen)
   2
   3 **Version 5.x of SpacePen is intended to be included as a direct dependency of 1.0-compatible Atom packages. If you're looking for SpacePen 3.x, used in [Atom Core](https://github.com/atom/atom), check out the [3.x branch](https://github.com/atom/space-pen/tree/3.x).**
   4
   5 ## Write markup on the final frontier
   6
   7 SpacePen is a powerful but minimalistic client-side view framework for
   8 CoffeeScript. It combines the "view" and "controller" into a single jQuery
   9 object, whose markup is expressed with an embedded DSL similar to Markaby for
  10 Ruby.
  11
  12 ## Changes In Version 4
  13
  14 This version of SpacePen depends on HTML 5 custom elements to support lifecycle
  15 hooks that previously depended on all DOM manipulation being performed via
  16 jQuery. The `afterAttach` and `beforeRemove` hooks have been replaced with
  17 `attached` and `detached` and their semantics have been altered.
  18
  19 If you need to use SpacePen in an environment that doesn't support custom
  20 elements, consider using the previous major version or switching frameworks.
  21
  22 ## Basics
  23
  24 View objects extend from the View class and have a @content class method where
  25 you express their HTML contents with an embedded markup DSL:
  26
  27 ```coffeescript
  28 class Spacecraft extends View
  29   @content: ->
  30     @div =>
  31       @h1 "Spacecraft"
  32       @ol =>
  33         @li "Apollo"
  34         @li "Soyuz"
  35         @li "Space Shuttle"
  36 ```
  37
  38 Views descend from jQuery's prototype, so when you construct one you can call
  39 jQuery methods on it just as you would a DOM fragment created with `$(...)`.
  40
  41 ```coffeescript
  42 view = new Spacecraft
  43 view.find('ol').append('<li>Star Destroyer</li>')
  44
  45 view.on 'click', 'li', ->
  46   alert "They clicked on #{$(this).text()}"
  47 ```
  48
  49 But SpacePen views are more powerful than normal jQuery fragments because they
  50 let you define custom methods:
  51
  52 ```coffeescript
  53 class Spacecraft extends View
  54   @content: -> ...
  55
  56   addSpacecraft: (name) ->
  57     @find('ol').append "<li>#{name}</li>"
  58
  59
  60 view = new Spacecraft
  61 view.addSpacecraft "Enterprise"
  62 ```
  63
  64 You can also pass arguments on construction, which get passed to both the
  65 `@content` method and the view's constructor.
  66
  67 ```coffeescript
  68 class Spacecraft extends View
  69   @content: (params) ->
  70     @div =>
  71       @h1 params.title
  72       @ol =>
  73         @li name for name in params.spacecraft
  74
  75 view = new Spacecraft(title: "Space Weapons", spacecraft: ["TIE Fighter", "Death Star", "Warbird"])
  76 ```
  77
  78 Methods from the jQuery prototype can be gracefully overridden using `super`:
  79
  80 ```coffeescript
  81 class Spacecraft extends View
  82   @content: -> ...
  83
  84   hide: ->
  85     console.log "Hiding Spacecraft List"
  86     super()
  87 ```
  88
  89 If you override the View class's constructor, ensure you call `super`.
  90 Alternatively, you can define an `initialize` method, which the constructor will
  91 call for you automatically with the constructor's arguments.
  92
  93 ```coffeescript
  94 class Spacecraft extends View
  95   @content: -> ...
  96
  97   initialize: (params) ->
  98     @title = params.title
  99 ```
 100
 101 ## Outlets and Events
 102
 103 SpacePen will automatically create named reference for any element with an
 104 `outlet` attribute. For example, if the `ol` element has an attribute
 105 `outlet=list`, the view object will have a `list` entry pointing to a jQuery
 106 wrapper for the `ol` element.
 107
 108 ```coffeescript
 109 class Spacecraft extends View
 110   @content: ->
 111     @div =>
 112       @h1 "Spacecraft"
 113       @ol outlet: "list", =>
 114         @li "Apollo"
 115         @li "Soyuz"
 116         @li "Space Shuttle"
 117
 118   addSpacecraft: (name) ->
 119     @list.append("<li>#{name}</li>")
 120 ```
 121
 122 Elements can also have event name attributes whose value references a custom
 123 method. For example, if a `button` element has an attribute
 124 `click=launchSpacecraft`, then SpacePen will invoke the `launchSpacecraft`
 125 method on the button's parent view when it is clicked:
 126
 127 ```coffeescript
 128 class Spacecraft extends View
 129   @content: ->
 130     @div =>
 131       @h1 "Spacecraft"
 132       @ol =>
 133         @li click: 'launchSpacecraft', "Saturn V"
 134
 135   launchSpacecraft: (event, element) ->
 136     console.log "Preparing #{element.name} for launch!"
 137 ```
 138 ## Markup DSL Details
 139
 140 ### Tag Methods (`@div`, `@h1`, etc.)
 141
 142 As you've seen so far, the markup DSL is pretty straightforward. From the
 143 `@content` class method or any method it calls, just invoke instance methods
 144 named for the HTML tags you want to generate. There are 3 types of arguments you
 145 can pass to a tag method:
 146
 147 * *Strings*: The string will be HTML-escaped and used as the text contents of the generated tag.
 148
 149 * *Hashes*: The key-value pairs will be used as the attributes of the generated tag.
 150
 151 * *Functions* (bound with `=>`): The function will be invoked in-between the open and closing tag to produce the HTML element's contents.
 152
 153 If you need to emit a non-standard tag, you can use the `@tag(name, args...)`
 154 method to name the tag with a string:
 155
 156 ```coffeescript
 157 @tag 'bubble', type: "speech", => ...
 158 ```
 159
 160 ### Text Methods
 161
 162 * `@text(string)`: Emits the HTML-escaped string as text wherever it is called.
 163
 164 * `@raw(string)`: Passes the given string through unescaped. Use this when you need to emit markup directly that was generated beforehand.
 165
 166 ## Subviews
 167
 168 Subviews are a great way to make your view code more modular. The
 169 `@subview(name, view)` method takes a name and another view object. The view
 170 object will be inserted at the location of the call, and a reference with the
 171 given name will be wired to it from the parent view. A `parentView` reference
 172 will be created on the subview pointing at the parent.
 173
 174 ```coffeescript
 175 class Spacecraft extends View
 176   @content: (params) ->
 177     @div =>
 178       @subview 'launchController', new LaunchController(countdown: params.countdown)
 179       @h1 "Spacecraft"
 180       ...
 181 ```
 182
 183 ## Freeform Markup Generation
 184
 185 You don't need a View class to use the SpacePen markup DSL. Call `View.render`
 186 with an unbound function (`->`, not `=>`) that calls tag methods, and it will
 187 return a document fragment for ad-hoc use. This method is also assigned to the
 188 `$$` global variable for convenience.
 189
 190 ```coffeescript
 191 view.list.append $$ ->
 192   @li =>
 193     @text "Starship"
 194     @em "Enterprise"
 195 ```
 196
 197 ## jQuery extensions
 198
 199 ### $.fn.view
 200 You can retrieve the view object for any DOM element by calling `view()` on it.
 201 This usually shouldn't be necessary, as most DOM manipulation will take place
 202 within the view itself using outlet references, but is occasionally helpful.
 203
 204 ```coffeescript
 205 view = new Spacecraft
 206 $('body').append(view)
 207
 208 # assuming no other li elements on the DOM, for example purposes,
 209 # the following expression should be true
 210 $('li').view() == view
 211 ```
 212
 213 ### Attached/Detached Hooks
 214 The `initialize` method is always called when the view is still a detached DOM
 215 fragment, before it is appended to the DOM. This is usually okay, but
 216 occasionally you'll have some initialization logic that depends on the view
 217 actually being on the DOM. For example, you may depend on applying a CSS rule
 218 before measuring an element's height.
 219
 220 For these situations, use the `attached` hook. It will be called whenever your
 221 element is actually attached to the DOM. Past versions of SpacePen would also
 222 call this hook when your element was attached to another detached node, but that
 223 behavior is no longer supported.
 224
 225 To be notified when your element is detached from the DOM, implement the
 226 `detached` hook.
 227
 228 ```coffeescript
 229 class Spacecraft extends View
 230   @content: -> ...
 231
 232   attached: ->
 233     console.log "With CSS applied, my height is", @height()
 234
 235   detached: ->
 236     console.log "I have been detached."
 237 ```
 238
 239 ## Hacking on SpacePen
 240
 241 ```sh
 242 git clone https://github.com/atom/space-pen.git
 243 cd space-pen
 244 npm install
 245 npm start
 246 ```
 247
 248 * Open http://localhost:1337 to run the specs
 249 * Open http://localhost:1337/benchmark to run the benchmarks
 250 * Open http://localhost:1337/examples to browse the examples