Really the question is do/should I care? If I am writing a new module or block (say) should I be writing 'stuff' in renderers. If so, what and why?
I'm looking at (what I assume is) the most relevant example of plugin_renderer_base. Firstly, I assume that the name of the class 'mod_workshop_renderer' is somehow inferred because it is never actually referred to anyway.
Secondly, I really have no idea what the interface 'renderable' is for or does. What does that class 'workshop_submission' actually do?
This seems to me like some pretty scary stuff in Moodle 2.0 and if anybody is going to use it then it will need some idiot-proof documentation
I was looking (as an example) at the block 'community' which has a renderer class. This just seems to be used as a conventional class, which is instantiated (using $PAGE->get_renderer) and then methods are called in the normal manner. This is nothing like the example in the docs which calls the method 'render' with a "widget" (an instance of a class that implements renderable). The community block doesn't seem to use these widget things at all - making me even more vague about what they actually are.
Another example is mod/quiz/renderer.php, which is used for all the student-facing parts of the quiz. (That is, view.php, attempt.php, summary.php and review.php. We have not fixed the editing UI to user a renderer yet.)
The answer is, yes, you should use a renderer, because then any theme can completely override any part of the output if it really wants. It also serves to keep the display code separated from the processing code.
In order to make the separation work, you have to pass all the necessary information into the renderer method. The renderer method then just focusses on generating the HTML required to display that information.
For simple things, you can do that by just passing all the information is as arguments to the method.
Once the number of pieces of information to display gets too large, using separate arguments becomes a nightmare. In that case, a better idea is to use an object so you just have one (or a few) arguments that have named fields. You may either have a convenient object already in existance, if your code is already object-oriented, or you could use a stdClass, or you could define a class specially for the purpose, like https://github.com/timhunt/moodle/blob/master/mod/quiz/renderer.php#L927
If you are defining a class specially, then you can use some magic.
If your class implements Renderable - let us suppose that $links is an instance of the class mod_quiz_links_to_other_attempts, which is renderable - then if you call $renderer->render($links), then it will automagically call the method $renderer->render_mod_quiz_links_to_other_attempts($links) for you. Exactly how useful this magic dispatch is, is open for debate. Anyway, you don't have touse it if you don't want.
Thanks for that Tim - learning how to use renderers has been on my todo list for a while (but I've been put off by the need to maintain all my current plugins as both 1.9 & 2.0 versions, so I've been trying to minimize the differences between the two).
I'm certainly going to look into this more in the future.
I think the docs pages manages to completely skip why one would use the renderable interface. If you want a job (!) could you amend that? I'd do it but I'm not sure I understand it clearly enough to get it right.