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

• 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

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:

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:

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.

Relevant links

Docs pages

• Render library specification
• Output element planning
• Renderer best practices
• Guide to creating output elements
• Element HTML and CSS guidelines
• Element Library

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.