PHING! Party on Wayne. Party on Garth!

If you’ve never used Phing, it’s an automation tool for PHP that is a port of Java’s ANT Build tool. But it’s not just for building (obviously, that’d be silly). You can hook all kinds of tasks into Phing: unit tests for your PHP code (you’re doing test driven development, aren’t you?), building your documentation, etc. But today, let’s look at automation of my favorite front end development tasks: packing (minimizing) our JavaScript and CSS.

To do this, I’m going to hook you up with two Filters for Phing that will use the PHP port of Dean Edwards JavaScript Packer, and the PHP class CSSTidy.

Here’s what you’ll be responsible for:

1. Download both CSSTidy and the PHP port of Packer using the links above.
2. Download Phing if you don’t already have it, and install it. Note the following change I had to make to my Phing \bin\phing.bat file to get it working: Change set PHP_CLASSPATH="%PHING_HOME%\classes" to remove the quotes: set PHP_CLASSPATH=%PHING_HOME%\classes
3. Download the two Filters I made for Phing: JSPackerFilter.phps and CssTidyFilter.phps, change the extensions to .php and copy into your phing directory \classes\phing\filters\
4. Change the path in the include_once declaration at the top of each of the files to point to the csstidy and packer libraries you downloaded above:

   include_once "C:\Lib\packer.php-1.0\class.JavaScriptPacker.php";
   

   include_once "C:\Lib\csstidy-1.3\class.csstidy.php";

5. Get a working build file set up to point the directories your project is using. Here is a sample I made:

   <project name="testProject" default="pack-all">
   	<target name="pack-all" depends="pack-javascript,pack-css"/>
   	<target name="pack-javascript">
   		<copy todir="./Web/js" overwrite="true">
   			<fileset dir="../Web/js">
   				<include name="*.js" />
   			</fileset>
    
   			<filterchain>
   				<filterreader classname="phing.filters.JSPackerFilter">
   				  <param name="encoding" value="62"/><!-- 0,10,62,95 or 'None', 'Numeric', 'Normal', 'High ASCII'. -->
   				  <param name="fastDecode" value="true"/><!-- include the fast decoder in the packed result -->
   				  <param name="specialCharacters" value="false"/><!-- have you flagged your private and local variables in the script -->
   				</filterreader>
   			</filterchain>
   		</copy>
   	</target>
   	<target name="pack-css">
   		<copy todir="./Web/css" overwrite="true">
   			<fileset dir="../Web/css">
   				<include name="*.css" />
   			</fileset>
    
   			<filterchain>
   				<filterreader classname="phing.filters.CssTidyFilter">
   					<param name="remove_last_;" value="true"/>
   					<param name="preserveCss" value="false"/>
   					<param name="template" value="high_compression"/>
   				</filterreader>
   			</filterchain>
   		</copy>
   	</target>
   </project>

   Templates for CssTidy include: low_compression, default, high_compression (declarations are limited to one line apiece), highest_compression (everything is put on one line).

   The above build file is set up to work with the following directory structure:

   • Build
     • Web
       • css
       • js
     • build.xml
   • Web
     • css
     • js

   Files are copied from the source in /Web to the /Build/Web directory. I hope that you can see from the build.xml file above that the target directory is specified in the copy tag, todir attribute.

   <copy todir="./Web/js" overwrite="true">

   and the source directory is specified in the fileset tag, dir attribute.

   <fileset dir="../Web/css">
   	<include name="*.css" />
   </fileset>

And then, all you need to do is navigate to the directory holding your build.xml and run the phing command (if you have phing in your path. If not, you can use an absolute link to phing, for example c:\software\phing\bin\phing). Your minimized javascript and css will be in the Build directory!

So, let’s plug one of them into YUI! Let’s get some of that power under the hood. And let’s make it work identically to how we write our code for YUI currently, instead of changing the coding style (a la Dustin Diaz’s great extension to YUI called DED|Chain).

How are we going to do this? Let’s dive into the shallow end of the pool.

The include order of our javascript files is going to be important. So, first we’ll do the YUI library core file (either yahoo-dom-event.js or utilities.js depending on your need for animation). Next, we need to include a CSS Selector DOM Querying class. For this proof of concept, I’ve provided examples for my two favorites, the jQuery engine and Jack Slocum’s DomQuery. These files are released under the MIT license, so make sure that complies with your project. It’s pretty liberal, so you shouldn’t have any problems. If you find these querying libraries useful, please donate to these projects!

For code simplicity, I’ve added a one liner to Jack’s DomQuery to make it work as a standalone file.

if( typeof Ext == 'undefined' ) var Ext = function(){};

If you want to read more about DomQuery, you can go to Jack’s site all about syntax and benchmarks.

Download: Jack Slocum’s DomQuery Standalone File (24 KB) 1.0 Alpha 3 – Rev 4
Download: Jack Slocum’s DomQuery Standalone File Packed (7 KB) 1.0 Alpha 3 – Rev 4

If you want to use jQuery’s selector engine, I’ve stripped out the functions unnecessary to the selector engine in the 1.1.3.1 release and packaged it up as jDomQuery. There are differences between these two package’s syntax, so make sure you keep that in mind, especially when looking at the pseudos, like :gt() and :lt() for example.

Download: jDomQuery Standalone File (23 KB) 1.1.3.1
Download: jDomQuery Standalone File Packed (10 KB) 1.1.3.1

If you want to read about jQuery syntax, go over to their documentation. My current preference is the jQuery syntax, given that it works with poorly implemented JSF ID attributes. But that’s a different argument.

If you want to use the full jQuery library, that should work too, but if you want to do that, you might just want to switch to using jQuery at that point (dare I say it).

Next, we’ll extend the YAHOO.util.Dom class into a new Y2 namespace. This will map all of the functions from YAHOO.util.Dom into a new CSS Selector extension.

Download: Y2.util.Dom (2 KB)

(pack at your own leisure, you can do it online at Dean Edward’s Packer)

Putting It All Together

<html>
	<body>
		<div>
			<div class="first">
				<span></span>
			</div>
			<div class="second">
				<b></b>
			</div>
		</div>
		<script type="text/javascript" src="/Lib/yui/build/yahoo-dom-event/yahoo-dom-event.js"></script>
		<script type="text/javascript" src="jdomquery-1.1.3.1-packer.js"></script>
		<!-- <script type="text/javascript" src="DomQuery-packer.js"> -->
		<script type="text/javascript" src="Dom.js"></script>
		<script type="text/javascript">
		Y2.util.Dom.addClass( 'div div:last', 'myClass' )
		Y2.util.Dom.hasClass( 'div div:last', 'myClass' ); // returns true
		var b = Y2.util.Dom.get( 'div div:last b' );
		Y2.util.Dom.addClass( b, 'myOtherClass' );
		</script>
	</body>
</html>

One important thing to note is that when using the CSS Selector syntax, when only one node is selected, functions will return a scalar instead of an array. So if you’re expecting to select multiple nodes in your selector query and only one node results, make sure your code handling the result is prepared for such an instance.

Have fun!