Skip to content

Instantly share code, notes, and snippets.

@agnellvj

agnellvj/jquery_in_rails.markdown

Forked from jcasimir/jquery_in_rails.markdown
Created September 12, 2011 20:20
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save agnellvj/1212286 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save agnellvj/1212286 to your computer and use it in GitHub Desktop.
Download ZIP

Revisions

  1. @jcasimir jcasimir created this gist Sep 12, 2011.
    118 changes: 118 additions & 0 deletions jquery_in_rails.markdown
    View file
    Original file line number Diff line number Diff line change
    @@ -0,0 +1,118 @@
    # Using jQuery

    jQuery has become the most popular JavaScript library both inside and outside the Rails community. Let's look at how to take advantage of the library with our applications.

    ## Setup

    The setup process differs depending on whether your app is running on a version of Rails before 3.1 or greater than 3.1.

    ### Before Rails 3.1: `jquery-rails`

    For political reasons, Rails has always shipped with the Prototype library instead of jQuery. The last "Rails Survey" showed that around 70% of projects were using jQuery instead. They install the library and override the default Prototype.

    #### Installing `jquery-rails`

    You could setup the library yourself, but that's too much work. Instead, rely on the official `jquery-rails` gem.

    Add `gem 'jquery-rails'` to your `Gemfile` then run `bundle`.

    #### Running the Generator

    Then, from your project's directory, run the generator:

    ```
    rails generate jquery:install
    ```

    The generator will remove the Prototype libraries and install the latest version of jQuery:

    ```
    $ rails generate jquery:install
    remove public/javascripts/prototype.js
    remove public/javascripts/effects.js
    remove public/javascripts/dragdrop.js
    remove public/javascripts/controls.js
    copying jQuery (1.6.1)
    create public/javascripts/jquery.js
    create public/javascripts/jquery.min.js
    copying jQuery UJS adapter (0e7426)
    remove public/javascripts/rails.js
    create public/javascripts/jquery_ujs.js
    ```

    Note that the `jquery_ujs.js` is a replacement for the `rails.js` which handles functions like making your delete links work.

    #### Redefining `:defaults`

    When the gem is loaded it automatically overrides Rails list of default JavaScripts. In your layout you can use this include tag, like normal:

    ```
    <%= javascript_include_tag :defaults %>
    ```

    That will load jQuery on all your pages.

    ### After Rails 3.1

    In Rails 3.1, jQuery is the default JavaScript library. `jquery-rails` is automatically included in your `Gemfile` and running the generator is not necessary.

    ## Writing Your JavaScript

    Once you have the library, it's time to write your JavaScript. Where you put your work varies based on pre-3.1 or after 3.1.

    ### Before Rails 3.1

    In older Rails applications, your JavaScripts will be loaded from `public/javascripts`. Your app will have an `application.js` file there which is included in the Rails defaults.

    As your JavaScript code grows, you'll likely want to break it into several files.

    #### Including Other JavaScript Files

    You have two options for loading those additional files. The first is to just add them to the layout:

    ```erb
    <%= javascript_include_tag :defaults, 'my_custom_file' %>
    ```

    That's a good choice if you want to be explicit and especially if you want to load different JS files for different pages/layouts.

    You could, though, choose to change the definition of `:defaults`. In your `config/application.rb` you'd add this:

    ```ruby
    config.action_view.javascript_expansions[:defaults] += 'my_custom_file'
    ```

    Or, if you're managing a large number of JS files, you might define your own expansion name. In `application.rb`:

    ```ruby
    config.action_view.javascript_expansions[:shopping_cart] = ['cart', 'product', 'support']
    ```

    Then in the layout:

    ```erb
    <%= javascript_include_tag :defaults, :shopping_cart %>
    ```

    ### Rails 3.1 and Beyond

    In Rails 3.1 the game has changed significantly. Developing effective web applications today necessitates writing JavaScript, and often a lot of it.

    Before 3.1, dumping all JavaScript into `public/javascripts` got messy as applications grew. Many teams chose to move the folder to the `app` directory so it was closer to the Ruby application code.

    As you split up JavaScript into a bunch of separate files you're increasing the number of request/response cycles the client must perform to display the page. That can really slow the client down.

    #### Enter the Pipeline

    The solution to both these issues is the *Asset Pipeline*. The pipeline allows us to assemble multiple JS files server side, minify and compress them, then output a single file to the browser. This results in just one request/response cycle, lower total I/O, and faster processing on the client. The component files live in the `app` directory and mirror the structure of other components.

    #### Writing JavaScript for the Pipeline

    The Rails 3.1 generators are setup to help you. When you generate an `ArticlesController`, for instance, it will create `app/assets/javascripts/articles.js.coffee`. That's where you'll write the JavaScript related to articles.

    What's `.coffee`? Let's next take a look at CoffeeScript.

    ## References

    * jQuery-Rails on Github: https://github.com/rails/jquery-rails
    * Asset Pipeline in Rails 3.1: http://guides.rubyonrails.org/asset_pipeline.html