[cgi-wiki-dev] Formatter API change proposal

[Kjetil Kjernsmo]

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
-- 
Kjetil Kjernsmo
Astrophysicist/IT Consultant/Skeptic/Ski-orienteer/Orienteer/Mountaineer
kjetil@kjernsmo.net  webmaster@skepsis.no  editor@learn-orienteering.org
Homepage: http://www.kjetil.kjernsmo.net/        OpenPGP KeyID: 6A6A0BBC