[TransWarp] Binding templates and resources

[Phillip J. Eby]

Okay, here's what Ty and I worked out today for how you'll use templates 
and other resources for peak.web:

* 'web.bindTemplate("foo")' -- this will find a template whose 
(before-the-extension) filename is 'foo', associated with the package that 
contains the class the binding is defined in.

* 'web.bindResource("foo")' -- this will find a resource (file) whose 
(before-the-extension) filename is 'foo', associated with the package that 
contains the class the binding is defined in.

"Associated with" in each case is a little complicated.  By default, in the 
absence of any skin definitions, templates are located in the package's 
directory, and resources are located in a 'resources/' subdirectory of the 
package.  However, when used with skins, it will be possible to create 
directories like this:

skinName/some.package/
skinName/another.package/

Bundling all the templates or resources for a variety of packages in a 
common directory for the skin.

Both resource and template bindings will work by mapping from the desired 
package name to a property namespace that contains naming context 
objects.  These context objects will map one or more physical directories 
into namespaces for templates.

The namespaces will be polymorphic; that is, you'll be able to refer to a 
resource like 'foo' without supplying an extension.  This is important for 
use with skins, where 'foo' might be a .gif in one skin and a .jpeg in 
another.  If a skin layer (or package/resource directory) contains more 
than one file with the same base name, it will be an error to look up that 
base name.  On the other hand, if you use an explicit file extension when 
there is only one file with that base name, there will be a warning issued, 
saying that you should not specify an extension except to resolve 
ambiguities.  (This is to discourage people from using explicit extensions 
and thus making it harder for third parties to re-skin their components.)

Resources must be referenceable in application URLs.  So we're going to 
have to reserve a URL name (tentatively '++resources++') to get at them.  A 
resource will be accessed via 
'/++resources++/some.package/resourceName'.  There will probably be a 
configuration property or properties to control this.

Resource and package directories will be allowed to contain 'resources.ini' 
files, that can map file names/extensions to object types and 
permissions.  To use resources in templates, there will be a 
'resource:attr=path' DOMlet.  The 'attr' designates the attribute that 
should be modified to refer to the resource.  If the optional '=path' is 
not supplied, the attribute will be used to obtain a path.  The path may be 
a relative path, in which case it is relative to the current package, or an 
absolute path, in which case it will start with a package name.

That's probably easier to explain with some examples:

<img src="http://example.com/proofs/anImage.jpeg"
  pwt:domlet="resource:src=anImage">

<img src="http://example.com/proofs/anImage.jpeg"
  pwt:domlet="resource:src=/some.package/anImage">

<img src="anImage" pwt:domlet="resource:src">

<img src="/some.package/anImage" pwt:domlet="resource:src">

Assuming that the template is in 'some.package', using any of the above 
four formats will have the same result.  The purpose of using an explicit 
path (e.g. "resource:src=whatever") is to allow WYSIWYG proofing of the 
source XHTML, by leaving in a valid URL to your original images.  But, if 
you are coding a template by hand, it's just as convenient to use the 
'src="anImage"' form to specify the path.

The 'src' in 'resource:src' of course can be replaced with other attribute 
names, e.g. 'resource:href' for links, 'resource:codebase' for an <object> 
tag, and so on.  For convenient use with images, we will probably offer an 
'img' DOMlet as well; redoing our examples above to use it, they would look 
like:

<img src="http://example.com/proofs/anImage.jpeg"
  pwt:domlet="img:anImage">

<img src="http://example.com/proofs/anImage.jpeg"
  pwt:domlet="img:/some.package/anImage">

<img src="anImage" pwt:domlet="img">

<img src="/some.package/anImage" pwt:domlet="img">

Apart from being shorter for this common usage of resources, the 'img' 
DOMlet will also automatically set width and height attributes using data 
from the actual image.  The image size will be computed at template 
compilation time, so that no additional per-request runtime overhead is 
added.  (Note that if if your template needs to force the image size to 
fixed values, regardless of the resource's actual dimensions, you should 
use "resource:src" rather than "img".)

I think that covers everything for now; Ty, please chime in if there's 
anything I've forgotten.

Comments and questions welcome.