need for a "provider" API?

[ras...@mindplay.dk]

I've been pondering a template "provider" API for Outline, and would
like to hear any comments/ideas on this.

A "provider" would be something that resolves template names and
retrieves templates.

Currently, the template-name you provide the Outline constructor, is
very simple, e.g.:

"products/list"

resolves to:

"/your/template/folder/products/list.html"

(depending on your configuration)

Some testers early on were asking why they could not simply specify a
path to a template, like most template engines allow.

A "provider" API would allow for this, as well as templates stored in
a database - I don't personally know why anyone would want to store
templates in a database, but it seems some people don't think their
lives can get complicated enough, who am I to stop them ;-)

You would specify the provider in the template-name, for example:

"db:123"

This would activate the custom "db" provider class, which would pull
record number 123 from your database and return the template.

A default provider setting would be added to Outline's configuration
settings, and a standard provider would be implemented, which would
resolve template names in the same way Outline does now.

This means that the public parts of the API would not have to change
as such - a template name, the way it is interpreted today, would
still work "out of the box", since template names with no "provider:"
at the start, would default to the standard "outline:" provider.

The biggest question here is, is such an API useful or necessary at
all?

In my opinion, storing templates in a database is a lousy idea - it
does not help performance, and it does not help you maintain a
codebase with, for example, CVS or SVN.

Even a "file:" provider, that lets you read templates from anywhere in
the file system, would be a bad idea in my opinion - what logical
reason could anyone have for wanting to store templates in random
directories? Most developers will choose a central location in their
repository for storing all of their templates. Or at the very least,
several known locations with different collections of templates - but
you could already do that now, if needed, by building a simple class
extension on top of Outline or OutlineTpl, that configures your root
paths as needed.

Another thing is, currently, caching is performed by organizing cached
content in a folder structure, mirroring the folder structure of the
templates folder. If a "file:" provider is used with caching, how do
you determine where, or how, to store the cache files? If you don't
define a "root" folder for your provider, you can't calculate a
relative path for a source template, and hence you can't mirror that
relative path anywhere else (cache folder, compiled templates folder)

...

Perhaps then, a much simpler system would be better.

Rather than implementing a complex provider API, how about adding a
simple registry for root folders?

So for example, I could register my various root folders:

Outline::registerRoot('products', '/var/www/sites/my_site/public/
templates/products');

Now this root folder would be registered with a shortcut name,
allowing me to do this:

$test = new Outline('products:software');

This would resolve to:

"/var/www/sites/my_site/public/templates/products/software.html"

Compiled templates and cache files could then still mirror the folder
structure from each root path and down - for example,

"products:software/cad_cam"

would resolve to:

"/var/www/sites/my_site/public/templates/products/software/
cad_cam.html"

and would compile to:

"{$compiled_path}/products/software/cad_cam.php"

and cache to:

"{$cache_path}/products/software/cad_cam.php"

etc.

This solves the problem of accessing multiple different template
repositories more elegantly, I think - it also means that you still
get the "short and sweet" include commands in your templates, e.g.:

{include products:software/cad_cam}

rather than:

{include "file:{$product_templates}/software/cad_cam.html"}

(or something equally horrible)

This solution does not directly support templates from a database,
but, indirectly, it actually could...

You could store templates in a database by implementing a stream-
handler in PHP, and registering a root path named "db" as
"your_handler://tablename/", for example. Outline does not need to
know how your stream handler retrieves or writes the stream data, for
this to work, so it actually makes for a cleaner approach, where your
database logic does not get tangled up in Outline's template engine
logic.

Anyhow, as said, I don't know why you would want to store templates in
a database, but then I don't claim to know everything, and these are
just my own personal opinions ;-)

Anyhow - unless someone has a really good argument against the root
folder registry idea, I think I will opt for that solution.

Please feel free to challenge my logic :-)

[ras...@mindplay.dk]

I have just committed a new version, which supports the notion of
"roots".

Please clear your "compiled" and "cache" folders, as the new version
of the engine uses a new directory structure - one more level is added
for the root.

This means that compiled templates and cache files, by default, go
into a subfolder named '__default__' - whereas template-names starting
with "root:" go into a subfolder named "root", etc.

Note that roots are inherited when using the {include} command - this
means that loading a template named "test:my_template" sets the
default root to "test:", so that subsequent include commands that do
not specify a root, inherit the root "test:".

Also note the presence of a new configuration switch, "default_root" -
this can be used to override the default root folder - if you want
template-names with no root, to fall back to a specific root, you can
use this setting.

This version will be released as 0.9 beta-2.