[cgi-wiki-dev] Formatter API change proposal
Sun, 23 Jan 2005 21:47:38 +0100
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
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
In the original API, I note the following things:
1) the format method did not define its meaning w.r.t. fragment vs.
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
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
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.
firstname.lastname@example.org email@example.com firstname.lastname@example.org
Homepage: http://www.kjetil.kjernsmo.net/ OpenPGP KeyID: 6A6A0BBC