User:Sam Hemelryk/Output 2.8 GDM reference

General developer meeting output summary

Is the start of a large movement to organise and improve output in Moodle.

What we're going to be doing:

Adoption + creation of elements.
Addition of element library.
Output documentation.

What we are trying to achieve:

Standardise output in Moodle so that interfaces are more consistent, accessible, usable and every other buzz word to describe would could be summed up as a good quality.
Make Moodle much easier to style, with the ultimate goal of making it possible to apply any frontend framework to Moodle with much greater ease.
Speed up the development of interfaces in Moodle by providing developers with a selection of ready to use elements.
Speed up the styling of interfaces by providing tools to aid designers in viewing the available elements in their available states without having to discover them.

The specification

The Render library specification is the spec document for these output changes.
Covers the goals for this project, what problems we currently face, how we hope to solve them and achieve our goals, and the general guff of any specification.
Links to all of the other things coming out from this specification, just like this page in fact.
Forum discussion on the spec to see how things have evolved.

The proposal prototype

There have been several iterations of prototypes now, the development of the specification and the discussion on the forum has been leading its changes. The current prototype code can be found here:

   Repository: git://github.com/samhemelryk/moodle.git
   Branch: output_proposal_5
   Diff URL: https://github.com/samhemelryk/moodle/compare/output_prototype_5~8...output_prototype_5

What's worth noting about this proposal:

It has implement atomic design, elements consisting of atoms, molecules and organisms are represented by classes.
element classes are namespaced under output, e.g. core_output_atom, mod_foo_output_atom.
element classes have common functionality (properties, attributes, and a prerender method for example).
existing renderer structure has been left unchanged so if you're already familiar with renderers you'll have no troubles with this.
There are three themes that have been added to show how this looks when we introduce different frameworks and make use of them.

Elements and Atomic design

We've chosen to run with Atomic Design, for those not familiar with it Brad Frost's article on Atomic web design explains it all.

It basically is a break down of interfaces in module components, compartmentalising as you go so that when you create interfaces you can build the components (aka elements) back up into larger purposeful structures.

There are five levels he defines:

Atoms (e.g. button, input, action)
Molecules (
Organisms
Templates
Pages

We plan to make use of all of these as follows:

Atoms - dedicated classes.
Molecules - dedicated classes.
Organisms - dedicated classes.
Templates - render methods for constructing what is on a page so that it can be overridden.
Pages - theme layout files essentially.

Important notes:

Worth noting is that we won't have atom classes for absolutely everything, only those that make sense to create atom classes for.
We will have an action atom, the action could be rendered as a button, a link, a form, whatever, can have JS actions.
We'll have a special text atom that can be used to pass plain text through the render system and apply the goodness available to atoms when required.

The element library

Tracker issue: MDL-45828

Admin tool to demonstrate how an element is rendered
Plugins can register elements (or any kind of renderable/renderer method) to display in the element library tool
The element library admin tool shows
- Developer notes about the element
- Sample output generated by the thing (supplied with dummy data)
- The list of renderables called when rendering the sample output
- An easy way to switch the language from LTR/RTL
All the new core elements will be listed in this tool
The tool renders using the current theme, so themers can use it to test their new themes

Documentation

Documentation is one of the big things that will come from this work, one of the most important.
Even if we convert very little for 2.8 this will form the basis for all future output work.

At present we have a significant lack of documentation, here we hope to properly document things. We want to have:

Style guides for CSS & HTML
Renderer best practices and guides
Writing element guides

Many of these have already been started. See below for some bullet points.

Renderer best practices

A Renderer best practices document has been started to aid people in writing better renderers.

To summarise some key ideas that have come through it:

Where renderers live, especially now that we've got autoloading and the output namespace available.
What a good renderer is.
What not to do in your renderer (and why perhaps?)
The different styles of render methods (layout, translator, render, convenience)

Element HTML and CSS guidelines

An Element HTML and CSS guidelines document has been started outlining a style guide for writing HTML and CSS for elements.
Important to note that this document is not intended to be applied outside of elements at present. As we are hoping to move entirely towards elements one day this will be the HTML and CSS guide for Moodle. However it will not be enforced in current output, its use may be recommended.

Key ideas in this document include:

Where to put CSS
Prefixing our id's a classes is being purposed.
Introducing notation (based somewhat on BEM) for classes on elements.
Structure and whitespace rules for writing CSS.
Commenting for CSS.
Grids in Moodle - thinking about choosing a specific grid format for core Moodle that can be theme independent but overridden by themes.

Guide to creating output elements

A document titled Guide to creating output elements has been written already on how to write an output element.
This will aid us and others in writing consistent elements that conform to the ideals we have chosen.

How this work is going to get done

As always there is a limited timeframe on the release and limited man hours. We've not converted everything to renderers yet so it'd be false to think we could convert everything to elements. We won't be able to do all of this in 2.8 so we will be focusing on establishing a solid base on which to progress this over future releases.

We will aim to create the useful elements in 2.8 and get some uses of each into Moodle to prove there use.
The documentation will be finalised and completed before the release of 2.8.
The element library will be integrated before the release of 2.8.
Elements can be delegated, we'll get core to do a couple to ensure what we are planning is spot on and then we will happily accept any help offered.
Conversion will be ongoing, it will likely be a couple of release before we truly see the benefits we hope to achieve.
We intend to convert the assignment module early on in the picture.
Complex conversions like forms will be tackled but we are not sure when yet.

Its important to note the impact that this ongoing conversion will have on themers.
We will be endeavouring to keep everything as backwards compatible as possible and conversions will be treated as improvements and only integrated to master.
However themes that have overridden renderers when conversion then take place will need to be reviewed and likely amended/fixed.
This will only happen on major releases, and as this brings many benefits we hope it will be well tolerated.

Relevant links

Docs pages

Tracker issues

MDL-45770 Stage 1 epic (see Render library specification)
MDL-45827 Spec the element library (see Element Library)
MDL-45828 Create the element library
MDL-45829 Initial elements (see Output element planning)
MDL-45853 Document renderer best practices (see Renderer best practices)
MDL-45830 Document CSS style guide for elements (see Element HTML and CSS guidelines)
MDL-45885 Design and document elements (see Guide to creating output elements)
MDL-45854 Document JS and how it works with elements.