- Configuration Options
- Configuration Example
- Usage In Layouts and Views
- Compiling Assets From The Console
Yii extension for js/less asset compilation and management
Github repo: https://github.com/machadolab/yii-assetcompiler
This extension uses the Google Closure compiler and lessphp to compile your assets into combined/optimized versions. The extension can do this compilation on the fly (using the autoCompile/forceCompile configuration parameters) but is designed to be compiled at deployment time using a yii console command. Views and layouts then make reference to the asset groups to bring in either the compiled asset (production mode) or the raw asset components (in developer mode).
The lessphp compiler was chosen because it is compatible with the Bootstrap framework's usage of LESS.
By default, the extension will look for these packages installed in
protected/vendor/lessphp, respectively. Simply extract compiler-latest.zip into protected/vendor/googleclosure and lessphp-0.3.5.tar.gz into protected/vendor/lessphp.
If you put these packages in another locaiton, you must manually set the googleClosure and/or plessc configuration options to their respective locations (see Configuration Options below ffor details).
extensions directory to your /protected/extensions directory and the contents of
commands to your /protected/commands directory.
Edit your main.php configuration file using the Configuration Options/Configuration Example below.
This extension supports developer mode whereby it renders the HTML to serve up the individual uncompiled files and uses less.js to serve the raw less files as well as a production mode where it serves the compiled/compressed files. By default this extension uses the YII_DEBUG define to know if it is in production mode or developer mode. If you run YII_DEBUG=true in production (you shouldn't be!), you can explicitly set the debugMode => false option.
In production mode (debugMode=>false), the compiled versions of the group are registered with the page.
Configuration Options ¶
All but the
groups option have sensible defaults that you will likely not need to change anything, but in case you need to adapt to your environment, the following configuration options can be passed as an element in the 'assetCompiler' array to control behavior, override defaults and set paths. Defaults for the option are listed in  next to the option name.
groups - This is the heart of the extension, defining what different groups of files you want to combine. More detail in the Groups section below.
basePath[root of application] - Path to application on filesystem.
baseUrl[webroot detected by Yii] - URL of application.
debugMode[YII_DEBUG] - (true/false) Enable debug/developer mode or not, defaults to using YII_DEBUG define.
autoCompile[false] - (true/false) Automatically check the timestamp of the output file and if it is older than any of the component file(s), automatically recompile the group. For autoCompile to be affective, you should preload the assetCompiler component in the Yii 'preload' section.
forceCompile[false] - (true/false) Recompile the group when it is used everytime to matter the timestamps - useful for debugging or dev mode.
googleClosureJavaPath[java] - Path to java program to run google closure compiler.jar.
googleClosureJarFile[approot/protected/vendor/googleclosure/compiler.jar] - Path to google closure compiler.jar file.
googleClosureCompilationLevel[WHITESPACE_ONLY] - Google closure compilation level, passed directly to java command. Options are WHITESPACE_ONLY, SIMPLE_OPTIMIZATIONS and ADVANCED_OPTIMIZATIONS. Read the google closure documentation for more detail.
lessCompiler[plessc] - Which less compiler to use - currently only 'plessc' is supported. Others may be supported in the future.
plesscPath[approot/protected/vendor/lessphp/plessc] - Path to plessc command from the lessphp package.
plesscFormat[compressed] - Which output format for plessc, passed directly to plessc command. Options are 'default' and 'compressed'.
Groups are the core part of this extension.
A group is defined as a name and an array value containing settings. The group name is used later in layout/views in calls to
Yii::app()->assetCompiler->registerAssetGroup(). A group definition looks like:
'siteJs' => array( 'type' => 'js', 'files' => array('js/script1.js','js/script2.js'), 'output' => 'js/scripts-min.js', ),
Configuration Example ¶
The following would go into your Yii 'components' array:
'assetCompiler'=>array( 'class' => 'ext.assetCompiler.AssetCompiler', 'lessJsUrl' => '/app/js/less-1.3.0.min.js', 'groups' => array( 'siteJs' => array( 'type' => 'js', 'files' => array('js/script1.js','js/script2.js'), 'output' => 'js/scripts-min.js', ), 'bootstrapJs' => array( 'type' => 'js', 'files' => array('js/bootstrap-transition.js','js/bootstrap-tooltip.js', 'js/bootstrap-tab.js','js/bootstrap-modal.js','js/bootstrap-alert.js', 'js/bootstrap-button.js','js/bootstrap-popover.js','js/bootstrap-dropdown.js'), 'output' => 'js/bootstrap-min.js', ), 'siteLess' => array( 'type' => 'less', 'file' => 'css/bootstrap/myapp.less', 'output' => 'css/style-min.css', ), ), ),
Usage In Layouts and Views ¶
From layouts or views, you can call the registerAssetGroup() method just like you would call clientScript->registerScriptFile() to have either the group components (in debug/dev mode) or the compiled asset (in non-debug/dev mode) registered in the page.
Compiling Assets From The Console ¶
To compile assets, make sure the commands/AssetCompilerCommand.php file is in your protected/commands/ directory and run from the protected/ directory:
./yiic assetcompiler all
You can also choose to compile a specifc group by:
./yiic assetcompiler group --group=siteJs
or just specific types of asset groups ~~~ ./yiic assetcompiler js
./yiic assetcompiler less ~~~