Skip to content
This repository has been archived by the owner on Jul 28, 2018. It is now read-only.

Commit

Permalink
Update README.md, removing all v3.0 features
Browse files Browse the repository at this point in the history 
These features aren't in Turbolinks Classic, which is currently at v2.5.3, so they shouldn't be in the Readme
  • Loading branch information
@samjewell
samjewell authored Jan 24, 2017
1 parent 37a7c29 commit 853daa8
Showing 1 changed file with 0 additions and 167 deletions.
167 changes: 0 additions & 167 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -154,14 +154,6 @@ Turbolinks.ProgressBar.done();
```


data-turbolinks-permanent (3.0+)
--------------------------------

DOM elements with `data-turbolinks-permanent` are transferred from page to page (along with all their state). This can make your application even faster by avoiding the need to re-initialize state on certain fixed elements (e.g. a sidebar) after page transitions.

`data-turbolinks-permanent` must have a unique `id`. You should also make sure that their initialization code is either idempotent or executed only once per Turbolinks session (e.g. on `DOMContentLoaded`).


Initialization
--------------

Expand Down Expand Up @@ -256,165 +248,6 @@ You can use `Turbolinks.visit(path)` to go to a URL through Turbolinks.
You can also use `redirect_to path, turbolinks: true` in Rails to perform a redirect via Turbolinks.


Partial Replacement (3.0+)
--------------------------

Turbolinks's partial replacement strategy relies on `id` attributes specified on individual nodes or a combination of `id` and `data-turbolinks-permanent` or `data-turbolinks-temporary` attributes.

```html
<div id="comments"></div>
<div id="nav" data-turbolinks-permanent></div>
<div id="footer" data-turbolinks-temporary></div>
```

Any node with an `id` attribute can be partially replaced. If the `id` contains a colon, the key before the colon can also be targeted to replace many nodes with a similar prefix.

```html
<div id="comments"></div>
<div id="comments:123"></div>
```

**Client-side partial replacement**

`Turbolinks.visit()` should be used when you want to perform an XHR request to fetch the latest content from the server and replace all or some of the nodes.

`Turbolinks.replace()` should be used when you already have a response body and want to replace the contents of the current page with it. This is needed for contextual responses like validation errors after a failed `create` attempt, since fetching the page again would lose the validation errors.

```html+erb
<body>
<div id="sidebar" data-turbolinks-permanent>
Never changes after initial load.
</div>
<div id="flash" data-turbolinks-temporary>
You have <%= @comments.count %> comments.
</div>
<section id="comments">
<%= @comments.each do |comment| %>
<article id="comments:<%= comment.id %>">
<h1><%= comment.author %></h1>
<p><%= comment.body %></p>
</article>
<% end %>
</section>
<%= form_for Comment.new, remote: true, id: 'new_comment' do |form| %>
<%= form.text_area :content %>
<%= form.submit %>
<% end %>
</body>
<script>
// Will change #flash, #comments, #comments:123
Turbolinks.visit(url, { change: ['comments'] });
// Will change #flash, #comments:123
Turbolinks.visit(url, { change: ['comments:123'] });
// Will only keep #sidebar
Turbolinks.visit(url)
// Will only keep #sidebar, #flash
Turbolinks.visit(url, { keep: ['flash'] });
// Will keep nothing
Turbolinks.visit(url, { flush: true });
// Same as visit() but takes a string or Document, allowing you to
// do inline responses instead of issuing a new GET with Turbolinks.visit.
// This is useful for things like form validation errors or other
// contextualized responses.
Turbolinks.replace(html, options);
</script>
```

**Server-side partial replacement**

Partial replacement decisions can also be made server-side by using `redirect_to` or `render` with `change`, `append`, `prepend`, `keep`, or `flush` options.

```ruby
class CommentsController < ActionController::Base
def index
@comments = Comment.page(params[:page]).per(25)

# Turbolinks appends the nodes in `comment_list`; useful for infinite scrolling
render :index, append: ['comment_list']
end

def create
@comment = Comment.new(comment_params)

if @comment.save
# This will change #flash, #comments
redirect_to comments_url, change: 'comments'
# => Turbolinks.visit('/comments', change: ['comments'])
else
# Validation failure
render :new, change: :new_comment
# => Turbolinks.replace('<%=j render :new %>', change: ['new_comment'])
end
end
end
```

```ruby
# Redirect via Turbolinks when the request is XHR and not GET.
# Refresh any `data-turbolinks-temporary` nodes.
redirect_to path

# Force a redirect via Turbolinks.
redirect_to path, turbolinks: true

# Force a normal redirection.
redirect_to path, turbolinks: false

# Partially replace any `data-turbolinks-temporary` nodes and nodes with `id`s matching `comments` or `comments:*`.
redirect_to path, change: 'comments'

# Partially replace any `data-turbolinks-temporary` nodes and nodes with `id` not matching `something` and `something:*`.
redirect_to path, keep: 'something'

# Replace the entire `body` of the document, including `data-turbolinks-permanent` nodes.
redirect_to path, flush: true
```

```ruby
# Render with Turbolinks when the request is XHR.
# Refresh any `data-turbolinks-temporary` nodes and nodes with `id` matching `new_comment`.
render view, change: 'new_comment'

# Refresh any `data-turbolinks-temporary` nodes and nodes with `id` not matching `something` and `something:*`.
render view, keep: 'something'

# Replace the entire `body` of the document, including `data-turbolinks-permanent` nodes.
render view, flush: true

# Force a render with Turbolinks.
render view, turbolinks: true

# Force a normal render.
render view, turbolinks: false
```

**Note:** a request is considered XHR when the `X-Requested-With` header contains `XMLHttpRequest`. This is added automatically by jQuery and other JavaScript frameworks. However, requests made by Turbolinks are not considered XHR on the server.

Server-side partial replacement was designed to play well with Rails's [`jquery-ujs`](https://github.com/rails/jquery-ujs).


XHR Request Caching (3.0+)
--------------------------

To prevent browsers from caching Turbolinks requests:

```javascript
Turbolinks.disableRequestCaching(); // globally
Turbolinks.visit(url, { cacheRequest: false }); // per request
```

This works just like `jQuery.ajax(url, { cache: false })`, appending `"_#{timestamp}"` to the GET parameters.


Client-side API
--------------------

Expand Down

0 comments on commit 853daa8

Please sign in to comment.