README

This is my second draft of an Assets plugin for Lithium PHP. The first was a great learning experiance but I've decided there are a number of things I would change.

This Plugin now uses the awesome Assetic library to power many of it's features.

Installation

There are several ways to grab and use this project:

Use Composer

Best Option (default)

Other install options require a configuration parameter be set in Libraries::add() More on that later.

Modify your projects composer.json file

{
    "require": {
    	...
        "joseym/li3_frontender": "master"
        ...
    }
}

Run php composer.phar install (or php composer.phar update) and, aside from adding it to your Libraries, you should be good to go.

Load via Submodule

More manual, bleh. Seriously, Composer is awesome

This option requires that you tell the plugin you are not using composer. See library option (source)

Clone/Download the plugin into your app's libraries directory.
Tell your app to load the plugin by adding the following to your app's config/bootstrap/libraries.php:

Libraries::add('li3_frontender', array('source' => 'submodule'));

Important to set the source to something else as 'composer'. Configuration options are available, standby
Pull in the the project dependencies.

Currently dependancies include Assetic, Symfony/Process and LessPHP.

$ cd app/libraries/li3_frontender
$ git submodule init
$ git submodule update

Usage

If you use coffee script you will have to ensure Node.JS and CoffeeScript are running on your server.

This project also comes packaged with YUI Compressor, which Assetic uses for compression of JS and CSS assets.

Currently this project supports the following frontend tools:

LessCSS compiling
CoffeeScript compiling
Instant cache busting thru unique filenames
CSS/JS Compression

The project comes bundled with it's own Helper, here's how use use it.

Linking Stylesheets

You assign page styles much like you would with the out-of-the-box Html helper

<?php $this->assets->style(array('main', 'menu', 'magic.less')); ?>

You may have noticed the .less file in there. Adding the file extension is required for .less files to ensure they are compiled, you may include the .css extension for standard stylesheets or just leave it off.

Linking Scripts

Like the style helper, the script helper also takes an array.

<?php $this->assets->script(array('plugins', 'common', 'niftythings.coffee')); ?>

Just like the .less file in the last example, if you pass a .coffee file to the script helper the plugin will compile it and serve up the proper, compiled, js. All other files are assumed .js. Feel free to add .js to these extensions if you would like.

Production vs Development

The backend of this plugin will do its best to determine if you're in a dev environment or production, if you're in a production environment this plugin will automatically compress your stylesheets and scripts and merge them into a single file and serve that file up to your layout or view.

This option, and several others are overwriteable from the Libraries::add() configuration. Here's an example

<?php
	Libraries::add('li3_frontender', array(
		'compress' => false,
		'production' => true,
		'assets_root' => LITHIUM_APP_PATH . "/webroot/assets",
		'locations' => array(
			'coffee' => '/usr/bin/libs/coffee',
			'node' => '/usr/bin/libs/node'
		),
		'source' => 'submodule',
		'cacheOnly' => true
	));
?>

Configuration options

Manifests

Use asset manifests if you wish to specify your assets in the library config rather than in the view.

First, specify the manifest like this (below, "main" is the name of a manifest for JavaScript files):

<?php
	Libraries::add('li3_frontender', array(
		'manifests' => array(
			'js' => array(
				'main' => array(
					'main.coffee',
					'popup.js'
				)
			)
		)
	));
?>

Then, reference the manifest by name when calling the helper:

<?php $this->assets->script('main'); ?>

Collaborate

As always, I welcome your collaboration to make things "even more betterer", so fork and contribute if you feel the need; these blokes did and the project is even more awesomer'r because of them.

joseym / li3_frontender

Maintainers

Details