This bundle provides an easy way to:
- generate require.js config file for a project;
- optimize, minify and merge all JS-file into one resources.
For details of configuration options see RequireJS API.
For details of build options see example.build.js.
OroRequireJSBundle requires fxpio/composer-asset-plugin to manage dependency in third-party asset libraries. The plugin has to be installed globally (per user):
composer self-update
composer global require "fxp/composer-asset-plugin"Common options for require.js config are placed in app/config.yml:
oro_require_js:
config: # common options which will eventually get into require.js config file
waitSeconds: 0
enforceDefine: true
scriptType: 'text/javascript'
Bundle specific options are defined inside requirejs.yml file, which is placed in %BundleName%\Resources\config\requirejs.yml.
It can have three sections shim, map and paths (see RequireJS API).
Each bundle's javascript module have to be defined in paths section, where key is a module name and value is its relative path from the document root.
config:
shim:
'jquery-ui':
deps:
- 'jquery'
map:
'*':
'jquery': 'oroui/js/jquery-extend'
'oroui/js/jquery-extend':
'jquery': 'jquery'
paths:
'jquery': 'bundles/oroui/lib/jquery-1.10.2.js'
'jquery-ui': 'bundles/oroui/lib/jquery-ui.min.js'
'oroui/js/jquery-extend': 'bundles/oroui/js/jquery-extend.js'
Main require.js config is generated automatically and embedded in HTML-page. The config is stored in application cache. In case you wish to renew require.js configuration, just clean cache.
To get require.js script with its configuration on your page, just include scripts.html.twig template from OroRequireJSBundle to <head/> tag of your index.html.twig template.
<head>
<!-- -->
{% include 'OroRequireJSBundle::scripts.html.twig' %}
<!-- -->
</head>
The template scripts.html.twig accepts two optional parameters compressed and config_extend.
-
compressedis boolean (trueby default), determines whether to use minified js-file or not. Usually it's opposite toapp.devflag. -
config_extendis a string with javascript code, allows to extend requirejs configuration in runtime mode (see runtime require.js config).{% set requirejs_config_extend %} // custom javascript code {% endset %} {% include 'OroRequireJSBundle::scripts.html.twig' with { compressed: not app.debug, config_extend: requirejs_config_extend } %}
Sometimes it is not enough to specify require.js configuration settings statically, it is required to modify certain parameters dynamically at each launch. It is possible to do this over config_extend parameter for OroRequireJSBundle::scripts.html.twig template.
That variable can contain a piece of custom configuration which will be applied after general configuration is loaded and before any module is utilized.
E.g. to dynamically define the path to translation dictionary (depending on what locale is currently used):
{% set requirejs_config_extend %}
require({
paths: {
'oro/translations':
'{{ url('oro_translation_jstranslation')[0:-3] }}'
}
});
{% endset %}
In terms of sequence of code execution, it looks the following way:
- Prod mode (and built resource exists)
- execute all custom configurations
require(/* ... */); require(/* ... */); require(/* ... */); - load single minified js-resource (with
require-config.js+require.jsand rest of modules)
- execute all custom configurations
- Dev mode (or built resource does not exist)
- load
require.js - load
js/require-config.js - execute all custom configurations
require(/* ... */); require(/* ... */); require(/* ... */);
- load
See @OroRequireJSBundle::scripts.html.twig
Build configuration starts in app/config.yml
oro_require_js:
build_path: "js/oro.min.js" # relative path from document root folder to project built
building_timeout: 3600
js_engine: "node" # can be configured to use other engine, e.g. Rhino
build: # build.js's common options
optimize: "uglify2"
preserveLicenseComments: true
generateSourceMaps: true
useSourceUrl: true
See details for oro_require_js.build options.
Beside general build-configuration, you can set bundle specific options inside %BundleName%\Resources\config\requirejs.yml file, root section build.
build:
paths:
'autobahn': 'empty:'
This directive will prevent module from getting concatenated into build file.
To make a build for JS-resources, just execute a command in console:
php app/console oro:requirejs:build
It will:
- take initial configuration from
oro_require_js.build(app/config.yml); - extend it with configuration found in bundles (
%BundleName%\Resources\config\requirejs.yml); - generate
build.js- a config for builder; - run builder (time consuming process, especially for Rhino JS-engine);
- remove
build.js.