Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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