Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/Shopify/turbograft
Hard fork of turbolinks, adding partial page replacement strategies, and utilities.
https://github.com/Shopify/turbograft
Last synced: 2 days ago
JSON representation
Hard fork of turbolinks, adding partial page replacement strategies, and utilities.
- Host: GitHub
- URL: https://github.com/Shopify/turbograft
- Owner: Shopify
- License: mit
- Created: 2014-09-11T13:47:46.000Z (about 10 years ago)
- Default Branch: master
- Last Pushed: 2024-05-16T21:13:01.000Z (6 months ago)
- Last Synced: 2024-09-01T05:38:32.733Z (2 months ago)
- Language: JavaScript
- Homepage:
- Size: 673 KB
- Stars: 214
- Watchers: 473
- Forks: 28
- Open Issues: 20
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: MIT-LICENSE
Awesome Lists containing this project
README
# TurboGraft
Turbograft extends [Turbolinks](https://github.com/rails/turbolinks), allowing you to perform partial page refreshes.
`Graft` - (noun) a shoot or twig inserted into a slit on the trunk or stem of a living plant, from which it receives sap.
In botany, 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.
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.
## One render path
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.
## Client-side performance
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.
Head asset tracking means that you can split your large CSS and Javascript bundles into smaller area bundles, decreasing your page weight and further increasing the responsiveness of your app.
## Simplicity
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.
## Status
[](http://badge.fury.io/rb/turbograft)
[](https://github.com/Shopify/turbograft/actions/workflows/build.yml)
## Installation
* Replace `gem "turbolinks"` with `gem "turbograft"` in your Gemfile
* Replace `//= require turbolinks` with `//= require turbograft` in _app/assets/javascripts/application.js_
* Run `bundle install`
## Dependencies
Turbograft requires a browser that supports [`Promise`](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise), or a polyfill (e.g., [core-js](https://github.com/zloirock/core-js).)
## Usage
Much of Turbograft’s functionality relies on attributes HTML elements. These attributes are currently namespaced to `data-tg-*` (e.g. `data-tg-refresh`).
Versions of Turbograft older than 0.2.0 did not use this namespacing. The old attribute names (e.g. `refresh`) are deprecated.
### Partial page refresh
```html
...
```
```html
Refresh the page
```
This performs a `GET` request, but our client state is maintained. Using the `data-tg-refresh` attribute, we tell TurboGraft to grab the new page, but only refresh elements where `data-tg-refresh="page"`. This is the lowest-level way to use TurboGraft.
`data-tg-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-tg-refresh="foo"` and all matching nodes will be replaced with `onlyKeys: ['foo']`. Each node with `data-tg-refresh` must have its own unique ID (this is how nodes are matched during the replacement stage). At the moment, `data-tg-refresh` does not support multiple keys (e.g., `data-tg-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.
```html
Refresh Section A and B
```
### exceptKeys
You can also tell TurboGraft to refresh the page, but exclude certain elements from being refreshed.
```html
Refresh everything but Section A and B
```
### data-tg-refresh-never
The `data-tg-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", "data-tg-refresh" => "page" %>
```
### updatePushState
Defaults to `true`. When set to false it prevents `Page.refresh()` from updating the url in the browser.
## data-tg-remote
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 `` to be marked up with:
Note that as `data-tg-refresh-on-*` pertains to partial refreshes and `data-tg-full-refresh-on-*-except` pertains to full refreshes, they are incompatible with each other and should not be combined.
### Examples
Call a remote method:
```html
Remote-method
```
The Rails way:
```erb
<%= link_to "Remote method", method_path, 'data-tg-refresh-on-success' => 'page section-a section-b', 'data-tg-full-refresh' => 'true', 'data-tg-remote' => 'post' %>
```
Post to a remote form:
```html
Use the field below to submit some content, and get a result.
Submit
```
### tg-remote events
* `turbograft:remote:init`: Before XHR is sent
* `turbograft:remote:start`: When XHR is sent
* `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 `data-tg-refresh-on-error` was supplied or because `data-tg-remote-norefresh` was present)
Each event also is sent with a copy of the XHR, as well as a reference to the element that initated the `data-tg-remote-method`.
### data-tg-static
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 `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 `data-tg-static`, the static aspect is no longer obeyed and it is replaced!
Examples of where this may be useful include:
- running `` or `` element
- a client-controlled static nav
### data-tg-refresh-always
For the lazy developer in all of us, we can use the attribute `data-tg-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.
### data-tg-remote-noserialize
When serializing forms for tg-remote calls, turbograft will check to ensure inputs meet the following criteria:
- the input has a `name` attribute
- the input does not have the `disabled` attribute
and
- the input does not have the `data-tg-remote-noserialize` attribute
- no ancestor of the input has the `data-tg-remote-noserialize` attribute
The `data-tg-remote-noserialize` is useful in scenarios where a whole section of the page should be editable, i.e. not `disabled`, but should only conditionally be submitted to the server.
## Head Asset Tracking
### NOTE: This functionality is experimental, has changed significantly since 0.3.0, and may change again in the future before 1.0
The Turbohead module allows you to track css and javascript assets in the head of the document and change them intelligently. This can be useful in large applications which want to lighten their asset weight by splitting their script and style bundles by area.
When a `` or `<link>` tag with a unique name in it's `data-turbolinks-track` is encountered in a response document Turbograft will insert it into the active DOM and, if it's a script, force it to execute.
If an asset with a different `src`/`href` but the same `data-turbolinks-track` value is found upstream, turbograft will force a full page refresh. This prevents potential multiple executions of a script bundle when a new version of your app is shipped.
As of version `0.4.0`, this functionality has been made backwards compatible. If `data-turbolinks-track="true"` head assets are present, turbograft will cause a full page refresh when the set is changed in any way.
## Example App
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.
```
./server
```
## jQuery and memory leaks
When turbograft replaces or removes a node it uses native DOM API to do so. If any objects use jQuery to listen to events on a node then these objects will leak when the node is replaced because jQuery will still have references to it. To clean these up you'll need to tell jQuery that they're removed. This can be done with something like:
```js
document.addEventListener('page:after-node-removed', function(event) {
$(event.data).remove();
});
```
## Contributing
1. Fork it ( http://github.com/Shopify/turbograft/fork )
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Commit your changes (`git commit -am 'Add some feature'`)
4. Write some tests, and edit the example app
5. Push to the branch (`git push origin my-new-feature`)
6. Create new Pull Request
## Testing
- `./server` and visit http://localhost:3000/teaspoon to run the JS test suite in the browser
- `bundle exec teaspoon` will run the JS test suite from the command line. Uses Selenium by default, but can be configured using the TEASPOON_DRIVER environment variable
- `bundle exec rake test` to run the browser test suite