Render library specification: Difference between revisions

Revision as of 05:51, 14 May 2014

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 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 deadlines)

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 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

@@ Line 12: / Line 12: @@
 * 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)
+{{Work in progress}}
+== 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 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 deadlines)
+== 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
+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
-{{Work in progress}}
+== Related links ==
+[Output_API]

Documentation