HearsayRequireJSBundle
Overview
This bundle provides integration of the RequireJS library into Symfony2., (*1)
Installation
1. Using Composer (recommended)
To install HearsayRequireJSBundle with Composer just add the following to
your composer.json file:, (*2)
{
// ...
"require": {
// ...
"hearsay/require-js-bundle": "2.0.*@dev"
// ...
}
// ...
}
Note that the master branch is under development and unstable yet. If you
want to use stable version then specify the 1.0.* version. However, remember
that the 1.0 branch no longer provides new features, only bug fixes., (*3)
Then, you can install the new dependencies by running Composer's update command
from the directory where your composer.json file is located:, (*4)
$ php composer.phar update hearsay/require-js-bundle
Now, Composer will automatically download all required files, and install them
for you. All that is left to do is to update your AppKernel.php file, and
register the new bundle:, (*5)
<?php
// in AppKernel::registerBundles()
$bundles = array(
// ...
new Hearsay\RequireJSBundle\HearsayRequireJSBundle(),
// ...
);
Configuration
This bundle configured under the hearsay_require_js key in your application
configuration. This includes settings related to paths, shim, optimization, and
more., (*6)
require_js_src
type: string default: //cdnjs.cloudflare.com/ajax/libs/require.js/2.1.8/require.min.js, (*7)
This is a string that represents the template name which will render the
RequireJS src or an URL to the RequireJS., (*8)
initialize_template
type: string default: HearsayRequireJSBundle::initialize.html.twig, (*9)
This is a string that represents the template name which will render the
RequireJS initialization output. You can pass into this template any extra
options., (*10)
base_url
type: string default: js, (*11)
This is a string that represents the base URL where assets are served, relative
to the website root directory. This URL also will exposed as an empty
namespace., (*12)
base_dir
type: string default: null required, (*13)
This is a string that represents the base URL for the r.js optimizer, that
is generally actually a filesystem path., (*14)
paths
type: array default: null, (*15)
This is a prototype that represents an array of paths. Each path:, (*16)
- includes the location and the key that determines whether the path is an
external;
- the location can be a string as well as an array of values
(paths fallbacks);
- the location can expose a file as well as a directory, if the location is a
file then MUST NOT ends with the
.js file extension;
- the location can referred to the files using a path like
@AcmeDemoBundle/Resources/public/js/src/modules;
- by default, is not an external;
- if specified as an external, will marked as an empty for the r.js
optimizer;
- will exposed as a namespace.
shim
type: array default: null, (*17)
This is a prototype that represents an array of shim, corresponds to the
RequireJS shim config., (*18)
options
type: array default: null, (*19)
An array of key-value pairs to pass to the RequireJS. The value can have
variable type., (*20)
optimizer
type: array default: null, (*21)
This block includes the r.js optimizer configuration options., (*22)
path
type: string default: null, (*23)
This is a string that represents the path to the r.js optimizer., (*24)
hide_unoptimized_assets
type: boolean default: false, (*25)
This determines whether the r.js optimizer should suppress unoptimized files., (*26)
exclude
type: array default: [], (*27)
An array of module names to exclude from the build profile., (*28)
modules
type: array default: null, (*29)
This is a prototype that represents an array of modules options for r.js
optimizer. Each array must contain name of the module and could contain include
and exclude options that explicitly includes/excludes defined dependencies. See
multipage module config for more details., (*30)
options
type: array default: null, (*31)
An array of key-value pairs to pass to the r.js optimizer. The value can have
variable type., (*32)
timeout
type: integer default: 60, (*33)
This determines the node.js process timeout, in seconds., (*34)
almond_path
type: string default: false, (*35)
This is a string that represents the path to almond.js., (*36)
declare_module_name
type: boolean default: false, (*37)
This is a boolean that configures module declarations as their actual module name or if it will be an md5 representation., (*38)
Full Default Configuration
hearsay_require_js:
require_js_src: //cdnjs.cloudflare.com/ajax/libs/require.js/2.1.8/require.min.js
initialize_template: HearsayRequireJSBundle::initialize.html.twig
base_url: js
base_dir: ~ # Required
paths:
# Prototype
path:
location: ~ # Required
external: false
shim:
# Prototype
name:
deps: []
exports: ~
options:
# Prototype
name:
value: ~ # Required
optimizer:
path: ~ # Required
hide_unoptimized_assets: false
almond_path: ~
exclude: []
modules:
# Prototype
name:
include: ~
exclude: ~
options:
# Prototype
name:
value: ~ # Required
timeout: 60
Usage
Just output the RequireJS initialization and load files normally:, (*39)
{{ require_js_initialize() }}
Alternately, you can specify a file to be required immediately via the
data-main attribute:, (*40)
{{ require_js_initialize({ 'main' : 'demo/main' }) }}
If you need to do anything fancy with the configuration, you can do so
manually by modifying the default configuration, and suppressing config output
when initializing RequireJS:, (*41)
{{ require_js_initialize({ 'configure' : false }) }}
To make global changes to the configuration/initialization output, you can
specify an initialization template in your configuration:, (*42)
# app/config/config.yml
hearsay_require_js:
initialize_template: ::initialize_require_js.html.twig
To use this bundle with CoffeeScript, you can specify a path that contains
.coffee scripts. The scripts will renamed to .js scripts., (*43)
Note that the r.js optimizer cannot optimize .coffee scripts. However, you
can apply the Assetic filter to this scripts by the file extension., (*44)
Optimization
This bundle provides the Assetic filter to create minified Javascript files
using by r.js optimizer. This also inlines any module definitions required by
the file being optimized. You need to provide a path to the r.js optimizer in
your configuration to use the filter:, (*45)
# app/config/config.yml
hearsay_require_js:
optimizer:
path: %kernel.root_dir%/../r.js
You can then use it like any other filter; for example, to optimize only in
production:, (*46)
{% javascripts
filter='?requirejs'
'@AcmeDemoBundle/Resources/public/js/src/main.js'
%}
{{ require_js_initialize({ 'main' : asset_url }) }}
{% endjavascripts %}
Note that your configured path definitions will be incorporated into the
optimizer filter, including the exclusion of external dependencies from the
built profile's file., (*47)
If you wish to prevent unoptimized assets from being served (in e.g. production),
you can suppress them:, (*48)
# app/config/config.yml
hearsay_require_js:
optimizer:
path: %kernel.root_dir%/../r.js
hide_unoptimized_assets: true
If you're doing this, be sure that all the modules you need are bundled into
your optimized assets (i.e. you're not accessing any modules by dynamic name, or
if you are, then you're explicitly including those modules via optimizer
options), otherwise you may see certain assets available in development, but
not in production., (*49)
Testing
$ make test
Contributing
Please see CONTRIBUTING for details., (*50)
Credits
License
This bundle is released under the MIT license. See the complete license in the
bundle:, (*51)
Resources/meta/LICENSE
Wallogit.com
