turbograft 0.1.4 → 0.1.5

Sign up to get free protection for your applications and to get access to all the features.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA1:
3
- metadata.gz: d0cf7f7c936415c6a11516f9a43f533f5b67b178
4
- data.tar.gz: ad506629d8ad4c6c27b778b3b2bfabbb40ca70ad
3
+ metadata.gz: 02d54ea2e6cd5256f9d5de5124c826d0c5a4873c
4
+ data.tar.gz: 67b141c9ea5940bd766e625ed451f79dfde388a8
5
5
  SHA512:
6
- metadata.gz: 4d98dd4f884babcf6538344e42ae3e728877711d37bc38cca97ca837eb7b2e606e32e455d4f33fca7b57fa21a3f53e7c57e5aabd51f0cbaaa6a0a82ff37e68af
7
- data.tar.gz: 54c66bd97efdbb41bdafb7a0edf710bb5f9b8a85a358fe3b9480052ce34159c5556f4494a9109b9c2922bcd9f3be01ca8d07a9166c75139def907e29eb59f59d
6
+ metadata.gz: 9f77a1c9d71b92cce89c4681210798d2159fa1607c8e09ffbfba67c24bf8db0bee9f052212cff74bf4c914dd97060ceefa7ae00e767d46e160fdad36ccd27de8
7
+ data.tar.gz: 7bb7e66e72f3969bfd076152244eb9f3afa727e5d42032e5744d2e78bb8a7d1e8a263dabac5592db27581f5165815a26bb270bc30badfeafc768c33cdad8ab10
data/README.md CHANGED
@@ -1,14 +1,22 @@
1
1
  # TurboGraft
2
-
3
- It's like turbolinks, but with partial page replacement and tests
2
+ Turbograft extends [Turbolinks](https://github.com/rails/turbolinks), allowing you to perform partial page refreshes.
4
3
 
5
4
  `Graft` - (noun) a shoot or twig inserted into a slit on the trunk or stem of a living plant, from which it receives sap.
6
5
 
7
6
  In botony, one can take parts of a tree and splice it onto another tree. The DOM is a tree. In this library, we're cutting off sub-trees of the DOM and splicing new ones on.
8
7
 
8
+ Turbolinks works by intercepting navigation requests and loading them via Ajax when possible, swapping the body tag of the document with the newly loaded copy. Turbograft builds on this to allow you to perform a partial page refresh on specified DOM nodes by adding a refresh key. This allows you reduce page load time, while the feeling of a native, single-page application.
9
+
10
+ ## One render path
11
+ Turbograft gives you the ability to maintain a single, canonical render path for views. Your ERB views are the single definition of what will be rendered, without the worry of conditionally fetching snippets of HTML from elsewhere. This approach leads to clear, simplified code.
12
+ ## Client-side performance
13
+ Partial page refreshes mean that CSS and JavaScript are only reloaded when you need them to be. Turbograft improves on the native, single-page application feel for the user while keeping these benefits inherited from Turbolinks.
14
+ ## Simplicity
15
+ Turbograft was built with simplicity in mind. It intends to offer the smallest amount of overhead required on top of a traditional Rails stack to solve the problem of making a Rails app feel native to the browser.
16
+
9
17
  ## Status
10
18
  [![Gem Version](https://badge.fury.io/rb/turbograft.svg)](http://badge.fury.io/rb/turbograft)
11
- [![Build Status](https://api.travis-ci.org/Shopify/turbograft.svg)](http://travis-ci.org/Shopify/turbograft)
19
+ [![Build Status](https://travis-ci.org/Shopify/turbograft.svg?branch=master)](http://travis-ci.org/Shopify/turbograft)
12
20
 
13
21
  ## Installation
14
22
 
@@ -17,18 +25,133 @@ In botony, one can take parts of a tree and splice it onto another tree. The DO
17
25
  * Add `#= require turbograft` to _app/assets/javascripts/application.js_
18
26
 
19
27
  ## Usage
28
+ ### Partial page refresh
29
+
30
+ ```html
31
+ <div id="content" refresh="page">
32
+ ...
33
+ </div>
34
+ ```
35
+
36
+
37
+ ```html
38
+ <a href="#" id="partial-refresh-page" refresh="page" onclick="event.preventDefault(); Page.refresh({url: '<%= page_path(@next_id) %>',onlyKeys: ['page']});">Refresh the page</a>
39
+ ```
40
+
41
+ This performs a `GET` request, but our client state is maintained. Using the refresh attribute, we tell TurboGraft to grab the new page, but only refresh elements where refresh="page". This is the lowest-level way to use TurboGraft.
42
+
43
+ `refresh` attributes on your DOM nodes can be considered somewhat analoguous to how `class` will apply styles to any nodes with that class. That is to say, many nodes can be decorated `refresh="foo"` and all matching nodes will be replaced with `onlyKeys: ['foo']`. Each node with `refresh` must have its own unique ID (this is how nodes are matched during the replacement stage). At the moment, `refresh` does not support multiple keys (e.g., `refresh="foo bar"`) like the `class` attribute does.
44
+
45
+ ### onlyKeys
46
+ You can specify multiple refresh keys on a page, and you can tell TurboGraft to refresh on one or more refresh keys for a given action.
47
+
48
+ ```html
49
+ <button id='refresh-a-and-b' href="<%= page_path(@id) %>" onclick="event.preventDefault(); Page.refresh({url: '<%= page_path(@id) %>', onlyKeys: ['section-a', 'section-b']});">Refresh Section A and B</button>
50
+ ```
51
+
52
+ ### exceptKeys
53
+ You can also tell TurboGraft to refresh the page, but exclude certain elements from being refreshed.
54
+
55
+ ```html
56
+ <button id='refresh-a-and-b' href="<%= page_path(@id) %>" onclick="event.preventDefault(); Page.refresh({url: '<%= page_path(@id) %>', exceptKeys: ['section-a', 'section-b']});">Refresh everything but Section A and B</button>
57
+ ```
58
+
59
+ ### refresh-never
60
+ The `refresh-never` attribute will cause a node only appear once in the `body` of the document. This can be used to include and initialize a tracking pixel or script just once inside the body.
61
+
62
+ ```html
63
+ <div refresh-never>
64
+ <%= link_to "Never refresh", page_path(@next_id), id: "next-page-refresh-never", refresh: "page" %>
65
+ </div>
66
+ ```
67
+
68
+ ## tg-remote
69
+
70
+ The `tg-remote` option allows you to query methods on or submit forms to different endpoints, and gives partial page replacement on specified refresh keys depending on the response status.
71
+
72
+ It requires your `<form>`, `<a>`, or `<button>` to be marked up with:
73
+
74
+ * `tg-remote`: (optionally valueless for `<form>`, but requires an HTTP method for links) the HTTP method you wish to call on your endpoint
75
+ * `href`: (if node is `<a>` or `<button>`) the URL of the endpoint you wish to hit
76
+ * `refresh-on-success`: (optional) The refresh keys to be refreshed, using the body of the response. This is space-delimited
77
+ * `refresh-on-error`: (optional) The refresh keys to be refreshed, but using body of XHR which has failed. Only works with error 422. If the XHR returns and error and you do not supply a refresh-on-error, nothing is changed
78
+ * `full-refresh-on-error-except`: (optional) Replaces body except for specified refresh keys, using the body of the XHR which has failed. Only works with error 422
79
+ * `remote-once`: (optional) The action will only be performed once. Removes `remote-method` and `remote-once` from element after consumption
80
+ * `full-refresh`: Rather than using the content of the XHR response for partial page replacement, a full page refresh is performed. If `refresh-on-success` is defined, the page will be reloaded on these keys. If `refresh-on-success` is not defined, a full page refresh is performed. Defaults to true if neither refresh-on-success nor refresh-on-error are provided
81
+ * `tg-remote-norefresh`: Prevents `Page.refresh()` from being called, allowing methods to be executed without updating client state
82
+
83
+ ### Examples
20
84
 
21
- TODO
85
+ Call a remote method:
86
+
87
+ ```html
88
+ <a href="#" tg-remote="post" refresh-on-success="page section-a section-b">Remote-method</a>
89
+ ```
90
+
91
+ The Rails way:
92
+
93
+ ```erb
94
+ <%= link_to "Remote method", method_path, 'refresh-on-success' => 'page section-a section-b', 'full-refresh' => 'true', 'tg-remote' => 'post' %>
95
+ ```
96
+
97
+ Post to a remote form:
98
+
99
+ ```html
100
+ <div id="results" refresh="results">
101
+ Use the field below to submit some content, and get a result.
102
+ </div>
103
+ <form tg-remote="" action="/pages/submit" method="post" refresh-on-success="results" refresh-on-error="results">
104
+ <input name="form-input" type="text">
105
+ <button type="submit">Submit</button>
106
+ </form>
107
+ ```
108
+
109
+ ### tg-remote events
110
+
111
+ * `turbograft:remote:init`: Before XHR is sent
112
+ * `turbograft:remote:start`: When XHR is sent
113
+ * `turbograft:remote:always`: Always fires when XHR is complete
114
+ * `turbograft:remote:success`: Always fires when XHR was successful
115
+ * `turbograft:remote:fail`: Always fires when XHR failed
116
+ * `turbograft:remote:fail:unhandled`: Fires after `turbograft:remote:fail`, but when no partial replacement with refresh-on-error was performed (because no `refresh-on-error` was supplied)
117
+
118
+ Each event also is sent with a copy of the XHR, as well as a reference to the element that initated the `remote-method`.
119
+
120
+ ### tg-static
121
+
122
+ With the `tg-static` attribute decorating a node, we can make sure that this node is not replaced during a fullpage refresh. Contrast this to partial page refreshes, where we normally specify the set of elements that need to change. With `tg-static`, we can define a set of elements (by annotating them with this attribute) that must never change.
123
+
124
+ The internal state of any nodes marked with `tg-static` will remain, even though the entire page has been swapped out. A partial page refresh with `onlyKeys` targeting a node inside of the `tg-static` node is also possible, persisting your static element but swapping the innards.
125
+
126
+ Though, if you were to refresh the page at a higher level -- e.g., refreshing an ancestor of the `tg-static`, the static aspect is no longer obeyed and it is replaced!
127
+
128
+ Examples of where this may be useful include:
129
+
130
+ - running `<video>` or `<audio>` element
131
+ - a client-controlled static nav
132
+
133
+ ### refresh-always
134
+
135
+ For the lazy developer in all of us, we can use the attribute `refresh-always` when we want to be sure we've absolutely replaced a certain element, if it exists. An example of such a node you may want to apply this might be an unread notification count -- always being sure to update it if it exists in the response.
22
136
 
23
137
  ## Example App
24
138
 
25
- cd test/example
26
- bundle exec rails server
139
+ There is an example app that you can boot to play with TurboGraft. Open the console and network inspector and see it in action! This same app is also used in the TurboGraft browser testing suite.
140
+
141
+ ```
142
+ ./server
143
+ ```
27
144
 
28
145
  ## Contributing
29
146
 
30
- 1. Fork it ( http://github.com/<my-github-username>/turbograft/fork )
147
+ 1. Fork it ( http://github.com/Shopify/turbograft/fork )
31
148
  2. Create your feature branch (`git checkout -b my-new-feature`)
32
149
  3. Commit your changes (`git commit -am 'Add some feature'`)
33
- 4. Push to the branch (`git push origin my-new-feature`)
34
- 5. Create new Pull Request
150
+ 4. Write some tests, and edit the example app
151
+ 5. Push to the branch (`git push origin my-new-feature`)
152
+ 6. Create new Pull Request
153
+
154
+ ## Testing
155
+
156
+ - `./server` and visit http://localhost:3000/teaspoon to run the JS test suite
157
+ - `bundle exec rake test` to run the browser test suite
@@ -104,6 +104,7 @@ class window.Turbolinks
104
104
  @loadPage: (url, xhr, partialReplace = false, onLoadFunction = (->), replaceContents = [], replaceAllExcept = []) ->
105
105
  triggerEvent 'page:receive'
106
106
 
107
+
107
108
  if doc = processResponse(xhr, partialReplace)
108
109
  reflectNewUrl url
109
110
  nodes = changePage(extractTitleAndBody(doc)..., partialReplace, replaceContents, replaceAllExcept)
@@ -115,13 +116,16 @@ class window.Turbolinks
115
116
 
116
117
  return
117
118
 
118
- changePage = (title, body, csrfToken, runScripts, partialReplace, replaceContents = [], replaceAllExcept = []) ->
119
+ changePage = (title, body, csrfToken, runScripts, partialReplace, onlyKeys = [], exceptKeys = []) ->
119
120
  document.title = title if title
120
- if replaceContents.length
121
- return refreshNodesWithKeys(replaceContents, body)
121
+
122
+ refreshRefreshAlwaysNodes(body)
123
+ if onlyKeys.length
124
+ return refreshNodesWithKeys(onlyKeys, body)
122
125
  else
123
- if replaceAllExcept.length
124
- refreshAllExceptWithKeys(replaceAllExcept, body)
126
+ persistStaticElements(body)
127
+ if exceptKeys.length
128
+ refreshAllExceptWithKeys(exceptKeys, body)
125
129
  else
126
130
  deleteRefreshNeverNodes(body)
127
131
 
@@ -141,15 +145,7 @@ class window.Turbolinks
141
145
 
142
146
  return
143
147
 
144
- refreshNodesWithKeys = (keys, body) ->
145
- allNodesToBeRefreshed = []
146
- for node in document.querySelectorAll("[refresh-always]")
147
- allNodesToBeRefreshed.push(node)
148
-
149
- for key in keys
150
- for node in document.querySelectorAll("[refresh=#{key}]")
151
- allNodesToBeRefreshed.push(node)
152
-
148
+ refreshNodes = (allNodesToBeRefreshed, body) ->
153
149
  triggerEvent 'page:before-partial-replace', allNodesToBeRefreshed
154
150
 
155
151
  parentIsRefreshing = (node) ->
@@ -177,19 +173,49 @@ class window.Turbolinks
177
173
 
178
174
  refreshedNodes
179
175
 
180
- refreshAllExceptWithKeys = (keys, body) ->
181
- allNodesToKeep = []
176
+ refreshRefreshAlwaysNodes = (body) ->
177
+ allNodesToBeRefreshed = []
178
+ for node in document.querySelectorAll("[refresh-always]")
179
+ allNodesToBeRefreshed.push(node)
180
+
181
+ refreshNodes(allNodesToBeRefreshed, body)
182
+ return
182
183
 
184
+ refreshNodesWithKeys = (keys, body) ->
185
+ allNodesToBeRefreshed = []
183
186
  for key in keys
184
187
  for node in document.querySelectorAll("[refresh=#{key}]")
185
- allNodesToKeep.push(node)
188
+ allNodesToBeRefreshed.push(node)
186
189
 
190
+ refreshNodes(allNodesToBeRefreshed, body)
191
+ return
192
+
193
+ keepNodes = (body, allNodesToKeep) ->
187
194
  for existingNode in allNodesToKeep
188
195
  unless nodeId = existingNode.getAttribute('id')
189
- throw new Error "Turbolinks refresh: Refresh key elements must have an id."
196
+ throw new Error("TurboGraft refresh: Kept nodes must have an id.")
190
197
 
191
- remoteNode = body.querySelector("##{ nodeId }")
192
- remoteNode.parentNode.replaceChild(existingNode, remoteNode)
198
+ if remoteNode = body.querySelector("##{ nodeId }")
199
+ remoteNode.parentNode.replaceChild(existingNode, remoteNode)
200
+
201
+ persistStaticElements = (body) ->
202
+ allNodesToKeep = []
203
+
204
+ nodes = document.querySelectorAll("[tg-static]")
205
+ allNodesToKeep.push(node) for node in nodes
206
+
207
+ keepNodes(body, allNodesToKeep)
208
+ return
209
+
210
+ refreshAllExceptWithKeys = (keys, body) ->
211
+ allNodesToKeep = []
212
+
213
+ for key in keys
214
+ for node in document.querySelectorAll("[refresh=#{key}]")
215
+ allNodesToKeep.push(node)
216
+
217
+ keepNodes(body, allNodesToKeep)
218
+ return
193
219
 
194
220
  executeScriptTags = ->
195
221
  scripts = Array::slice.call document.body.querySelectorAll 'script:not([data-turbolinks-eval="false"])'
@@ -1,3 +1,3 @@
1
1
  module TurboGraft
2
- VERSION = '0.1.4'
2
+ VERSION = '0.1.5'
3
3
  end
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: turbograft
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.1.4
4
+ version: 0.1.5
5
5
  platform: ruby
6
6
  authors:
7
7
  - Kristian Plettenberg-Dussault
@@ -13,7 +13,7 @@ authors:
13
13
  autorequire:
14
14
  bindir: bin
15
15
  cert_chain: []
16
- date: 2014-12-15 00:00:00.000000000 Z
16
+ date: 2015-01-09 00:00:00.000000000 Z
17
17
  dependencies:
18
18
  - !ruby/object:Gem::Dependency
19
19
  name: coffee-rails