Carabiner

Category:Libraries

Carabiner is a library for managing JavaScript and CSS assets. It's different from others that currently exist (for CodeIgniter, anyway) in that it acts differently depending on whether it is in a [i]production[/i] or [i]development[/i] environment. In a production environment, it will combine, minify, and cache assets. (As files are changed, new cache files will be generated.) In a development environment, it will simply include references to the original assets.

[size=3][b]Requirements[/b][/size] Carabiner requires the [url=http://codeigniter.com/forums/viewthread/103039/]JSMin[/url] and [url=http://codeigniter.com/forums/viewthread/103269/]CSSMin[/url] libraries that I previously ported. They're both included in this release. You don't need to load them, unless you'll be using them elsewhere. Carabiner will load them automatically as needed. [i](Note: the only reason they're included as separate libraries is that it allows you to use them independently of Carabiner. If desired, you could probably include them in the carabiner.php file itself. You'd have to edit the Carabiner functions, but it could work.)[/i]

[size=3][b]GZIP, Packer, etc.[/b][/size] Carabiner does not implement GZIP encoding, because I think that the web server should handle that. I think GZIPing is important, I just prefer not to do it PHP. If you need GZIP in an Asset Library, [url=http://code.google.com/p/assetlib-pro/]AssetLibPro[/url] does it. I've also chosen not to implement any kind of JavaScript obfuscation (like [url=http://dean.edwards.name/packer/]packer[/url]), primarily because of the client-side decompression overhead. More about this idea from [url=http://ejohn.org/blog/library-loading-speed/]John Resig[/url]. However, that's not to say you can't do it. You can easily provide a production version of a script that is packed. However, note that combining a packed script with minified scripts could cause problems. In that case, you can flag it to be not combined. (See usage below) Also, that's not to say that I won't port a [url=http://joliclic.free.fr/php/javascript-packer/en/]PHP Version[/url] and include it eventually.

[size=3][b]Inspiration/License[/b][/size] Carabiner is inspired by [url=http://code.google.com/p/minify/]Minify[/url], [url=http://rakaz.nl/extra/code/combine/]PHP Combine[/url] by Niels Leenheer and [url=http://code.google.com/p/assetlib-pro/]AssetLibPro[/url] by Vincent Esche, among other things. Carabiner is released under a [url=http://www.opensource.org/licenses/bsd-license.php]BSD License[/url].

[size=3][b]Usage[/b][/size] Load the library as normal: [code]$this->load->library('carabiner');[/code]

Configuration can happen in either a config file, or by passing an array of values to the config() method. Config options passed to the config() method will override options in the config file.

See the included config file for more info.

To configure Carabiner using the config() method, do this: [code]$carabiner_config = array( 'script_dir' => 'assets/scripts/', 'style_dir' => 'assets/styles/', 'cache_dir' => 'assets/cache/', 'base_uri' => $base, 'combine' => TRUE, 'dev' => FALSE );

$this->carabiner->config($carabiner_config);[/code]

There are 8 relevant configuration options. The first 3 are required for Carabiner to function, the last 5 are not.

[b]script_dir[/b] STRING Path to the script directory. Relative to the CI front controller (index.php)

[b]style_dir[/b] STRING Path to the style directory. Relative to the CI front controller (index.php)

[b]cache_dir[/b] STRING Path to the cache directory. Must be writable. Relative to the CI front controller (index.php)

[b]base_uri[/b] STRING Base uri of the site, like 'http://www.example.com/'. Defaults to base_url config setting from main CodeIgniter config.

[b]dev[/b] BOOLEAN Flags whether your in a development environment or not. See above for what this means. Defaults to FALSE.

[b]combine[/b] BOOLEAN Flags whether to combine files. Defaults to TRUE.

[b]minify_js[/b] BOOLEAN Flags whether to minify javascript. Defaults to TRUE.

[b]minify_css[/b] BOOLEAN Flags whether to minify CSS. Defaults to TRUE.

Add assets like so: [code]// add a js file $this->carabiner->js('scripts.js');

// add a css file $this->carabiner->css('reset.css');

// add a css file with a mediatype $this->carabiner->css('admin/print.css','print');[/code]

To set a (prebuilt) production version of an asset: [code]//JS: pass a second string to the method with a path to the production version $this->carabiner->js('wymeditor/wymeditor.js', 'wymeditor/wymeditor.pack.js' );

// CSS: add a css file with prebuilt production version $this->carabiner->css('framework/type.css', 'screen', 'framework/type.pack.css');[/code]

And to prevent a file from being combined: [code]// JS: pass a boolean FALSE as the third attribute of the method $this->carabiner->js('wymeditor/wymeditor.js', 'wymeditor.pack.js', FALSE );

// CSS: pass a boolean FALSE as the fourth attribute of the method $this->carabiner->css('framework/type.css', 'screen', 'framework/type.pack.css', FALSE);;[/code]

You can also pass arrays (and arrays of arrays) to these methods. Like so: [code]// a single array $this->carabiner->css( array('mobile.css', 'handheld', 'mobile.prod.css') );

// an array of arrays $js_assets = array( array('dev/jquery.js', 'prod/jquery.js'), array('dev/jquery.ext.js', 'prod/jquery.ext.js'), )

$this->carabiner->js( $js_assets );[/code]

Carabiner is smart enough to recognize URLs and treat them differently: [code]// this now works as expected $this->carabiner->js('http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.js');[/code]

To output your assets, including appropriate markup: [code]// display css $this->carabiner->display('css');

//display js $this->carabiner->display('js');

// display both $this->carabiner->display(); // OR $this->carabiner->display('both');[/code]

Finally, since Carabiner won't delete old cached files, you'll need to clear them out manually. To do so programatically: [code]// clear css cache $this->carabiner->empty_cache('css');

//clear js cache $this->carabiner->empty_cache('js');

// clear both $this->carabiner->empty_cache(); // clear both $this->carabiner->empty_cache(); // OR $this->carabiner->empty_cache('both');[/code]

Download Carabiner in the [url=http://codeigniter.com/forums/viewthread/105693/]Ignited Code thread[/url] or from the Wiki: File:carabiner_1.2.zip.