nlsclientscript NLSClientScript extends the CClientScript class smart loading javascript files and optionally merging/minifying js+css files

Project moved to github as 7.0beta

  1. History
  2. Requirements
  3. Limitations
  4. Usage (v6.3+)
  5. Resources

Motivated by earlier suggestions, a lot of improvements made on the library.

  • What's new compared to 6.x?
  • huge refactor
  • one-file code splitted to parts
  • completely new css processing part: processing @import-s, url-s
  • composer support
  • demo app
  • moved to github

Visit ***

NLSClientScript prevents duplicated linking of javascript files when updating a view by ajax, when eg. paging or sorting a gridview, ajax-submitting a form or any custom ajax-updating a part of a view.

The extension does not prevent the multiple loading of CSS files. I simply couldn't find a way to manage it clearly (too long to explain here).

The issue what this extenson fights is for example when you render Jui widgets by CHtml::ajax, the js files used by the widget will be loaded as many times as you render such a widget in a view. The unnecessary bandwidth usage is the smaller problem, the bigger problem is eg. loading jquery.js again may reset some js objects set by previously loaded ui-related js files. That can cause js errors and the view may stop working.

Using NLSClientScript helps to avoid it all.

From 6.0, it optionally merges/caches + minifies the registered js and css files.


  • 6.7
  • fixed toAbsUrl() and optimized init() methods (reported + fix by le_top)
  • 6.6
  • fixed regexp in normUrl (reported by le_top)
  • 6.5
  • fixed buggy behavior when more xhr "script"-dataType requests started for the same script
  • eliminated deprecated jQuery.browser reference
  • 6.4
  • followed the change of the registerScriptFile() arguments in yii 1.1.14
  • removed/added some comments
  • 6.3
  • serious bug fixed: filtering duplications (usually) failed when js-merging applied for the response of an xhr request
  • new params: mergeIfXhr, mergeJsExcludePattern, mergeJsIncludePattern, mergeCssExcludePattern, mergeCssIncludePattern, resMap2Request (see the phpdoc comments in the source for more info)
  • appended an extra ; to the js files
  • some other small improvements

  • 6.21
  • fixed another bug: merged files have been re-generated on every request when the appVersion parameter was used

  • 6.2 (see the updated Usage)
  • fixed a serious bug broke the original functionality when merging happened (duplicates couldn't been recognized)
  • added a new parameter appVersion

  • 6.1 (see the updated Usage)
  • fixed several bugs (serverBaseUrl composing, merging css files by media correctly)
  • added parameters mergeAbove, curlTimeOut, curlConnectionTimeOut

  • 6.0 (see the updated Usage)
  • added optional merge and minify functionalities
  • to keep the simpleness of the single-file extension, embedded JSMin.php from

  • 5.0 (see the updated Usage)
  • in 4.0RC found an issue couldn't worked around: it registered also the script tags being in html/css/js comments, input field, textarea value so i had to drop the native source analysis by regexp. Fortunately found the solution in 5.0 looks like the most perfect till now. Tested successfully in IE7+, latest FF,Chrome,Opera. Reports about testing are welcome as always.

  • 4.0 RC
  • refactored, hopefully all bugs reported about 3.x have been eliminated

  • 3.6
  • fixed a typo

  • 3.5 (see the updated Usage)
  • handling special case when updating a table by tr tag
  • further IE fixes
  • added 2 new parameters: ignoredPattern and processedPattern
  • general refactoring

  • 3.4
  • fixed non-script-rendering bug in IE

  • 3.3
  • removes the occasional ...?_=3767454656434 -like timestamps from the url keys used to store/identify the loaded scripts
  • fixed the accidental naming NLSClientScript to EClientScript

  • 3.2
  • fixed accessing HEAD element for IE
  • compressed js code (full source is still there in the php source)

  • 3.1
  • the extension now prevents the duplicated loading of css files also.

  • 3.0
  • brand new approach simplifying dramatically the extension and the usage of the extension, based the great idea of Eirik Hoem
  • see the Usage below!

  • 2.1
  • dirty fix for a rendering bug of jquery.js v1.6.1 affecting binline=true mode in Yii 1.18
  • 2.0
  • brand new approach: resource hash stored at the server side, in the webuser state. All these info deleted when a non-ajax request comes
  • no $.ajax usage - better performance
  • the extension does not require jquery.js and jquery.yii.js to be linked initially any more
  • js/css files can be linked from other domain
  • new parameter: bInlineJs - if true, the scriptFile method will insert the js file content into the html instead of linking the file what can result even better performance

  • 1.3
  • added cache:true to the ajax js load
  • compressed core js code

  • 1.2
  • fixed js error when app not in YII_DEBUG mode
  • 1.1
  • hash key generated on server side
  • two hash key mode: PATH and CONTENT
  • shortened client-side code
  • 1.0
  • base version

If you interest the details, see the comments in the source.


Yii 1.x


  • The extension identifies the scripts by its paths so it does not prevent to load the same script content from different paths. So eg. if you published the same js file into different asset directories, NLSClientScript considers those to be different and won't prevent to load those several instances.

  • The extension doesn't watch wether a js/css file has been changed. If you set the merge functionality and some file changed, you need to delete the cached merged file manually, otherwise you'll get the old merged one.

Usage (v6.3+)

1 . Set the class for the clientScript component in /protected/config/main.php, like

  'clientScript' => array(
    'class' => '',
    //'excludePattern' => '/\.tpl/i', //js regexp, files with matching paths won't be filtered is set to other than 'null'
    //'includePattern' => '/\.php/', //js regexp, only files with matching paths will be filtered if set to other than 'null'

    'mergeJs' => true, //def:true
    'compressMergedJs' => false, //def:false

    'mergeCss' => true, //def:true
    'compressMergedCss' => false, //def:false
    'mergeJsExcludePattern' => '/edit_area/', //won't merge js files with matching names
    'mergeIfXhr' => true, //def:false, if true->attempts to merge the js files even if the request was xhr (if all other merging conditions are satisfied)

    'serverBaseUrl' => 'http://localhost', //can be optionally set here
    'mergeAbove' => 1, //def:1, only "more than this value" files will be merged,
    'curlTimeOut' => 10, //def:10, see curl_setopt() doc
    'curlConnectionTimeOut' => 10, //def:10, see curl_setopt() doc
    'appVersion'=>1.0 //if set, it will be appended to the urls of the merged scripts/css

For more information about the parameters, see the header comment of NLSClientScript.php.

2 . use Yii::app()->getClientScript() by the standard way to link js and css files/snippets


$cs = Yii::app()->getClientScript();
$systemJsPath = Yii::app()->getAssetManager()->publish( Yii::getPathOfAlias( 'system.web.js' ), false, -1, false );
$cs->registerScriptFile( $systemJsPath . '/ext/yii_ext.js');
$cs->registerScriptFile( $systemJsPath . '/ext/plugins/jquery.form.js');

3 . DOES NOT WORK FROM v5.0: If you want to do a custom ajax request with "dataType"="json" and there are some fields of the response you want to update your page with, filter that part "by hand" with $.ajaxSettings.dataFilter like eg.:

echo CHtml::ajaxLink('custom update', array('/site/testupdate'), array(

  'dataType' => 'json',

  'success'=>'js:function(data){ $("#cont").html($.ajaxSettings.dataFilter(data.content)); }',



34 0
7 042 downloads
Yii Version: 1.1
License: BSD-2-Clause
Category: Others
Developed by: nlac
Created on: Jun 1, 2011
Last updated: 9 years ago


show all

Related Extensions