Skip to content

Latest commit

 

History

History
202 lines (158 loc) · 7.22 KB

README.md

File metadata and controls

202 lines (158 loc) · 7.22 KB
Raw

Assets Plugin for li3

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)

  1. Clone/Download the plugin into your app's libraries directory.

  2. 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

  3. 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:

  1. LessCSS compiling
  2. CoffeeScript compiling
  3. Instant cache busting thru unique filenames
  4. 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

Name Options Defaults Description
compress bool (true/false) false Force assets to be compressed, if production this defaults to true, otherwise false.
production bool (true/false) attempts to read from Lithium Environments class Force assets to render in production or not, if this isn't set then the plugin will attempt to determine this automagically.
assets_root Pass in a path to your assets LITHIUM_APP_PATH . "/webroot" Where should the plugin look for your files, defaults to the standard webroot directory. The example above would look for CSS files in /webroot/assets/css/
locations array: coffee - path to coffeescript on server
node - path to node on server		 coffee - /usr/bin/coffee
node - /usr/bin/node		 These are the locations of node and coffeescript on your server, defaults should suffice.
source string: composer
submodule		 composer This determines where the library will pull dependency libraries, composer uses vendor paths in `libraries/_source` whereas submodule loads librarys within this plugin `libraries/li3_frontender/libraries`. Normally you only need to set this option if you do not install this plugin via composer.
cacheOnly boolean false If true, will display a 404 if the assets could not be read from cache. For some plugins, such as `li3_docs` this will result in not being able to load the css contained in the plugin.
manifests array null If set, you can specify assets in named lists in the config, then reference them from the helper by name. See below.

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.