Render library specification

Renderer consistency
Project state	Specification
Tracker issue	-
Discussion	-
Assignee	Damyon, Sam

Project goals

• Make it easier to write UI pages in Moodle
• Make it easier for themers to customise UI pages in Moodle
• Make it easier to switch CSS frameworks
• Make the appearance of Moodle more consistent (through reuse of components)

Note: This page is a work-in-progress. Feedback and suggested improvements are welcome. Please join the discussion on moodle.org or use the page comments.

Identified issues with renderers in 2.7

• Poorly implemented renderers are full of logic/db queries/access checks that would need to be duplicated by a themer wanting to change the HTML (and forces the themer to be good at PHP and know all the Moodle apis)
• Lack of consistency
• Lack of documentation
• No abstraction from CSS framework
• Requirement to style each page individually causes the CSS to balloon

Tasks

• Rewrite the docs for renderers
• Add an admin tool that can show a list of renderable objects for each plugin - filled with test data. The goal of this tool is to
  • validate that the renderer/renderable follows best practice (no DB queries, complex types, complex logic)
  • provide a page for themers to check that their new theme correctly displays all the renderables
  • provide a page for developers to see all the reusable renderables they can use when building their own pages
• Define a comprehensive list of low level widgets we can add to core as renderables. This is a library of components that should be used by other renderers (by compositing them). E.g. list, table, warning. Sources for this list should come from:
  • Existing CSS Frameworks (bootstrap, pureio) (but must be framework agnostic)
  • Existing renderables in Moodle that we see as “perfect” already (maybe there are some)
  • Existing patterns in Moodle that we do over and over but don’t have a renderable for yet
• Build this list of widgets as core renderables with a generator so they are listed in the admin tool
• Use compositions of these new core renderables for all new code (policy decision)
• Slowly convert the old renderers to compositions of the new ones with no logic etc (no eta)

Notes on renderers / renderables

Proposed improvements to the docs on renderers / renderables. First - the docs need an overhaul to more clearly explain how renderers / renderables work for core devs, plugin devs and themers. There needs to be clearer guidelines for the things that can be done in a renderable, and in a renderer.

A "good renderer" is:

• Receives some “data” through a renderable
• Produces some “output”
• Where “output” is some HTML and any javascript init calls
• Can use basic PHP functions/loops, like for(), foreach(), count()

A "good renderer" is not:

• nasty php logic (or even non-nasty php logic)
• access checks
• non-trivial function calls
• using any Moodle functions
• calling the database
• unshaven
• a bad renderer

A “renderable” is:

• All the data required to generate the output.
• Properties should be simple data types only, or renderables, or array of those

Related links

Output API Migrating_your_code_to_the_2.0_rendering_API#Outputting_HTML_specific_to_your_module