`. This configuration is widely when you have list of items that are paginated, sorted or maybe grouped by some attributes and you want to update only these items and nothing more on page.
```html
...
```
**Form processing**
Wiselinks can process forms. After submit button is clicked, Wiselinks will perform a request to form url with form attributes serialized to a string. Wiselinks always performs a HTTP GET request.
```html
...
```
**data-include-blank-url-params**
During form submit Wiselinks excludes blank parameters to make your URLs cleaner. You can disable this behaviour with ```data-include-blank-url-params``` attribute.
```html
```
**data-optimize-url-params**
Array parameters ```category_ids[]=1&category_ids[]=2&category_ids[]=3``` are optimized to more human readable ```category_ids=1,2,3```. To changed this behaviour use ```data-optimize-url-params``` attribute.
```html
```
### Server processing
The idea of Wiselinks is that you should render only content that you need in current request. Usually you don't need to reload your stylesheets and javascripts on every request.
`X-Wiselinks` header is passed with every Wiselinks request. Server should respond with content that should be inserted into `$target`.
In Rails after installing Wiselinks gem, all requests that have `X-Wiselinks` header will be automatically processed within 'app/views/layouts/wiselinks' layout, that basically has only `yield` operator. Of course you can override layout name by redefining `wiselinks_layout` method in your controller.
### Javascript Events
While using Wiselinks you **can rely** on `DOMContentLoaded` or `jQuery.ready()` to trigger your JavaScript code, but Wiselinks gives you some additional useful event to deal with the lifecycle of the page:
**page:loading ($target, render, url)**
Event is triggered before the `XMLHttpRequest` is initialised and performed.
* *$target* – JQuery object in which result of the request will be inserted;
* *url* - URL of the request that will be performed;
* *render* – what should be rendered; can be 'template' or 'partial';
**page:redirected ($target, render, url)**
Event is triggered when you were redirected during `XMLHttpRequest` (with HTTP 30x status).
* *$target* – jQuery object in which result of the request will be inserted;
* *url* - URL where you have been redirected to;
* *render* – what should be rendered; can be 'template' or 'partial';
**page:done ($target, status, url, data)**
Event is triggered if the request succeeds.
* *$target* – jQuery object that was updated with the request;
* *status* – a string describing the status;
* *url* – url of the request;
* *data* – content of the request;
**page:fail ($target, status, url, error)**
Event is triggered if the request fails.
* *$target* – jQuery object that had to be updated with the request;
* *status* – a string describing the status;
* *url* – url of the request;
* *error* – a string describing the type of error that occurred;
**page:always ($target, status, url)**
Event is triggered after each request.
* *$target* – jQuery object that had to be updated with the request;
* *status* – a string describing the status;
* *url* – url of the request;
So if you want to show a client-side loading spinner, you could listen for `page:loading` to start it and `page:always` to stop it.
### ActionDispatch::Request extensions
Wiselinks adds a couple of methods to `ActionDispatch::Request`. These methods are mostly syntax sugar and don't have any complex logic, so you can use them or not.
#### #wiselinks? ###
Method returns `true` if current request is initiated by Wiselinks (has `X-Wiselinks` header), `false` otherwise.
#### #wiselinks_template? ###
Method returns `true` if current request is initiated by Wiselinks and client want to render template (`X-Wiselinks != 'partial'`), `false` otherwise.
#### #wiselinks_partial? ###
Method returns `true` if current request is initiated by Wiselinks and client want to render partial (`X-Wiselinks == 'partial'`), `false` otherwise.
### Assets change detection
You can enable assets change detection with Wiselinks. To do this you have to enable assets digests by adding this to you environment file:
```ruby
config.assets.digest = true
```
Then you should append your layout by adding this to head section:
```erb
<%= wiselinks_meta_tag %>
```
Now Wiselinks will track changes of your assets and if anything will change, your page will be reloaded completely.
### Title handling
Wiselinks handles page titles by passing `X-Wiselinks-Title` header with response. To set this header you can use `wiselinks_title` helper (in Rails).
```html
<% wiselinks_title("Wiselinks is awesome") %>
...
```
Of course you can use `wiselinks_title` helper in your own helpers too.
### Redirect handling
Wiselinks follows 30x HTTP redirects. Location is updated in browser with `X-Wiselinks-Url` header that is setting up automatically (in Rails) on every wiselinks request.
### Target missing handling
By default, if Wiselinks cannot find target that you specified during initialization, it will fail silently. But you can override this behaviour:
```coffeescript
#= require jquery
#= require wiselinks
$(document).ready ->
window.wiselinks = new Wiselinks(
$('something that does not exist'),
target_missing: 'exception'
)
```
`[Wiselinks] Target missing` exception will be thrown. This also works for `data-target` attributes.
### Google Analytics and Yandex Metrika
If you want to handle these analytics tools, then you should add handler to `page:done` event.
Let's say, that you have two objects, first is `_gaq` – instance of Google Analytics, second is `_metrika` – instance of Yandex Metrika. Then you have to add the following code somewhere in your `application.js.coffee`.
```coffeescript
$(document).off('page:done').on(
'page:done'
(event, $target, status, url, data) ->
_gaq.push(['_trackPageview', url])
_metrika.hit(url)
)
```
After this, you will have correct page view statistics in your analytics tools.
## Example
We crafted example application that uses nearly all features of Wiselinks so you can see it in action.
* GitHub Repository: [https://github.com/igor-alexandrov/wiselinks_example](https://github.com/igor-alexandrov/wiselinks_example)
* Live Example: [http://wiselinks.herokuapp.com/](http://wiselinks.herokuapp.com/)
## Note on Patches / Pull Requests
* Fork the project.
* Make your feature addition or bug fix.
* Add tests for it. This is important so I don't break it in a
future version unintentionally.
* Commit, do not mess with rakefile, version, or history.
(if you want to have your own version, that is fine but
bump version in a commit by itself I can ignore when I pull)
* Send me a pull request. Bonus points for topic branches.
## Credits
Wiselinks is maintained by [JetRockets](http://www.jetrockets.ru/en).
Contributors:
* [Igor Alexandrov](http://igor-alexandrov.github.com/)
* [Alexey Solilin](https://github.com/solilin)
* [Julia Egorova](https://github.com/vankiru)
* [Alexandr Borisov](https://github.com/aishek)
## License
It is free software, and may be redistributed under the terms specified in the LICENSE file.