Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 166 lines (101 sloc) 6.955 kb
ceec8c6 @ncri version 0.0.2
authored
1 # Ajaxify Rails
383ef45 @ncri initial commit
authored
2
8587390 @ncri Update README.md
authored
3 No more full page reloads for your Rails app! Yay!
4
5 Automatically makes your app loading content in the background via ajax.
6
312dc60 @ncri Update README.md
authored
7 Works by turning all internal links into ajax links that trigger an update of the page's content area.
8 Also form submission are automatically turned into ajax requests.
8587390 @ncri Update README.md
authored
9
10 Features:
383ef45 @ncri initial commit
authored
11
ceec8c6 @ncri version 0.0.2
authored
12 - Uses the html5 history interface for changing the url and making the browser's back and forward buttons work with ajax.
13 - Falls back to a hash based approach for browsers without the history interface (like Internet Explorer version <10)
8587390 @ncri Update README.md
authored
14 - Hash based and non-hash URLs are interchangeable.
15 - Transparently handles redirects and supports page titles and flash messages.
ceec8c6 @ncri version 0.0.2
authored
16 - Requires Ruby 1.9 and the asset pipeline.
17 - Tested with Chrome, Firefox, Safari and Internet Explorer 8+
18
19 Demo: http://ajaxify-demo.herokuapp.com/
383ef45 @ncri initial commit
authored
20
21 Inspired by the pjax_rails gem (https://github.com/rails/pjax_rails)
22
23 ## Installation
24
25 Add this line to your application's Gemfile:
26
27 gem 'ajaxify_rails'
28
29 And then execute:
30
31 $ bundle
32
33 In your application.js file add:
34
35 //= require ajaxify_rails
36
37 ## Usage
38
ceec8c6 @ncri version 0.0.2
authored
39 ### Content Area
40
312dc60 @ncri Update README.md
authored
41 Ajaxify assumes that your app has a content container html tag with the id `main`.
8587390 @ncri Update README.md
authored
42 This tag is the container wrapping the yield statement in your layout.
43 If yield doesn't have a wrapper in your app yet, you need to supply one to get ajaxification working:
ceec8c6 @ncri version 0.0.2
authored
44
45 #main
46 = yield
47
312dc60 @ncri Update README.md
authored
48 You can change the content wrapper in your javascript by setting
ceec8c6 @ncri version 0.0.2
authored
49
50 Ajaxify.content_container = 'content_container_id'
8587390 @ncri Update README.md
authored
51
312dc60 @ncri Update README.md
authored
52
8587390 @ncri Update README.md
authored
53 ### Loader Animation
54
55 You probably like to have a loader image to be displayed to the user while content loads via ajax.
312dc60 @ncri Update README.md
authored
56 This is simple. Ajaxify automatically inserts a loader div with the class `ajaxify_loader` into
57 the content wrapper before starting an ajax request. So just supply styles for `.ajaxify_loader` in your css, with an
8587390 @ncri Update README.md
authored
58 animated gif as a background.
59
ceec8c6 @ncri version 0.0.2
authored
60
61 ### Page Title
62
312dc60 @ncri Update README.md
authored
63 If you define a method called `page_title` in your application controller, Ajaxify will automatically
8587390 @ncri Update README.md
authored
64 update the page's title tag after the main content has changed.
ceec8c6 @ncri version 0.0.2
authored
65
8587390 @ncri Update README.md
authored
66 ### Navigation and other Layout Updates
ceec8c6 @ncri version 0.0.2
authored
67
68 It's a common use case to have a navigation that needs to change its appearence and possibly functioning when the user navigates
312dc60 @ncri Update README.md
authored
69 to a different section of the page. Ajaxify provides a success callback that is triggered after successful
70 updates of he page's main content. Just hook into it in your javascript and make your layout changes:
ceec8c6 @ncri version 0.0.2
authored
71
72 Ajaxify.success ->
73 # update navigation and/or other layout elements
74
75
76 ### Flash Messages
77
8587390 @ncri Update README.md
authored
78 Ajaxify Rails correctly displays your flash messages after ajaxified requests. To do so it stores them in cookies.
312dc60 @ncri Update README.md
authored
79 By default, only `flash[:notice]` is supported. If you are using for example `flash[:warning]` as well you have to set:
ceec8c6 @ncri version 0.0.2
authored
80
81 Ajaxify.flash_types = ['notice', 'warning']
8587390 @ncri Update README.md
authored
82
83 Also make sure that you supply invisible wrapper tags in your layout with the flash type as its id, e.g.:
84
85 #notice{ style: "#{'display:none' unless flash[:notice]}" }
86 = flash[:notice]
87
88 ### Links that need to trigger full Page Reloads
89
90 We all know them. Those big requests changing the layout of the page so significantly that
312dc60 @ncri Update README.md
authored
91 loading ajax into a content area and doing some minor layout tweaks here and there simply doesn't cut it. Sigh.
92
93 There might also be links and forms that have already their own ajax functionality.
94
95 To turn Ajaxify off for certain links and forms, simply add the class `no_ajaxify` directly to the link or form:
8587390 @ncri Update README.md
authored
96
97 = link_to 'Change everything!', re_render_it_all_path, class: 'no_ajaxify'
ceec8c6 @ncri version 0.0.2
authored
98
99
100 ### Root Redirects
101
8587390 @ncri Update README.md
authored
102 Sometimes you need to redirect on the root url.
103
104 For example you might have a localized application with the locale inside the url.
312dc60 @ncri Update README.md
authored
105 When a user navigates to `your_domain.com` he/she gets redirected to e.g. `your_domain.com/en/`. This works fine in browsers supporting
106 the html 5 history api. However, for browsers without the history api like Internet Explorer before version 10, Ajaxify needs hints
8587390 @ncri Update README.md
authored
107 about your url structure to not get confused (it creates endless redirects otherwise!). You need to explicitly supply some regex.
108
312dc60 @ncri Update README.md
authored
109 Example: if your app's root url potentially redirects to `your_domain.com/en/` and `your_domain.com/de/`
ceec8c6 @ncri version 0.0.2
authored
110 you need to hint Ajaxyfiy like this:
111
112 Ajaxify.base_path_regexp = /^(\/en|\/de)/i
113
114
115 ### Extra Content
116
117 Sometimes you need to do non trivial modifications of the layout whenever the content in the main content area of your site changes.
312dc60 @ncri Update README.md
authored
118 Ajaxify allows you to attach arbitrary html to ajaxified requests. This extra html is then stripped from the main content
ceec8c6 @ncri version 0.0.2
authored
119 that is inserted in the content area. But before that a callback is triggered which can be used to grab the extra content and do something with it.
312dc60 @ncri Update README.md
authored
120 To use this feature you need to provide a method `ajaxify_extra_content` in your ApplicationController:
ceec8c6 @ncri version 0.0.2
authored
121
122 def ajaxify_extra_content
123 ... your extra html ...
124 end
125
126 For example you could provide url for a widget in the layout like this:
127
128 def ajaxify_extra_content
8587390 @ncri Update README.md
authored
129 "<div id='my_fancy_widget_html'> some html </div>"
ceec8c6 @ncri version 0.0.2
authored
130 end
131
312dc60 @ncri Update README.md
authored
132 And then, on the client side hook into Ajaxify using the `handle_extra_content` callback and select the widget html via `#ajaxify_content`:
ceec8c6 @ncri version 0.0.2
authored
133
134 Ajaxify.handle_extra_content = ->
8587390 @ncri Update README.md
authored
135 $('#my_fancy_widget').html $('#ajaxify_content #my_fancy_widget_html').html()
ceec8c6 @ncri version 0.0.2
authored
136
137
312dc60 @ncri Update README.md
authored
138 ### Reference: All Javascript Options and Callbacks
ceec8c6 @ncri version 0.0.2
authored
139
312dc60 @ncri Update README.md
authored
140 Here is a reference of all options and callbacks you can set on the client side via `Ajaxify.<i>option_or_callback</i> =` :
ceec8c6 @ncri version 0.0.2
authored
141
312dc60 @ncri Update README.md
authored
142 Option/Callback Default Description
ceec8c6 @ncri version 0.0.2
authored
143
312dc60 @ncri Update README.md
authored
144 active true Toggles link ajaxification.
145 content_container 'main' Id of the container to insert the main content into ("yield wrapper").
146 base_path_regexp null Regex hint for applications with root url redirects.
ceec8c6 @ncri version 0.0.2
authored
147
312dc60 @ncri Update README.md
authored
148 on_before_load null Callback: Called before the ajaxify request is started.
149 on_success null Callback: Called when an ajaxify requests finished successfully.
150 on_success_once null Callback: Like on_success but only called once.
151 handle_extra_content null Callback: Called before extra content is stripped from the ajax request's response.
ceec8c6 @ncri version 0.0.2
authored
152
312dc60 @ncri Update README.md
authored
153 flash_types ['notice'] Flash types your Rails app uses. E.g. ['notice', 'warning', 'error']
154 flash_effect null Callback: Called for each flash type after flash is set.
155 clear_flash_effect null Callback: Called for each flash type whenever flash message is not present
ceec8c6 @ncri version 0.0.2
authored
156
157 Also check the example app source code for usage: https://github.com/ncri/ajaxify_rails_demo_app
383ef45 @ncri initial commit
authored
158
159
160 ## Contributing
161
162 1. Fork it
163 2. Create your feature branch (`git checkout -b my-new-feature`)
164 3. Commit your changes (`git commit -am 'Added some feature'`)
165 4. Push to the branch (`git push origin my-new-feature`)
55b358c @ncri fixed readme merge conflict
authored
166 5. Create new Pull Request
Something went wrong with that request. Please try again.