Render library specification: Difference between revisions
From MoodleDocs
Damyon Wiese (talk | contribs) No edit summary |
Damyon Wiese (talk | contribs) |
||
Line 42: | Line 42: | ||
A "good renderer" is: | A "good renderer" is: | ||
Receives some “data” through a renderable | * Receives some “data” through a renderable | ||
Produces some “output” | * Produces some “output” | ||
Where “output” is some HTML and any javascript init calls | * Where “output” is some HTML and any javascript init calls | ||
Can use basic PHP functions/loops, like for(), foreach(), count() | * Can use basic PHP functions/loops, like for(), foreach(), count() | ||
A "good renderer" is not: | A "good renderer" is not: | ||
nasty php logic (or even non-nasty php logic) | * nasty php logic (or even non-nasty php logic) | ||
access checks | * access checks | ||
function calls | * non-trivial function calls | ||
using any Moodle functions | * using any Moodle functions | ||
calling the database | * calling the database | ||
unshaven | * unshaven | ||
a bad renderer | * a bad renderer | ||
A “renderable” is: | A “renderable” is: | ||
All the data required to generate the output. | * All the data required to generate the output. | ||
Properties should be simple data types only, or renderables, or array of those | * Properties should be simple data types only, or renderables, or array of those | ||
== Related links == | == Related links == | ||
[Output_API] | [Output_API] |
Revision as of 05:53, 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
- 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]