phnq_widgets
============

Phnq_widgets is a framework for buliding Rich JavaScript Applications by
organizing UI code along functional instead of technological lines. Instead
of, for example, putting all the JS files into one folder, CSS files into
another folder, and the HTML files into yet another folder, phnq_widgets
enncourages the grouping together of code that is functionally related,
regardless of file type, into widgets. I call this "functional code
organization".

A widget is a self-contained chunk of application functionality that may
include any or all of HTML markup, CSS, JavaScript or static resources such as
images, all in a single folder.

Carving a UI into widgets has many benefits:

- intuitive modularization of UI functionality
- prevents (or at least discourages) monolithic JS and CSS files
- facilitates the reuse of UI functionality
- etc.

Features
--------

In addition to providing the substrate for functional code organization,
phnq_widgets also provides several advanced web framework features:

- implicit and explicit dependency management
- lazy loading and deployment of client-side functionality
- compilation of templates into JS object code, executable on server or client
- automatic static file aggregation/minification/compression
- pluggable interface for auto-publishing to CDNs

The details of these features will be discussed below.

Everything's a Widget
---------------------

One of the benefits of functional code organization is that it is **very**
amenable to modularization. Remember that a widget is self-contained and can
contain everything that it needs (HTML, CSS, JS, images, etc.). Perhaps most
important is that widgets particiapte in dependency management. Examples of
things that can be widgets:

- chunk of rich application functionality (i.e. toolbar, fancy select box, etc.)
- 3rd party library (i.e. Twitter Bootstrap, jQuery UI, Isotope, etc.)
- JS API for accessing some remote web service

Getting Started
---------------

Requirements: node.js, npm

First create an application folder and change into it.

	mkdir my-app
	cd my-app

Install phnq_widgets into your application.

	npm install phnq_widgets

Generate your first widget called com.example.HelloWorld.

	node_modules/.bin/phnq_widgets -g com.example.HelloWorld

Start up a minimal server.

	node_modules/.bin/phnq_widgets -s

Now point your browser to:

	http://localhost:7777/widgets/com.example.HelloWorld

You should see an extremely basic page.

Add some style. Edit the generated file
widgets/com/example/HelloWorld/HelloWorld.css and make it look like this:

	.__CLASS__ h1
	{
		padding: 10px;
		border: 1px solid #999;
		background: #ccc;
		color: #fff;
		font-family: sans-serif;
	}

Refresh your browser and and you should see the effect of the above CSS
stylings.

Add some behaviour. Edit the generated file
widgets/com/example/HelloWorld/HelloWorld.js and make it look like this:

	var widget =
	{
		ready: function($$)
		{
			$$("h1").click(function()
			{
				alert("Hi!");
			});
		}
	};

Refresh your browser. Click on the text HelloWorld and you should trigger
the alert box to open.

Putting the phnq_widgets utility in your PATH
---------------------------------------------
In the Getting Started section we used the phnq_widgets utility a few times,
but the relative path to the utility is a bit cumbersome to type, so putting
it in your PATH helps:

	export PATH=$PATH:./node_modules/.bin

Put that in your shell startup script, relaunch your shell and then
phnq_widgets will be in your PATH whenever you're in a directory that has the
phnq_widgets module installed.

Now, starting your minimal server is a bit more concise:

	phnq_widgets -s

More documentation soon...