Hi all!
The Formatter API was designed on #openguides and here a few months ago. I just released Apache::AxKit::Provider::File::Formatter to make it easy to use any Formatter formatted file within AxKit, but I bumped into a problem that I would like your input on:
All the current Formatters simply return HTML fragments from the format method. That is, the stuff they return is something that you would stick in a body element of a HTML document. That's what you'd want in most cases.
In other cases, you can't reasonably expect to get just a fragment, you'll get the whole document, even if you're just interested in a fragment. I'd like to create a Formatter around HTML::Tidy RSN, and while libtidy can format fragments, HTML::Tidy can't yet, AFAIK. For an AxKit Provider, you would usually want to return a document, since, in principle it can be served directly to the user.
So, I think we need to do something that distinguishes fragments from entire documents.
In the original API, I note the following things:
1) the format method did not define its meaning w.r.t. fragment vs. whole document. 2) To retrieve things like title, one needs to first call the format method to do the hard work, then the title method.
I suppose it is a Good Thing for those two points to stay the same.
Since we allready have to call additional methods to get things like title, I think the most reasonable way to distinguish between fragment and document is to make two additional methods with those names.
format would have to be called first, and is free to return what is most reasonable, for Formatter::HTML::Textile, that would be a fragment, like it is now, and for a HTML::Tidy based Formatter::XHTML::HTML it would be a document.
If the user needs to be sure to get a fragment or document, s/he would have to call fragment or document on the object _after_ having called format.
How does this sound?
Then, we need to define what happens if the object cannot return either a fragment or document. I guess the choices are 1) croak, 2) warn the user that the method is not implemented and return undef, or 3) just return undef.
If it just returns undef, this should be noted in the documentation of each Formatter. One should be able to meaningfully implement a something that uses different Formatters without having the code die in a special case. OTOH, one would perhaps want to know about it, so a warning may be in order. But then, the warning may just be an annoyance too, and for those who are surprised by a Formatter returning undef in some cases, well, they should have RTFMed... ;-)
I'd love to hear your input on these things.
Cheers,
Kjetil