interfacelab » Uncategorized

Introducing makejs

Jon Gilkison — Tue, 26 Oct 2010 19:17:28 +0000

I have recently been working on the mobile UI for a site I built called Sessions+. Sessions+ is a poker bankroll tracker that has a companion iPhone application for live tracking during live poker games, and now a mobile UI for Android and other HTML5 capable mobile browsers which replicates the most of the important functionality of the iPhone app.

The framework I used to build the app uses a lot of separate javascript and css files, though the entire app is housed in a single html file. So I end up with a element jam packed with stuff. While this is perfect for development, it’s no good for deployment or QA.

For an example of what the element looks like during development:

That’s a lot of stuff. To optimize for mobile, I’m going to need to smash these files together and run them through yui-compressor to make it as small as possible (and then serve it up with GZip to make it even smaller).

Now after some googling, I ran into Juicer. Juicer is a great tool, but it still didn’t do everything I wanted, and specifying the dependencies within the javascript and CSS files was not as explicit as I desire. It just seemed to prone to error. Finally, after merging everything with Juicer, I’d have to manually update the html files by hand to replace all those script and link tags with the new ones.

Next up on the google list was Apache Ant. I haven’t used Ant since doing a random Flex project a few years ago, and I was afraid it was simply too complicated to setup for my small little project. But in my quest to avoid NIH syndrome, I gave it a spin anyhow.

I gave up after an hour or two as it was just too much. Maybe I’m getting lazy in my older years, maybe I am suffering insufferable NIH syndrome, I’m not sure. Also, I hate XML.

Tick Tock

So the clock is ticking down on my self-imposed deadline to get a system setup that “builds” my little HTML5 app into a production ready thing. There were a couple of other options presented to me by google, but again, they either used the dependency thing of Juicer, or were horribly complicated.

So I did what any self-respecting developer would do: fired up TextMate and started hammering.

Meet makejs

When I set about building it, I had a few simple goals in mind:

YAML based configuration files. I love me some YAML. I love being explicit.
Ability to modify HTML files to replace
Now that’s a lot to process, but it’s pretty simple once you break it down. The general layout for the build configuration is thus:
- Build Target
  - Version (Major.Minor.Build)
  - Pre-Requisite Build Targets
  - Build
    - Build Phase
      - Settings
And that’s essentially it. But let’s look at it in more detail.

In the configuration above, you’ll notice I have two distinct build targets: “glamrock” and “example”. GlamRock is the mobile framework I built, Example is a sample project that uses GlamRock. For the GlamRock build target, you’ll see that I have 3 build phases: copy, compress and manifest.

The copy build phase does exactly as it sounds, it copies files to a destination in the build directory. Nothing more, nothing less. In this case, I like to keep jQuery and jQuery’s template stuff separate and not mashed into all of the other files.

The compress build phase takes a list of files, joins them together and then runs them through yui-compressor. Let’s take a look at that build phase again:

If you look at the files element, you’ll see a filename (in this case, js/glam.rock.min.{VERSION}.js) with a list of files associated with it. These files are the ones that are joined together and compressed to generate js/glam.rock.min.{VERSION}.js. So what’s the deal with the {VERSION} thing? That tells makejs to replace {VERSION} with the newest build version, which makejs takes care of automatically for you. For example, if you’re configuration says version: 0.0.81 – the next time you build, makejs will auto-increment the build #, re-save the conf file, and then when it generates the compressed files, you’ll end up with a file name js/glam.rock.min.0.0.82.js.

The manifest phase is what builds the HTML5 cache manifest, a definite must for mobile HTML5 apps. For GlamRock, it won’t actually build a manifest (see below for why), but it is important to list what files that this build produces which can be included in the cache manifest.

Now, let’s turn our attention to the example build target. This build target has a copy, compress, alter and manifest build phase. But before we dive into those, you’ll see that this build phase has a pre-requisite for GlamRock. When this build target is built, GlamRock will be built first and the output of that build will be put into whatever the build directory for example is. This is nice because we treat each build target as independent projects and get some nice dependency functionality out of it. Keeps things clean and relatively simple.

Back to the build phases for the example build target. I won’t go over copy and compress because there is nothing different happening here then there was in the GlamRock target. So let’s look at the alter build phase:

The alter build phase takes any input file and replaces any denoted blocks with the proper
Pretty nice, right? Note, that this never alters the original, it simply transforms the input into the destination in the build output directory.

The example build phase has a manifest phase, like GlamRock, but with one important difference: it has a name setting. When building a manifest phase, if there is a name specified, than a physical cache manifest is generated. So running this phase on the example build target yields a cache manifest saved to example.manifest in the output directory. The example.manifest looks like this:

Perfect-o.

Getting It

Head on over to GitHub and check out the project: http://github.com/jawngee/makejs

Hope someone finds this useful!

Is This Really The Future of Magazines or Why Didn’t They Just Use HTML 5?

Jon Gilkison — Thu, 27 May 2010 17:55:27 +0000

I just downloaded the Wired iPad application, and like most iPad applications (and most magazines for that matter), I found myself bored with it within the first 20 minutes. I’m sure the content is engaging, I’m sure the articles are worth reading – but I am stumped as to why I would chose this over the physical magazine itself, or their website for that matter. In fact, for reasons I’ll get into below, I’m starting to believe that the physical magazine’s “interface” is vastly superior to it’s iPad cousin.

However, what strikes me most about the Wired app is how amazingly similar it is to a multimedia CD-ROM from the 1990′s. This is not a compliment and actually turns out to be a fairly large problem…

1990′s Here We Come … Again

The only real differentiation between the Wired application and a multimedia CD-ROM is the delivery mechanism: you download it via the App Store versus buying a CD-ROM at the now defunct Egg Head store at your local strip mall. And I really mean that comparison. For all of the interactivity that was touted in the Flash prototype, what we’ve really ended up with is a glorified slide show. Instead of the “Next” and “Previous” buttons you might have been used to on those old CD-ROMs of yore, you instead swipe left and right to change pages (well *cough* images of pages).

There are certain interactive elements to the articles, but – and I apologize to all of the people who put in a lot of back breaking work into this – they’re pretty lame. Tapping on a button-looking element switches out part of the page with another image. You can drag your finger across certain images to make them sort of animate like a flipbook (and in truth, that’s what it is – a series of PNG or JPEG images). There are videos you can tap on to view fullscreen. There are audio clips that you can play. The interactivity in the Wired application is very 1990′s. I am not trying to be insulting either, it’s simply the truth. The Wired application has pretty much brought back image rollovers.

And that’s about the extent of the interactivity. Which makes me wonder if that should be the extent of it or should we be wanting more? I don’t have an answer to that, though my gut feeling is that there is a massive opportunity to reinvent the concept of a magazine – yet we end up with something akin to what the web was like in the mid to late 90′s. This basically boils down to a print designer’s vision of what the web should be like – but in this case it’s a print magazine person’s vision of what an interactive magazine should be like.

If you can think back that far, and you were doing web development during that time, you will glumly remember the frustration of web development driven by print design, where pages were essentially huge images cut and sliced and then reconstituted back into insane table structures for pixel perfect layouts. That’s what we’ve essentially gotten with the Wired app: a giant step backwards and a complete dismissal of the lessons we learned from that dark period of interaction design and development.

Holy Shit, That’s Big

With the Wired app weighing in at a whopping 500 megabytes – just 100 shy of a full CD-ROM – how do they intend to maintain new editions of the magazine? 500 MB is too large for a 3G download (no help from AT&T’s less than spectacular network performance) and for those with iPad’s with the smaller storage, each issue will take a significant chunk of space on the device. With no apparent means for managing which issues you keep on your device, this will become huge issue for a lot of people. Obviously they will fix this with updates to the application, but I’m still wondering what they were thinking to begin with. I’m hoping there were voices of dissent that pointed out the end product was not worth it’s weight in megabytes. A PDF version would have been a tenth of the size, though without the interactivity. But is the interactivity worth the 500MB price? I personally don’t think so.

Why is the magazine so large? Being the intrepid hacker that I am (*wink*) I mounted my jail broken iPad via AppleTalk and quickly tore into the app itself to see how it was constructed. Similar to the PopSci+ magazine application, each Wired issue is actually a bunch of XML files that lay out a bunch of images. And by “a bunch of images” I mean 4,109 images weighing in at 397MB.

Each full page is a giant image – there are actually two images for each page: one for landscape and one for portrait mode. Yes, I’m laughing on the inside too. There is no text or HTML, just one gigantic image. The “interactive” pieces where you can slide your finger to animate it are just a series of JPG files. When you press play on the audio file and see the progress meter animate? A series of PNG files.

Something is wrong with this picture. Something wrong and something very lazy and/or desperate.

Over Architect Much? (or How Desperation Ruins Good Ideas)

I have no inside knowledge on how the Wired app was produced, so the following is all conjecture on my part. That said, my guess is that Adobe sold Conde Nast on doing the thing in Flash. Or if Adobe didn’t do the selling, some Flash loving technologist at Conde Nast sold them on it. Either way, since Flash CS5 was going to be able to target the iPhone/iPad, they’d be able to publish the thing as it had been shown to the press. But then Steve Jobs came along and threw section 3.1.3 into the iPhone licensing terms and … well … Adobe and Conde Nast were pretty much fucked. So fast forward to this moment in time and the best short term solution they could come up with was some jury rigged XML based layout framework and an epic shit ton of images.

The Wired app isn’t alone in this weird architectural choice either. The PopSci+ magazine is based on a very similar architecture. There are also other magazines that work along the same lines, or simply go the route of PDFs with a customized PDF viewer application.

The problem with these XML + images architectures is that they are essentially reinventing HTML with no added benefit. When I showed the Wired app to a colleague of mine, someone I consider to be one of the top HTML/Javascript developers in NYC, his assessment was the same: Why the heck didn’t they use HTML5? We stepped through each “page” of the Wired application, looked at each interactive piece – but failed to find anything that ruled out the use of HTML and JavaScript.

The argument might be that it needs to be cross platform – the very thing Adobe and Conde Nast were banking on by going with Flash – but guess what? For all of the tablets about to fall on the heads of consumers in the coming years, each one of them uses WebKit. If anything was built for this type of application, it most certainly is WebKit. And even for harder interactivity puzzles – in terms of how do we do X and Y – one can easily hook into WebKit to enable that stuff that might otherwise be more difficult to do in straight HTML + CSS + JavaScript. I have yet to see anything in any magazine application on the iPad that would really require this though.

So why didn’t they choose HTML5 and build a custom viewer application around WebKit? It comes down to either a sense of desperation, a sense of Adobe overselling a bad idea or simply a dumb technology decision. Possibly all three. It certainly isn’t a development challenge and it certainly isn’t because WebKit isn’t capable. I had a thought that perhaps memory management was an issue, but by going with HTML5/WebKit, you wouldn’t be showing pages and pages of huge images – you’d actually be able to build those pages the right way. And doing it this way, in my professional opinion, the magazine itself would be slashed dramatically in size, as well as acting and reacting in ways familiar to people who’ve been browsing the web for the last 15+ years. Furthermore, the cost savings from a production standpoint would be drastically lower as Wired already maintains a staff of web developers. There wouldn’t be an impetus for Adobe to create some “solution” at Conde Nast’s expense and a lot of the great interactivity you saw in the YouTube videos of their prototype could very easily come to life.

But as it stands now, the Wired iPad app is even far behind their own website. That’s embarrassing. Did anyone at Conde Nast look at this and wonder why someone would choose to use this over their very own website? That iPad – unless you are in a subway – is constantly connected to the intertubehighway. That fact alone makes one wonder what the point of the whole thing is. Specifically since they’ve not done any sort of interactivity or visual presentation that I think anyone can say is amazing. Sure, it’s a print designers wet dream – but it really should be a consumer’s wet dream. And it most certainly is not that.

So, from a technical perspective, I think what we are looking at is the result of equal parts desperation and ignorance. Desperation on the part of Adobe to carry forward their relationship with Conde Nast in this new publishing market and ignorance on the part of their development team for ignoring the best solution to their “No Flash Allowed” problem: HTML5.

Is This The Future For Magazine Publishing?

I hope not.

I actually think it’s a huge step backwards and I think the wrong people are working on the problem – just like the wrong people were working on the web problem back in the day. Sure, we corrected course and we’re seeing the web done correctly more and more these days – but can the magazine publishing industry afford to get this wrong for any amount of time? Once could argue that the internet is quickly making their industry irrelevant. By the time an article is published in Time, I’ve read six or seven different takes on the same story on the web well before it hits the newsstands. I don’t think that’s a unique or new insight. But now you want me to download 500MB a month just so some print designer can have pixel perfect layouts with custom fonts?

Unfortunately, as long as Conde Nast allows Adobe to dupe them into believing Adobe has a solution, it’s going to fail. They need to go outside the box to get this right, and all the technology to do it is sitting right there in front of them. And they’ve been using it very well … until now when they’ve chosen not to even use it all.

Update

People have been mentioning that you can’t do application specific fonts with the WebKit browser. Not sure why.

Here is a simple iPad app that loads up a custom open type font, and then displays an html file in a UIWebView with that custom font: http://github.com/jawngee/iPadFontExample

So it can be done. Enjoy.

My Mom is Going to Love the iPad

Jon Gilkison — Fri, 29 Jan 2010 08:24:18 +0000

My mom is totally going to love the shit out of this thing.

Off the top of my head:

She can read her books in the dark.
She can use it in the kitchen to look up recipes and watch cooking videos.
She can use the GPS to help my dad drive their RV around the country.
She can be better connected to her iPhone wielding grandchildren.
She can play Words with Friends on a bigger screen.
She can browse the web on a readable screen. While in the RV.
Watch all of her NFL games while sitting on the porch.

And that’s just to start. Later down the road, maybe after revision 2, she’ll also be able to:

Draw her knitting patterns and sync it with her knitting machine via Bonjour over WiFi.
Have video chats with the kids.
Augmented reality tour guides for the new places they travel to.
Telemedical (god forbid) monitoring to save trips to the doctor.
Control surface for manipulating certain controls of the RV.

The best part? I won’t have to show her how to do those things, not most of them anyway. So to do 80% of what she uses her laptop for, she can do all of those things without having to lug the thing out, plug it in, hook up the mouse, etc. She’ll be able to take the information she is looking for to the place where she needs it to be: the kitchen, the sewing room, the co-pilot’s seat.

So thinking about my mother using it, and loving it, I started to think how I would use it. My list is almost equally as long.

Control Boxee.
Use it as a control surface for Final Cut or Ableton Live or Traktor via Bluetooth or WiFi.
Home automation.
The ultimate universal remote (extra hardware required)
Pornography
Better in-flight DVD viewing experience

There are so many more integration points the iPad can make with day to day living and day to day information needs. The key aspect of it all is mobility and portability, having the information you need not only when you need it, but where you need it.

I understand the let down from the perspective of people who were wishing for a multi-touch Mac Book. But I think they are thinking about it wrong. People are thinking about it as if it’s a computer, but it isn’t just a computer, it’s a whole new category of device, a whole new definition of what a computer is.

I also agree with most that the lock down to the App Store is a let down, though you don’t have to think too hard about it to understand it’s a necessary evil. It reduces any potential confusion on how to make the thing do something new. My Mom and I were playing Words with Friends without me having to walk her through how to install it and get it running. Now compare that with what it was like to show her how to do something similar on her Windows laptop … yeah no thanks, I’ll take the App Store. Not to mention not having to run that crappy antivirus and anti-spyware junk – the stuff that sucks the performance out of her laptop and yields endless complaints about how slow everything is. Perhaps it’s a false sense of security, but I can live with that.

Some of the complaints about usability and related things are complete nonsense and even defy logic. I’m pretty sure Apple did some usability testing on this thing … but maybe that’s just wild speculation on my part.

I think Apple is definitely onto something, maybe it’s not quite there yet, but they’ve definitely accomplished more than bringing an oversized iPhone to market. But only time will tell.

And, yes, she does kick my ass in Words with Friends. She hit me with two 70+ pointers yesterday.

Slicehost API Notes for the Non-Rails Posse

Jon Gilkison — Sat, 09 May 2009 06:38:23 +0000

I just want to start out by stating that I, in fact, am a big fan of Slicehost and constantly recommend them to friends setting up anything more serious than blogs. They have a truly great offering and their customer service has only been rivaled, in my experience, by the support team from DataPipe – whom I whole heartedly recommend for any colo or managed hosting.

One thing that is truly great about Slicehost is that they offer an awesome API that allows you to do most everything you can do in their management console, but instead through web services. You can create new slices, reboot them, change and add DNS, as well as rebuild or destroy slices.

The only problem is that the API follows a “standard ActiveResource pattern” that comes straight from the bowels of Rails and is way too convoluted for something this simple.

My biggest complaint is that instead of POSTing standard post variables, you POST XML, but none of the data being posted approaches any kind of structural complexity that warrants it’s usage. It just a layer of crap that doesn’t need to be there. Every modern language has some sort of HTTP request mechanism that handles all this stuff without some arbitrary object model forced on top of it.

Curiously, there appears to be another way where you can POST regular form data, but the variable names are in the form “resource[field]” which, again, seems completely unnecessary. I also couldn’t get it to work reliably.

As a point of reference, I was able to implement S3, EC2 and SQS API’s from amazon in just under 6 hours. It took me two days to figure out the Slicehost API. The ActiveResource pattern is a failure in my estimation.

The following are my notes on implementing the slicehost API. Hope you find it useful.

NOTE: This post doesn’t cover their DNS API as I don’t have a particular need for it. I will be posting the PHP library I wrote for the Slicehost API to github over the weekend. Perhaps someone can build on top of that…

Authentication

I actually had a bit of a bitch with this. The docs and ruby samples specify that you put your API key in the url, like this:

https://APIKEY@api.slicehost.com

Problem is that I just could not get it to work. Even the ruby samples in their docs didn’t run without authentication errors. Copying and pasting the URLs into Safari didn’t work either (simply pasting your API key into the user input when the Basic Authentication popup shows does work though).

So, make sure you always set the USER part of Basic Auth with your API key. In PHP it looks like this (using PEAR’s HTTP_Request object):

$request->basic_auth(YOUR_API_KEY,’’);

Dealing With Slices

This is the part that drove me nuts. I ended up having to debug their ruby examples through Charles, after patching activeresource.rb to support proxies. And even then, their examples didn’t work due to a typo and another error I couldn’t sort out.

Listing Slices

This is easy as pie. Simply make a GET request to:

https://api.slicehost.com/slices.xml

You will get back an XML document as a response:



	
		slicename
		active
		
			XXX.XXX.XXX.XXX
			XXX.XXX.XXX.XXX
		
		666
		100
		0.0
		0.0
		10
		XXX.XXX.XXX.XXX
		2

The one issue I have with this is that the

element doesn’t specify if the address is internal or external. Right now, you can only make the assumption that the first address is external and the second one is internal. Not a big deal though.

Also, note the .xml extension. I believe this is arbitrary, but it would be dope if you could specify .json or .yaml or some other format. Again, not a big deal.

Getting Slice Info

This is equally as simple:

https://api.slicehost.com/slices/666.xml

Where 666 is the ID of the slice you want to get info about. You get another XML document in return containing a element as above.

Creating a Slice From an Image

This is relatively simple, but there are a couple of steps to it.

First you need a list of the images that Slicehost offers. Easy enough. GET request to :

https://api.slicehost.com/images

Will return an XML document that looks like this:


	
		CentOS 5.2
		2
	
	
		Gentoo 2008.0
		3
	
	
		Debian 5.0 (lenny)
		4
	
	{ .. and so on .. }

Once you have this list, you’ll have need to figure out what flavors of slices you can create. Do this by sending another GET request to:

https://api.slicehost.com/flavors

Again, you’ll get another list that looks like this:


	
		1
		256 slice
		2000
		256
	
	
		2
		512 slice
		3800
		512
	
	
		3
		1GB slice
		7000
		1024
	
	{ ... and so on ... }

So now we know the ID for the image and the ID for flavor of slice. Let’s keep going!

This next bit took me awhile to get going. When I tried to go through the method of posting good old post data, I would get back really obscure errors. So debugging the HTTP traffic of the ruby examples, I unearthed the secret sauce.

To create the slice with the image of your choosing, POST an XML document to:

https://api.slicehost.com/slices/

But, make absolutely sure that you have set the “Content-Type” of your request to “text/xml” otherwise it no worky. Your XML document will look like:


	NAME OF YOUR SLICE
	1
	2

The must be a valid ID from the list above, of course. Their API docs have a typo where the sample code to create a slice uses an ID of 1, which doesn’t exist. A little hair pulling on that one, even though the bug was so obvious. The same thing goes for the .

The response you receive will be information about you slice, including the root password. You only get this root password once, so make sure you take note of it. The response looks like:


	build
	SLICE NAME
	
		XXX.XXX.XXX.XXX
		XXX.XXX.XXX.XXX
	
	666
	ROOT PASSWORD
	0
	0.0
	0.0
	2
	XXX.XXX.XXX.XXX
	1

And that’s it, you’ve created your slice!

Creating a Slice From a Backup

This is nearly the same as creating from an image, but this time we’ll need a list of available backups. Backups are things you create through the Slicehost management interface. What I like to do is build a base system and then take a snapshot. With that snapshot I can create new slices based on it.

To grab a list of backups, send a GET request to:

https://api.slicehost.com/backups

You will receive a list (if you have any backups):


	
		3-666
		666
		daily
		Sat May 09 04:15:05 UTC 2009
	
	
		3-667
		666
		webserver_snapshot
		Sat May 09 04:15:05 UTC 2009

And, then, in the XML document you POST:


	NAME OF YOUR SLICE
	1
	3-666

Everything else is the same as creating a slice from an image.

Updating a Slice

The only thing you can update with your slice is it’s name. This is accomplished by PUTing an XML document to:

https://api.slicehost.com/slices

The XML doc looks like:


	666
	NAME OF YOUR SLICE

All you need is the ID of the slice and it’s new name. The response will be an XML document with a node.

Deleting a Slice

Delete a slice by sending an XML document using the DELETE HTTP verb:

NOTE: You will have to have this option enabled in the API settings on your account. You can edit those settings at: https://manage.slicehost.com/api/

Rebooting Your Slices

To reboot your slice with a hard reset, send a PUT request to:

https://api.slicehost.com/slices/YOUR SLICE ID/hard_reboot.xml

To do a soft reboot, a PUT request to:

https://api.slicehost.com/slices/YOUR SLICE ID/reboot.xml

Rebuilding Your Slices

To rebuild your slice, you’ll need to use an image ID or a backup ID. Once you’ve picked one, send a PUT request to:

https://api.slicehost.com/slices/YOUR SLICE ID/rebuild.xml?image_id=X

or:

https://api.slicehost.com/slices/YOUR SLICE ID/rebuild.xml?backup_id=X

Conclusion

So that’s all I know. As you can see the API is pretty simple, but not as simple as it could be, nor are the documents even remotely near as useful as they should be. But, it’s awesome they have this API in the first place so I’ll stop bitching now!

Again, thanks to Slicehost for making awesome. The world sure does need it.

Variables in CSS via PHP

Jon Gilkison — Wed, 18 Jun 2008 03:19:10 +0000

UPDATED: Added support for expressions with variables so that you can add, multiply, divide, etc. variables when using them in the CSS. See below for more info.

Back in April of 2008, I came across a proposal by Daniel Glazman and David Hyatt for using variables in CSS stylesheets. I thought the proposal was absolutely brilliant, filling a much needed void for sites using complicated stylesheets across a variety of different pages. Another part of their proposal was being able to include/import other stylesheets. I don’t know anyone that couldn’t find this useful.

I put together a quick class for implementing most of their proposal using PHP. Nothing fancy going on here, most of it is some simple regexes.

Download the code here.

Using the CSS Compiler

Let’s first talk about how to setup your CSS stylesheets to use variables and imports.

Important: Any stylesheet that uses variables or includes stylesheets that use variables must end with the extension ‘.cssp‘.

To declare variables, you place them within an @variables at-rule like so:


@variables
{
    titleFont:bold 18px "Verdana, Arial";
    titleBG: #FF0000;
}

To use the variables:


div.title { font: var(titleFont); background: var(titleBG); }

Couldn’t get much simpler.

Importing CSS and Variables

You can also import/include css and variables from an external stylesheet using @import:


@import "vars.cssp";

div.title { font: var(defaultFont); };

Alternately:


@import url("vars.cssp");

div.title { font: var(defaultFont); };

Evaluating Expressions

You can also perform math operations with measurement units. For instance, you could do something like:

@variables {
    lc_width: 240px;
    rc_width: 180px;
    all_padding: 20px;
}

#some_div {
    width: eval((lc_width+rc_width)-(all_padding*2));
    padding: eval(all_padding/2);
}

You can only do this with px/em/% measurement units and the units must match. For instance you can’t add a variable that is 2em with another that is 120px. Doing so will throw an exception. Also, if you use a variable reference that doesn’t exist, it will also throw an Exception.

Using in HTML Pages

To use these stylesheets, you’re going to have to write a little PHP, but not too much:




    
        
    
    
        Hello World

At the top of this file, we’re including the css compiler and then defining a global variable COMPILE_CSS. COMPILE_CSS tells the compiler to do the compilation and save the resulting .css files. You will not want to do this in a production environment, so comment out the define when deploying to the masses.

In the head tags, the style() function is a helper function that compiles the css. The first argument is the full path to where the css is. The second argument is the css file to use without it’s extension. Note: if your css files have a relative path of /css/whatever.css on your webserver, the relative path should be part of the second argument and not the first.

For example, let’s say our PHP application is located at /var/www/. Our css files are located at /var/www/css/. Our style function is going to look like:


style('/var/www/','/css/testing');

Our actual usage of this code at massify is way different. I’ve added the style() function so that people reading this blog can use it, but you should definitely do your own legwork to blend it into whatever framework you are using. This should be enough to get started however.

Also, make sure that your css directory is writable by your webserver or the whole thing won’t work at all.

Leave a comment or drop me a line if you find this useful/find bugs/have suggestions.

Enjoy!

Metadata/Attributes in PHP

Jon Gilkison — Mon, 16 Jun 2008 07:56:09 +0000

There’s a ton of stuff I miss from C#, having moved to PHP. Did I say a ton? I meant a megaton.

One of the things I miss the most (besides the sanity) are attributes (annotations for Java peeps). To be able to ascribe metadata to class, method and property definitions opens up a whole new world of introspection which enables you to do some pretty wicked hacks.

In this post, I present a PHP class that allows you to do metadata/attribute programming with PHP. You can download the class here. But before we dig in, we must understand what attributes are and how they are useful…

Introduction to Attributes

For those that don’t know about attribute based programming, let me quote an excerpt from OnDotnet:

Attributes are a mechanism for adding metadata, such as compiler instructions and other data about your data, methods, and classes, to the program itself. Attributes are inserted into the metadata and are visible through ILDasm and other metadata-reading tools.

Reflection is the process by which a program can read its own metadata. A program is said to reflect on itself, extracting metadata from its assembly and using that metadata either to inform the user or to modify its own behavior.

One of the last things I wrote in C# before switching over was a simplistic REST-esque framework for web services for C#. I used attributes on classes to mark which ones were exposed to the outside world and then used attributes on the methods to specify such things as the URI, description, etc. This allowed the services to be discoverable versus declared and to be self documenting. For example:

namespace SimpleWebService {
[RestService(baseURI='/simple/',Name='Simple', Description='Simple service', Persistent=false)]
class Service
{
[RestMethod(URI='something',Name='Do Something',Description='Does something.')]
public void DoSomething()
{
// …
}
}
}

In the above example, the attributes are declared in the brackets. On our Service class, we give the service a name, define it’s base URI, give it a description and declare if the service is persistant between requests (meaning that the class is only instantiated once, or is instantiated every time). On the DoSomething method it’s a similar deal: we declare the URI endpoint for the method, the name of the method and it’s description.

By going to http://example.com/simple/something would eventually invoke the DoSomething method on our Service class. The beautiful thing here is that my classes needn’t implement any interfaces or descend from any parent classes to be exposed as a web service. I could drop the attributes on the class, recompile and they would then be instantly available. When the application loaded, it scanned all of the classes in the loaded assemblies, did some reflection on them and created a cache of exposed services. An HTTPHandler would dispatch the incoming requests to the corresponding service, map any POST/GET or URI fragments to the parameters of the method being called and then returned the results of the method call as serialized XML.

Nice and easy.

Attributes and PHP

PHP has no built-in mechanism for declaring attributes, but it does have a primitive retrospection capability. For any class or function in PHP, there are a set of functions that you can call that will provide information about the class. For instance, with methods, you can get it’s parameters and any associated block of comments:

class DumbClass
{
    /**
     * Comment block
     */
    public function thing($parameter,$another)
    {
        return false;
    }
}

$method=new ReflectionMethod('DumbClass','thing');
echo $method->getDocComment();

In the above example, we create an instance of the ReflectionMethod class and echo the comment block. If we run this script, the output would look like:

    /**
     * Comment block
     */

Now if we put 2 and 2 together, you’ll see that we could use the comment block to insert our class metadata. Now all we need …

Introducting AttributeReader

The AttributeReader class is a simple class that extracts YAML from the comment block on a class, it’s methods or properties. You can download the class here. Note: You must have the pecl syck package installed, details are here.

Since we have access to the comment block, it’s the most obvious place to express our metadata. Obviously, the 100% correct solution would be to patch PHP to support attributes out of the box, but that’s a much bigger effort that would require some serious coding. The performance of this method is fast enough for most use cases.

So how do we use this? At massify, we use metadata for our ORM layer. All of our models have metadata attached to them that define what database table to use, the column name, etc. Here’s an example:

/**
 * Sample model
 *
 * [[
 * table: sample.item
 * database: default
 * read_only: false
 * ]]
 *
 */
class Item extends Model
{
    //@ fields

    /**
     * [[
     * label: Title
     * type: string
     * length: 32
     * description: Title of the item
     * validate:
     *   required: true
     *   length: 8-32
     *   unique: true
     * ]]
     */
    public $title;

    /**
     * [[
     * label: URI
     * type: string
     * length: 32
     * description: URI of the item
     * validate:
     *   required: true
     *   length: 4-32
     *   unique: true
     *   format: alpha_numeric
     * ]]
     */
    public $uri;

    /**
     * [[
     * label: Description
     * type: text
     * description: Description of the item
     * ]]
     */
    public $description;

    //@ end fields
}

In the above example, our metadata is nestled between double brackets [[]]. Inside the double brackets is YAML expressing the metadata. The cool thing here is that we can nest attributes of the metadata. Let’s look at what we’ve done:

On the declaration for the Item class, we’ve described metadata that tells us which database table this model represents, which database it resides in and if it’s read_only (a view, in database parlance). On the properties of the model, the metadata describes the label to use for forms, what the database type is (simplified), the length (for string types), a description and a list of validators. For instance, on the $uri property, we’ve declared validators that make sure the property has a value before saving (required), is of a specified length (4-32 characters), is unique in the database (unique) and matches a specific format (alpha_numeric).

Since the class extends from Model, the model knows to use the metadata to build the correct SQL statements for insert, updates, etc. It also knows how to validate itself when saved to the database, returning the correct errors to the user if any of the validations fail. Finally, we are able to automatically build forms to edit the models by using the metadata as a guide when constructing the form in code.

All of this is completely possible to do without using metadata, but would require a lot of redundant code with a predetermined set of use cases. Metadata frees us from this because we can write use cases that work with a known quantity, rather than the other way around.

Using the AttributeReader

Using the class is straight forward. Here’s an example. Let’s assume we have the Item model from the previous example loaded and want to extract metadata for it and it’s URI property:

$item=new Item();

$class=AttributeReader::ClassAttributes($item);

echo $class->database;
echo $class->table;

$method=AttributeReader::PropertyAttributes($item,'uri');

echo $method->label;
if ($method->validate->required)
    echo "Required field";
else
    echo "Not required.";

It’s that simple.

Caveats

Make sure you are familiar with the rules of YAML.

Performance is acceptable, but always make sure you measure performance for yourself. We use a caching strategy via APC at massify for caching model metadata. This requires that you restart apache if your models change (you can disable APC on your development/staging to get around this). With the APC caching strategy, it’s super fast. Find out what works best for you.

I hope people find this useful, I think it opens a whole new world for serious PHP development. Feel free to drop me an email if you have questions or successes.