[jifty-devel] Template::Declare Updates

[David E. Wheeler]

Fellow Templaters,

Jesse was foolish enough to give me a commit bit a few days ago, and  
I've been going to town on the Template::Declare documentation. See  
the [archives][] for what I've been about. A partial overview:

* Various whitespace fixes.
* Documented `alias`. I also updated `t/alias.t` as I read it, trying to
   understand how aliasing works.
* Reformatted the POD, moving things around, fixed some broken examples,
   and separated example outputs from the scripts that generate them.
* Fixed the TODO utf8 tests. I am not a fan of HTML::Lint.
* Switched from 'Template::Declare' to __PACKAGE__ where possible.
* Documented `import_templates`, updating the tests as I read them to
   understand how it worked.
* Fixed a regression in `import_templates` that I discovered while
   fooling around with an idea (more below on that idea).
* Made example code and example output indentation consistent.
* Fixed some more bugs in the examples.
* Added a proper SYNOPSIS section to the Template::Declare POD.
* Cleaned up the POD in Template::Declare::Tags,  
Template::Declare::TagSet,
   and Template::Declare::TagSet::*.
* Re-instated the pod-coverage test, which now passes.

[archives](http://lists.jifty.org/pipermail/jifty-commit/2009-September/subject.html 
)

Now, I was doing all this in order to better understand  
Template::Declare, towards improving the Catalyst view for it. I have  
a few questions, though, and would appreciate some feedback:

* Is my documentation for `alias` and `import_templates` correct?
* Why do we have both `alias` and `import_templates`? The latter
   seems superfluous.
* What are the `new_buffer_frame()` and `end_buffer_fram()` methods
   for? They were not documented, but I see that the catalyst view
   uses them.
* `package_variables()` had a bug that made it useless. It also was
   not previously documented. Should I remove it?
* What is the `append_attr()` function for, and how does it work?
* Can `get_current_attr()` be removed, since it's deprecated?
* How does `show_page()` differ from `show()`?
* How are roots supposed to work? They don't seem to be searched
   for more packages to load. Why call them roots if it's really
   just a list of packages that define templates?
* What is the meaning of paths? Is there one by convention among
   Jifty users, perhaps?

And finally, I have a couple of ideas I'd like to run by the group,  
for new featuers:

* I'd like to add a `move` method. It would work just like
   `import_templates`, except that the original template name
   would be removed. Basically, it would move all templates in
   the named subclass under the given path:

     move MyApp::Templates under '/here';

* I'm thinking of adding a `wrap()` function like `show()` that
   would invoke the named wrapper. So if you'd created a wrapper
   function using `create_wrapper foo => sub { ... }`, you could
   then call it like so:

     wrap( foo => show('bar') )

   This will allow a (public) wrapper to easily be used in namespaces
   outside of which it was defined. Thoughts?

Thanks for your thoughts. As I said, I'm doing this all towards  
improving the Catalyst view for Template::Declare. Specifically, I'm  
looking at using the `move` method to move all the templates defined  
in a Catalyst template package under a path. for example, if I have  
MyApp::View::TD, and all the templates were under it, there might be:

   MyApp::View::TD::Root
   MyApp::View::TD::Lookup
   MyApp::View::TD::List

My thought is to make it s that the templates in the latter two  
packages are moved to be under /lookup/ and /list/, which would make  
them better parallel Catalyst controller and action names. Thoughts?

Best,

David