From b31db925b1fa49053178de9c434c5862a2bf68e9 Mon Sep 17 00:00:00 2001 From: Dave Newton Date: Mon, 16 Nov 2015 10:45:20 -0500 Subject: [PATCH 1/8] support data attrs --- README.md | 70 +++++++++---------- .../turbograft/initializers.coffee | 22 +++--- .../javascripts/turbograft/remote.coffee | 4 +- .../javascripts/turbograft/turbolinks.coffee | 12 ++-- 4 files changed, 55 insertions(+), 53 deletions(-) diff --git a/README.md b/README.md index 717e3229..3d708ce0 100644 --- a/README.md +++ b/README.md @@ -29,19 +29,19 @@ Turbograft was built with simplicity in mind. It intends to offer the smallest a ### Partial page refresh ```html -
+
...
``` ```html -Refresh the page +Refresh the page ``` -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. +This performs a `GET` request, but our client state is maintained. Using the `data-refresh` attribute, we tell TurboGraft to grab the new page, but only refresh elements where `data-refresh="page"`. This is the lowest-level way to use TurboGraft. -`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. +`data-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 `data-refresh="foo"` and all matching nodes will be replaced with `onlyKeys: ['foo']`. Each node with `data-refresh` must have its own unique ID (this is how nodes are matched during the replacement stage). At the moment, `data-refresh` does not support multiple keys (e.g., `data-refresh="foo bar"`) like the `class` attribute does. ### onlyKeys 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. @@ -57,54 +57,54 @@ You can also tell TurboGraft to refresh the page, but exclude certain elements f ``` -### refresh-never -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. +### data-refresh-never +The `data-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. ```html -
- <%= link_to "Never refresh", page_path(@next_id), id: "next-page-refresh-never", refresh: "page" %> +
+ <%= link_to "Never refresh", page_path(@next_id), id: "next-page-refresh-never", "data-refresh" => "page" %>
``` -## tg-remote +## data-tg-remote -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. +The `data-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. It requires your `
`, ``, or `
@@ -117,28 +117,28 @@ Post to a remote form: * `turbograft:remote:always`: Always fires when XHR is complete * `turbograft:remote:success`: Always fires when XHR was successful * `turbograft:remote:fail`: Always fires when XHR failed -* `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) +* `turbograft:remote:fail:unhandled`: Fires after `turbograft:remote:fail`, but when no partial replacement with refresh-on-error was performed (because no `data-refresh-on-error` was supplied) -Each event also is sent with a copy of the XHR, as well as a reference to the element that initated the `remote-method`. +Each event also is sent with a copy of the XHR, as well as a reference to the element that initated the `data-remote-method`. -### tg-static +### data-tg-static -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. +With the `data-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 `data-tg-static`, we can define a set of elements (by annotating them with this attribute) that must never change. -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. +The internal state of any nodes marked with `data-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 `data-tg-static` node is also possible, persisting your static element but swapping the innards. -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! +Though, if you were to refresh the page at a higher level -- e.g., refreshing an ancestor of the `data-tg-static`, the static aspect is no longer obeyed and it is replaced! Examples of where this may be useful include: - running `