0

requirejs-rails

RequireJS support for your Rails 3 or 4 application

Github 資源庫
主要指標
  • 所有者: jwhitley/requirejs-rails
  • 平台:
  • 許可證: MIT License
  • 分類:
  • 主題:
  • 喜歡:
    0
      比較:

Github星跟蹤圖

RequireJS for Rails

Integrates RequireJS into the Rails 3+ Asset Pipeline.

UPGRADE NOTES: Users upgrading within the 0.x series should read the Changes section for relevant usage changes. We're pushing hard to 1.0, when the configuration and setup details will be declared stable. Until that time expect some bumps as things bake out.

Usage

  1. Add this to your Rails app's Gemfile:

    gem 'requirejs-rails'

  2. Remove all Sprockets directives such as //= require jquery from application.js and elsewhere. Instead establish JavaScript dependencies using AMD-style define() and require() calls.

  3. Use requirejs_include_tag at the top-level of your app's layout(s). Other modules will be pulled in dynamically by require.js in development and for production builds optimized by r.js. Here's a basic app/views/layouts/application.html.erb modified for requirejs-rails:

    <!DOCTYPE html>
<html>
<head>
  <title>Frobnitz Online</title>
  <%= stylesheet_link_tag   "application" %>
  <%= requirejs_include_tag "application" %>
  <%= csrf_meta_tags %>
  <meta charset="utf-8">
</head>
<body>

<%= yield %>

</body>
</html>

  4. Organize your JavaScript or CoffeeScript code into modules using define():

    # app/assets/javascripts/views/tweet_view.js.coffee

define ['backbone'], (Backbone) ->
  class TweetView extends Backbone.View
    # ...

  5. Instantiate your app using require() from a top-level module such as application.js:

    # app/assets/javascripts/application.js.coffee

require ['jquery', 'backbone', 'TheApp'], ($, Backbone, TheApp) ->

  # Start up the app once the DOM is ready
  $ ->
    window.App = new TheApp()
    Backbone.history.start
      pushState: true
    window.App.start()

  6. When ready, build your assets for production deployment as usual.
    requirejs-rails defaults to a single-file build of application.js.
    Additional modules and r.js layered builds may be specified via
    config/requirejs.yml; see the Configuration section below.

    rake assets:precompile

Configuration

The Basics

Configuration lives in config/requirejs.yml. These values are inspected and
used by requirejs-rails and passed along as configuration for require.js and
r.js. The default configuration declares application.js as the sole
top-level module. This can be overridden by creating
a config/requirejs.yml, such as:

modules:
  - name: 'mytoplevel'

You may pass in require.js config
options as needed. For example,
to add path parameters:

paths:
  d3: "d3/d3"
  "d3.time": "d3/d3.time"

Layered builds

Only modules specified in the configuration will be created as build artifacts
by r.js. Layered r.js
builds be
configured like so:

modules:
  - name: 'appcommon'
  - name: 'page1'
    exclude: ['appcommon']
  - name: 'page2'
    exclude: ['appcommon']
priority: ['appcommon']

In this example, only modules page1 and page2 are intended for direct
loading via requirejs_include_tag. The appcommon module contains
dependencies shared by the per-page modules. As a guideline, each module in
the configuration should be referenced by one of:

  • A requirejs_include_tag in a template
  • Pulled in via a dynamic require() call. Modules which are solely
    referenced by a dynamic require() call (i.e. a call not optimized by r.js)
    must be specified in the modules section in order to produce a correct
    build.
  • Be a common library module like appcommon, listed in the priority config
    option.

Almond support

This gem supports single-file builds with
almond. Use the following setting in
application.rb to enable it:

config.requirejs.loader = :almond

Almond builds have the restriction that there must be exactly one modules entry in
requirejs.yml. Typically the wrap option will be used to create a self-contained build:

modules:
  - name: 'main'
wrap: true

Build-time asset filter

The requirejs-rails build process uses the Asset Pipeline to assemble assets
for the r.js build. By default, assets ending in .js, .html, and .txt
will be made available to the build. If you have other asset suffixes to
include, use the logical_path_patterns config setting to add them.

For example, if your templates all end in .templ like so...

// in app/assets/javascripts/myapp.js
define(function (require) {
  var stuff = require('text!stuff.templ');
  // ...
});

... then this config setting will ensure they're picked up in the build:

# in config/application.rb
config.requirejs.logical_path_patterns += [/\.templ$/]

Advanced features

Additional data attributes

requirejs_include_tag accepts an optional block which should return a hash.
This hash will be used to populate additional data-... attributes like so:

<%= requirejs_include_tag "page1" do, controller, { 'foo' => controller.foo,
        'bar' => controller.bar
      }
    end
%>

This will generate a script tag like so:

<script data-main="/assets/page1.js" data-foo="..." data-bar="..." src="/assets/require.js"></script>

External domain (CDN) support

There are two ways in which requirejs-rails supports the use of different
domains for serving built JavaScript modules, as is the case when using
a CDN.

  1. URLs in paths config in requirejs.yml:

    If requirejs-rails encounters an URL as the right-hand side of a paths
    configuration, it will correctly emit that as "empty:" during the build
    process so that r.js will do the right thing.

    Example:

    paths:
  jquery: "https://ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.min.js"

  2. Deploying all requirejs-rails assets to a CDN:

    In config/environments/production.rb (or another environment)
    set the run_config as follows:

    config.requirejs.run_config['baseUrl'] = 'http://mycdn.example.com/12345abc/assets'

    The asset_sync gem is one
    tool that can be used to deploy your built assets to a CDN (S3, in this
    case).

Troubleshooting

Avoid config.assets.precompile

Don't set config.assets.precompile to reference any of your AMD module code.
Avoid it altogether, except to reference non-AMD code that you're loading via
javascript_include_tag, and which is never referenced by the AMD codebase.

Using AMD libraries

I currently recommend placing your AMD libraries into
vendor/assets/javascripts. The needs of a few specific libraries are
discussed below.

jQuery

jQuery users must use jQuery 1.7 or later (jquery-rails >= 1.0.17) to use it as an AMD module with RequireJS. To use jQuery in a module:

# app/assets/javascripts/hello.js

define ['jquery'], ($) ->
  (id) ->
    $(id).append('<div>hello!</div>')

Backbone.js

Backbone 0.9.x doesn't support AMD natively. I recommend the amdjs
fork of Backbone which adds AMD
support and actively tracks mainline.

Underscore.js

Underscore 1.3.x likewise doesn't have AMD support. Again, see
the amdjs fork of Underscore.

0.x API Changes

Usage changes that may break functionality for those upgrading along the 0.x
series are documented here. See the Changelog for the full
list of feature additions, bugfixes, etc.

v0.9.2

  • Support for Rails 4.

v0.9.0

  • The upgrade to RequireJS and r.js 2.0 includes changes that will break some
    apps.

v0.5.1

  • requirejs_include_tag now generates a data-main attribute if given an argument, ala:

    <%= requirejs_include_tag "application" %>

    This usage is preferred to using a separate
    javascript_include_tag, which will produce errors from require.js or
    r.js if the included script uses define anonymously, or not at all.

v0.5.0

  • application.js is configured as the default top-level module for r.js builds.
  • It is no longer necessary or desirable to specify baseUrl explicitly in the configuration.
  • Users should migrate application configuration previously in application.js (ala require.config(...)) to config/requirejs.yml

TODOs

Please check out our GitHub issues page
to see what's upcoming and to file feature requests and bug reports.

Copyright 2011-2014 John Whitley. See the file MIT-LICENSE for terms.

主要指標

概覽
名稱與所有者jwhitley/requirejs-rails
主編程語言JavaScript
編程語言Ruby (語言數: 5)
平台
許可證MIT License
所有者活动
創建於2011-11-17 02:17:35
推送於2022-12-13 20:32:05
最后一次提交2019-09-12 21:22:26
發布數21
最新版本名稱0.9.5 (發布於 )
第一版名稱v0.0.1 (發布於 2011-11-16 19:22:00)
用户参与
星數590
關注者數17
派生數199
提交數271
已啟用問題?
問題數181
打開的問題數47
拉請求數48
打開的拉請求數22
關閉的拉請求數48
项目设置
已啟用Wiki?
已存檔?
是復刻?
已鎖定?
是鏡像?
是私有?