# sfLESSPlugin #

*less.js in symfony.*

sfLESSPlugin is a plugin for symfony applications. It's descendant of sfLessPhpPlugin, but with LESS2 compiler in mind.

It can do most of `less.js` can:

* Automatically parse your application `.less` files through LESS and outputs CSS files;
* Automatically include your application `.less` files into page source & enable browser-side LESS parsing.

## LESS & less.js ##

LESS extends CSS with: variables, mixins, operations and nested rules. For more information, see [http://lesscss.org](http://lesscss.org).

less.js is LESS2. It's written on pure JavaScript & can be runned on both sides - in browser or in node.js.

## Installation ##

### Using symfony plugin:install ###

Use this to install sfLESSPlugin:

	$ symfony plugin:install sfLESSPlugin

### Using git clone ###

Use this to install as a plugin in a symfony app:

	$ cd plugins && git clone git://github.com/everzet/sfLESSPlugin.git

### Using git submodules ###

Use this if you prefer to use git submodules for plugins:

	$ git submodule add git://github.com/everzet/sfLESSPlugin.git plugins/sfLESSPlugin
	$ git submodule init
	$ git submodule update

and enable plugin in your ProjectConfigurations class.

## Usage ##

After installation, you need to create directory `web/less`. Any LESS file placed in this directory, including subdirectories, will
automatically be parsed through LESS and saved as a corresponding CSS file in `web/css`. Example:

	web/less/clients/screen.less => web/css/clients/screen.css

If you prefix a file with an underscore, it is considered to be a partial, and will not be parsed unless included in another file. Example:

	<file: web/less/clients/partials/_form.less>
	@text_dark: #222;
	
	<file: web/less/clients/screen.less>
	@import "partials/_form";
	
	input { color: @text_dark; }

The example above will result in a single CSS file in `web/css/clients/screen.css`.

## Setup ##

sfLESSPlugin can use 2 workflows to manage your *.less files:

1. Compile on browser side by `less.js`;
2. Compile on server side by `lessc`.

### Update your layout files ###

Update your layout php files (at least the ones using less stylesheets):

* include the less css helper:

		<?php use_helper('LessCss'); ?>

* update the way stylesheets are included by changing `<?php include_stylesheets() ?>` for `<?php include_less_stylesheets() ?>`

### Compile on browser side ###

This is default plugin behaviour. In this behaviour, all stylesheets ending with `.less`, added:

* in your `view.yml` configs:

		stylesheets:      [header/main.less]
  
* in a template view file:

		<?php use_stylesheet('header/main.less') ?>

In this case, it will be automatically changed from something like

	<link href="/css/header/main.less" media="screen" rel="stylesheet" type="text/css" />

to

	<link href="/less/header/main.less" media="screen" rel="stylesheet/less" type="text/css" />

and will add link to `less.js` into javascripts list.

This will cause browser to parse your linked less files on the fly.

### Compile on server side ###

In details, sfLESSPlugin server side compiler does the following:

* Recursively looks for LESS (`.less`) files in `web/less`
* Ignores partials (prefixed with underscore: `_partial.less`) - these can be included with `@import` in your LESS files
* Saves the resulting CSS files to `web/css` using the same directory structure as `web/less`

You have to install 2 packages:

1. `node.js`;
2. `less.js`.

After that, enable server behavior & disable browser behavior in `app.yml`:

	sf_less_plugin:
	  compile:  true
	  use_js:   false

In this case, sfLESSPlugin will try to find all your less files inside `web/less/*.less` & compile them into `web/css/*.css`, so you can link your less styles as default css stylesheets:

	stylesheets:      [main.css]

## Configuration ##

sfLESSPlugin server side compiler rechecks `web/less/*.less` at every routes init. To prevent this, add this in your apps/APP/config/app.yml:

	prod:
	  sf_less_plugin:
	    compile:  false

sfLESSPlugin server side compiler checks the dates of LESS & CSS files, and will by default compile again only if LESS file have been changed since last parsing .

When you use `@import` statements in your LESS files, you should also turn on dependencies checking in one of you app.yml:

    dev:
      sf_less_plugin:
        check_dates:        true
        check_dependencies: true

**warning:** Checking for the dependencies will affect performances and should not be turned on in production

The safest (but probably slowest) option is to enforce everytime compiling:

	dev:
	  sf_less_plugin:
	    check_dates:	false

Also, sfLESSPlugin server side compiler has Web Debug Panel, from which you can view all styles to compile & can open them for edit in prefered editor. For that you need to configure sf_file_link_format in settings.yml.

Last but not least, you can enable CSS compression (remove of whitespaces, tabs & newlines) in server side compiler with:

	all:
	  sf_less_plugin:
	    use_compression:	true

## Tasks ##

sfLESSPlugin server side compiler provides a set of CLI tasks to help compiling your LESS styles.

To parse all LESS files and save the resulting CSS files to the destination path, run:

	$ symfony less:compile

To delete all compiled CSS (only files, that been compiled from LESS files) files before parsing LESS, run:

	$ symfony less:compile --clean

If you want to compress CSS files after compilation, run:

	$ symfony less:compile --compress

Also, by default tasks don't use settings from app.yml such as "path". But you can specify application option to tell compiler from which app to get config:

	$ symfony less:compile --application=frontend

If you want to compile specific file, not all, just use argument & file name without ".less". To compile style.less into style.css, just run:

	$ symfony less:compile style


## Contributors ##

* everzet (lead): [http://github.com/everzet](http://github.com/everzet)
* vicb (contributor): [http://github.com/vicb](http://github.com/vicb)

less.js is maintained by Alexis Sellier [http://github.com/cloudhead](http://github.com/cloudhead)

## History ##

### v1.1.0 released on 2010-07-01 ###

* added an helper to include less stylesheets in layouts / templates
* [client side] less javascript updated to version 1.0.30
* [server side] added a visual feedback in the debug bar when some files have been compiled
* [server side] added an optional dependency check