Permalink
Browse files

Update README.md

  • Loading branch information...
1 parent 55b358c commit 312dc600558b943cbfabde9d811efb2fda5ebc5a @ncri committed Sep 28, 2012
Showing with 35 additions and 30 deletions.
  1. +35 −30 README.md
View
@@ -4,7 +4,8 @@ No more full page reloads for your Rails app! Yay!
Automatically makes your app loading content in the background via ajax.
-Works by turning all internal links into ajax links that trigger an update of the page's content area.
+Works by turning all internal links into ajax links that trigger an update of the page's content area.
+Also form submission are automatically turned into ajax requests.
Features:
@@ -37,35 +38,36 @@ In your application.js file add:
### Content Area
-Ajaxify Rails assumes that your app has a content container html tag with the id 'main'.
+Ajaxify assumes that your app has a content container html tag with the id `main`.
This tag is the container wrapping the yield statement in your layout.
If yield doesn't have a wrapper in your app yet, you need to supply one to get ajaxification working:
#main
= yield
-You can change the content wrapper by setting
+You can change the content wrapper in your javascript by setting
Ajaxify.content_container = 'content_container_id'
+
### Loader Animation
You probably like to have a loader image to be displayed to the user while content loads via ajax.
-This is simple. Ajaxify Rails automatically inserts a loader div with the class ajaxify_loader into
-the content wrapper before starting an ajax request. So just supply styles for .ajaxify_loader in your css, with an
+This is simple. Ajaxify automatically inserts a loader div with the class `ajaxify_loader` into
+the content wrapper before starting an ajax request. So just supply styles for `.ajaxify_loader` in your css, with an
animated gif as a background.
### Page Title
-If you define a method called 'page_title' in your application controller, Ajaxify Rails will automatically
+If you define a method called `page_title` in your application controller, Ajaxify will automatically
update the page's title tag after the main content has changed.
### Navigation and other Layout Updates
It's a common use case to have a navigation that needs to change its appearence and possibly functioning when the user navigates
-to a different section of the page. Ajaxify Rails provides a success callback that is triggered after successful
-updates of he page's main content. Just hook into it and make your layout changes:
+to a different section of the page. Ajaxify provides a success callback that is triggered after successful
+updates of he page's main content. Just hook into it in your javascript and make your layout changes:
Ajaxify.success ->
# update navigation and/or other layout elements
@@ -74,7 +76,7 @@ updates of he page's main content. Just hook into it and make your layout change
### Flash Messages
Ajaxify Rails correctly displays your flash messages after ajaxified requests. To do so it stores them in cookies.
-By default, only flash[:notice] is supported. If you are using for example flash[:warning] as well you have to set:
+By default, only `flash[:notice]` is supported. If you are using for example `flash[:warning]` as well you have to set:
Ajaxify.flash_types = ['notice', 'warning']
@@ -86,8 +88,11 @@ Also make sure that you supply invisible wrapper tags in your layout with the fl
### Links that need to trigger full Page Reloads
We all know them. Those big requests changing the layout of the page so significantly that
-simply loading ajax into a content area and doing some minor layout tweaks here and there simply doesn't cut it. Sigh.
-Well, okay here is how to turn Ajaxify Rails off for certain links. Simply add the class no_ajaxify directly to the link:
+loading ajax into a content area and doing some minor layout tweaks here and there simply doesn't cut it. Sigh.
+
+There might also be links and forms that have already their own ajax functionality.
+
+To turn Ajaxify off for certain links and forms, simply add the class `no_ajaxify` directly to the link or form:
= link_to 'Change everything!', re_render_it_all_path, class: 'no_ajaxify'
@@ -97,11 +102,11 @@ Well, okay here is how to turn Ajaxify Rails off for certain links. Simply add t
Sometimes you need to redirect on the root url.
For example you might have a localized application with the locale inside the url.
-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
-the html 5 history api. However, for browsers without the history api like Internet Explorer before version 10, Ajaxify Rails needs hints
+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
+the html 5 history api. However, for browsers without the history api like Internet Explorer before version 10, Ajaxify needs hints
about your url structure to not get confused (it creates endless redirects otherwise!). You need to explicitly supply some regex.
-Example: if your app's root url potentially redirects to your_domain.com/en/ and your_domain.com/de/
+Example: if your app's root url potentially redirects to `your_domain.com/en/` and `your_domain.com/de/`
you need to hint Ajaxyfiy like this:
Ajaxify.base_path_regexp = /^(\/en|\/de)/i
@@ -110,9 +115,9 @@ you need to hint Ajaxyfiy like this:
### Extra Content
Sometimes you need to do non trivial modifications of the layout whenever the content in the main content area of your site changes.
-Ajaxify Rails allows you to attach arbitrary html to ajaxified requests. This extra html is then stripped from the main content
+Ajaxify allows you to attach arbitrary html to ajaxified requests. This extra html is then stripped from the main content
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.
-To use this feature you need to provide a method ajaxify_extra_content in your ApplicationController:
+To use this feature you need to provide a method `ajaxify_extra_content` in your ApplicationController:
def ajaxify_extra_content
... your extra html ...
@@ -124,30 +129,30 @@ For example you could provide url for a widget in the layout like this:
"<div id='my_fancy_widget_html'> some html </div>"
end
-And then, on the client side hook into Ajaxify via the handle_extra_content callback and select the widget html via #ajaxify_content:
+And then, on the client side hook into Ajaxify using the `handle_extra_content` callback and select the widget html via `#ajaxify_content`:
Ajaxify.handle_extra_content = ->
$('#my_fancy_widget').html $('#ajaxify_content #my_fancy_widget_html').html()
-### Reference: All Options and Callbacks
+### Reference: All Javascript Options and Callbacks
-Here is a reference of all options and callbacks you can set on the client side via Ajaxify.<i>option_or_callback</i> = :
+Here is a reference of all options and callbacks you can set on the client side via `Ajaxify.<i>option_or_callback</i> =` :
- Option/Callback Default Description
+ Option/Callback Default Description
- active true Toggles link ajaxification.
- content_container 'main' Id of the container to insert the main content into ("yield wrapper").
- base_path_regexp null Regex hint for applications with root url redirects.
+ active true Toggles link ajaxification.
+ content_container 'main' Id of the container to insert the main content into ("yield wrapper").
+ base_path_regexp null Regex hint for applications with root url redirects.
- on_before_load null Callback: Called before the ajaxify request is started.
- on_success null Callback: Called when an ajaxify requests finished successfully.
- on_success_once null Callback: Like on_success but only called once.
- handle_extra_content null Callback: Called before extra content is stripped from the ajax request's response.
+ on_before_load null Callback: Called before the ajaxify request is started.
+ on_success null Callback: Called when an ajaxify requests finished successfully.
+ on_success_once null Callback: Like on_success but only called once.
+ handle_extra_content null Callback: Called before extra content is stripped from the ajax request's response.
- flash_types ['notice'] Flash types your Rails app uses. E.g. ['notice', 'warning', 'error']
- flash_effect null Callback: Called for each flash type after flash is set.
- clear_flash_effect null Callback: Called for each flash type whenever flash message is not present
+ flash_types ['notice'] Flash types your Rails app uses. E.g. ['notice', 'warning', 'error']
+ flash_effect null Callback: Called for each flash type after flash is set.
+ clear_flash_effect null Callback: Called for each flash type whenever flash message is not present
Also check the example app source code for usage: https://github.com/ncri/ajaxify_rails_demo_app

0 comments on commit 312dc60

Please sign in to comment.