Permalink
Browse files

Update README.md

  • Loading branch information...
1 parent b715109 commit 8587390e945288e7238345718ea21e67a5a83238 @ncri committed Sep 27, 2012
Showing with 127 additions and 4 deletions.
  1. +127 −4 README.md
View
@@ -1,11 +1,19 @@
# Ajaxify Rails
-Rails gem for automatically turning internal links into ajax links that load content without a full page reload.
+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.
+
+Features:
- Uses the html5 history interface for changing the url and making the browser's back and forward buttons work with ajax.
-- Falls back to a hash based approach for browsers without the history interface (like Internet Explorer).
-- Transparently handles redirects and supports flash messages and page titles.
+- Falls back to a hash based approach for browsers without the history interface (like Internet Explorer version <10)
+- Hash based and non-hash URLs are interchangeable.
+- Transparently handles redirects and supports page titles and flash messages.
- Requires Ruby 1.9 and the asset pipeline.
+- Tested with Chrome, Firefox, Safari and Internet Explorer 8+
Demo: http://ajaxify-demo.herokuapp.com/
@@ -27,7 +35,122 @@ In your application.js file add:
## Usage
-Coming soon...
+### Content Area
+
+Ajaxify Rails 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
+
+ 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
+animated gif as a background.
+
+
+### Page Title
+
+If you define a method called 'page_title' in your application controller, Ajaxify Rails 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:
+
+ Ajaxify.success ->
+ # update navigation and/or other layout elements
+
+
+### 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:
+
+ Ajaxify.flash_types = ['notice', 'warning']
+
+Also make sure that you supply invisible wrapper tags in your layout with the flash type as its id, e.g.:
+
+ #notice{ style: "#{'display:none' unless flash[:notice]}" }
+ = flash[:notice]
+
+### 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:
+
+ = link_to 'Change everything!', re_render_it_all_path, class: 'no_ajaxify'
+
+
+### Root Redirects
+
+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
+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/
+you need to hint Ajaxyfiy like this:
+
+ Ajaxify.base_path_regexp = /^(\/en|\/de)/i
+
+
+### 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
+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:
+
+ def ajaxify_extra_content
+ ... your extra html ...
+ end
+
+For example you could provide url for a widget in the layout like this:
+
+ def ajaxify_extra_content
+ "<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:
+
+ Ajaxify.handle_extra_content = ->
+ $('#my_fancy_widget').html $('#ajaxify_content #my_fancy_widget_html').html()
+
+
+### Reference: All 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> = :
+
+ 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.
+
+ 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
+
+Also check the example app source code for usage: https://github.com/ncri/ajaxify_rails_demo_app
+
## Contributing

0 comments on commit 8587390

Please sign in to comment.