Document twisted.web.template usage in Resource.

[Stephen Thorne]

twisted.web.template docs only show how to template in a static context, not inside a twisted.web server.

The docs should show a simple usage inside a twisted.web server, perhaps including a (working) snippet along these lines:

    def render(self, request):
        element = SomeElement(...)
        flatten(request, element, request.write).addCallbacks(lambda _:request.finish)
        return server.NOT_DONE_YET

[Jean-Paul Calderone]

Rendering incrementally into the response is a mixed bag. I think people should render into a string and then write the string to the response all at once. If you encounter an error while flattening, it's hard to display the error coherently if a random prefix of your page has already been sent to the browser. You also have to deal with the client disconnecting partway through.

[Glyph]

Replying to exarkun:

Rendering incrementally into the response is a mixed bag. I think people should render into a string and then write the string to the response all at once. If you encounter an error while flattening, it's hard to display the error coherently if a random prefix of your page has already been sent to the browser. You also have to deal with the client disconnecting partway through.

It would be possible, however, to address these issues with a sufficiently smart resource object that knew stuff about what was being rendered. This is why I didn't include a resource object though: the implementation that was feasible to do as part of the initial feature would have simply gotten error-reporting wrong, and I didn't want to have to provide compatibility and a deprecation for that.

[Glyph]

I just filed #5395 for just implementing the appropriate sufficiently-smart resource. Perhaps these will be resolved together.