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

   1 # Atom SpacePen Views [![Build Status](https://travis-ci.org/atom/atom-space-pen-views.svg?branch=master)](https://travis-ci.org/atom/atom-space-pen-views)
   2
   3 This library contains SpacePen views that used to be provided as part of Atom
   4 Core. `TextEditorView`, `SelectListView`, and `ScrollView` exports from the
   5 `atom` module are now deprecated will soon be removed, but can still be used in
   6 packages by depending on this library in your `package.json`.
   7
   8 ## TextEditorView
   9
  10 A text editor can now be created in Atom by inserting an `<atom-text-editor>`
  11 tag in any location you want an editor. However, if you still want to use the
  12 SpacePen view in order to conveniently convert packages off the deprecated
  13 export, you can use this class.
  14
  15 ### Example
  16
  17 ```coffee
  18 {View} = require 'space-pen'
  19 {TextEditorView} = require 'atom-space-pen-views'
  20
  21 class MyView extends View
  22   @content: ->
  23     @div =>
  24       @div "Type your answer:"
  25       @subview 'answer', new TextEditorView(mini: true)
  26 ```
  27
  28 ### Constructor Params
  29
  30 Pass an optional params object to the constructor with the following keys:
  31
  32 * `mini` If `true`, will construct a single-line editor for use as an input
  33     field.
  34 * `placeholderText` A string of placeholder text to appear in the editor when
  35     empty
  36
  37 ### Methods
  38
  39 #### `::getModel`
  40
  41 Returns the underlying `TextEditor` model instance.
  42
  43 ## ScrollView
  44
  45  Handles several core events to update scroll position:
  46
  47  * `core:move-up` Scrolls the view up
  48  * `core:move-down` Scrolls the view down
  49  * `core:page-up` Scrolls the view up by the height of the page
  50  * `core:page-down` Scrolls the view down by the height of the page
  51  * `core:move-to-top` Scrolls the editor to the top
  52  * `core:move-to-bottom` Scroll the editor to the bottom
  53
  54  Subclasses must call `super` if overriding the `initialize` method.
  55
  56 ### Example
  57
  58  ```coffee
  59  {ScrollView} = require 'atom-space-pen-views'
  60
  61  class MyView extends ScrollView
  62    @content: ->
  63      @div()
  64
  65    initialize: ->
  66      super
  67      @text('super long content that will scroll')
  68  ```
  69
  70 ## SelectListView
  71
  72 Essential: Provides a view that renders a list of items with an editor that
  73 filters the items. Used by many packages such as the fuzzy-finder,
  74 command-palette, symbols-view and autocomplete.
  75
  76
  77 ### Example
  78
  79 ```coffee
  80 {SelectListView} = require 'atom-space-pen-views'
  81
  82 class MySelectListView extends SelectListView
  83  initialize: ->
  84    super
  85    @addClass('overlay from-top')
  86    @setItems(['Hello', 'World'])
  87    @panel ?= atom.workspace.addModalPanel(item: this)
  88    @panel.show()
  89    @focusFilterEditor()
  90
  91  viewForItem: (item) ->
  92    "<li>#{item}</li>"
  93
  94  confirmed: (item) ->
  95    console.log("#{item} was selected")
  96
  97  cancelled: ->
  98    console.log("This view was cancelled")
  99 ```
 100
 101 ## Methods
 102
 103 ### Subclasses Must Implement
 104
 105 #### `::viewForItem`
 106
 107 Create a view for the given model item. This method must be overridden by
 108 subclasses. Called when the item is about to appended to the list view.
 109
 110 * `item` The model item being rendered. This will always be one of the items
 111   previously passed to `::setItems`.
 112
 113 Returns a String of HTML, DOM element, jQuery object, or View. Note the root element must be an `li`.
 114
 115 #### `::confirmed`
 116
 117 Callback function for when an item is selected. This method must
 118 be overridden by subclasses.
 119
 120 * `item` The selected model item. This will always be one of the items
 121   previously passed to `::setItems`.
 122
 123 Returns a DOM element, jQuery object, or {View}.
 124
 125 ### Managing the list of items
 126
 127 #### `::setItems`
 128
 129 Set the array of items to display in the list. This should be
 130 model items, not actual views. `::viewForItem` will be called to render the
 131 item when it is being appended to the list view.
 132
 133 * `items` The array of model items to display in the list (default: []).
 134
 135 #### `::getSelectedItem`
 136
 137 Get the model item that is currently selected in the list view.
 138
 139 #### `::getFilterKey`
 140
 141 Get the property name to use when filtering items.
 142
 143 This method may be overridden by classes to allow fuzzy filtering based
 144 on a specific property of the item objects.
 145
 146 For example if the objects you pass to {::setItems} are of the type
 147 `{"id": 3, "name": "Atom"}` then you would return `"name"` from this method
 148 to fuzzy filter by that property when text is entered into this view's
 149 editor.
 150
 151
 152 #### `::getFilterQuery`
 153
 154 Get the filter query to use when fuzzy filtering the visible elements.
 155
 156 By default this method returns the text in the mini editor but it can be
 157 overridden by subclasses if needed.
 158
 159 Returns a {String} to use when fuzzy filtering the elements to display.
 160
 161
 162 #### `::setMaxItems`
 163
 164 Set the maximum numbers of items to display in the list.
 165
 166 This should be called before `setItems` is called or else the first time the
 167 list displays it will include all the items.
 168
 169 * `maxItems` The maximum {Number} of items to display.
 170
 171 #### `::populateList`
 172
 173 Extended: Populate the list view with the model items previously set by calling
 174 {::setItems}.
 175
 176 Subclasses may override this method but should always call `super`.
 177
 178 ### Messages
 179
 180 #### `::setError`
 181
 182 Set the error message to display.
 183
 184 * `message` A string with an error message (default: '').
 185
 186 #### `::setLoading`
 187
 188 Set the loading message to display.
 189
 190 * `message` A string with a loading message (default: '').
 191
 192 #### `::getEmptyMessage`
 193
 194 Get the message to display when there are no items.
 195
 196 Subclasses may override this method to customize the message.
 197
 198 * `itemCount` The {Number} of items in the array specified to {::setItems}
 199 * `filteredItemCount` The {Number} of items that pass the fuzzy filter test.
 200
 201 Returns a {String} message (default: 'No matches found').
 202
 203 ### View Actions
 204
 205 #### `::cancel`
 206
 207 Cancel and close this select list view.
 208
 209 This restores focus to the previously focused element if `::storeFocusedElement`
 210 was called prior to this view being attached.
 211
 212 #### `::focusFilterEditor`
 213
 214 Focus the fuzzy filter editor view.
 215
 216 #### `::storeFocusedElement`
 217
 218 Store the currently focused element. This element will be given back focus when
 219 `::cancel` is called.