= Ajaxlibs

== Synopsis

Simplify standard javascript library includes :
* specify your library name and if necessary version number
* provides most common javascript libraries, no need to download them
* easy CDN for javascript libraries : relies on Google CDN to distribute javascript files on production environment

All that using a simple helper ruby method.

== Description

Ajaxlibs provides helpers to load various javascript libraries, specifying version number, locally served or using google CDN.

In development environment, it provides local javascript files for the development server. In production environment, it will automatically use google CDN to serve your standard javascript libraries.

You can specify a specific version of each library to use, or the latest available.

== Examples

=== simple library load, under the development environment

 <%= ajaxlibs_include :jquery %>

will produce, under the development environment :

 <script src="/javascripts/ajaxlibs/jquery/1.4.2/jquery.js?1267013480" type="text/javascript"></script>

and in production :

 <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.js" type="text/javascript"></script>

=== multiple libraries load

 <%= ajaxlibs_include :jquery, :jqueryui %>

in development environment :

 <script src="/javascripts/ajaxlibs/jquery/1.4.2/jquery.js?1267013480" type="text/javascript"></script> 
 <script src="/javascripts/ajaxlibs/jqueryui/1.7.2/jqueryui.js?1267013480" type="text/javascript"></script>

this time in production :

 <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.js" type="text/javascript"></script>
 <script src="http://ajax.googleapis.com/ajax/libs/jqueryui/1.7.2/jquery-ui.js" type="text/javascript"></script>

=== forcing a version

 <%= ajaxlibs_include :prototype, :version => '1.6.0.3' %>

will produce :

 <script src="/javascripts/ajaxlibs/prototype/1.6.0.3/prototype.js?1267013480" type="text/javascript"></script>

=== https support

 <%= ajaxlibs_include :jquery, :secure => true %>

used in production, will produce :

 <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.js" type="text/javascript"></script>

=== automatic dependencies

 <%= ajaxlibs_include :scriptaculous %>

will produce :

 <script src="/javascripts/ajaxlibs/prototype/1.6.1.0/prototype.js?1267013480" type="text/javascript"></script> 
 <script src="/javascripts/ajaxlibs/scriptaculous/1.8.3/scriptaculous.js?1267013481" type="text/javascript"></script>

=== define alternate production environments

You can define alternate production environments to use CDNs under those environments :

	Ajaxlibs::ProductionEnvironments << 'another_production_environment'

== Installation

First, install gem on your system and servers. You can also specify it as a dependency on your rails enviroment :

 config.gem 'ajaxlibs'

Then, just restart your rails server to copy files from gem the public directory of your rails application.

Finally, include some javascript libraries to your views or layouts :

 <%= ajaxlibs_include :scriptaculous %>

== TODO

* support more javascript libraries : available though Google CDN (mootools, ...), not available through Google CDN (jrails, ...), available only from google (google maps, ...).
* support plain/minified versions.
* provide a rake task to copy only required javascript libraries.
* automatic support for jrails.

== 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.

== Copyright

Copyright (c) 2010 Fabien Jakimowicz. See LICENSE for details.