|
|
| (45 intermediate revisions by 2 users not shown) |
| Line 1: |
Line 1: |
| A guide to writing output components and the render methods for them.
| | This page has now being published at [[Guide to creating output elements]] |
| | |
| ==Terminology==
| |
| | |
| Don't worry if you don't understand these yet, this document is going to explain them.
| |
| However for the sake of providing a quick understanding of some of the terminology used in output here it is:
| |
| | |
| * '''Atom''' A simple building block, think of it like a HTML tag as that is what it is in many cases.
| |
| * '''Molecule''' A collection of atoms combined together to serve a single purpose or offer a single interaction.
| |
| * '''Organism''' A collection of molecules and atoms combined together to form a part of the user interface, serving one or more related purposes.
| |
| * '''Element''' An element is an meta concept for the above, a base from which all atoms, molecules, and organisms begin.
| |
| * '''Component''' Used to refer to any or all of the above. A component is a general term for renderable something relating to this output approach.
| |
| * '''Renderable''' Used to mark the object as something that can be converted into output.
| |
| | |
| ==Understanding output in Moodle==
| |
| | |
| In 2.8 the direction of output in Moodle was changed, or more accurately re-organised.<br />
| |
| Most Moodle sites out there use a third party theme, or have a had a theme created for them. We can assume that themes are the most widely created plugin within Moodle.
| |
| They deal with the design of the site, and design by nature is a moving, shifting, trending, fluid.<br />
| |
| How Moodle produces its look need to be flexible enough to cater to current trends, requirements such as usability and accessibility, be able to keep up with trends, and cater to personal tastes.<br />
| |
| We've long had renderers now that allow us to cater to this flexibility, however as Moodle has grown so has its interfaces. There are more interfaces, more controls, more possible interactions.<br />
| |
| The move in 2.8 was to bring organisation to what was being done, to bring consistency to the party and the make this flexible a manageable possibility by having an organised set of components to style rather than an endless array of interfaces and unique parts.
| |
| | |
| The goals for the output project were:
| |
| * Add an element library to Moodle (A page in Moodle listing all of the renderables and how they look in the current theme).
| |
| * Add a complete set of core renderables that should be capable of completely rendering every new user interface.
| |
| * Update the Output API documentation.
| |
| * Create a output guide documentation including best practices.
| |
| | |
| All of this leans towards making Moodle framework agnostic, so that any frontend framework can be applied to Moodle with as little work as possible.
| |
| | |
| After reflection and research the decision to use a style of Atomic Design was made. Atomic Design is as you will come to understand later a compartmentalisation approach to interface design that facilitates simplicity and re-use.
| |
| | |
| ===Atomic Design, Renderables and Moodle===
| |
| | |
| Renderables have been around for a long time now, they were one of the initial preferred means of creating a reusable output components.<br />
| |
| As of Moodle 2.8 there is a new kid on the block, Elements.<br />
| |
| Elements within Moodle is based upon the Atomic Design principles outlined by Brad Frost in his [http://bradfrostweb.com/blog/post/atomic-web-design/ Atomic Design blog post] and can be one of three distinct types in Moodle, they are either Atoms, Molecules, or Organisms.<br />
| |
| These elements are within Moodle actually renderables by inheritance, all elements (atoms, molecules, and organisms) must have an associated render method to produce HTML, but more on that later.
| |
| | |
| Lets look at the three types of elements within Moodle.
| |
| | |
| ====Atoms====
| |
| | |
| Atoms are the smallest part of the puzzle. Easily understood as HTML elements, an image, a table, list etc.<br />
| |
| Individually they offer very little, but are essential as they are what all larger things are built out of.
| |
| | |
| Simply - Atoms don't serve any explicit purpose nor do they provide any interaction, they are just building blocks.
| |
| | |
| ====Molecules====
| |
| | |
| Molecules are the combination of atoms into structures that begin to form part of the picture.<br />
| |
| Atoms by themselves aren't useful, but by sticking a few of them together we create a molecule.<br />
| |
| Think of molecules as simple objects that the user can interact with for a single purpose, a login prompt (title + two inputs + a button), a search form (title + input + button), or a menu (several links).
| |
| | |
| Simply - Molecules provide a single interaction or purpose. They are constructed of Atoms only.
| |
| | |
| ====Organisms====
| |
| | |
| Organisms make things interesting, the are more complex than molecules but not so clearly differentiated.<br />
| |
| An organism is a construct of molecules that when combined together form a distinct part of an interface.<br />
| |
| They tend to both interesting, and obviously more than a molecule.<br />
| |
| The following are examples of molecules:
| |
| * A navigation bar containing a title, some navigation, and a user picture.
| |
| * A user content block (like a forum post) containing a user picture, a title, some content, and a date.
| |
| * A Moodle block containing a header, some actions, content, and a footer.
| |
| | |
| Simple - Organisms can group several purposes or interactions into one related structure. They are constructed of Molecules.
| |
| | |
| ====What about templates and pages?====
| |
| | |
| Atomic Design defines two additional compartmentalisations, templates and pages.<br />
| |
| * *Templates* it states are the grouping of predominantly organisms into a structure, think of it like a layout. It is organisation without content.<br />
| |
| * *Pages* are specific instances of the above templates, loaded with content as the user would see them.
| |
| | |
| In regards to Moodle neither of these two ideas is explicitly dealt with, both ideas however are already partly included in Moodle in the form of theme layouts and current renderers.<br />
| |
| Pages are a direct match to this approach, content in Moodle is dynamic and those layouts are where the output and content is joined.<br />
| |
| Templates on the other hand are partly covered by layouts (for the page as a whole), and partly covered by renderers.
| |
| | |
| Renderers form part of that picture because it is within a script that things are assembled.<br />
| |
| Again as of Moodle 2.8 with the work on output a best practices guide for renderers has been written which will outline how best to write renderers to match our chosen approach and why they should be written as such.
| |
| | |
| ===How we made this fit within the Moodle dodecahedron===
| |
| | |
| Within Moodle we've decided to use the terminology from the Atomic Design approach. As discussed above templates and pages are not explicitly handled within Moodle, however atoms, molecules, and organisms are.<br />
| |
| Class auto-loading has being used, and as these things belong to the Output API they have been organised by namespace under classes/output.
| |
| | |
| The following are the base structures:
| |
| | |
| ; core\output\element implements renderable : This is the absolute bottom unit, it can only be utilised by the core Output API. It contains basic functionality to all atoms, molecules and organisms.
| |
| ; core\output\atom extends element : This matches the Atomic Design atom concept. It is a basic building block often equating to just a single HTML tag.<br />Within Moodle we don't created atom classes for each HTML tag. That approach was considered but the clutter, the classes it would introduce, and the render methods for those classes was deemed to outweigh the advantages having them would provide. Instead in many cases our smallest "renderable" element will be the molecule.
| |
| ; core\output\molecule extends element : This matches the Atomic Design molecule concept. It serves a single purpose/interaction and can consist of atoms (as properties) but because we don't have classes/objects for every atom can also in some situations contain no atom objects at all.
| |
| ; core\output\organism extends element : This matches the Atomic Design organism concept. It is a collection of other molecules and atoms, and can have serve several purposes and/or interactions that have all being grouped under a single umbrella, this organism.
| |
| | |
| All of these base structure are abstract and cannot be directly instantiated. Instead actual atoms, molecules, and organisms must derive from one of atom, molecule, or organism.<rb />
| |
| The element class is deemed to be internal to the Output API and therefore cannot be extended outside of the core Output API (at least the integrators won't accept it).
| |
| | |
| ===The importance of inheritance in rendering===
| |
| | |
| By now you have a good picture of how we've organised output in Moodle in 2.8.<br />
| |
| What is left to discuss is the importance of this hierarchy and its impact on how we produce output in renderers.
| |
| | |
| We know that Atoms form Molecules, which in turn form Organisms.<br />
| |
| We try to apply this same inheritance within our renderers so that when you render an organism we start by producing the encompassing structure, then for each of the molecules that make it up we render on each. This passes the molecule to its own render method to produce the molecule. The same goes for the molecules that contain atoms, we produce the structure for the molecule and call render on each atom at the appropriate time for the structure.<br />
| |
| Through this means there should in the perfect world scenario be one way to render each organism, molecule, and atom. Thus when a theme designer wishes to change how the search molecule looks for instance they need only change the render method for that one molecule, and every place that molecule is used, either stand alone or as part of a larger organism will be updated at the same time.
| |
| | |
| Unfortunately, with the present state of Moodle themes this idea of having the minimal possible render methods to produce the most consistent output is but a pipe-dream.<br />
| |
| However as time goes on that will slowly correct itself, as more of Moodle is converted and themes begin to develop with this new approach.<br />
| |
| For the time being the consistency that having a specific set of components and the organisation of those components is going to be a big win.
| |
| | |
| ==The element library==
| |
| | |
| Hopefully you are already familiar with the element library in Moodle; if not then you really should take a look at it and get to understand what is it doing.
| |
| | |
| The element library is a very important piece in the puzzle that is Output within Moodle.<br />
| |
| It shows how a component looks in one or more scenarios, the scenarios usually revolving around varying contents.
| |
| | |
| ==Designing a component==
| |
| | |
| ==Writing the component==
| |
| | |
| ==Writing the render method==
| |
| | |
| ==Tracker issues==
| |
| The following tracker issues relate in one way or another to the development and continued work on Output.
| |
| | |
| * MDL-45885 Decide how output components (the issue that saw this document created)
| |
| * MDL-45770 Implement stage 1 tasks from the Render Library specification
| |
| * MDL-41663 Allow renderers and renderables in a namespace to be auto loaded.
| |
| * MDL-45828 Create the element library admin tool.
| |
| | |
| | |
| | |
| ==See also==
| |
| | |
| * [[Render library specification]]
| |
| * [https://moodle.org/mod/forum/discuss.php?d=261202 Render library specification discussion]
| |
| * [[User:Sam Hemelryk/Render library element planning]]
| |
