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

== Supported Libraries

* dojo
* ext-core (use <tt>:extcore</tt> to load it)
* jquery
* jquery-ui
* jrails
* mootools
* prototype
* scriptaculous
* swfobject
* Google Chrome Frame
* Google Webfont

== 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.min.js?1267013480" type="text/javascript"></script>

and in production :

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

=== multiple libraries load

 <%= ajaxlibs_include :jquery, :jqueryui %>

in development environment :

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

this time in production :

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

=== minified / non-minified

By default, each javascript are the minified version. But you can ask for a plain version :

 <%= ajaxlibs_include :jquery, :minified => false %>

will produce

 <script src="/javascripts/ajaxlibs/jquery/1.4.2/jquery.js?1267013480" 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 %>

=== Migration
==== from 0.1.9 and below

Ajaxlibs prior to version 0.1.10 was copying all javascript libraries in all available version to the public javascript directory. Version 0.1.10 provide an automatic copy of needed libraries in their local version (copy is not performed if you are using google CDN, in production environment by default). You can now safely remove <tt>public/javascripts/ajaxlibs</tt> and ignore it in your SCM.

== TODO

* support more javascript libraries : available though Google CDN (yui), not available through Google CDN, available only from google (google maps, ...).

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

== Contributors

* Jesse Cooke : Chrome Frame & Webfont support

== Copyright

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