upjs-rails 0.12.1 → 0.12.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -16,9 +16,7 @@ We need to work on this page:
16
16
  - Explain that the server needs to send `X-Up-Location` and `X-Up-Method` headers
17
17
  if an successful form submission resulted in a redirect
18
18
  - Examples
19
-
20
19
 
21
-
22
20
  @class up.form
23
21
  ###
24
22
  up.form = (($) ->
@@ -66,15 +64,15 @@ up.form = (($) ->
66
64
  The transition to use when a failed form submission updates the `options.failTarget` selector.
67
65
  Defaults to the form's `up-fail-transition` attribute, or to `options.transition`, or to `'none'`.
68
66
  @param {Number} [options.duration]
69
- The duration of the transition. See [`up.morph`](/up.motion#up.morph).
67
+ The duration of the transition. See [`up.morph`](/up.morph).
70
68
  @param {Number} [options.delay]
71
- The delay before the transition starts. See [`up.morph`](/up.motion#up.morph).
69
+ The delay before the transition starts. See [`up.morph`](/up.morph).
72
70
  @param {String} [options.easing]
73
- The timing function that controls the transition's acceleration. [`up.morph`](/up.motion#up.morph).
71
+ The timing function that controls the transition's acceleration. [`up.morph`](/up.morph).
74
72
  @param {Element|jQuery|String} [options.reveal]
75
73
  Whether to reveal the target element within its viewport.
76
74
  @param {Boolean} [options.restoreScroll]
77
- If set to `true`, this will attempt to [`restore scroll positions`](/up.layout#up.restoreScroll)
75
+ If set to `true`, this will attempt to [`restore scroll positions`](/up.restoreScroll)
78
76
  previously seen on the destination URL.
79
77
  @param {Boolean} [options.cache]
80
78
  Whether to force the use of a cached response (`true`)
@@ -153,7 +151,7 @@ up.form = (($) ->
153
151
  For instance, the following would submit the form whenever the
154
152
  text field value changes:
155
153
 
156
- up.observe('input', { change: function(value, $input) {
154
+ up.observe('input[name=query]', { change: function(value, $input) {
157
155
  up.submit($input)
158
156
  } });
159
157
 
@@ -170,8 +168,8 @@ up.form = (($) ->
170
168
  \#\#\#\# Throttling
171
169
 
172
170
  If you are concerned about fast typists causing too much
173
- load on your server, you can use a `delay` option to wait before
174
- executing the callback:
171
+ load on your server, you can use a `delay` option to wait
172
+ a few miliseconds before executing the callback:
175
173
 
176
174
  up.observe('input', {
177
175
  delay: 100,
@@ -269,7 +267,7 @@ up.form = (($) ->
269
267
 
270
268
  ###*
271
269
  Submits the form through AJAX, searches the response for the selector
272
- given in `up-target` and replaces the selector content in the current page:
270
+ given in `up-target` and [replaces](/up.replace) the selector content in the current page:
273
271
 
274
272
  <form method="post" action="/users" up-target=".main">
275
273
  ...
@@ -278,11 +276,16 @@ up.form = (($) ->
278
276
  @method form[up-target]
279
277
  @ujs
280
278
  @param {String} up-target
281
- The selector to replace if the form submission is successful (200 status code).
279
+ The selector to [replace](/up.replace) if the form submission is successful (200 status code).
282
280
  @param {String} [up-fail-target]
281
+ The selector to [replace](/up.replace) if the form submission is not successful (non-200 status code).
282
+ If omitted, Up.js will replace the `<form>` tag itself, assuming that the
283
+ server has echoed the form with validation errors.
283
284
  @param {String} [up-transition]
285
+ The animation to use when the form is replaced after a successful submission.
284
286
  @param {String} [up-fail-transition]
285
- @param {String} [up-history]
287
+ The animation to use when the form is replaced after a failed submission.
288
+ @param {String} [up-history='true']
286
289
  @param {String} [up-method]
287
290
  The HTTP method to be used to submit the form (`get`, `post`, `put`, `delete`, `patch`).
288
291
  Alternately you can use an attribute `data-method`
@@ -34,8 +34,8 @@ up.history = (($) ->
34
34
  Returns the previous URL in the browser history.
35
35
 
36
36
  Note that this will only work reliably for history changes that
37
- were applied by [`up.history.push`](#up.history.replace) or
38
- [`up.history.replace`](#up.history.replace).
37
+ were applied by [`up.history.push`](/up.history.replace) or
38
+ [`up.history.replace`](/up.history.replace).
39
39
 
40
40
  @method up.history.previousUrl
41
41
  @protected
@@ -1,5 +1,5 @@
1
1
  ###*
2
- Viewport scrolling
2
+ Application layout
3
3
  ==================
4
4
 
5
5
  This modules contains functions to scroll the viewport and reveal contained elements.
@@ -35,10 +35,10 @@ up.layout = (($) ->
35
35
  See [W3C documentation](http://www.w3.org/TR/css3-transitions/#transition-timing-function)
36
36
  for a list of pre-defined timing functions.
37
37
  @param {Number} [config.snap]
38
- When [revealing](#up.reveal) elements, Up.js will scroll an viewport
38
+ When [revealing](/up.reveal) elements, Up.js will scroll an viewport
39
39
  to the top when the revealed element is closer to the top than `config.snap`.
40
40
  @param {Number} [config.substance]
41
- A number indicating how many top pixel rows of an element to [reveal](#up.reveal).
41
+ A number indicating how many top pixel rows of an element to [reveal](/up.reveal).
42
42
  ###
43
43
  config = u.config
44
44
  duration: 0
@@ -134,7 +134,7 @@ up.layout = (($) ->
134
134
  u.resolvedDeferred()
135
135
 
136
136
  ###*
137
- @method up.viewport.finishScrolling
137
+ @method up.layout.finishScrolling
138
138
  @private
139
139
  ###
140
140
  finishScrolling = (elementOrSelector) ->
@@ -143,7 +143,7 @@ up.layout = (($) ->
143
143
  existingScrolling.resolve()
144
144
 
145
145
  ###*
146
- @method up.viewport.anchoredRight
146
+ @method up.layout.anchoredRight
147
147
  @private
148
148
  ###
149
149
  anchoredRight = ->
@@ -172,8 +172,8 @@ up.layout = (($) ->
172
172
  element are visible for the user.
173
173
 
174
174
  By default Up.js will always reveal an element before
175
- updating it with Javascript functions like [`up.replace`](/up.flow#up.replace)
176
- or UJS behavior like [`[up-target]`](/up.link#up-target).
175
+ updating it with Javascript functions like [`up.replace`](/up.replace)
176
+ or UJS behavior like [`[up-target]`](/up-target).
177
177
 
178
178
  \#\#\#\# How Up.js finds the viewport
179
179
 
@@ -183,7 +183,7 @@ up.layout = (($) ->
183
183
  - the currently open [modal](/up.modal)
184
184
  - an element with the attribute `[up-viewport]`
185
185
  - the `<body>` element
186
- - an element matching the selector you have configured using `up.viewport.config.viewports.push('my-custom-selector')`
186
+ - an element matching the selector you have configured using `up.layout.config.viewports.push('my-custom-selector')`
187
187
 
188
188
  \#\#\#\# Fixed elements obstruction the viewport
189
189
 
@@ -192,8 +192,8 @@ up.layout = (($) ->
192
192
 
193
193
  To make `up.aware` of these fixed elements you can either:
194
194
 
195
- - give the element an attribute [`up-fixed="top"`](#up-fixed-top) or [`up-fixed="bottom"`](up-fixed-bottom)
196
- - [configure default options](#up.layout.config) for `fixedTop` or `fixedBottom`
195
+ - give the element an attribute [`up-fixed="top"`](/up-fixed-top) or [`up-fixed="bottom"`](up-fixed-bottom)
196
+ - [configure default options](/up.layout.config) for `fixedTop` or `fixedBottom`
197
197
 
198
198
  @method up.reveal
199
199
  @param {String|Element|jQuery} element
@@ -338,9 +338,13 @@ up.layout = (($) ->
338
338
 
339
339
  ###*
340
340
  Saves the top scroll positions of all the
341
- viewports configured in [`up.layout.config.viewports`](#up.layout.config).
342
- The saved scroll positions can be restored by calling
343
- [`up.layout.restoreScroll()`](#up.layout.restoreScroll).
341
+ viewports configured in [`up.layout.config.viewports`](/up.layout.config).
342
+
343
+ The scroll positions will be associated with the current URL.
344
+ They can later be restored by calling [`up.layout.restoreScroll()`](/up.layout.restoreScroll)
345
+ at the same URL.
346
+
347
+ Up.js automatically saves scroll positions whenever a fragment was updated on the page.
344
348
 
345
349
  @method up.layout.saveScroll
346
350
  @param {String} [options.url]
@@ -354,8 +358,11 @@ up.layout = (($) ->
354
358
  lastScrollTops.set(url, tops)
355
359
 
356
360
  ###*
357
- Restores the top scroll positions of all the
358
- viewports configured in [`up.layout.config.viewports`](#up.layout.config).
361
+ Restores [previously saved](/up.layout.saveScroll) scroll positions of viewports
362
+ viewports configured in [`up.layout.config.viewports`](/up.layout.config).
363
+
364
+ Up.js automatically restores scroll positions when the user presses the back button.
365
+ You can disable this behavior by setting [`up.history.config.restoreScroll = false`](/up.history.config).
359
366
 
360
367
  @method up.layout.restoreScroll
361
368
  @param {jQuery} [options.around]
@@ -405,8 +412,11 @@ up.layout = (($) ->
405
412
 
406
413
 
407
414
  ###*
408
- Marks this element as a scrolling container. Apply this ttribute if your app uses
409
- a custom panel layout with fixed positioning instead of scrolling `<body>`.
415
+ Marks this element as a scrolling container ("viewport").
416
+
417
+ Apply this attribute if your app uses a custom panel layout with fixed positioning
418
+ instead of scrolling `<body>`. As an alternative you can also push a selector
419
+ matching your custom viewport to the [`up.layout.config.viewports`](/up.layout.config) array.
410
420
 
411
421
  [`up.reveal`](/up.reveal) will always try to scroll the viewport closest
412
422
  to the element that is being revealed. By default this is the `<body>` element.
@@ -101,7 +101,7 @@ up.link = (($) ->
101
101
  @param {String} [options.target='body']
102
102
  The selector to replace.
103
103
  @param {Object} options
104
- See options for [`up.replace`](/up.flow#up.replace)
104
+ See options for [`up.replace`](/up.replace)
105
105
  ###
106
106
  visit = (url, options) ->
107
107
  options = u.options(options)
@@ -109,7 +109,7 @@ up.link = (($) ->
109
109
  up.replace(selector, url, options)
110
110
 
111
111
  ###*
112
- Follows the given link via AJAX and replaces a CSS selector in the current page
112
+ Follows the given link via AJAX and [replaces](/up.replace) a CSS selector in the current page
113
113
  with corresponding elements from a new page fetched from the server.
114
114
 
115
115
  Any Up.js UJS attributes on the given link will be honored. E. g. you have this link:
@@ -122,7 +122,7 @@ up.link = (($) ->
122
122
  up.follow($link);
123
123
 
124
124
  @method up.follow
125
- @param {Element|jQuery|String} link
125
+ @param {Element|jQuery|String} linkOrSelector
126
126
  An element or selector which resolves to an `<a>` tag
127
127
  or any element that is marked up with an `up-href` attribute.
128
128
  @param {String} [options.target]
@@ -132,23 +132,23 @@ up.link = (($) ->
132
132
  @param {Function|String} [options.transition]
133
133
  A transition function or name.
134
134
  @param {Number} [options.duration]
135
- The duration of the transition. See [`up.morph`](/up.motion#up.morph).
135
+ The duration of the transition. See [`up.morph`](/up.morph).
136
136
  @param {Number} [options.delay]
137
- The delay before the transition starts. See [`up.morph`](/up.motion#up.morph).
137
+ The delay before the transition starts. See [`up.morph`](/up.morph).
138
138
  @param {String} [options.easing]
139
- The timing function that controls the transition's acceleration. [`up.morph`](/up.motion#up.morph).
139
+ The timing function that controls the transition's acceleration. [`up.morph`](/up.morph).
140
140
  @param {Element|jQuery|String} [options.reveal]
141
141
  Whether to reveal the target element within its viewport before updating.
142
142
  @param {Boolean} [options.restoreScroll]
143
- If set to `true`, this will attempt to [`restore scroll positions`](/up.layout#up.restoreScroll)
143
+ If set to `true`, this will attempt to [`restore scroll positions`](/up.restoreScroll)
144
144
  previously seen on the destination URL.
145
145
  @param {Boolean} [options.cache]
146
146
  Whether to force the use of a cached response (`true`)
147
147
  or never use the cache (`false`)
148
148
  or make an educated guess (`undefined`).
149
149
  ###
150
- follow = (link, options) ->
151
- $link = $(link)
150
+ follow = (linkOrSelector, options) ->
151
+ $link = $(linkOrSelector)
152
152
 
153
153
  options = u.options(options)
154
154
  url = u.option($link.attr('up-href'), $link.attr('href'))
@@ -164,10 +164,18 @@ up.link = (($) ->
164
164
  up.replace(selector, url, options)
165
165
 
166
166
  ###*
167
+ Returns the HTTP method that should be used when following the given link.
168
+
169
+ Looks at the link's `up-method` or `data-method` attribute.
170
+ Defaults to `get`.
171
+
167
172
  @protected
168
173
  @method up.link.followMethod
174
+ @param linkOrSelector
175
+ @param options.method {String}
169
176
  ###
170
- followMethod = ($link, options) ->
177
+ followMethod = (linkOrSelector, options) ->
178
+ $link = $(linkOrSelector)
171
179
  options = u.options(options)
172
180
  u.option(options.method, $link.attr('up-method'), $link.attr('data-method'), 'get').toUpperCase()
173
181
 
@@ -304,7 +312,7 @@ up.link = (($) ->
304
312
  <a href="/users" up-follow>User list</a>
305
313
 
306
314
  To only update a fragment instead of the entire page,
307
- see [`up-target`](#up-target).
315
+ see [`up-target`](/up-target).
308
316
 
309
317
  \#\#\#\# Turn any element into a link
310
318
 
@@ -345,7 +353,7 @@ up.link = (($) ->
345
353
  </div>
346
354
 
347
355
  In the example above, clicking anywhere within `.notification` element
348
- would [follow](#up-follow) the *Close* link.
356
+ would [follow](/up.follow) the *Close* link.
349
357
 
350
358
  `up-expand` honors all the UJS behavior in expanded links
351
359
  (`up-target`, `up-instant`, `up-preload`, etc.).
@@ -372,9 +380,9 @@ up.link = (($) ->
372
380
  Marks up the current link to be followed *as fast as possible*.
373
381
  This is done by:
374
382
 
375
- - [Following the link through AJAX](/up.link#up-target) instead of a full page load
376
- - [Preloading the link's destination URL](/up.proxy#up-preload)
377
- - [Triggering the link on `mousedown`](/up.link#up-instant) instead of on `click`
383
+ - [Following the link through AJAX](/up-target) instead of a full page load
384
+ - [Preloading the link's destination URL](/up-preload)
385
+ - [Triggering the link on `mousedown`](/up-instant) instead of on `click`
378
386
 
379
387
  Use `up-dash` like this:
380
388
 
@@ -21,15 +21,36 @@ up.magic = (($) ->
21
21
  DESTROYABLE_CLASS = 'up-destroyable'
22
22
  DESTROYER_KEY = 'up-destroyer'
23
23
 
24
+ liveDescriptions = []
25
+ defaultLiveDescriptions = null
26
+
24
27
  ###*
25
- Binds an event handler to the document, which will be executed whenever the
26
- given event is triggered on the given selector:
28
+ # Convert an Up.js style listener (second argument is the event target
29
+ # as a jQuery collection) to a vanilla jQuery listener
30
+ ###
31
+ upListenerToJqueryListener = (upListener) ->
32
+ (event) ->
33
+ $me = event.$element || $(this)
34
+ upListener.apply($me.get(0), [event, $me, data($me)])
35
+
36
+ ###*
37
+ Listens to an event on `document`.
38
+
39
+ The given event listener which will be executed whenever the
40
+ given event is [triggered](/up.emit) on the given selector:
27
41
 
28
42
  up.on('click', '.button', function(event, $element) {
29
43
  console.log("Someone clicked the button %o", $element);
30
44
  });
31
45
 
32
- This is roughly equivalent to binding a jQuery element to `document`.
46
+ This is roughly equivalent to binding an event listener to `document`:
47
+
48
+ $(document).on('click', '.button', function(event) {
49
+ console.log("Someone clicked the button %o", $(this));
50
+ });
51
+
52
+ Other than jQuery, Up.js will silently discard event listeners
53
+ on [browsers that it doesn't support](/up.browser.isSupported).
33
54
 
34
55
 
35
56
  \#\#\#\# Attaching structured data
@@ -81,18 +102,6 @@ up.magic = (($) ->
81
102
  @return {Function}
82
103
  A function that unbinds the event listeners when called.
83
104
  ###
84
- liveDescriptions = []
85
- defaultLiveDescriptions = null
86
-
87
- ###*
88
- # Convert an Up.js style listener (second argument is the event target
89
- # as a jQuery collection) to a vanilla jQuery listener
90
- ###
91
- upListenerToJqueryListener = (upListener) ->
92
- (event) ->
93
- $me = event.$element || $(this)
94
- upListener.apply($me.get(0), [event, $me, data($me)])
95
-
96
105
  live = (args...) ->
97
106
  # Silently discard any event handlers that are registered on unsupported
98
107
  # browsers and return a no-op destructor
@@ -112,12 +121,26 @@ up.magic = (($) ->
112
121
 
113
122
  # Return destructor
114
123
  -> $document.off(description...)
115
-
124
+
125
+
116
126
  ###*
117
127
  Registers a function to be called whenever an element with
118
- the given selector is inserted into the DOM through Up.js.
128
+ the given selector is inserted into the DOM.
129
+
130
+ $('.action').compiler(function($element) {
131
+ // your code here
132
+ });
119
133
 
120
- This is a great way to integrate jQuery plugins.
134
+ Compiler functions will be called on matching elements when
135
+ the page loads, or whenever a matching fragment is [updated through Up.js](/up.replace)
136
+ later.
137
+
138
+ If you have used Angular.js before, this resembles [Angular directives](https://docs.angularjs.org/guide/directive).
139
+
140
+
141
+ \#\#\#\# Integrating jQuery plugins
142
+
143
+ `up.compiler` is a great way to integrate jQuery plugins.
121
144
  Let's say your Javascript plugin wants you to call `lightboxify()`
122
145
  on links that should open a lightbox. You decide to
123
146
  do this for all links with an `[rel=lightbox]` attribute:
@@ -131,14 +154,10 @@ up.magic = (($) ->
131
154
  $element.lightboxify();
132
155
  });
133
156
 
134
- Note that within the compiler, Up.js will bind `this` to the
135
- native DOM element to help you migrate your existing jQuery code to
136
- this new syntax.
137
-
138
157
 
139
158
  \#\#\#\# Custom elements
140
159
 
141
- You can also use `up.compiler` to implement custom elements like this:
160
+ You can use `up.compiler` to implement custom elements like this:
142
161
 
143
162
  <clock></clock>
144
163
 
@@ -214,12 +233,28 @@ up.magic = (($) ->
214
233
  });
215
234
 
216
235
 
217
- \#\#\#\# Migrating jQuery event handlers to `up.on`
236
+ \#\#\#\# Migrating jQuery event handlers to `up.compiler`
218
237
 
219
238
  Within the compiler, Up.js will bind `this` to the
220
239
  native DOM element to help you migrate your existing jQuery code to
221
240
  this new syntax.
222
241
 
242
+ So if you had this before:
243
+
244
+ $(function() {
245
+ $('.action').on('click', function() {
246
+ $(this).something();
247
+ });
248
+ });
249
+
250
+ ... you can reuse the event handler like this:
251
+
252
+ $('.action').compiler(function($element) {
253
+ $element.on('click', function() {
254
+ $(this).something();
255
+ });
256
+ });
257
+
223
258
 
224
259
  @method up.compiler
225
260
  @param {String} selector
@@ -238,7 +273,7 @@ up.magic = (($) ->
238
273
  object before it is removed from the DOM. The destructor is supposed to
239
274
  clear global state such as time-outs and event handlers bound to the document.
240
275
  The destructor is *not* expected to remove the element from the DOM, which
241
- is already handled by [`up.destroy`](/up.flow#up.destroy).
276
+ is already handled by [`up.destroy`](/up.destroy).
242
277
  ###
243
278
  compilers = []
244
279
  defaultCompilers = null
@@ -295,11 +330,11 @@ up.magic = (($) ->
295
330
 
296
331
  If an element annotated with [`up-data`] is inserted into the DOM,
297
332
  Up will parse the JSON and pass the resulting object to any matching
298
- [`up.compiler`](/up.magic#up.magic.compiler) handlers.
333
+ [`up.compiler`](/up.magic.compiler) handlers.
299
334
 
300
335
  Similarly, when an event is triggered on an element annotated with
301
336
  [`up-data`], the parsed object will be passed to any matching
302
- [`up.on`](/up.magic#up.on) handlers.
337
+ [`up.on`](/up.on) handlers.
303
338
 
304
339
  @ujs
305
340
  @method [up-data]
@@ -315,7 +350,7 @@ up.magic = (($) ->
315
350
 
316
351
  ###*
317
352
  Makes a snapshot of the currently registered event listeners,
318
- to later be restored through [`up.bus.reset`](/up.bus#up.bus.reset).
353
+ to later be restored through [`up.bus.reset`](/up.bus.reset).
319
354
 
320
355
  @private
321
356
  @method up.magic.snapshot
@@ -343,16 +378,21 @@ up.magic = (($) ->
343
378
  into the DOM. This causes Up.js to compile the fragment (apply
344
379
  event listeners, etc.).
345
380
 
346
- This method is called automatically if you change elements through
347
- other Up.js methods. You will only need to call this if you
348
- manipulate the DOM without going through Up.js.
381
+ **As long as you manipulate the DOM using Up.js, you will never
382
+ need to call this method.** You only need to use `up.hello` if the
383
+ DOM is manipulated without Up.js' involvement, e.g. by plugin code that
384
+ is not aware of Up.js:
385
+
386
+ // Add an element with naked jQuery, without going through Upjs:
387
+ $element = $('<div>...</div>').appendTo(document.body);
388
+ up.hello($element);
349
389
 
350
390
  @method up.hello
351
391
  @param {String|Element|jQuery} selectorOrElement
352
392
  ###
353
393
  hello = (selectorOrElement) ->
354
394
  $element = $(selectorOrElement)
355
- up.bus.emit('up:fragment:inserted', $element: $element)
395
+ up.emit('up:fragment:inserted', $element: $element)
356
396
  $element
357
397
 
358
398
  onEscape = (handler) ->