re*ing HTMLPresenter

[FND]

cdent writes[1]:

> I've kind of lost my love for HTMLPresenter. [...] the implementation
> feels awkward. Part of it is probably my lingering desire for the core
> of TiddlyWeb to be just JSON over the API but if we do that it becomes
> much less capable of being inspected and played with. So better would
> be a good solution.

I'm not quite sure what that last sentence is supposed to mean, but I
figured it might be worth sharing my two cents here:

I don't think I ever liked HTMLPresenter, as it always seemed a bit
alien: a pluggable module within a plugging module. While that itself is
not a bad thing, it seems to add a fair amount of hidden (as in
undiscoverably detached, due to it being middleware) complexity - for
what seems like questionable, conflating purpose (generating a
resource's atomic HTML representation and rendering a web interface).

Granted, it's been quite a while since I've looked at the code in
detail, but skimming it just now made me scratch my head in a few places
(most notably its checking the user agent).

While I don't have any concrete recommendations right now, it seems to
me that HTMLPresenter should be removed. Coming up with a suitable
replacement should be possible now, thanks to experience gained over the
last few years. (Being intentionally vague here for now because I
believe there'll have to be some sync'ing of perspectives before we can
discuss alternative implementations.)

FWIW, the discussion at [2] might be relevant to the "just JSON" part.


-- F.


[1] http://cdent.tiddlyspace.com/20121221#cb9cefbf6a3841a81f2c8b91e8c67c87
[2] https://github.com/tiddlyweb/tiddlyweb/issues/55#issuecomment-11569529

[chris...@gmail.com]

On Sat, 22 Dec 2012, FND wrote:

> cdent writes[1]:
>
>> I've kind of lost my love for HTMLPresenter. [...] the implementation
>> feels awkward. Part of it is probably my lingering desire for the core
>> of TiddlyWeb to be just JSON over the API but if we do that it becomes
>> much less capable of being inspected and played with. So better would
>> be a good solution.
>
> I'm not quite sure what that last sentence is supposed to mean, but I
> figured it might be worth sharing my two cents here:

Better than either HTMLPresenter or switching over to just JSON would
be something else, something that is a good solution.

> I don't think I ever liked HTMLPresenter, as it always seemed a bit
> alien: a pluggable module within a plugging module. While that itself is
> not a bad thing, it seems to add a fair amount of hidden (as in
> undiscoverably detached, due to it being middleware) complexity - for
> what seems like questionable, conflating purpose (generating a
> resource's atomic HTML representation and rendering a web interface).

It exists exactly to avoid conflating two different purposes:

* the HTML serialization creates the core HTML of a tiddler, bag or
recipe, or collections thereof, not a document
* HTMLPresenter looks at the current context, at the middleware layer,
and decides, if, in the current context, an HTML document is
required, not a fragment

This was created a time when the thought was that some other framework
would want "tiddler(s) HTML" to present in its own presentational
layer. So you ask the tiddlyweb HTTP API for "some HTML" and then hork
that into your Django template

It's not clear that use case ever really saw the light of day, but
that the time there was strong belief in that possibility.

Which is why you get things like checking the user agent in the
middleware: If this isn't a browser, just send the fragment.

It's all a bit nasty, yes, but it was trying to cover what was
expected to be the common case.

HTMLPresenter went in middleware because that's where it fits,
logically, it's transforming the output generated by the core.
That core output was expected to stay the same, the container was
expected to vary. The belief was that someone would come along with a
"nice" HTMLPresenter.

Now, a few years later we know these assumptions are not that
aligned with what people actually did. Changing the HTML serialization
became the norm and when that happens HTMLPresenter is redudant.

Which ends in three sort of general directions about options:

1. Remove HTMLPresenter's function

So, once you start thinking "well, I guess the HTML serialization
should make the entire HTML document" (that's what "remove
HTMLPresenter means) then the HTML serialization begins to feel like
something that ought to have templates, and once you get there, it
starts to feel a bit heavy, and not quite right in the core.

2. Replace HTMLPresenter's function

This means keep the idea that the HTML serialization is a fragment,
and make it into a document in some other piece (in middleware), but
something that is somehow better than the current piece.

3. Keep HTMLPresenter as it is but provide a better external alternative

Don't change the existing stuff, or choose to make it simpler, but
create an officially blessed tiddlywebplugins.html serialization which
is a) good HTML b) uses templates c) is a full document


--
Chris Dent http://burningchrome.com/
[...]

[FND]

>> what seems like questionable, conflating purpose (generating a
>> resource's atomic HTML representation and rendering a
>> web interface).
>
> It exists exactly to avoid conflating two different purposes

I need to clarify that I see conflation not in HTMLPresenter itself, but
in the resulting serialization or representation. Regarded from a
slightly different perspective, it seems wrong for the same combination
of URI + content type to return different representations (whether those
representations are related is irrelevant IMO).

I would argue that clients wanting to get to the "pure" representation
of a resource (e.g. a tiddler) should be provided simple clues to
extract the relevant portion from the HTML document (e.g. via a
`.tiddler.` class - microformats, essentially).

If that turns out to be a bottleneck (unlikely), an optimization might
be to suppress the surrounding document (e.g. via a `?layout=false` URI
parameter - this is rather a common approach for AJAX optimizations[1]).

The difference to the current approach is one of perspective: Here the
canonical HTML representation is defined as an entire document rather
than just an HTML snippet - with that potential optimization doing the
inverse of what HTMLPresenter provides.[2]

I guess that means I'm advocating your option #1.

> once you start thinking "well, I guess the HTML serialization should
> make the entire HTML document" (that's what "remove HTMLPresenter
> means) then the HTML serialization begins to feel like something that
> ought to have templates, and once you get there, it starts to feel a
> bit heavy, and not quite right in the core.

I don't necessarily agree with the first conclusion - sure, a
template-based HTML serializer might be nice, but that doesn't mean it's
something the core's HTML serializer needs to (or should) do. After all,
the resulting HTML output might remain identical - so it'd be a simple
matter of moving around some code, from the middleware into the
serialization.

As for moving things out of the core, well, that's a different
discussion I'd be happy to continue elsewhere.

> It's all a bit nasty, yes, but it was trying to cover what was
> expected to be the common case.

No doubt - but we're smarter (or wiser) now, so adjusting the original
design is an acceptable outcome of this review (as you've already
agreed).


-- F.


[1] which are often premature as well
[2] This migth also get around the "middleware seems the wrong layer"
objection - at the cost of having to pass some sort of parameter to
the serialization, but we already know that optimizations are nasty.