MoodleDocs - User contributions [en]

Render library specification

2015-01-16T02:37:16Z

Samhemelryk:

{{Infobox Project
|name = Renderer consistency
|state = Specification
|tracker = https://tracker.moodle.org/browse/MDL-45770
|discussion = https://moodle.org/mod/forum/discuss.php?d=261202
|assignee = Damyon, Sam
}}
{{Work in progress|forumurl=https://moodle.org/mod/forum/discuss.php?d=261202}}
== Project Goals ==
* 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.

== Benefits ==
* Make it easier to create user interfaces.
* Make it easier to style the user interface.
* Make it easier for themers to customise the user interface.
* Better facilitate frontend frameworks in Themes.
* Better facilitate usable and accessible design.
* Give Moodle a more consistent look and feel.
* Improve site performance by reducing the CSS footprint.

==Understanding renderers in Moodle==

Renderers have been around since Moodle 2.0 and are now the requirement when writing any code that produces output.
Renderers come in many shapes and forms depending upon the developers take on how output should be produced.

When renderables were introduced - the API was designed to make it easy for existing code to be updated to make use of renderers and renderables. A renderable is an interface with no methods, so any existing class could be made to implement renderable. This means that the renderable class can be a mixture of data and methods that perform logic associated with the module. This also means that the renderer can call those methods on the renderable class - effectively using the API of the module. The problem with this - is that it complicates the renderer and makes it harder to override in a theme - the themer requires knowledge about the API for the module. Some renderables in core are built as separate classes - only used for the purpose of supplying data to the renderer - here there is a clear separation of the logic - and the properties of the renderable are made up of only simple types that can be checked for in the renderer - e.g. access checks are done in advance and the result is put into a boolean in the renderable. The current renderers / renderables in Moodle are a mixture of these styles.

Because there is no mandated organisation, nor has there ever been, there is immense variation in what constitutes content to a renderer.

One of the upsides to our current render system is that you are not limited to having a single renderer for a component, you can make use of language capabilities and the output framework and create layers of renderers to cut back code duplication and to aid in preparing a base for consistent structuring and output.

Into the equation we add targets and subtypes. Targets allow us to create both standard renderers and renderers specific to the needs of the output method. Standard being HTML, without output methods including CLI, AJAX, HTML email and plain text email.

People have never being constrained as to how they implement a renderer. We've being happy enough to simply guide them towards using renderers because of the benefits they provide and while there are numerous benefits there are two fundamental benefits:

; A change in thinking : It requires developers to think about their code organisation. Renderers were introduced in a time before Object Orientation was used in Moodle, and logic and output were tightly intermingled in most code. Renderers were about separating logic and design and while what was created was not always perfect it was always an improvement.

; An extensible approach to output : The render system allows for the overriding of renderers to occur. Theme designers can overwrite any renderer in their theme. The more that renderers that get implement the more of Moodle you can customise.

==Understanding themes==

Themes are without a doubt the most widely customised plugin provided by Moodle. But we are currently struggling with several problems with renderers and themes as they are being implemented currently.

1. There is no strict relationship between the HTML generated by a renderable, and the accompanying CSS that is required to make it display properly. The HTML is coded in the renderer - and then the CSS is added, either directly to the styles.css for the plugin in an unorganised way - or directly in the CSS in the theme - again in a loosely organised way. There is no systematic way to determine if any line of CSS is still in use - and there is no simple way to find the CSS that requires updating when the HTML is updated.

2. The CSS framework (bootstrap 2, bootstrap 3, zurb, pureio) specific attributes for renderables are currently being hardcoded in the HTML generated by the renderables. This prevents themers from using a different framework without creating an impossible amount of work to overwrite every renderer in Moodle.

==So what is the problem==

There are several. Lets be blunt about this. This specification is not a single task. It is about improving the state of output in Moodle and there are going to be several steps in achieving this. On a positive note these steps can in many cases be broken down into granular tasks that can be worked on asynchronously.
First lets understand some of the major problems:
* We have no established best practices, nor even documentation on what constitutes a good renderer, or considerations that should be paid mind in planning and designing of code.
* We have no established style guide, nor pattern library, nor element library, nor anything that could be referenced when someone starts building a new user interface - or creating a new theme.
* Inconsistency - because of a lack of best practice documentation and examples, there is huge variation in the design of our different modules. Different modules exhibit different problems such as a mixing of logic and output and code duplication.
* Developers are encouraged to push functionality boundaries in order to take it places observed in other projects or to challenge oneself. While consistency is often talked about it is rarely observed when designing output. We end up with numerous "similar" looking widgets all functioning slightly differently and consequently there is a feeling that this is the way to achieve a new fresh look. (E.g. we have multiple implementations of a "toolbar" - one in Atto and one in EditPDF).
* Existing renderer implementations vary widely and in many cases contain logic they should not. Access checks, database queries, object manipulations. All of which should not be present as it introduces muddling of concepts and logic that must be duplicated and then maintained for anyone overriding renderers.
* Themers have a mammoth task at present in applying a consistent style to Moodle, or in choosing to implement a new frontend framework (bootstrap, foundation, pureio etc). Our lack of organisation in the output leaves a lot to be desired. Having the theme responsible for choosing a frontend framework is the right way to handle this, however backend Moodle doesn't support themeing as well as it should be/could be.
* On top of the above it introduces a need to override several renderers should you want to create a consistent style and because of inconsistent renderer implementations this can easily lead to a maintenance nightmare. E.g. the user_picture renderable is not used in mod_forum - so there is no way to override it there.
* JavaScript introduces problems of its own. We are doing more and more with JavaScript these days. However there is a heavy dependence on the output that gets produced and the JavaScript enhancing it. In a lot of cases the relationship is ill defined and due to the complexity and structure of the JavaScript overriding the output structure of the rendered component is completely impossible for all but the most experienced developers.
* Inline with the above we lack good examples and documentation on how to deliver output templates for JavaScript User Interfaces as well as the creation, and manipulation of HTML structures that are enhanced by JavaScript.

== Identified issues==
There is a general trend in the problems noted, when looking at output we lack organisation, documentation, and consistency across the board. However the actual issues we are focusing on in this spec can be identified as below:

* Lack of a style guide / element library / pattern library.
** Leading to inconsistent output and style.
** Increased workload due to usability and accessibility thinking and testing needing to occur repetitively.
** Increased workload due to multilang (rtl) support usually coming after the designs of new output.
* Inconsistent renderer implementations.
** Lack of best practices.
** Lacking plus outdated documentation.
** Logic-full renderers greatly hinder theming.
** An unnecessarily increased requirement to understand both PHP and Moodle code as each renderer differs and are usually poorly documented.
* No abstraction from CSS framework.
** Without organised structure classes are applied in a chaotic fashion leading to the requirement to duplicate core styles.
** As there is no core styles newly created output widgets need to be styled in all base themes leaving chance of design regressions occurring in predominantly major upgrades but occasionally minor releases as well.
** Inconsistent output structure ensures CSS quickly balloons as styles need to be both created and copied to several areas.
* Poor linking between UI components and the JavaScript.
** Ill-defined link between output and the JavaScript enhancing it.
** No common technique to template UIs generated by javascript

==Manageable Tasks==
The following are the major tasks we have identified so far. These tasks can be though of as Epic's, or tasks for which we will create subtasks (if this output specification itself becomes an Epic).
Within this section will include notes and implementation ideas on the major tasks we've identified.

* [[#Define the elements that make up Moodle|Choose an output methodology and begin defining core elements]]
* [[#Element library and style guide|Create an element library and accompanying style guide]]
* [[#Style guide|Create a style guide document]]
* [[#Define and document renderer best practices|Define and document renderer best practices]]
* [[#Define and update the JS documentation|Update the JavaScript documentation]]
* [[#Update renderer documentation|Update renderer documentation]]
* [[#Update theme documentation and theme tutorials|Update theme documentation and theme tutorials]]
* [[#Progressively convert renderers|Progressively convert renderers]]

===Define the elements that make up Moodle===
There are several tasks that will go into this, but the first and most important will be deciding upon an organisational methodology. Some way to compartmentalise the Moodle output.
At present a reducing granularity system is looking the most appealing. Go and read [http://bradfrostweb.com/blog/post/atomic-web-design/ Atomic Design] written by Brad Frost - it describes very well the type of compartmentalisation we are proposing.

Once a system has being chosen the following tasks can be tackled:
* Identify the layers we require.
* Define the boundaries and responsibilities of those layers.
* Identify the initial set of elements, likely the finest granularity first as I imagine starting at the bottom and working up will be the best way to proceed.

Further elements (those relating to Moodle will be defined as part of the element library work).

===Element library and style guide===
Draft docs for element library tool: [[Element_Library]]

Add an admin tool that can show a categorised list of renderable objects for each plugin/and core - filled with test data. The goal of this tool is to:

* 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 (in a well defined structure) they can use when building their own pages

The tasks here will be:
* Spec the element library tool with regard to our chosen element methodology.
* Create the element library tool.
* Establish a definition method of elements, and compositions of elements as renderables.
* Define the core elements from the task above in code somehow and verify the element library tool reveals them.
* Finally 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, grid. These renderables should be structured into layers, starting from renderables that cannot be broken into smaller parts, up to widgets made of smaller renderables, up to layouts (and possibly up to entire pages). 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

On top of this there is functionality that would be great to add to it:

* Validate that the renderer/renderable follows best practice (no DB queries, complex types, complex logic)
* Provide responsive testing immediately within the tool. Adjusting the viewing area on queue to allow both developers and designers to experience how the individual renderables respond in varying presentation medias.
* Provide language direction testing immediately within the tool. Like the above allow designers and developers to quickly experience a renderable in a different language directions.
* Renderable linear reporting. So that you can see which other renderables make use of this renderable and which renderables get used by this renderable. This will be hugely helpful in judging impact when themeing.

===Thoughts on naming===

We will need to define useful names for the different categories of renderables so that we can effectively organise them and provide guidelines for writing each type - the names are a small part of this solution but will possibly be a point for contention. Different frameworks have different names for these things and people will prefer something that sounds like something they are already using.

(draft!) Categories for renderables - taken straight from Atomic design

http://bradfrostweb.com/blog/post/atomic-web-design/

* Atoms == Tiny reusable elements that cannot be broken down into smaller elements
* Molecules == Relatively simple combinations of atoms built for reuse
* Organisms == Organisms are groups of molecules joined together to form a relatively complex, distinct section of an interface.
* Templates == Layout files in a theme
* Pages == The actual pages in Moodle

Refs for categorizing patterns
* http://bradfrostweb.com/blog/post/atomic-web-design/
* http://oocss.org/
* http://alistapart.com/blog/post/getting-started-with-pattern-libraries
* http://style.codeforamerica.org/

===Style guide===
This has two real advantages.

# First assuming this will be developed initially while defining the elements that will make up Moodle output and will aid us in verifying what we are doing. If it can be easily documented then we are on the right track. If we start encountering to many conditions and or too much variation then we are drifting off track.
# When defining new elements we are able to use our style guide to do so and it'll provide us measure of how Moodle output evolves.

===Define and document renderer best practices===

This will be tricky and no doubt how we decide to define a best practice will have to have regard for the output methodology we choose.

===Update the JavaScript documentation===

Discuss and agree on a best practice for writing JS that depends on HTML structures in the DOM (e.g. progressive enhancement - or just ids for action listeners) (perhaps a specific renderable for a JS region)

===Update renderer documentation===
This will of course need to be done after the element library and renderer best practices but should be pretty simple at that point.
* Read and rate each of the existing docs pages (see related links below)
* Write new complete docs for everyone (at [[Output API]])
* Cross link old docs to the new ones

===Update theme documentation and theme tutorials===
There are likely the most well documented plugin type within Moodle. There are good specification docs, good 2.0 conversion docs and good tutorials on many aspects of theming.
Many of these pages will need to be updated to reflect best practices and such after we start ticking off some of the other tasks.

===Progressively convert renderers===
This is the very last task really - but we will start work on it in parallel with creating the new set of core renderables (to prove the design is usable). There is no deadline for this to be complete - and it will take a long time to convert all the existing renderers (and code not using renderers).

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

Goals for renderers - should be devoid of logic for these reasons:
* Theme overridden renderers do not need to be updated when logic is changed
* Themers can override renderers without understanding all the logic
* Renderables can be filled with mock data for display in the element library

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 not related to output
* calling the database

A “renderable” is:
* All the data required to generate the output.
* Properties should be simple data types only, or renderables, or array of those

== Evaluations of some existing renderers / renderables ==
Existing renderer styles - because there are few rules/guidelines for how renderers should be written - there are differing examples of renderers in core. Looking at the 3 of the better maintained modules to see how they are implemented will be useful in evaluating the benefits of any stricter rules for renderers.
=== Assign ===
Contains a list of renderables (in renderables.php) and a single renderer. The logic is mostly out of the renderer methods (pre-calculated and added as data to the renderer). There are some cases when renderables could be broken down further - e.g. the expand/collapse on the submission history (mod/assign/yui/src/history/js/history.js). Also the assignment sub-plugins do not use renderers (and they should).

=== Quiz ===
Uses a lot of renderers - but not renderables. The renderer methods directly call methods of the business logic to determine what to display. e.g. "attemptobj->get_access_manager(time())->attempt_must_be_in_popup()". This is not terrible for a themer trying to override a renderer method because the calls are mostly simple - but it is a grey area for when this becomes business logic in the renderer (and would e.g. need updating to fix bugs etc). If we want to add these renderer methods to the element library - it would require a way to pass mock business logic classes to the renderer methods (and a way for the generator to return a renderer and a method - instead of only a renderable).

=== Workshop ===
Very nice renderers and renderables in workshop. Would only need updating to re-use core renderables instead of using html_writer directly - and adding the existing renderables to the element library.

=== Badges ===
Mix of renderer methods and renderables. This is similar to quiz where the renderer is calling lots of methods of the business model in the renderer methods and has the same effect (harder to override, maintain etc). To add these renderer methods to the element library would require the same sort of changes as mentioned in quiz.

== Example of forum post renderer using composition ==
This is not a real example (yet), it's just a demonstration of the type of renderers we should be aiming for (using composition etc). This structure would be created in the render_form_post method of the forum renderer. This method would receive a forum_post renderable containing only data - and build up this structure of smaller renderable components, then return the result of calling render(x) on each of the smaller renderables.

[[Image:forumpost-renderer-breakdown.png|center|500px|Example forum renderer]]

== Initial thoughts on renderables and what we should provide (Draft) ==
This list is not intended to be the final list - it is more of a scoping exercise. One of the tasks from this project is to decide on the full set of required renderables.
There are several renderables within Moodle that have being included in this table and we will need to look closely at how they fit within our chosen model and whether they are still required.

{| class="nicetable"
|-
! Name
! Description
! Source (links)
|-
| action_menu
| UI component for a drop down edit menu
| Existing renderable (should be renamed "menu")
|-
| action_menu_link
| UI component for a menu item in an action menu
| Existing renderable
|-
| action_menu_filler
| UI component for a filler menu item in an action menu
| Existing renderable
|-
| action_menu_link_primary
| UI component for a primary menu item in an action menu
| Existing renderable
|-
| action_menu_link_secondary
| UI component for a secondary menu item in an action menu
| Existing renderable
|-
| action_link
| Link with alt text, and an icon
| Existing renderable
|-
| single_button
| A form with a single button
| Existing renderable
|-
| confirm
| A form with a message and cancel/confirm buttons
| Existing renderable
|-
| single_select
| A form with a single drop down list that submits on change
| Existing renderable
|-
| url_select
| A navigation element consisting of a single drop down list of urls that navigates on change
| Existing renderable
|-
| doc_link
| A link to the Moodle docs
| Existing renderer method
|-
| pix_icon
| A small icon
| Existing renderable
|-
| emoticon_icon
| A small emoticon
| Existing renderable
|-
| heading_with_help
| A page heading with a link to help docs
| Existing renderer method
|-
| help_icon
| A help icon that opens a help popup when clicked
| Existing renderable
|-
| help_icon_scale
| A help icon that opens a help popup when clicked
| Existing renderable
|-
| user_picture
| A user profile picture which links to their profile
| Existing renderable
|-
| container
| A block level element used to surround something. Can have a class to allow specific targeting with CSS.
| Existing renderable
|-
| error_text
| An error to show to the user.
| Existing renderable
|-
| notification
| A message for the user
| Existing renderable
|-
| continue_button
| A message and a button to continue to the next page
| Existing renderable
|-
| paging_bar
| A list of next previous and specific page links
| Existing renderable
|-
| skip_link_to
| A link to a section on the page
| Existing renderable
|-
| skip_link_target
| A target for a matching skip_link_to call
| Existing renderable
|-
| heading
| A page heading
| Existing renderable
|-
| box
| A page section with a border
| Existing renderable
|-
| rarrow
| A right arrow
| Existing renderable
|-
| larrow
| A left arrow
| Existing renderable
|-
| tabtree
| A list of tabs
| Existing renderable
|-
| tabobject
| A single tab panel
| Existing renderable
|-
| toolbar *new
| A container for toolbar button groups
| Bootstrap equiv btn-toolbar (needs aria support)
|-
| toolbar-group *new
| A group of toolbar buttons
| Bootstrap equiv btn-group (needs aria support)
|-
| toolbar-button *new
| A toolbar button
| Bootstrap equiv btn (needs aria support)
|-
| toolbar-menu *new
| A toolbar button that opens a drop down menu
| Bootstrap equiv nested btn-groups (needs aria support)
|-
| navbar *new
| The navigation bar that shows at the top of the page
| Bootstrap equiv navbar - There is an existing renderer method that needs converting into renderables
|-
| navbar_item *new
| Items in the navigation bar that shows at the top of the page
| Bootstrap equiv list item in a navbar - There is an existing renderer method that needs converting into renderables
|-
| navbar_item *new
| Items in the navigation bar that shows at the top of the page
| Bootstrap equiv list item in a navbar - There is an existing renderer method that needs converting into renderables
|-
| progress_bar *new
| A bar showing progress of something
| Bootstrap equiv progress_bar - There is an existing moodle class that needs converting to use renderables
|-
| progress_bar *new
| A bar showing progress of something
| Bootstrap equiv progress_bar - There is an existing moodle class that needs converting to use renderables
|-
| panel *new
| A container with a heading and borders
| Bootstrap equiv panel, panel-heading, panel-body, panel-footer
|-
| vertical-list *new
| A vertical list of items
| Bootstrap equiv - list-group
|-
| horizontal-list *new
| A horizontal list of items
| Bootstrap equiv - list-inline
|-
| Two column list *new
| Short cut for a list of pairs with the left column fixed-width and right aligned
| Similar to our current moodle forms
|-
| table (and cells headings etc) * new
| We need to convert tablelib to use renderers to output all table elements
|
|-
| forms (and labels, inputs etc) * new
| We need to convert formslib to use renderers to output all form elements
|
|-
| grids *new
| We need to support renderables for a simple responsive grid system
| Everything has grids...
|-
| floats *new
| We need to support floating elements left and right
| Bootstrap - pull-left, pull-right
|-
| clearfix *new
| If we have this simple thing as a renderable we can avoid repeating the CSS
| Bootstrap - clearfix
|-
| expandable *new
| Initially shows only a summary with an expand button to show more details
| mod_assign
|-
| dialog *new
| Tie into M.core.dialogue so it can be adjusted in a renderer
| aria
|-
| timer *new
| There is an aria role for this - so we should make sure it is used correctly if required.
| aria
|-
| tree *new
| Reusable version of the nav tree
| aria tree, tree-item, tree-grid etc
|-
| indent *new
| (eg threaded forum post)
|
|-
| media block *new
| large media element side by side with some text
| http://demo.patternlab.io/
|-
| hero *new
| content section with borders/oversized text etc designed to be a landing point
| Bootstrap jumbotron
|}

== Prototyping ==
We built a lot of prototypes here - trying to find the perfect solution - but even the most elegant PHP class design still means that the renderer is hard to build and understand.

List of corpses :)
https://github.com/samhemelryk/moodle/tree/output_prototype
https://github.com/samhemelryk/moodle/tree/output_prototype2
https://github.com/samhemelryk/moodle/tree/output_prototype3
https://github.com/samhemelryk/moodle/tree/output_prototype5
https://github.com/samhemelryk/moodle/tree/output_prototype2
https://github.com/damyon/moodle/tree/MENU_RENDERABLE

We also tried to explain the importance of separating logic from renderer methods - but there were gray areas when people asked about simple capability checks, calling helper methods etc.

The new proposal is to add support for mustache templates to renderers and build support so they can be used from Javascript or PHP.

== Mustache ==

What is Mustache and why does this hipster want to climb in my renderables ?

Mustache is a templating library designed to use "Logic-less templates". It is very popular with Javascript developers.

http://mustache.github.io/

Side note: Handlebars is an alternative to mustache that builds on the mustache syntax with more features, but unfortunately the php implementation of handlebars is unreliable and does not conform to the specification (I tested). Handlebars also allows more logic to leak into the templates (function calls with params etc) and I found it led to more mess.

Question: How does it work in Moodle?

Answer: Really well! Say I have a renderable called "foobar". Instead of defining a function in my renderer named render_foobar($foobar), I just create a file in the templates folder for my plugin named foobar.mustache. A mustache template contains real HTML and mustache tags and nothing else. My new template will be rendered using the renderable as the context.

=== Mustache Examples ===

Old renderer method:
<code php>
public function render_assign_grading_summary(assign_grading_summary $summary) {
// Create a table for the data.
$o = '';
$o .= $this->output->container_start('gradingsummary');
$o .= $this->output->heading(get_string('gradingsummary', 'assign'), 3);
$o .= $this->output->box_start('boxaligncenter gradingsummarytable');
$t = new html_table();

// Status.
if ($summary->teamsubmission) {
$this->add_table_row_tuple($t, get_string('numberofteams', 'assign'),
$summary->participantcount);
} else {
$this->add_table_row_tuple($t, get_string('numberofparticipants', 'assign'),
$summary->participantcount);
}

// Drafts count and dont show drafts count when using offline assignment.
if ($summary->submissiondraftsenabled && $summary->submissionsenabled) {
$this->add_table_row_tuple($t, get_string('numberofdraftsubmissions', 'assign'),
$summary->submissiondraftscount);
}

// Submitted for grading.
if ($summary->submissionsenabled) {
$this->add_table_row_tuple($t, get_string('numberofsubmittedassignments', 'assign'),
$summary->submissionssubmittedcount);
if (!$summary->teamsubmission) {
$this->add_table_row_tuple($t, get_string('numberofsubmissionsneedgrading', 'assign'),
$summary->submissionsneedgradingcount);
}
}

$time = time();

if ($summary->duedate) {
// Due date.
$duedate = $summary->duedate;
$this->add_table_row_tuple($t, get_string('duedate', 'assign'),
userdate($duedate));

// Time remaining.
$due = '';
if ($duedate - $time <= 0) {
$due = get_string('assignmentisdue', 'assign');
} else {
$due = format_time($duedate - $time);
}
$this->add_table_row_tuple($t, get_string('timeremaining', 'assign'), $due);

if ($duedate < $time) {
$cutoffdate = $summary->cutoffdate;
if ($cutoffdate) {
if ($cutoffdate > $time) {
$late = get_string('latesubmissionsaccepted', 'assign');
} else {
$late = get_string('nomoresubmissionsaccepted', 'assign');
}
$this->add_table_row_tuple($t, get_string('latesubmissions', 'assign'), $late);
}
}

}

// All done - write the table.
$o .= html_writer::table($t);
$o .= $this->output->box_end();

// Link to the grading page.
$o .= $this->output->container_start('submissionlinks');
$urlparams = array('id' => $summary->coursemoduleid, 'action'=>'grading');
$url = new moodle_url('/mod/assign/view.php', $urlparams);
$o .= $this->output->action_link($url, get_string('viewgrading', 'assign'));
$o .= $this->output->container_end();

// Close the container and insert a spacer.
$o .= $this->output->container_end();

return $o;
}
</code>

New template:
<code html5>
<div class="gradingsummary">
<h3>{{str.mod_assign.gradingsummary}}</h3>
<div class="boxaligncenter gradingsummarytable">
<table class="generaltable">
<tbody>
<tr>
<td class="cell c0">
{{#teamsubmission}}
{{str.mod_assign.numberofteams}}
{{/teamsubmission}}
{{^teamsubmission}}
{{str.mod_assign.numberofparticipants}}
{{/teamsubmission}}
</td>
<td class="cell c1 lastcol">{{participantcount}}</td>
</tr>
{{#submissionsenabled}}
{{#submissiondraftsenabled}}
<tr>
<td class="cell c0">
{{str.mod_assign.numberofdraftsubmissions}}
</td>
<td class="cell c1 lastcol">{{submissiondraftscount}}</td>
</tr>
{{/submissiondraftsenabled}}
<tr>
<td class="cell c0">
{{str.mod_assign.numberofsubmittedassignments}}
</td>
<td class="cell c1 lastcol">{{submissionssubmittedcount}}</td>
</tr>
{{^teamsubmission}}
<tr>
<td class="cell c0">
{{str.mod_assign.numberofsubmissionsneedgrading}}
</td>
<td class="cell c1 lastcol">{{submissionsneedgradingcount}}</td>
</tr>
{{/teamsubmission}}
{{/submissionsenabled}}
{{#duedate}}
<tr>
<td class="cell c0">
{{str.mod_assign.duedate}}
</td>
<td class="cell c1 lastcol">{{duedate}}</td>
</tr>
<tr>
<td class="cell c0">
{{str.mod_assign.timeremaining}}
</td>
{{#late}}
<td class="cell c1 lastcol">{{str.mod_assign.assignmentisdue}}</td>
{{/late}}
{{^late}}
<td class="cell c1 lastcol">{{timeremaining}}</td>
{{/late}}
</tr>
{{#late}}
<tr>
<td class="cell c0">
{{str.mod_assign.latesubmissions}}
</td>
{{#latesubmissionaccepted}}
<td class="cell c1 lastcol">{{str.mod_assign.latesubmissionsaccepted}}</td>
{{/latesubmissionaccepted}}
{{^latesubmissionaccepted}}
<td class="cell c1 lastcol">{{str.mod_assign.nomoresubmissionsaccepted}}</td>
{{/latesubmissionaccepted}}
</tr>
{{/late}}
{{/duedate}}
</tbody>
</table>
</div>
<div class="submissionlinks">
{{#links}}
{{.}}
{{/links}}
</div>
</div>

</code>

==Documents created as part of this spec==
* [[Output element planning]] - Thoughts on initial elements that should be created.
* [[Renderer best practices]]
* [[Guide to creating output elements]]
* [[Element HTML and CSS guidelines]]

== See also ==
* [[Output API]]
* [[Migrating your code to the 2.0 rendering API#Outputting HTML specific to your module]]
* [[Output_renderers]]
* [[Overriding_a_renderer]]
* [http://moodle.org/mod/forum/discuss.php?d=177535 Forum discussion on renderers]
* [[Renderer]]

Developer meeting July 2014

2014-07-22T13:53:08Z

Samhemelryk:

[[Developer meetings]] > July 2014 meeting notes

{| class="nicetable"
|-
| Time
| [http://timeanddate.com/worldclock/fixedtime.html?year=2014&month=7&day=22&hour=13&min=0&sec=0 13:00 UTC on Tuesday, 22 July 2014]
|-
| Meeting video
| [http://youtu.be/Qw9xtl9pGac Youtube stream]
|-
| Chat
| [https://moodle.org/local/chatlogs/info.php Regular Dev chat]
|-
| Twitter
| [https://twitter.com/search?q=%23moodledev #moodledev]
|}

This meeting will focus on development happening outside of Moodle HQ

The meeting will be streamed live on YouTube with chat through the regular Dev chat room and comments on Twitter.

== Agenda ==
* Invited speaker: Justin Hunt ([https://moodle.org/mod/forum/discuss.php?d=260165 Atto plugin development]).
* Development in progress at HQ
** [[Render_library_specification|Output plan]] (Sam Hemelryk, Damyon Wiese) [[User:Sam_Hemelryk/Output_2.8_GDM_reference#Relevant_links|talk notes]]
** [[Navigation_overhaul_specification|User menu]] (Jetha Chan, Frédéric Massart)
** [[Event_Monitor_specification|Event Monitor]] (Ankit Agarwal, Simey Lameze)
** [[reportbuilder/API|Report Builder Source API]] (Adrian Greeve, John Okely)
** [https://tracker.moodle.org/browse/MDL-44673 Gradebook changes] (Martin Dougiamas)
** [[VERP|VERP for email processing]] (Andrew Nicols)
* Featured plugins campaign in Moodle plugins directory (David Mudrák)

== Meeting Video ==

[http://youtu.be/Qw9xtl9pGac Link to meeting on YouTube]

If you have something you'd like to add to this page, please [https://docs.moodle.org/dev/index.php?title=Developer_meeting_July_2014&action=edit edit this page] or contact [http://moodle.org/user/profile.php?id=381842 Michael d].

User:Sam Hemelryk/Output 2.8 GDM reference

2014-07-22T12:49:14Z

Samhemelryk: /* Relevant links */

==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.
* [https://moodle.org/mod/forum/discuss.php?d=261202 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 [http://bradfrostweb.com/blog/post/atomic-web-design/ 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

[[Image:prototype-screenshot-element-library.png]]

==Documentation==

Documentation is one of the big things that will come from this work, one of the most important.<br />
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.<br />
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.<br />
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.<br />
We will be endeavouring to keep everything as backwards compatible as possible and conversions will be treated as improvements and only integrated to master.<br />
However themes that have overridden renderers when conversion then take place will need to be reviewed and likely amended/fixed.<br />
This will only happen on major releases, and as this brings many benefits we hope it will be well tolerated.

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

'''Other links'''
* [http://bradfrostweb.com/blog/post/atomic-web-design/ Atomic web design by Brad Frost]
* [http://bem.info/tutorials/start-with-project-stub/ BEM introduction]

User:Sam Hemelryk/Output 2.8 GDM reference

2014-07-22T12:47:14Z

Samhemelryk: /* How this work is going to get done */

User:Sam Hemelryk/Output 2.8 GDM reference

2014-07-22T12:41:59Z

Samhemelryk: /* The element library */

==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.
* [https://moodle.org/mod/forum/discuss.php?d=261202 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 [http://bradfrostweb.com/blog/post/atomic-web-design/ 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

[[Image:prototype-screenshot-element-library.png]]

==Documentation==

Documentation is one of the big things that will come from this work, one of the most important.<br />
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.<br />
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.<br />
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 itd be false to think we could convert everything to elements.
* We will aim to create the designated 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.

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

File:prototype-screenshot-element-library.png

2014-07-22T12:41:24Z

Samhemelryk: A screenshot of the element library prototype.

A screenshot of the element library prototype.

User:Sam Hemelryk/Output 2.8 GDM reference

2014-07-22T12:39:57Z

Samhemelryk: /* Relevant links */

==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.
* [https://moodle.org/mod/forum/discuss.php?d=261202 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 [http://bradfrostweb.com/blog/post/atomic-web-design/ 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.<br />
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.<br />
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.<br />
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 itd be false to think we could convert everything to elements.
* We will aim to create the designated 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.

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

User:Sam Hemelryk/Output 2.8 GDM reference

2014-07-22T12:33:22Z

Samhemelryk: /* Documentation */

==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.
* [https://moodle.org/mod/forum/discuss.php?d=261202 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 [http://bradfrostweb.com/blog/post/atomic-web-design/ 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.<br />
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.<br />
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.<br />
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.

User:Sam Hemelryk/Output 2.8 GDM reference

2014-07-22T12:33:01Z

Samhemelryk: /* Documentation */

==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.
* [https://moodle.org/mod/forum/discuss.php?d=261202 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 [http://bradfrostweb.com/blog/post/atomic-web-design/ 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.<br />
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.<br />
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.<br />
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.

User:Sam Hemelryk/Output 2.8 GDM reference

2014-07-22T12:23:59Z

Samhemelryk: /* Elements and Atomic design */

User:Sam Hemelryk/Output 2.8 GDM reference

2014-07-22T12:15:15Z

Samhemelryk: /* The specification */

User:Sam Hemelryk/Output 2.8 GDM reference

2014-07-22T12:07:39Z

Samhemelryk: /* The specification */

User:Sam Hemelryk/Output 2.8 GDM reference

2014-07-22T12:05:10Z

Samhemelryk: /* General developer meeting output summary */

User:Sam Hemelryk/Output 2.8 GDM reference

2014-07-22T11:56:54Z

Samhemelryk:

==General developer meeting output summary==

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

Overall project goals:
# Adoption + creation of elements.
# Addition of element library.
# Output documentation.

==The specification==

* The [[Render library specification]] is the spec document for these output changes.
* [https://moodle.org/mod/forum/discuss.php?d=261202 Forum discussion on the spec] to see how things have evolved.

==Elements and Atomic design==
==The element library==

==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.<br />
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.<br />
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.

User:Sam Hemelryk/Output 2.8 GDM reference

2014-07-22T11:45:52Z

Samhemelryk: Created page with "==General developer meeting output summary== Is the start of a large movement to organise and improve output in Moodle. Overall project goals: # Output documentation. # Adop..."

==General developer meeting output summary==

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

Overall project goals:
# Output documentation.
# Adoption + creation of elements.
# Addition of element library.

==Documentation==

==The specification==

* The [[Render library specification]] is the spec document for these output changes.
* [https://moodle.org/mod/forum/discuss.php?d=261202 Forum discussion on the spec] to see how things have evolved.

==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.<br />
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 has been written already on how to write an output element.<br />
This will aid us and others in writing consistent elements that conform to the ideals we have chosen.

User:Sam Hemelryk

2014-07-22T11:45:34Z

Samhemelryk:

Hello, I am a senior developer at Moodle and have been with the project since the June 2009.

For those interested I have written a tutorial on my Moodle development process with Git: [[User:Sam_Hemelryk/My_Moodle_Git_workflow]]

A short list of documents I have created:

* [[Themes 2.0]]
* [[Themes 2.0 creating your first theme]] - A quick step by step guide to creating your first theme.
* [[Themes 2.0 overriding a renderer]] - A tutorial on creating a custom renderer and changing the HTML Moodle produces.
* [[Themes 2.0 How to use images within your theme]] - Explains how to use and override images within your theme.
* [[Themes 2.0 adding a settings page]] - Looks at how to add a setting page making your theme easily customisable.
* [[Themes 2.0 extending the custom menu]] - Customising the custom menu.
* [[Themes 2.0 adding courses and categories to the custom menu]] - Extending the custom menu further adding all categories + courses
* [[Themes 2.0 how to make the dock horizontal]] - Modifying the dock to make it horizontal.
* [[Themes 2.0 adding upgrade code]]
* [[Styling and customising the dock]] - How to style and customise the dock.
* [[Using jQuery with Moodle 2.0]]
* [[The Moodle Universal Cache (MUC)]] ''originally written at [[User:Sam_Hemelryk/MUC_proposal]]''
* [https://docs.moodle.org/27/en/Caching Caching] ''originally written at [[User:Sam_Hemelryk/Caching]]''
* [https://docs.moodle.org/27/en/Cache_definitions Cache definitions] ''originally written at [[User:Sam Hemelryk/Cache definitions]]''

'''Output in Moodle 2.8'''
* [[Output_element_planning]] ''originally written at [[User:Sam Hemelryk/Render library element planning]]''
* [[Guide to creating output elements]] ''originally written at [[User:Sam Hemelryk/Creating renderable components]]''
* [[Renderer best practices]] ''originally written at [[User:Sam Hemelryk/Renderer best practices]]''
* [[Element HTML and CSS guidelines]] ''originally written at [[User:Sam Hemelryk/CSS style guidelines]]''
* [[User:Sam Hemelryk/Output 2.8 GDM reference]] ''reference notes on the output to be talked about at the General Developer Meeting July 2014''

User:Sam Hemelryk

2014-07-22T11:44:26Z

Samhemelryk:

Guide to creating output elements

2014-07-22T11:42:06Z

Samhemelryk:

{{Infobox Project
|name = Renderer consistency
|state = Specification
|tracker = https://tracker.moodle.org/browse/MDL-45885
|discussion = https://moodle.org/mod/forum/discuss.php?d=261202
|assignee = Damyon, Sam
}}
{{Work in progress|forumurl=https://moodle.org/mod/forum/discuss.php?d=261202}}
A guide to writing output elements and the render methods for them.

==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, when we talk about elements we talk about one of or more of atoms, molecules, and organisms.
* '''Subelement ''' When we speak of subelements we are talking about the smaller elements that are going to be of a larger element. e.g the molecules that are present in an organism.
* '''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 elements 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 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 elements and the organisation of those elements 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 an element looks in one or more scenarios, the scenarios usually revolving around varying contents.

==Designing and writing an element==

A step by step approach to working through the creation and rendering of an element so that it meets the Output standards for Moodle.<br />
If you want a quick overview of what to do have a look at the [[#Peer-review checklist|peer-review checklist]] in the next section

===Step 1: Are you sure you need to create an element===
We want Moodle to contain a limited number of elements. The problem that existed before this work was that every bit of code was creating its own output, and we do not want to end up back there.

The very first thing to do is to be absolutely sure that you need to create this element.

'''Atoms and molecules'''
After the initial release this should be rare. It should be especially rare that you need to write an atom or molecule for a plugin.<br />
Moodle should provide 95% of the atoms and molecules you could ever need. However if you have something that is truly new and unique in some way then perhaps indeed you do need to write an element.

'''Organisms'''
Writing an organism is going to be a common requirement. Within core there may be a finite number of organisms, only increasing as new Moodle elements are created and new interfaces added. However when creating plugins or updating output in existing plugins it is very likely that new organisms will be created. If you have an interface in a plugin that is somehow unique to that plugin then you have a organism.

In both cases it is important that you search through the elements already in Moodle and see if there are any that meet your needs.<br />
If there is something close in Moodle core already then perhaps you need to adjust your design to make use of the existing element rather than introducing something similar but slightly different.<br />
If you find an element you could use in a core plugin then you should create an issue in our Tracker and request that the element be moved from the plugin to core.<br />
Then for the time being copy the element from the plugin you found it in, into your plugin. This way it will look consistent, you can use it and if it does get accepted into core you don't have to change anything about how you use it.

===Step 2: Define the element===

It very important to be sure of what you want to create.

The first thing to do is to work out what is it going to be, is it an atom, a molecule, or an organism?<br />
Remember the following, they describe each of those in a single sentence:
; Atom : A basic building block that severs no purpose or interaction.
; Molecule : Serves just a single purpose OR interaction, not usually a part of an interface by itself, grouped with other molecules and atoms to form an organism.
; Organism : A part of the interface, it is constructed of molecules and atoms, it can facilitate several like purposes and interactions

It should be possible to create a flow chart to aid this decisions, unfortunately one has not being created yet.

Once you've decided what type of element it is going to be you are ready to start designing what other elements (if any) will make it up.

Now is a good time to be very clear about the purpose of your element, as well as any interactions that you want it facilitate.
Consider writing down a clear and concise description of your element and sharing what you are planning in the forums, with colleagues or just generally with other developers.
This output approach is still fresh and we are all still learning how it works in detail so the more exposure you can get now the easier it will be down the track.

When thinking about your element try to think about it is a blueprint to what you want to display. When displaying an actual something it is populated by data and that data is then used by a render method of a renderer to produce HTML.
Think about where that data is coming from, think about the renderer best practices, think about the style guide, and think about what others may and will do when overriding a renderer to override your render method.

There are two additional important concepts to consider at this point as well, attributes and properties. Important enough to have their own heading so as to be easily found.

====Attributes====
These are HTML attributes. It may be very very tempting to set attributes like classes and ID's within an element. But please do not.<br />
Attributes should only be added to an element by the renderer. They may be added by any one of the three types of render methods you'll read about later.

The reason for this is that we want the renderer to be solely responsible for translating an element to HTML. An instance of an element is simply a catalyst for the data contained within.

Within a renderer attributes can be interacted with as follows:
<code php>
// A publicly accessable array of attributes. Key => Value.
$element->attributes;

// Set an attribute on the element.
$element->set_attribute($key, $value);

// Set an array of attributes on the element;
$element->set_attributes(array(key1 => value, key2 => value));

// Addes a CSS class to the attributes
$element->add_class('some-class');

// Returns the attributes as a string suitable for use in HTML output.
$element->get_attributes();
</code>

====Properties====
Talking about properties here I am not talking about class properties of the element that are used to contain data.<br />
I am talking about the properties that describe the instance of the element. To get your head around this consider a menu that has several items within it. There are three common properties added by default to all elements that are applicable here:

; active : A boolean property, set this to true if this item points to the current page. The active item.
; enabled : A boolean property again, set to true this says that the item is enabled and the user can perform the associated action. Set to false is like saying the user cannot interact with this menu item.
; dimmed : A Moodle-esq property. Set to true if the item is visible to the current user but not to every other user. Think of it like viewing a hidden course because you have the capability to.

Properties can be added, and set by either a parent element, or a renderer if need be. They are used to convey properties that are applicable only in certain situations.<br />
The ability for an element to add properties to its subelements allows us more re-use of elements within renderers so that we don't need dedicated objects in situations where it is simply a property or two that differs from an available element.

Properties can be interacted with the following methods and properties:

<code php>
// Publicly accessable array of properties. Key => Value.
$element->properties;

// Add a property to this element.
$element->add_property(name, value);

// Add an array of properties to this element.
$element->add_properties(array(n1 => value, n2 => value));

// Sets the value of a property.
$element->set(name, value);

// Gets the value of a property.
$element->get(name);

// Returns true is a property is set and is not empty.
$element->is(name);
</code>

===Step 3: Create the element class===

Creating an element is really quite simple, the following headings explain what you need to know.
Remember if in doubt there are a lot of examples that can be easily found in Moodle core (within lib/output).

====Element location====
All elements belong to the Output API and should be namespaced within it for autoloading and consistency with Moodle core elements.
This makes locating elements very easy, core elements will be located within an output subdirectory of the classes directory as shown below:

: lib/classes/output/'''myelement.php'''

Plugin elements will be located in a similar fashion within an output subdirectory of the classes directory. e.g.

: mod/''myplugin''/classes/'''myelement.php'''

====Class name and inheritance====
Classes are namespaced for the output API and located in the file above. Because classes are namespaced the actual class name is simply the element name. The same name as was used for the file.
They must however extend the appropriate element type, if you are creating a molecule it must extend ''\core\output\molecule'', if its an organism it must extend ''\core\output\organism''.
For following is an example of how this would look for a core element:

<code php>
<?php
namespace core\output;
defined('MOODLE_INTERNAL') || die();

class myelement extends organism {
</code>

And for an element you are creating within a module plugin:

<code php>
<?php
namespace mod_myplugin\output;
defined('MOODLE_INTERNAL') || die();

class myelement extends \core\output\organism {
</code>

====Class properties====

We like to keep elements simple to interact with. For that reason we encourage people to store data and subelements that will be used during rendering as public class properties.
This is done so that data is accessed in a consistent fashion when interacting with an element. For this reason we would rather '''not''' see developers adding methods to an element unless truly required.

Subelements are a good example. If you were writing a navigation bar organism for example you may have a title molecule, a menu molecule, and a search molecule. The title, menu and search molecules are the elements.<br />
These will become public class properties of your element.

====Class methods====

Elements should only have methods to support their own construction. As expressed above all information useful to a renderer should be stored in publicly accessible properties, none of it should have to be accessed via method calls.
This is done so that interaction with elements is consistent across all elements. Methods to aid the construction of the element are encouraged so that information can be easily added to the element.

====Your constructor====
The constructor for your element should allow the developer to pass in the required data and subelements.
Consider when writing the constructor how developers will pass information into the element. In many cases there are going to be two types of data that will commonly be passed in:
# Elements (or arrays of) that make up parts of your element.
# Scalars (or arrays of) e.g. strings, integers, floats and booleans.

Make the data that is absolutely required part of the constructor and simply have publicly accessible properties for the optional data that can be set by calling code if required.

Its also worth considering if you are creating a molecule that perhaps data handling for the atoms that make it up may be worth including in your constructor.<br />
For instance a dropdown consists of a trigger element (button, link, image) and a menu, the menu is a molecule that consists of items. The constructor of the dropdown could aid construction by accepting two arguments, the first a way to pass in a trigger, and the second either an already build menu element OR an array of items that get used to construct a menu element within the dropdown constructor.

Some points to remember:
* Don't forget all properties should default to null if they do not have data set.
* If you have a collection of something as a property consider adding add_xxx() and add_xxxs() methods to aid the construction of elements.

===Step 4: Write the render methods===

There are 3 categories of render methods that will exist within every renderer and depending upon the type of your element you will be creating one or more of these methods for it.

Why the three types of render method? There are two key reasons to take the above apporach.

'''Re-use'''<br />
By ensuring we call the render method to produce elements and subelements when ever possible we will hopefully be making it easier to style Moodle as it won't be necessary to style absolutely everything individually. Instead if render has being used consistently to produce a button for example styling the HTML produced by ''render_button()'' should style all buttons throughout Moodle.

'''Make overriding renderers in themes more controlable'''<br />
The three types of render methods are designed to separate the logic and display that is permissable in renderers.<br />
Render method should contain as little logic and PHP as possible, however in many situations a bit of PHP and perhaps a bit of logic is going to be required in order to take data from one form and make it ready to present.<br />
If overriding a renderer within a theme the theme developer can look at what they want to achieve and choose the suitable method to override.<br />
If they are looking to change the markup for an element then they can override the render method, they will not need to know anything about how the element was constructed or what information went into it. They can focus on the data the element has and produce the HTML they desire.<br />
If they choose to change data, or want to display something different to what is there by default then they can override the translator method and continue to hack away to their hearts content.

Hopefully as you read about the render methods below the advantages to this approach will become clear.

====Render method====

This is the easiest to understand and no matter what type of element you have created you will need to write a render method.
The render method takes an element and returns HTML to display it.

The render method takes a strict format:
<code php>
/**
* Produce HTML to display myelement.
*
* @param \core\output\myelement $myelement The element to display.
* @return string An HTML version of the element.
*/
protected function render_myelement(\core\output\myelement $myelement) {
// Generate HTML for the element.
return $html;
}
</code>

The following are rules to follow when creating a render method.

* It display the element, nothing else.
* It is a protected method.
* The name of the method is always "render_" followed by the '''non-namespaced''' name of your element.
* There is only ever '''one''' argument, the element to render and it should be typehinted.
* It will contain no logic.
* It uses the public properties of the element for data.
* It supplments this by using the available methods '''ONLY IF ABSOLUTELY REQUIRED'''
* It returns a string, the HTML to display the element.

This method is very simple to understand, and providing you have properly researched and proposed your element it should be even easier to write.

If you are writing a render method for molecule or organism then you likely will have subelements that have being used within your element.
Where possible you should call '''$this->render()''' on the subelements to produce HTML for them that can then be included in the HTML that you are producing for your element.
Only if you absolutely must should you handle the generation of HTML for subelements directly within the render method for your element.<br />
If you do produce the HTML for a subelement without calling render than '''you must''' manually call the subelements ''prerender'' method to ensure that it has an opertunity to complete and requisits it has before rendering.

This is done to ensure that where possible we re-use the HTML for an element. By doing it we reduce the number of elements that a theme must style if all it is doing is styling.<br />
If a theme overrides a render method it is not obligated to take this same approach. Theme overridden renderers can do as they please, any duplication of structure they introduce is their own business.

====Convenience method====

The name for this type of method provide a big hint as to what it is, it is a method to conveniently construct and render an instance of your element.
This method also takes a very simple, predicatable form.

<code php>
/**
* Create and render a new myelement.
*
* @param mixed $arg1
* @param mixed $arg2
* @param mixed $arg3
* @return string HTML for myelement.
*/
public function myelement($arg1, $arg2, $arg3 = null) {
$obj = new \core\output\myelement($arg1, $arg2, $arg3);
return $this->render($obj);
}
</code>

This type of method always does three things:
# It takes the arguments necessary to create a new instance of myelement.
# It creates a new instance of myelement given the arguments it is given and sets it up as required.
# It calls '''$this->render()''' and gives it the object, returning the outcome.

There are a few things to observe when writing a convenience method:
# It is always public.
# Its arguments should be complete.
#* Meaning that they should be arguments that can be immediately to the element
#* OR can be checked in conditions to alter the element.
#* They should not be objects to support the generation of data. The data should be complete.
# It should '''not''' produce any HTML itself, the render method is responsible for this.
# It returns a string, the HTML to display for the given element.

In the case of molecules and organisms it is permissable for the convencience method to take actual subelements OR the arguments required to create necessary subelements. This is at the discretion of the developer and may be determinent on the number of arguments required to construct the element.<br />
Complex elements that require a lot of data to set up are probably not ideal candidates to create convenience methods for.

====Translator method====

These methods take complex arguments such as data and objects from outside of the Output scope and manipulate/smooth the data into a complex organism or molecule.<br />
They should be used to pass in the information the current element requires as well as any information that may be used by an overriding renderer to access additional data that may be desired.

These are likely to be rare for core elements, however just about essential for elements being introduced by plugins for example where having retrieving data from plugin objects for use in an element or subelements is going to be required.<br />
If for example you consider how your would render a forum discussion the translator method would likely take a forum discussion object and use a method of it to retrieve a nested array of forum posts that can then be used to create a discussion element, and its post subselements.

Just like the above convenience method the translator method should not produce HTML itself, instead it should create the necessary element and any required subelements before calling '''$this->render()''' on the subelement.

Its important to note the pupose of having these methods as renderer methods and not having them abstracted to another layer of your code.<br />
Because these methods exist within the renderer they can overridden by the theme in order to change the information that is used to construct the elements. This is also why translator methods should be given arguments that not just relate to what you immediately require for your idea of output, but also closely related things that may be required for others who wish to change the output.

===Step 5: Enhance your output with JavaScript===
If you've planned to add JavaScript to your project then now is the time to look at achieving this.

This section needs a lot more work, there is a tracker issue [https://tracker.moodle.org/browse/MDL-45854 MDL-45854 Define and document JavaScript output guide] which once complete should make writing this section easy.

Some notes for the time being:
* JavaScript should be initialised by the renderer within the render method.
* Simple element_actions can be attached to elements by calling ''$element->add_js_action()''.
* When attaching events to an element it should be done by ID.
* When delegating events to an element it should be done using a data attribute '''data-enhance="action"''' which requires the JS selector ''[data-enhance="action"]''
* If you need an ID on your element for JS call '''$element->require_id()''' which will generate an ID if one is not present (remember you are enhancing you can't assume one has or has not been set already)
* JS should follow our [[JavaScript guidelines]]

===Step 6: Write generator samples===
More to come here as the [[Element_Library]] evolves.

===Step 7: Style those samples in bootstrapbase and base===

Hopefully when designing your element you have already considered how it is going to look, and had taken into consideration what is available in at least bootstrap base.<br />
Because you have already written the element generator in the steps above you can easily refer to the element library when styling your element and testing.

Its recommended to start with bootstrapbase as this is the scaffolding theme that our default theme ''clean'' is build upon.
All CSS for your element within the bootstrapbase theme should be added to '''theme/bootstrapbase/less/output_elements.less''' and be written in hierarchical less so that it is clear which styles apply to your element.<br />
The CSS should be preceeded by a clear heading that identifies which element the styles belong to as well.

It is also necessary to style the element in the base theme.<br />
All CSS for your element within the base theme should be added to '''theme/base/style/element.css''' and like above should preceeded by a clear heading that identifies which element the styles belong to.

The actual Less/CSS should be styled according to our [[Element HTML and CSS guidelines]]

===Step 8: Write tests===

Both acceptance and unit tests may be applicable to your element depending upon what you've done, and just like all of new code arriving for Moodle tests are now an expectation.
You can not of course create tests to automatically check the display of your element, however the element library facilitates a user manually doing that.

'''PHPUnit tests'''
If your constructor contains any logic for smooth data into its properties then this should certainly be tested.<br />
Likewise if you've added any methods to aid the construction of your element they should be tested as well.

'''Acceptance tests'''
These are particularly applicable if your element facilitates any kind of interaction. If so then it is worthwhile creating a test scenario for this interaction.<br />
If the interaction triggers a visual response, like clicking a button and a dropdown appears then this can be easily tested within the element library.<br />
If a more complex interaction is taking place then you should consider writing a test that belongs to a code that makes use of your element.
For instance if your element is a search form and it is used within the forum consider writing an acceptance test for the forum testing your element if there is not already one there.

===Step 7: Use your element===
Congratulations! At this point you have written your element, you've written the required renderer methods and supporting generators and tests.<br />
You are now ready to use your element within your code.

==Peer-review checklist==
The following is a checklist guide of what to look for when reviewing an element and/or element render methods.
Items already on the peer-review checklist have being excluded.

'''The element class'''
[ ] The file is located in classes/output/elementname.php
[ ] Autoloading is used, the file has not being included anywhere.
[ ] The element is correctly namespaced to the Output API (namespace core\output OR mod_plugin\output).
[ ] The element name is accurate to its function and concise.
[ ] It is a unique element and not a duplicate of another element.
[ ] It extends either atom, molecule or organism
[ ] All data used during rendering is accessed through public properties.
[ ] All public properties of the class are data that can be used during rendering.
[ ] All optional public properties (not set within the constructor) default to null.
[ ] All/any methods the class has aid in its construction (importantly they don't return data)
'''Styles for a core element'''
[ ] The element has being styled in at least the bootstrapbase and base themes.
[ ] The styles in bootstrap base have being added to theme/bootstrapbase/less/output_elements.less
[ ] Bootstrapbase styles have been written in less format and are preceeded by a clear heading of the element they belong to.
'''Styles for a plugin element'''
[ ] The element has being styled in at least the bootstrapbase and base themes.
'''Renderer'''
[ ] Does the renderer conform to the [[Renderer best practices]]?
'''Renderer - render method (required)'''
[ ] A method has being written.
[ ] The method is protected.
[ ] The method takes a single argument, an element and and adequate typehint is in place.
[ ] The method contains no logic, no globals.
[ ] The method returns HTML.
'''Renderer - convenience method (optional)'''
[ ] The method is public.
[ ] All arguments are complete arguments (see above docs for details)
[ ] Contains no logic other than data smoothing if absolutely required.
[ ] Does not produce any HTML itself.
[ ] Call '''$this->render($element);''' and returns the output.
'''Renderer - translator method (optional)'''
[ ] The method is public.
[ ] Logic is minimal and the related to smoothing data from arguments into elements.
[ ] Produces a single element only/
[ ] Produces no HTML itself.
[ ] Call '''$this->render($element);''' and returns the output.

==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 elements (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]] - The original output specification for Moodle 2.8
* [[Output element planning]] - Thoughts on initial elements that should be created.
* [[Guide to creating output elements]]
* [[Renderer best practices]]
* [[Element HTML and CSS guidelines]]

Element HTML and CSS guidelines

2014-07-22T11:40:03Z

Samhemelryk: /* See also */

{{Infobox Project
|name = Renderer consistency
|state = Specification
|tracker = https://tracker.moodle.org/browse/MDL-45830
|discussion = https://moodle.org/mod/forum/discuss.php?d=261202
|assignee = Damyon, Sam
}}
{{Work in progress|forumurl=https://moodle.org/mod/forum/discuss.php?d=261202}}

This is a guide to writing HTML and CSS for elements within Moodle.
In the future this will likely become the HTML and CSS guide for output in Moodle as we want to move elements. However at present we don't want to enforce this for all output, just new conversions to elements.

==Why have a strict guide==

At the time of writing this CSS within Moodle (2.7) themes is in a poor state and has been for a long time. Without previously having a guide we were finding that:

* As there was no formal guide to creating id's or classes, each developer does there own thing.
* As there was no formal guide on how to write CSS there were numerous techniques used when writing CSS and no consistency.
* Majority of pages create uniuqe output and require unique CSS, there is very little re-use of design.

While those points may not sound bad to you consider that in following stats from Moodle 2.7 themes:

* Base theme contains 3802 rulesets with a total of 5800 styles.
* Bootstrapbase theme contains 5170 rulesets with a total of 9362 styles.
* Clean theme contains 5172 rulesets with a total of 9366 styles.
* More theme contains 5177 rulesets with a total of 9063 styles.

You get the picture, several thousand selectors containing nearly 10000 styles.

For Moodle 2.8 we commited to introducing a element library to aid the reuse of design and documenting all aspects of output including a guide on writing CSS for Moodle. This is that guide.

==Our goals==

Its very important to understand what we are trying to achieve with this style guide and output in general.

; Frontend framework agnostic : We want theme designers to be able to apply present and future frontend frameworks to Moodle with minimal effort.
; Consistent interfaces : We want Moodle to have consistency throughout its interfaces, minimising the amount of frontend design and development that is required in coding and styling an interface.
; Cleanly formatted HTML and CSS : to minimise both development time and to make our renderers and CSS and more maintainable.

We plan to faciliate these with the following:
; Elements : Highly re-usable objects to produce HTML, these will be used consistently and relied upon by developers creating interfaces. By having these elements we create a consistent look, interface creation will be much quicker and theme designers through the re-use of a limited number of elements.
; Element library : A tool to show samples of each element, this can be used to view and test designs. It aids the developer by showing them the elements they can select from when creating an interface, and it aids designers by giving them a test area that doesn't require them to dig through every page in Moodle.
; Documentation : We will now have proper documentation on all aspects of output. Including this CSS style guide, a renderer best practices guide, and a guide to creating elements.

==Where to put CSS in Moodle core==

CSS can reside in a number of locations depending upon what you are styling.

Remember it doesn't matter how many CSS files we end up with, on a production site with Theme designer mode switched off (default) all CSS files will be combined and minimised into a single file that is served to the client.
Excepting the case of IE where we must split the CSS into several smaller files to work around browser limitations.

===CSS for elements===
As we are moving to using elements you will find that CSS for elements is where most of the effort is going to go.

CSS for elements should reside within themes only, you will find that elements must be styled in all core base themes, this means at least Bootstrapbase and base.

CSS for elements should be located within either '''theme/themename/style/elements/elementname.css''' or '''theme/themename/less/elements/elementname.css'''

The actual CSS file should be named according to the element. As elements can be namespaced we need to ensure that that is reflected in the name of the file.
For instance:

{|
! Element
! CSS location in base
! CSS location in bootstrapbase
|-
| \core\output\button
| style/elements/core_output_button.css
| less/moodle/elements/core_output_button.css
|-
| \core\output\navigation_bar
| style/elements/core_output_navigation_bar.css
| less/moodle/elements/core_output_navigation_bar.css
|-
| \mod_assign\output\user_submission
| style/elements/mod_assign_output_user_submission.css
| less/moodle/elements/mod_assign_output_user_submission.css
|}

These will still need to be included in the theme, by which ever means is relevant.
If you are using ''.css'' files like the base theme does then you will use:

<code php>
// In your themes config.php
$THEME->sheets = array(
'elements/core_output_button',
'elements/core_output_navigation_bar',
'elements/mod_assign_output_user_submission'
);
</code>

If you are using less as bootstrapbase does then you will use:
<code css>
/** In your primary less file **/
@import "moodle/elements/core_output_button";
@import "moodle/elements/core_output_navigation_bar";
@import "moodle/elements/mod_assign_output_user_submission";
</code>

===General CSS===

This is CSS for the theme that doesn't relate to a specific element. Hopefully as we convert more and more of Moodles interfaces to use elements we should see less general CSS.

In any case nothing has changed in regards to the location of general CSS.
; CSS : If your theme is using standard CSS then it must be located within the ''style'' directory of your theme and should be in logically separated files.
; Less : If your theme is using less then it should be located in a ''less/moodle'' directory within your theme.

We recommend that you separate styles into files based upon the Moodle component being styled. Again as all CSS files get combined into a single file on production sites it doesn't matter how many files you end up with.

This would lead to files named like:
* style/core.css
* style/course.css
* style/mod_forum.css

===Where to put CSS in plugins===

It is possible in Moodle to add CSS stylesheets to all plugins (including core plugins).<br />
Moodle always looks for a ''styles.css'' file within your plugins directory, and it also looks for a styles_themename.css where themename is the name of the currect theme being used.

For instance the following could be added to the forum module:

* ''mod/forum/styles.css'': Used all the time.
* ''mod/forum/styles_base.css'' : Used when the user is using the base theme.
* ''mod/forum/styles_bootstrapbase.css'' : Used when the user is using the bootstrapbase theme.
* ''mod/forum/styles_clean.css'' : Used when the user is using the clean theme.

===CSS in core plugins===

For core plugins only styles.css is permitted and it should only ever contain styles essential to the presentation of the plugin.<br />
At present styles essential for the display of the plugin are allowed here, however when the plugin interfaces have been converted to use elements this file should be nearly empty and contain only the following:
* Images, icons and text used for visual presentation such as icons to notify state (expanded/collapsed, warnings...)
* Accessiblity orientated styles required to make the interface accessible.

'''Under no circumstances should it contain any visual stylings such as border, rounded corners, and background colours not associated with state.'''

==HTML==

The following sections detail rules in place for writing HTML.

Before we start a couple of general recommendations:

; Use hyphens rather than underscores when concatenating strings in attributes : for example ''.course-new-activity-chooser'' instead of ''.course_new_activity_chooser''. By all doing this we will have a more consistent appearance and as We use underscores as part of frankenstyle which is prominent in CSS helps us to reduce the chance of naming conflicts.
; Think semantics - but don't get caught up in it : Semantic CSS is beautiful CSS lending itself ultimately to the redesign that is going to happen. But enforcing a semantic design can be an arduous journey. Instead we encourage semantic CSS but are happy to see non-semantic CSS when it is for the greater good.

===Using the ID attribute===

The situation of having a single JavaScript driven element was considered but even then it is better to style only classes and other attributes as we can't be sure what the future holds.

There are three rules you should follow when creating an ID:

# They should only be given to elements and HTML nodes that need to be interacted with by JavaScript.
# It should always start with '''m-''' ''(see note below)''
# The actual ID should be descriptive of the node and contents as a whole unit. It must fully and concisely describe its purpose.

Keep in mind that in an ideal world ID's should not be used for styling.

'''Good'''
<code html5>
<div id="m-dock"> ... </div>

<div id="m-course-new-activity-chooser"> ... </div>
</code>

'''Bad'''
<code html5>

<div id="dock"> ... </div>


<div id="m-activity-selector"> ... </div>
</code>

'''Note:''' The requirement to use m- prefix is entirely new, this has been created as this instantly reduces the chances of conflicting with present and future frontend frameworks that may be adopted by core or third party themes. Aiding our goal of being frontend framework agnostic.<br />
It will also help reduce the chance of conflicts in any third party code that may be used either by us in core, or by outside developers in their own code.
Moodle ID's will also be much more easily recognisable which we expect will be a benefit as JavaScript use in Moodle continues to increase.

===Naming CSS classes===

This is where a bit of organisation goes a long way and we want to be reasonably thorough in a consistent naming scheme and implementation.

The very first thing to mention is that all classes in Moodle must now be prefixed by *m-*.
This instantly identifes a class as belonging to Moodle, it aids us in avoiding conflicts with any non-Moodle css that may be loaded, and it is part of our framework agnostic plan.

<blockquote>
All CSS classes must start with *m-*
</blockquote>

There are several prefix that are used within Moodle output now that should not be used as prefixs for classes unless they are serving the desired purpose.

Reserved prefixes are:

; m-element : Prefix used on element classes, where m-element preceeds the name of the element, e.g. m-element-button, m-element-search
; m-state : Prefix used for CSS classes representing the state of an item, e.g. m-state-disabled, m-state-active, m-state-expanded.
; m-grid : Prefix used for creating HTML grids.

====Elements====

Semantic design where it gives the best result, smart design where there is a better solution.

If you're not already familiar with the idea of semantic CSS then Chris Coylers artical [http://css-tricks.com/semantic-class-names/ What makes for a semantic class name] is a great starting point.

We've not commit to adopting any one strict approach for writing CSS. We have adopted atomic design for our HTML elements, a design style which fits nicely with the likes of OOCSS, however be very clear that we are not adopting the OOCSS approach in its entirety. The high level abstraction of the visual aspects of elements into highly reusable agnostic classes does not always lend itself well to the Moodle world in which the we wish to be frontend framework agnostic and support largescale completely customisable themes.<br />
The highly reusable classes that appeal to one designer, or to one frontend framework may not apply to another.<br />
This decision is also impacted by our current default theme bootstrapbase that does not use well abstracted OOCSS in its design.

Atomic design is going to see us end up with many parent child relationships in our HTML that we must carry through to our CSS. Through atomic design we start with smalled atoms and molecules that get built into larger organisms and placed within layouts.

Every element should have a single class that identifies it as element X.

For instance the button atom will have the class *m-element-button*

<code html5>
<button class="m-element-button">I am a button</button>
</code>

This is simply the prefix "m-element" plus the element name.

The purpose of this class is to allow the element to be styled with ease. The class name should be applied to the root node for the element, it should never be applied any lower.

By having one class for the element, and always and only applied to the root node it makes it very easy in HTML to see where one element belongs to another.

The following is an example of the search molecule, which in turn contains two button atoms.
<code html5>
<form class="m-element-confirmation">
<h3>Are you sure?</h3>
<p>Are you sure you want to perform this action?</p>
<input type="submit" name="cancel" class="m-element-button" value="Cancel" />
<input type="submit" name="continue" class="m-element-button" value="Continue" />
</form>
</code>

We've chosen to partially adopt BEM as a CSS standard when writing CSS for elements.
BEM isn't a new CSS standard, but its not widely known either. Its existence fills a gap in how to style elements consistently. Through two basic notation techniques you can easily notate the purpose of structures that belong to an element and notate the intent of an element that is desired if the element has multiple versions.

; Notating purpose : Here we use a suffix *__purpose*, the key being the two underscores.
; Notating intent : Here we use a suffix *--intent*, the key being the two hyphens.

You'll notice in the example above that there is no way to style the continue button differently from the cancel button without relying on its name, something we certainly don't want to do.
The solution is to wrap each button in a div and give each div a class.
The BEM standard comes into play here in naming the classes, the following shows how you would apply BEM to show the purpose of each button in a way that can be easily interpreted and styled in CSS.

<code html5>
<form class="m-element-confirmation">
<h3>Are you sure?</h3>
<p>Are you sure you want to perform this action?</p>
<div class="m-element-confirmation__cancel">
<input type="submit" name="cancel" class="m-element-button" value="Cancel" />
</div>
<div class="m-element-confirmation__continue">
<input type="submit" name="continue" class="m-element-button" value="Continue" />
</div>
</form>
</code>

You can now each button is wrapped in a div with a class, *m-element-confirmation__cancel* and *m-element-confirmation__continue*.
This class can be read by the themer and because of the __ can be easily identified as both belonging to the m-element-confirmation and serving a specific purpose, continue or cancel.

Now to explain the idea of intents.
An intent is when a single element takes on a different apprearance to convey a specific meaning. A little bit like a state, but with more meaning.
An easy example is notifications where you will no doubt be familiar with the idea of having a error notifications, warning notifications, success notification etc. Each of error, warning, and success is a intent.

The following shows how this would work:
<code html5>

<div class="m-element-notification">You have not changed your password in the past 60 days</div>


<div class="m-element-notification m-element-notification--warning">You have not changed your password in the past 60 days</div>
</div>
</code>

====Grids====

We need to adopt a single grid framework.

Personally I don't think we should use pure bootstrap or pure YUI, instead we should choose one of these and build it use our class name structures.

All grid classes should start with m-grid.

==CSS==

Before we begin lets lay down some ground level goals, things that will help us achieve clear and understandable CSS in the future.
* Formatting, ordering, alignment, and spacing are all important in having CSS that can be easily read by others.
* Don't optimise your CSS, be verbose and stick to the styles in this guide. We have tools that will handle optimisation for you.
* Never use *!important* in your CSS unless it is absolutely impossible to avoid doing so.

===Terminology===

Its important that when we are speaking about CSS we are speaking the same language.
Lets look at the following example:

<code css>
.m-page .m-selector-1,
.m-page .m-selector-2,
.m-page .m-selector-3 {
background-color: #FFF;
color: #000;
}

.m-selector-1 {
margin: 1em;
}
</code>

; Ruleset : Each of the two rules is a single *ruleset*.
; Rule: _.m-page .m-selector-1_ is a rule.
; Selector : _.m-selector-1_ is a *selector*, it is a single part of a rule.
; Declaration : _background-color: #FFF_ is a declaration.
;

===Essential formatting===

The following are the guies for writing CSS.

* Always use spaces - never use tabs. All editors can be configured to do it.
* Indent by 4 spaces - never more, never less.
* A single empty line between rulesets to maintain consistent spacing of rules.
* One rule per line.
* A single space between each selector in a rule.
* No space between a rule and the comma in a ruleset.
* A single space between a selector and the opening brace of a ruleset.
* One level of indentation before each declaration.
* A single space the colon in a declaration.
* A single space after each item in a declaration containing multiple items.

The following shows how the above rules apply:
<code css>
.m-selector-1,
.m-selector-2 .m-selector-3 {
background: #ffa800 url("background.png") no-repeat right top;
border: 1px solid #000;
display: inline-block;
font-family: arial, sans-serif;
margin: 5px 10px;
padding: 0;
}

.m-selector-4 {
border-radius: 3px;
}
</code>

===General rules===

Declaration ordering is the very first thing to discuss. There is no strict rule on how to order your declarations, however there is a recommendation.
We recommend that you order declarations within a ruleset alphabetically.
If we all start doing this then when you read CSS written by someone else you will soon learn to very quickly find your way around the declarations within a rule.
<code css>
/** Recommended **/
.m-selector {
background-color: #fff;
border: 1px solid #000;
color: #000;
display: block;
margin: 5px;
padding: 5px;
}
</code>

Do not use a measurement unit when writing a 0 value.
<code css>
/** Good **/
.m-selector {
margin: 5px 0;
}

/** Bad **/
.m-selector {
margin: 5px 0px;
}
</code>

Use lowercase and shorthand values for colours.
<code css>
/** Good **/
.m-selector {
background-color: #fff;
}

/** Bad **/
.m-selector {
background-color: #ffffff;
}
.m-selector {
background-color: #FFFFFF;
}
.m-selector {
background-color: white;
}
</code>

Always quote variable values.
<code css>
/** Good **/
.m-selector[attr="variable"] {
background-image: url("image.png");
}

/** Bad **/
.m-selector[attr=variable] {
background-image: url(image.png);
}
</code>

===Commenting===

Always comment your CSS and Less.

<code css>
/**
* Styles for the button atom.
*/
.m-element-button {
}
</code>

===Rules and exceptions for less===

Need to write some guff on Less.

==See also==
* [[Render library specification]] - The original output specification for Moodle 2.8
* [[Output element planning]] - Thoughts on initial elements that should be created.
* [[Guide to creating output elements]]
* [[Renderer best practices]]
* [[Element HTML and CSS guidelines]]

Renderer best practices

2014-07-22T11:39:56Z

Samhemelryk: /* See also */

{{Infobox Project
|name = Renderer consistency
|state = Specification
|tracker = https://tracker.moodle.org/browse/MDL-45853
|discussion = https://moodle.org/mod/forum/discuss.php?d=261202
|assignee = Damyon, Sam
}}
{{Work in progress|forumurl=https://moodle.org/mod/forum/discuss.php?d=261202}}

This page documents renderer best practices.

==Notes==

* Must mention atomic design and how the concept of "templates" should be applied. Relates to the next note. A forth method type for renderers?
* Within a component or plugin that has a renderer use the renderer for EVERYTHING within that area. [https://moodle.org/mod/forum/discuss.php?d=262817#p1138926 forum post that ignited this]
* Reference and probably copy the three render methods from [Guide to creating output elements]

==Renderer best practices==

This document discusses the recommended practises to follow when writing renderers for Moodle. It was created in Moodle 2.8 as part of the element library specification that took place.

Renderers provide an abstraction of logic and display. They serve Moodle to both encourage us to properly structure our code and to provide a means by which themes can take control of output to completely customise the look of Moodle.
Elements and the element library provide us a set of building blocks to use when creating output. These provide us a consistent and manageable look that also minimising the amount of customisation required by a theme to change the look and feel of Moodle.
Here we make a recommendation on how to write renderers to maximise the benefits to both yourself as a developer and to designers who have to customise the interfaces you create.

==Goals==

Its important to understand the goals for output before you start looking at renderers as they are just one part of the output plan.

'''Output in Moodle is designed to:'''
* Aid developers in properly abstracting output from logic.
* Allow designers to take complete control of output from within a theme if they wish.
* Provide a consisten look and feel for Moodle user.
* Allow developers to more rapidly create interfaces by having a set of elements at their finger tips.
* Minimise the efforts designers must extrude in order to customise the look and feel of Moodle by limiting the output to a set of elements.
* Aid designers by providing tools to support styling Moodle such as the element library.

'''Renderers in Moodle:'''
* Are the link between Moodle and a theme through which all output is generated.
* Are organised for the benefit of designers, and should be written following this document.
* Most importantly allow designers to override the HTML that wraps the data being displayed in turn allowing designers to re-design output in a theme.
* Allow designers to change the information being displayed by providing not just what is initially required but that which that may require.

==A simple set of rules for a good renderer==

Summarising what will be discussed further in this document a good renderer can be summarised as:

* Think in elements. We have an element library, when planning the output for your plugin/component start with the elements in the element library and the markup they provide.
* Containing only methods confroming to the four method types discussed below.
* Encapsulated data is given, maximising the information available to the renderer and minimising the number of arguments.
* Free of logic relating to anything except output. This includes not calculating the likes of links and capabilities.
* Uses helper methods to manipulate data where manipulate is absolutely required, essentially abstracting logic to conform to the above rule.
* Utilise the core elements as much as is possible.
* Recognise unique output needs and create element(s) for it.
* The render method should be used as often as possible to maximise consistent look.

==The don'ts==

The following are things that should not be done within a renderer.

'''DO NOT:'''
* design interfaces from scratch when desiging output for your plugin/component. Always start with the elements found in the element library.
* Use logic that isn't essential to producing output. This includes but is not limited to the following:
** Database interaction of any kind.
** Access or capability checks.
** Generation of data such as producing URL's, that should be owned by the plugin/component and made available preferably through the given arguments or failing that through a helper method.
* Generate HTML for something that should be an element, convert it to an element and call render on it.
* Create custom elements for everything you plan to output, instead try to maximise the core elements that you use.
* Write your own render methods for subelements of the elements you create. Only do this if you absolutely must change the markup from that produced by the natural render method for the element.

==Creating a renderer==

===Location and naming===
As of Moodle 2.8 renderers can be put into the output namespace. This is the recommended placement for Renderers in Moodle 2.8 and up, however the alternatives will also be listed here.

Recommended:
* Put your renderer in '''mod/yourplugin/output/renderer.php''' use the namespace '''mod_yourplugin\output''' and call your class '''renderer'''.
* To get an instance of your renderer ''$PAGE->get_renderer('mod_yourplugin')'''

This is how mod/yourplugin/output/renderer.php will look:
<code php>
<?php

namespace mod_yourplugin\output;

class renderer extends \plugin_renderer_base {
// Your renderer methods in here.
}
</code>

Also available but not recommended:
* Put your renderer in '''mod/yourplugin/renderer.php''' do NOT namespace it, and call your class '''mod_yourplugin_renderer'''.
* To get an instance of your renderer ''$PAGE->get_renderer('mod_yourplugin')'''

This was how things were done in earlier versions of Moodle (2.7 and below).

===Render methods===

Renderers can be well structured, the purpose of them is the same across all plugins and components.
There are four distinct types of render methods that you can expect to find in a renderer, and these four can be categorised into one of two categories.

The four types of render methods:
# Layout methods
# Translator methods
# Render methods
# Convenience methods

These four methods can then be categorised in two ways:
; Plugin|Component method : The layout and translator methods are plugin or component methods. They take data for a plugin or component and meld it into renderables. These methods relate to and can be said to be owned by the plugin or component.
; Element methods : The render and convenience methods relate only to elements. They take already encapsulated abstracted data and simply output HTML structure around it. They pay no regard to the plugin or component and are completely and solely bound to the output of an element.

====Layout methods====

====Translator methods====

====Render methods====
If you've spent any time working with renderers in the past you will already be familiar with the concept of a render method.
All elements within Moodle inherit the renderable interface. To produce output for them you call the renderers render method and give the element.
The render method looks at what is given and looks

====Convenience methods====
These are very simple. A convenience method is simply an easy way to build and output an element in a single step.
If you take an element, likely an atom or molecule, a convenience method would have the same arguments as the constructor for the element, build an instance of the element and call render on it.
The following is a simple example using heading:

<code php>
/**
* A convenience method to render a heading.
*/
public function heading($content, $level = 2) {
$heading = new \core\output\heading($content, $level);
return $this->render($heading);
}
</code>

==Creating output elements==
This is a big field and as such a dedicated document has been writen as a [[Guide to creating output elements]].

==Tips on properly structuring your plugin==
Talk here about OO structuring of code, ensuring a traversable heirarchy that enables maximum movement of code structure to obtain data and in turn minimises necessary arguments for layout methods.

==See also==
* [[Render library specification]] - The original output specification for Moodle 2.8
* [[Output element planning]] - Thoughts on initial elements that should be created.
* [[Guide to creating output elements]]
* [[Renderer best practices]]
* [[Element HTML and CSS guidelines]]

Guide to creating output elements

2014-07-22T11:39:41Z

Samhemelryk: /* See also */

{{Infobox Project
|name = Renderer consistency
|state = Specification
|tracker = https://tracker.moodle.org/browse/MDL-45885
|discussion = https://moodle.org/mod/forum/discuss.php?d=261202
|assignee = Damyon, Sam
}}
{{Work in progress|forumurl=https://moodle.org/mod/forum/discuss.php?d=261202}}
A guide to writing output elements and the render methods for them.

==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, when we talk about elements we talk about one of or more of atoms, molecules, and organisms.
* '''Subelement ''' When we speak of subelements we are talking about the smaller elements that are going to be of a larger element. e.g the molecules that are present in an organism.
* '''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 elements 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 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 elements and the organisation of those elements 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 an element looks in one or more scenarios, the scenarios usually revolving around varying contents.

==Designing and writing an element==

A step by step approach to working through the creation and rendering of an element so that it meets the Output standards for Moodle.<br />
If you want a quick overview of what to do have a look at the [[#Peer-review checklist|peer-review checklist]] in the next section

===Step 1: Are you sure you need to create an element===
We want Moodle to contain a limited number of elements. The problem that existed before this work was that every bit of code was creating its own output, and we do not want to end up back there.

The very first thing to do is to be absolutely sure that you need to create this element.

'''Atoms and molecules'''
After the initial release this should be rare. It should be especially rare that you need to write an atom or molecule for a plugin.<br />
Moodle should provide 95% of the atoms and molecules you could ever need. However if you have something that is truly new and unique in some way then perhaps indeed you do need to write an element.

'''Organisms'''
Writing an organism is going to be a common requirement. Within core there may be a finite number of organisms, only increasing as new Moodle elements are created and new interfaces added. However when creating plugins or updating output in existing plugins it is very likely that new organisms will be created. If you have an interface in a plugin that is somehow unique to that plugin then you have a organism.

In both cases it is important that you search through the elements already in Moodle and see if there are any that meet your needs.<br />
If there is something close in Moodle core already then perhaps you need to adjust your design to make use of the existing element rather than introducing something similar but slightly different.<br />
If you find an element you could use in a core plugin then you should create an issue in our Tracker and request that the element be moved from the plugin to core.<br />
Then for the time being copy the element from the plugin you found it in, into your plugin. This way it will look consistent, you can use it and if it does get accepted into core you don't have to change anything about how you use it.

===Step 2: Define the element===

It very important to be sure of what you want to create.

The first thing to do is to work out what is it going to be, is it an atom, a molecule, or an organism?<br />
Remember the following, they describe each of those in a single sentence:
; Atom : A basic building block that severs no purpose or interaction.
; Molecule : Serves just a single purpose OR interaction, not usually a part of an interface by itself, grouped with other molecules and atoms to form an organism.
; Organism : A part of the interface, it is constructed of molecules and atoms, it can facilitate several like purposes and interactions

It should be possible to create a flow chart to aid this decisions, unfortunately one has not being created yet.

Once you've decided what type of element it is going to be you are ready to start designing what other elements (if any) will make it up.

Now is a good time to be very clear about the purpose of your element, as well as any interactions that you want it facilitate.
Consider writing down a clear and concise description of your element and sharing what you are planning in the forums, with colleagues or just generally with other developers.
This output approach is still fresh and we are all still learning how it works in detail so the more exposure you can get now the easier it will be down the track.

When thinking about your element try to think about it is a blueprint to what you want to display. When displaying an actual something it is populated by data and that data is then used by a render method of a renderer to produce HTML.
Think about where that data is coming from, think about the renderer best practices, think about the style guide, and think about what others may and will do when overriding a renderer to override your render method.

There are two additional important concepts to consider at this point as well, attributes and properties. Important enough to have their own heading so as to be easily found.

====Attributes====
These are HTML attributes. It may be very very tempting to set attributes like classes and ID's within an element. But please do not.<br />
Attributes should only be added to an element by the renderer. They may be added by any one of the three types of render methods you'll read about later.

The reason for this is that we want the renderer to be solely responsible for translating an element to HTML. An instance of an element is simply a catalyst for the data contained within.

Within a renderer attributes can be interacted with as follows:
<code php>
// A publicly accessable array of attributes. Key => Value.
$element->attributes;

// Set an attribute on the element.
$element->set_attribute($key, $value);

// Set an array of attributes on the element;
$element->set_attributes(array(key1 => value, key2 => value));

// Addes a CSS class to the attributes
$element->add_class('some-class');

// Returns the attributes as a string suitable for use in HTML output.
$element->get_attributes();
</code>

====Properties====
Talking about properties here I am not talking about class properties of the element that are used to contain data.<br />
I am talking about the properties that describe the instance of the element. To get your head around this consider a menu that has several items within it. There are three common properties added by default to all elements that are applicable here:

; active : A boolean property, set this to true if this item points to the current page. The active item.
; enabled : A boolean property again, set to true this says that the item is enabled and the user can perform the associated action. Set to false is like saying the user cannot interact with this menu item.
; dimmed : A Moodle-esq property. Set to true if the item is visible to the current user but not to every other user. Think of it like viewing a hidden course because you have the capability to.

Properties can be added, and set by either a parent element, or a renderer if need be. They are used to convey properties that are applicable only in certain situations.<br />
The ability for an element to add properties to its subelements allows us more re-use of elements within renderers so that we don't need dedicated objects in situations where it is simply a property or two that differs from an available element.

Properties can be interacted with the following methods and properties:

<code php>
// Publicly accessable array of properties. Key => Value.
$element->properties;

// Add a property to this element.
$element->add_property(name, value);

// Add an array of properties to this element.
$element->add_properties(array(n1 => value, n2 => value));

// Sets the value of a property.
$element->set(name, value);

// Gets the value of a property.
$element->get(name);

// Returns true is a property is set and is not empty.
$element->is(name);
</code>

===Step 3: Create the element class===

Creating an element is really quite simple, the following headings explain what you need to know.
Remember if in doubt there are a lot of examples that can be easily found in Moodle core (within lib/output).

====Element location====
All elements belong to the Output API and should be namespaced within it for autoloading and consistency with Moodle core elements.
This makes locating elements very easy, core elements will be located within an output subdirectory of the classes directory as shown below:

: lib/classes/output/'''myelement.php'''

Plugin elements will be located in a similar fashion within an output subdirectory of the classes directory. e.g.

: mod/''myplugin''/classes/'''myelement.php'''

====Class name and inheritance====
Classes are namespaced for the output API and located in the file above. Because classes are namespaced the actual class name is simply the element name. The same name as was used for the file.
They must however extend the appropriate element type, if you are creating a molecule it must extend ''\core\output\molecule'', if its an organism it must extend ''\core\output\organism''.
For following is an example of how this would look for a core element:

<code php>
<?php
namespace core\output;
defined('MOODLE_INTERNAL') || die();

class myelement extends organism {
</code>

And for an element you are creating within a module plugin:

<code php>
<?php
namespace mod_myplugin\output;
defined('MOODLE_INTERNAL') || die();

class myelement extends \core\output\organism {
</code>

====Class properties====

We like to keep elements simple to interact with. For that reason we encourage people to store data and subelements that will be used during rendering as public class properties.
This is done so that data is accessed in a consistent fashion when interacting with an element. For this reason we would rather '''not''' see developers adding methods to an element unless truly required.

Subelements are a good example. If you were writing a navigation bar organism for example you may have a title molecule, a menu molecule, and a search molecule. The title, menu and search molecules are the elements.<br />
These will become public class properties of your element.

====Class methods====

Elements should only have methods to support their own construction. As expressed above all information useful to a renderer should be stored in publicly accessible properties, none of it should have to be accessed via method calls.
This is done so that interaction with elements is consistent across all elements. Methods to aid the construction of the element are encouraged so that information can be easily added to the element.

====Your constructor====
The constructor for your element should allow the developer to pass in the required data and subelements.
Consider when writing the constructor how developers will pass information into the element. In many cases there are going to be two types of data that will commonly be passed in:
# Elements (or arrays of) that make up parts of your element.
# Scalars (or arrays of) e.g. strings, integers, floats and booleans.

Make the data that is absolutely required part of the constructor and simply have publicly accessible properties for the optional data that can be set by calling code if required.

Its also worth considering if you are creating a molecule that perhaps data handling for the atoms that make it up may be worth including in your constructor.<br />
For instance a dropdown consists of a trigger element (button, link, image) and a menu, the menu is a molecule that consists of items. The constructor of the dropdown could aid construction by accepting two arguments, the first a way to pass in a trigger, and the second either an already build menu element OR an array of items that get used to construct a menu element within the dropdown constructor.

Some points to remember:
* Don't forget all properties should default to null if they do not have data set.
* If you have a collection of something as a property consider adding add_xxx() and add_xxxs() methods to aid the construction of elements.

===Step 4: Write the render methods===

There are 3 categories of render methods that will exist within every renderer and depending upon the type of your element you will be creating one or more of these methods for it.

Why the three types of render method? There are two key reasons to take the above apporach.

'''Re-use'''<br />
By ensuring we call the render method to produce elements and subelements when ever possible we will hopefully be making it easier to style Moodle as it won't be necessary to style absolutely everything individually. Instead if render has being used consistently to produce a button for example styling the HTML produced by ''render_button()'' should style all buttons throughout Moodle.

'''Make overriding renderers in themes more controlable'''<br />
The three types of render methods are designed to separate the logic and display that is permissable in renderers.<br />
Render method should contain as little logic and PHP as possible, however in many situations a bit of PHP and perhaps a bit of logic is going to be required in order to take data from one form and make it ready to present.<br />
If overriding a renderer within a theme the theme developer can look at what they want to achieve and choose the suitable method to override.<br />
If they are looking to change the markup for an element then they can override the render method, they will not need to know anything about how the element was constructed or what information went into it. They can focus on the data the element has and produce the HTML they desire.<br />
If they choose to change data, or want to display something different to what is there by default then they can override the translator method and continue to hack away to their hearts content.

Hopefully as you read about the render methods below the advantages to this approach will become clear.

====Render method====

This is the easiest to understand and no matter what type of element you have created you will need to write a render method.
The render method takes an element and returns HTML to display it.

The render method takes a strict format:
<code php>
/**
* Produce HTML to display myelement.
*
* @param \core\output\myelement $myelement The element to display.
* @return string An HTML version of the element.
*/
protected function render_myelement(\core\output\myelement $myelement) {
// Generate HTML for the element.
return $html;
}
</code>

The following are rules to follow when creating a render method.

* It display the element, nothing else.
* It is a protected method.
* The name of the method is always "render_" followed by the '''non-namespaced''' name of your element.
* There is only ever '''one''' argument, the element to render and it should be typehinted.
* It will contain no logic.
* It uses the public properties of the element for data.
* It supplments this by using the available methods '''ONLY IF ABSOLUTELY REQUIRED'''
* It returns a string, the HTML to display the element.

This method is very simple to understand, and providing you have properly researched and proposed your element it should be even easier to write.

If you are writing a render method for molecule or organism then you likely will have subelements that have being used within your element.
Where possible you should call '''$this->render()''' on the subelements to produce HTML for them that can then be included in the HTML that you are producing for your element.
Only if you absolutely must should you handle the generation of HTML for subelements directly within the render method for your element.<br />
If you do produce the HTML for a subelement without calling render than '''you must''' manually call the subelements ''prerender'' method to ensure that it has an opertunity to complete and requisits it has before rendering.

This is done to ensure that where possible we re-use the HTML for an element. By doing it we reduce the number of elements that a theme must style if all it is doing is styling.<br />
If a theme overrides a render method it is not obligated to take this same approach. Theme overridden renderers can do as they please, any duplication of structure they introduce is their own business.

====Convenience method====

The name for this type of method provide a big hint as to what it is, it is a method to conveniently construct and render an instance of your element.
This method also takes a very simple, predicatable form.

<code php>
/**
* Create and render a new myelement.
*
* @param mixed $arg1
* @param mixed $arg2
* @param mixed $arg3
* @return string HTML for myelement.
*/
public function myelement($arg1, $arg2, $arg3 = null) {
$obj = new \core\output\myelement($arg1, $arg2, $arg3);
return $this->render($obj);
}
</code>

This type of method always does three things:
# It takes the arguments necessary to create a new instance of myelement.
# It creates a new instance of myelement given the arguments it is given and sets it up as required.
# It calls '''$this->render()''' and gives it the object, returning the outcome.

There are a few things to observe when writing a convenience method:
# It is always public.
# Its arguments should be complete.
#* Meaning that they should be arguments that can be immediately to the element
#* OR can be checked in conditions to alter the element.
#* They should not be objects to support the generation of data. The data should be complete.
# It should '''not''' produce any HTML itself, the render method is responsible for this.
# It returns a string, the HTML to display for the given element.

In the case of molecules and organisms it is permissable for the convencience method to take actual subelements OR the arguments required to create necessary subelements. This is at the discretion of the developer and may be determinent on the number of arguments required to construct the element.<br />
Complex elements that require a lot of data to set up are probably not ideal candidates to create convenience methods for.

====Translator method====

These methods take complex arguments such as data and objects from outside of the Output scope and manipulate/smooth the data into a complex organism or molecule.<br />
They should be used to pass in the information the current element requires as well as any information that may be used by an overriding renderer to access additional data that may be desired.

These are likely to be rare for core elements, however just about essential for elements being introduced by plugins for example where having retrieving data from plugin objects for use in an element or subelements is going to be required.<br />
If for example you consider how your would render a forum discussion the translator method would likely take a forum discussion object and use a method of it to retrieve a nested array of forum posts that can then be used to create a discussion element, and its post subselements.

Just like the above convenience method the translator method should not produce HTML itself, instead it should create the necessary element and any required subelements before calling '''$this->render()''' on the subelement.

Its important to note the pupose of having these methods as renderer methods and not having them abstracted to another layer of your code.<br />
Because these methods exist within the renderer they can overridden by the theme in order to change the information that is used to construct the elements. This is also why translator methods should be given arguments that not just relate to what you immediately require for your idea of output, but also closely related things that may be required for others who wish to change the output.

===Step 5: Enhance your output with JavaScript===
If you've planned to add JavaScript to your project then now is the time to look at achieving this.

This section needs a lot more work, there is a tracker issue [https://tracker.moodle.org/browse/MDL-45854 MDL-45854 Define and document JavaScript output guide] which once complete should make writing this section easy.

Some notes for the time being:
* JavaScript should be initialised by the renderer within the render method.
* Simple element_actions can be attached to elements by calling ''$element->add_js_action()''.
* When attaching events to an element it should be done by ID.
* When delegating events to an element it should be done using a data attribute '''data-enhance="action"''' which requires the JS selector ''[data-enhance="action"]''
* If you need an ID on your element for JS call '''$element->require_id()''' which will generate an ID if one is not present (remember you are enhancing you can't assume one has or has not been set already)
* JS should follow our [[JavaScript guidelines]]

===Step 6: Write generator samples===
More to come here as the [[Element_Library]] evolves.

===Step 7: Style those samples in bootstrapbase and base===

Hopefully when designing your element you have already considered how it is going to look, and had taken into consideration what is available in at least bootstrap base.<br />
Because you have already written the element generator in the steps above you can easily refer to the element library when styling your element and testing.

Its recommended to start with bootstrapbase as this is the scaffolding theme that our default theme ''clean'' is build upon.
All CSS for your element within the bootstrapbase theme should be added to '''theme/bootstrapbase/less/output_elements.less''' and be written in hierarchical less so that it is clear which styles apply to your element.<br />
The CSS should be preceeded by a clear heading that identifies which element the styles belong to as well.

It is also necessary to style the element in the base theme.<br />
All CSS for your element within the base theme should be added to '''theme/base/style/element.css''' and like above should preceeded by a clear heading that identifies which element the styles belong to.

The actual Less/CSS should be styled according to our [[User:Sam Hemelryk/CSS style guidelines|CSS style guidelines]]

===Step 8: Write tests===

Both acceptance and unit tests may be applicable to your element depending upon what you've done, and just like all of new code arriving for Moodle tests are now an expectation.
You can not of course create tests to automatically check the display of your element, however the element library facilitates a user manually doing that.

'''PHPUnit tests'''
If your constructor contains any logic for smooth data into its properties then this should certainly be tested.<br />
Likewise if you've added any methods to aid the construction of your element they should be tested as well.

'''Acceptance tests'''
These are particularly applicable if your element facilitates any kind of interaction. If so then it is worthwhile creating a test scenario for this interaction.<br />
If the interaction triggers a visual response, like clicking a button and a dropdown appears then this can be easily tested within the element library.<br />
If a more complex interaction is taking place then you should consider writing a test that belongs to a code that makes use of your element.
For instance if your element is a search form and it is used within the forum consider writing an acceptance test for the forum testing your element if there is not already one there.

===Step 7: Use your element===
Congratulations! At this point you have written your element, you've written the required renderer methods and supporting generators and tests.<br />
You are now ready to use your element within your code.

==Peer-review checklist==
The following is a checklist guide of what to look for when reviewing an element and/or element render methods.
Items already on the peer-review checklist have being excluded.

'''The element class'''
[ ] The file is located in classes/output/elementname.php
[ ] Autoloading is used, the file has not being included anywhere.
[ ] The element is correctly namespaced to the Output API (namespace core\output OR mod_plugin\output).
[ ] The element name is accurate to its function and concise.
[ ] It is a unique element and not a duplicate of another element.
[ ] It extends either atom, molecule or organism
[ ] All data used during rendering is accessed through public properties.
[ ] All public properties of the class are data that can be used during rendering.
[ ] All optional public properties (not set within the constructor) default to null.
[ ] All/any methods the class has aid in its construction (importantly they don't return data)
'''Styles for a core element'''
[ ] The element has being styled in at least the bootstrapbase and base themes.
[ ] The styles in bootstrap base have being added to theme/bootstrapbase/less/output_elements.less
[ ] Bootstrapbase styles have been written in less format and are preceeded by a clear heading of the element they belong to.
'''Styles for a plugin element'''
[ ] The element has being styled in at least the bootstrapbase and base themes.
'''Renderer'''
[ ] Does the renderer conform to the [[User:Sam Hemelryk/Renderer best practices|Renderer best practices]]?
'''Renderer - render method (required)'''
[ ] A method has being written.
[ ] The method is protected.
[ ] The method takes a single argument, an element and and adequate typehint is in place.
[ ] The method contains no logic, no globals.
[ ] The method returns HTML.
'''Renderer - convenience method (optional)'''
[ ] The method is public.
[ ] All arguments are complete arguments (see above docs for details)
[ ] Contains no logic other than data smoothing if absolutely required.
[ ] Does not produce any HTML itself.
[ ] Call '''$this->render($element);''' and returns the output.
'''Renderer - translator method (optional)'''
[ ] The method is public.
[ ] Logic is minimal and the related to smoothing data from arguments into elements.
[ ] Produces a single element only/
[ ] Produces no HTML itself.
[ ] Call '''$this->render($element);''' and returns the output.

==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 elements (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]] - The original output specification for Moodle 2.8
* [[Output element planning]] - Thoughts on initial elements that should be created.
* [[Guide to creating output elements]]
* [[Renderer best practices]]
* [[Element HTML and CSS guidelines]]

Render library specification

2014-07-22T11:39:30Z

Samhemelryk: /* Documents created as part of this spec */

{{Infobox Project
|name = Renderer consistency
|state = Specification
|tracker = https://tracker.moodle.org/browse/MDL-45770
|discussion = https://moodle.org/mod/forum/discuss.php?d=261202
|assignee = Damyon, Sam
}}
{{Work in progress|forumurl=https://moodle.org/mod/forum/discuss.php?d=261202}}
== Project Goals ==
* 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.

== Benefits ==
* Make it easier to create user interfaces.
* Make it easier to style the user interface.
* Make it easier for themers to customise the user interface.
* Better facilitate frontend frameworks in Themes.
* Better facilitate usable and accessible design.
* Give Moodle a more consistent look and feel.
* Improve site performance by reducing the CSS footprint.

==Understanding renderers in Moodle==

Renderers have been around since Moodle 2.0 and are now the requirement when writing any code that produces output.
Renderers come in many shapes and forms depending upon the developers take on how output should be produced.

When renderables were introduced - the API was designed to make it easy for existing code to be updated to make use of renderers and renderables. A renderable is an interface with no methods, so any existing class could be made to implement renderable. This means that the renderable class can be a mixture of data and methods that perform logic associated with the module. This also means that the renderer can call those methods on the renderable class - effectively using the API of the module. The problem with this - is that it complicates the renderer and makes it harder to override in a theme - the themer requires knowledge about the API for the module. Some renderables in core are built as separate classes - only used for the purpose of supplying data to the renderer - here there is a clear separation of the logic - and the properties of the renderable are made up of only simple types that can be checked for in the renderer - e.g. access checks are done in advance and the result is put into a boolean in the renderable. The current renderers / renderables in Moodle are a mixture of these styles.

Because there is no mandated organisation, nor has there ever been, there is immense variation in what constitutes content to a renderer.

One of the upsides to our current render system is that you are not limited to having a single renderer for a component, you can make use of language capabilities and the output framework and create layers of renderers to cut back code duplication and to aid in preparing a base for consistent structuring and output.

Into the equation we add targets and subtypes. Targets allow us to create both standard renderers and renderers specific to the needs of the output method. Standard being HTML, without output methods including CLI, AJAX, HTML email and plain text email.

People have never being constrained as to how they implement a renderer. We've being happy enough to simply guide them towards using renderers because of the benefits they provide and while there are numerous benefits there are two fundamental benefits:

; A change in thinking : It requires developers to think about their code organisation. Renderers were introduced in a time before Object Orientation was used in Moodle, and logic and output were tightly intermingled in most code. Renderers were about separating logic and design and while what was created was not always perfect it was always an improvement.

; An extensible approach to output : The render system allows for the overriding of renderers to occur. Theme designers can overwrite any renderer in their theme. The more that renderers that get implement the more of Moodle you can customise.

==Understanding themes==

Themes are without a doubt the most widely customised plugin provided by Moodle. But we are currently struggling with several problems with renderers and themes as they are being implemented currently.

1. There is no strict relationship between the HTML generated by a renderable, and the accompanying CSS that is required to make it display properly. The HTML is coded in the renderer - and then the CSS is added, either directly to the styles.css for the plugin in an unorganised way - or directly in the CSS in the theme - again in a loosely organised way. There is no systematic way to determine if any line of CSS is still in use - and there is no simple way to find the CSS that requires updating when the HTML is updated.

2. The CSS framework (bootstrap 2, bootstrap 3, zurb, pureio) specific attributes for renderables are currently being hardcoded in the HTML generated by the renderables. This prevents themers from using a different framework without creating an impossible amount of work to overwrite every renderer in Moodle.

==So what is the problem==

There are several. Lets be blunt about this. This specification is not a single task. It is about improving the state of output in Moodle and there are going to be several steps in achieving this. On a positive note these steps can in many cases be broken down into granular tasks that can be worked on asynchronously.
First lets understand some of the major problems:
* We have no established best practices, nor even documentation on what constitutes a good renderer, or considerations that should be paid mind in planning and designing of code.
* We have no established style guide, nor pattern library, nor element library, nor anything that could be referenced when someone starts building a new user interface - or creating a new theme.
* Inconsistency - because of a lack of best practice documentation and examples, there is huge variation in the design of our different modules. Different modules exhibit different problems such as a mixing of logic and output and code duplication.
* Developers are encouraged to push functionality boundaries in order to take it places observed in other projects or to challenge oneself. While consistency is often talked about it is rarely observed when designing output. We end up with numerous "similar" looking widgets all functioning slightly differently and consequently there is a feeling that this is the way to achieve a new fresh look. (E.g. we have multiple implementations of a "toolbar" - one in Atto and one in EditPDF).
* Existing renderer implementations vary widely and in many cases contain logic they should not. Access checks, database queries, object manipulations. All of which should not be present as it introduces muddling of concepts and logic that must be duplicated and then maintained for anyone overriding renderers.
* Themers have a mammoth task at present in applying a consistent style to Moodle, or in choosing to implement a new frontend framework (bootstrap, foundation, pureio etc). Our lack of organisation in the output leaves a lot to be desired. Having the theme responsible for choosing a frontend framework is the right way to handle this, however backend Moodle doesn't support themeing as well as it should be/could be.
* On top of the above it introduces a need to override several renderers should you want to create a consistent style and because of inconsistent renderer implementations this can easily lead to a maintenance nightmare. E.g. the user_picture renderable is not used in mod_forum - so there is no way to override it there.
* JavaScript introduces problems of its own. We are doing more and more with JavaScript these days. However there is a heavy dependence on the output that gets produced and the JavaScript enhancing it. In a lot of cases the relationship is ill defined and due to the complexity and structure of the JavaScript overriding the output structure of the rendered component is completely impossible for all but the most experienced developers.
* Inline with the above we lack good examples and documentation on how to deliver output templates for JavaScript User Interfaces as well as the creation, and manipulation of HTML structures that are enhanced by JavaScript.

== Identified issues==
There is a general trend in the problems noted, when looking at output we lack organisation, documentation, and consistency across the board. However the actual issues we are focusing on in this spec can be identified as below:

* Lack of a style guide / element library / pattern library.
** Leading to inconsistent output and style.
** Increased workload due to usability and accessibility thinking and testing needing to occur repetitively.
** Increased workload due to multilang (rtl) support usually coming after the designs of new output.
* Inconsistent renderer implementations.
** Lack of best practices.
** Lacking plus outdated documentation.
** Logic-full renderers greatly hinder theming.
** An unnecessarily increased requirement to understand both PHP and Moodle code as each renderer differs and are usually poorly documented.
* No abstraction from CSS framework.
** Without organised structure classes are applied in a chaotic fashion leading to the requirement to duplicate core styles.
** As there is no core styles newly created output widgets need to be styled in all base themes leaving chance of design regressions occurring in predominantly major upgrades but occasionally minor releases as well.
** Inconsistent output structure ensures CSS quickly balloons as styles need to be both created and copied to several areas.
* Poor linking between UI components and the JavaScript.
** Ill-defined link between output and the JavaScript enhancing it.
** No common technique to template UIs generated by javascript

==Manageable Tasks==
The following are the major tasks we have identified so far. These tasks can be though of as Epic's, or tasks for which we will create subtasks (if this output specification itself becomes an Epic).
Within this section will include notes and implementation ideas on the major tasks we've identified.

* [[#Define the elements that make up Moodle|Choose an output methodology and begin defining core elements]]
* [[#Element library and style guide|Create an element library and accompanying style guide]]
* [[#Style guide|Create a style guide document]]
* [[#Define and document renderer best practices|Define and document renderer best practices]]
* [[#Define and update the JS documentation|Update the JavaScript documentation]]
* [[#Update renderer documentation|Update renderer documentation]]
* [[#Update theme documentation and theme tutorials|Update theme documentation and theme tutorials]]
* [[#Progressively convert renderers|Progressively convert renderers]]

===Define the elements that make up Moodle===
There are several tasks that will go into this, but the first and most important will be deciding upon an organisational methodology. Some way to compartmentalise the Moodle output.
At present a reducing granularity system is looking the most appealing. Go and read [http://bradfrostweb.com/blog/post/atomic-web-design/ Atomic Design] written by Brad Frost - it describes very well the type of compartmentalisation we are proposing.

Once a system has being chosen the following tasks can be tackled:
* Identify the layers we require.
* Define the boundaries and responsibilities of those layers.
* Identify the initial set of elements, likely the finest granularity first as I imagine starting at the bottom and working up will be the best way to proceed.

Further elements (those relating to Moodle will be defined as part of the element library work).

===Element library and style guide===
Draft docs for element library tool: [[Element_Library]]

Add an admin tool that can show a categorised list of renderable objects for each plugin/and core - filled with test data. The goal of this tool is to:

* 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 (in a well defined structure) they can use when building their own pages

The tasks here will be:
* Spec the element library tool with regard to our chosen element methodology.
* Create the element library tool.
* Establish a definition method of elements, and compositions of elements as renderables.
* Define the core elements from the task above in code somehow and verify the element library tool reveals them.
* Finally 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, grid. These renderables should be structured into layers, starting from renderables that cannot be broken into smaller parts, up to widgets made of smaller renderables, up to layouts (and possibly up to entire pages). 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

On top of this there is functionality that would be great to add to it:

* Validate that the renderer/renderable follows best practice (no DB queries, complex types, complex logic)
* Provide responsive testing immediately within the tool. Adjusting the viewing area on queue to allow both developers and designers to experience how the individual renderables respond in varying presentation medias.
* Provide language direction testing immediately within the tool. Like the above allow designers and developers to quickly experience a renderable in a different language directions.
* Renderable linear reporting. So that you can see which other renderables make use of this renderable and which renderables get used by this renderable. This will be hugely helpful in judging impact when themeing.

===Thoughts on naming===

We will need to define useful names for the different categories of renderables so that we can effectively organise them and provide guidelines for writing each type - the names are a small part of this solution but will possibly be a point for contention. Different frameworks have different names for these things and people will prefer something that sounds like something they are already using.

(draft!) Categories for renderables - taken straight from Atomic design

http://bradfrostweb.com/blog/post/atomic-web-design/

* Atoms == Tiny reusable elements that cannot be broken down into smaller elements
* Molecules == Relatively simple combinations of atoms built for reuse
* Organisms == Organisms are groups of molecules joined together to form a relatively complex, distinct section of an interface.
* Templates == Layout files in a theme
* Pages == The actual pages in Moodle

Refs for categorizing patterns
* http://bradfrostweb.com/blog/post/atomic-web-design/
* http://oocss.org/
* http://alistapart.com/blog/post/getting-started-with-pattern-libraries
* http://style.codeforamerica.org/

===Style guide===
This has two real advantages.

# First assuming this will be developed initially while defining the elements that will make up Moodle output and will aid us in verifying what we are doing. If it can be easily documented then we are on the right track. If we start encountering to many conditions and or too much variation then we are drifting off track.
# When defining new elements we are able to use our style guide to do so and it'll provide us measure of how Moodle output evolves.

===Define and document renderer best practices===

This will be tricky and no doubt how we decide to define a best practice will have to have regard for the output methodology we choose.

===Update the JavaScript documentation===

Discuss and agree on a best practice for writing JS that depends on HTML structures in the DOM (e.g. progressive enhancement - or just ids for action listeners) (perhaps a specific renderable for a JS region)

===Update renderer documentation===
This will of course need to be done after the element library and renderer best practices but should be pretty simple at that point.
* Read and rate each of the existing docs pages (see related links below)
* Write new complete docs for everyone (at [[Output API]])
* Cross link old docs to the new ones

===Update theme documentation and theme tutorials===
There are likely the most well documented plugin type within Moodle. There are good specification docs, good 2.0 conversion docs and good tutorials on many aspects of theming.
Many of these pages will need to be updated to reflect best practices and such after we start ticking off some of the other tasks.

===Progressively convert renderers===
This is the very last task really - but we will start work on it in parallel with creating the new set of core renderables (to prove the design is usable). There is no deadline for this to be complete - and it will take a long time to convert all the existing renderers (and code not using renderers).

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

Goals for renderers - should be devoid of logic for these reasons:
* Theme overridden renderers do not need to be updated when logic is changed
* Themers can override renderers without understanding all the logic
* Renderables can be filled with mock data for display in the element library

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 not related to output
* calling the database

A “renderable” is:
* All the data required to generate the output.
* Properties should be simple data types only, or renderables, or array of those

== Evaluations of some existing renderers / renderables ==
Existing renderer styles - because there are few rules/guidelines for how renderers should be written - there are differing examples of renderers in core. Looking at the 3 of the better maintained modules to see how they are implemented will be useful in evaluating the benefits of any stricter rules for renderers.
=== Assign ===
Contains a list of renderables (in renderables.php) and a single renderer. The logic is mostly out of the renderer methods (pre-calculated and added as data to the renderer). There are some cases when renderables could be broken down further - e.g. the expand/collapse on the submission history (mod/assign/yui/src/history/js/history.js). Also the assignment sub-plugins do not use renderers (and they should).

=== Quiz ===
Uses a lot of renderers - but not renderables. The renderer methods directly call methods of the business logic to determine what to display. e.g. "attemptobj->get_access_manager(time())->attempt_must_be_in_popup()". This is not terrible for a themer trying to override a renderer method because the calls are mostly simple - but it is a grey area for when this becomes business logic in the renderer (and would e.g. need updating to fix bugs etc). If we want to add these renderer methods to the element library - it would require a way to pass mock business logic classes to the renderer methods (and a way for the generator to return a renderer and a method - instead of only a renderable).

=== Workshop ===
Very nice renderers and renderables in workshop. Would only need updating to re-use core renderables instead of using html_writer directly - and adding the existing renderables to the element library.

=== Badges ===
Mix of renderer methods and renderables. This is similar to quiz where the renderer is calling lots of methods of the business model in the renderer methods and has the same effect (harder to override, maintain etc). To add these renderer methods to the element library would require the same sort of changes as mentioned in quiz.

== Example of forum post renderer using composition ==
This is not a real example (yet), it's just a demonstration of the type of renderers we should be aiming for (using composition etc). This structure would be created in the render_form_post method of the forum renderer. This method would receive a forum_post renderable containing only data - and build up this structure of smaller renderable components, then return the result of calling render(x) on each of the smaller renderables.

[[Image:forumpost-renderer-breakdown.png|center|500px|Example forum renderer]]

== Initial thoughts on renderables and what we should provide (Draft) ==
This list is not intended to be the final list - it is more of a scoping exercise. One of the tasks from this project is to decide on the full set of required renderables.
There are several renderables within Moodle that have being included in this table and we will need to look closely at how they fit within our chosen model and whether they are still required.

{| class="nicetable"
|-
! Name
! Description
! Source (links)
|-
| action_menu
| UI component for a drop down edit menu
| Existing renderable (should be renamed "menu")
|-
| action_menu_link
| UI component for a menu item in an action menu
| Existing renderable
|-
| action_menu_filler
| UI component for a filler menu item in an action menu
| Existing renderable
|-
| action_menu_link_primary
| UI component for a primary menu item in an action menu
| Existing renderable
|-
| action_menu_link_secondary
| UI component for a secondary menu item in an action menu
| Existing renderable
|-
| action_link
| Link with alt text, and an icon
| Existing renderable
|-
| single_button
| A form with a single button
| Existing renderable
|-
| confirm
| A form with a message and cancel/confirm buttons
| Existing renderable
|-
| single_select
| A form with a single drop down list that submits on change
| Existing renderable
|-
| url_select
| A navigation element consisting of a single drop down list of urls that navigates on change
| Existing renderable
|-
| doc_link
| A link to the Moodle docs
| Existing renderer method
|-
| pix_icon
| A small icon
| Existing renderable
|-
| emoticon_icon
| A small emoticon
| Existing renderable
|-
| heading_with_help
| A page heading with a link to help docs
| Existing renderer method
|-
| help_icon
| A help icon that opens a help popup when clicked
| Existing renderable
|-
| help_icon_scale
| A help icon that opens a help popup when clicked
| Existing renderable
|-
| user_picture
| A user profile picture which links to their profile
| Existing renderable
|-
| container
| A block level element used to surround something. Can have a class to allow specific targeting with CSS.
| Existing renderable
|-
| error_text
| An error to show to the user.
| Existing renderable
|-
| notification
| A message for the user
| Existing renderable
|-
| continue_button
| A message and a button to continue to the next page
| Existing renderable
|-
| paging_bar
| A list of next previous and specific page links
| Existing renderable
|-
| skip_link_to
| A link to a section on the page
| Existing renderable
|-
| skip_link_target
| A target for a matching skip_link_to call
| Existing renderable
|-
| heading
| A page heading
| Existing renderable
|-
| box
| A page section with a border
| Existing renderable
|-
| rarrow
| A right arrow
| Existing renderable
|-
| larrow
| A left arrow
| Existing renderable
|-
| tabtree
| A list of tabs
| Existing renderable
|-
| tabobject
| A single tab panel
| Existing renderable
|-
| toolbar *new
| A container for toolbar button groups
| Bootstrap equiv btn-toolbar (needs aria support)
|-
| toolbar-group *new
| A group of toolbar buttons
| Bootstrap equiv btn-group (needs aria support)
|-
| toolbar-button *new
| A toolbar button
| Bootstrap equiv btn (needs aria support)
|-
| toolbar-menu *new
| A toolbar button that opens a drop down menu
| Bootstrap equiv nested btn-groups (needs aria support)
|-
| navbar *new
| The navigation bar that shows at the top of the page
| Bootstrap equiv navbar - There is an existing renderer method that needs converting into renderables
|-
| navbar_item *new
| Items in the navigation bar that shows at the top of the page
| Bootstrap equiv list item in a navbar - There is an existing renderer method that needs converting into renderables
|-
| navbar_item *new
| Items in the navigation bar that shows at the top of the page
| Bootstrap equiv list item in a navbar - There is an existing renderer method that needs converting into renderables
|-
| progress_bar *new
| A bar showing progress of something
| Bootstrap equiv progress_bar - There is an existing moodle class that needs converting to use renderables
|-
| progress_bar *new
| A bar showing progress of something
| Bootstrap equiv progress_bar - There is an existing moodle class that needs converting to use renderables
|-
| panel *new
| A container with a heading and borders
| Bootstrap equiv panel, panel-heading, panel-body, panel-footer
|-
| vertical-list *new
| A vertical list of items
| Bootstrap equiv - list-group
|-
| horizontal-list *new
| A horizontal list of items
| Bootstrap equiv - list-inline
|-
| Two column list *new
| Short cut for a list of pairs with the left column fixed-width and right aligned
| Similar to our current moodle forms
|-
| table (and cells headings etc) * new
| We need to convert tablelib to use renderers to output all table elements
|
|-
| forms (and labels, inputs etc) * new
| We need to convert formslib to use renderers to output all form elements
|
|-
| grids *new
| We need to support renderables for a simple responsive grid system
| Everything has grids...
|-
| floats *new
| We need to support floating elements left and right
| Bootstrap - pull-left, pull-right
|-
| clearfix *new
| If we have this simple thing as a renderable we can avoid repeating the CSS
| Bootstrap - clearfix
|-
| expandable *new
| Initially shows only a summary with an expand button to show more details
| mod_assign
|-
| dialog *new
| Tie into M.core.dialogue so it can be adjusted in a renderer
| aria
|-
| timer *new
| There is an aria role for this - so we should make sure it is used correctly if required.
| aria
|-
| tree *new
| Reusable version of the nav tree
| aria tree, tree-item, tree-grid etc
|-
| indent *new
| (eg threaded forum post)
|
|-
| media block *new
| large media element side by side with some text
| http://demo.patternlab.io/
|-
| hero *new
| content section with borders/oversized text etc designed to be a landing point
| Bootstrap jumbotron
|}

== Prototyping ==
Because there are several ways to implement a renderer/renderable - we have spent some time exploring an example renderer/renderable implementation. What we intended to achieve with these dev branches is an implementation of a "menu" and a "list" renderable in several themes, using several CSS frameworks. The frameworks chosen are: Bootstrap 2 (clean), Bootstrap 3, Zurb Foundation and YUI Pure IO. The prototypes both produce exactly the same output (and only a little effort was made to get nice output) - it's just the implementations we are interested in at this stage. Each prototype branch adds a local plugin with a test page that can be viewed at "/local/output/index.php" and viewed in several themes (clean, output_bs3, output_pureio, output_zurb).

Some different approaches were explored here:

=== Approach A ===
This design takes a strong objected oriented view of renderables and introduces some concepts of the HTML DOM to the renderables. There is an abstract class core_ui_element which implements renderable, that all the new renderables inherit from. Each core_ui_element has additional properties including a type, a chain of parent types, a list of attributes to be mixed into the html and a generic list of name/value properties. The type variable can influence which renderer method renders this core_ui_element (this requires a core change). The renderer method can adjust the output based on the chain of parent types of the current node, and the properties of the immediate parent.

'''The concepts applied in this approach:'''

; Everything is an element : Everything that forms a part of output will be represented by a class and can be interacted with in a consistent fashion.
; All elements are renderables : All elements and components inherit from a common core_ui_element class that implements the renderable interface.
; All elements are also core_ui_elements : The core_ui_element class allows for common functionality across every element and component. It facilitates ownership of one element to another (building complex elements aka components) as well as adding attributes and properties.
; Attributes : Element objects have attributes, these are of direct relation to HTML attributes, they are managed as a public array and can easily added to and worked with. There is also a helper method on the renderer that turns them into an HTML attribute string that can be put immediately within a tag for ease of use.
; Properties : These are used for non-renderable attributes of the element. For instance when producing a menu with items that are disabled, and where one item is active. Properties get assigned by the parent element allowing for properties to appear with specific relation to the context the element is appearing in. For example a link can be a menu item, when it is a menu item it has "active" as a property. When it is used elsewhere it does not have that property.
; Chained render methods : When render is called on a link that is by itself ''render_link'' gets called. When render is called on a link within a menu ''render_menu_link'' gets called, and if it doesn't exist ''render_link'' gets called. When render is called on a link that is within a menu that is within a dropdown ''render_dropdown_menu_link'' gets called, if that doesn't exist then ''render_menu_link'' gets called and so on and so forth. Through this chaining you can override the individual elements within a complex component using predictable means.

'''Pros'''
* All elements take on a predictable, consistent structure through the core_ui_element.
* The magic gets rolled into the core_ui_element class so that elements need only publish the public properties that they consist of, any any helper methods used in the construction of the object or in setting its properties. There is no need to add any more logic than that.
* Absolutely all logic not associated with producing output to the needs of the theme gets rolled into the element objects. When rendering an element in most cases you should only need to render the structure for the element and then call render on its properties in the order you want.
* It will be very easy to deem good interfaces from bad as anything that is not consisting of core_ui_elements will not be an ideal interface.
* It will be very easy to see in code when writing a renderer what elements are available as each will be a class.
* Its a clean approach - we will be able to do things as we believe is correct without concern of getting in the way of existing practises.

'''Cons'''
* There is going to be a lot of classes. I don't mean hundreds, but we may end up with over a hundred easily enough.
* Complexity of knowing PHP. In order to override a renderer you will need to know enough about PHP to understand what an object is.
* This is a completely new approach, while it provides clean separation from current practices it is yet another learning curve.
* There is a potential limitation if you have multiple elements of the same time occurring within a component each that needs to be rendered differently. I've not actually thought of a use case for this yet, but am mentioning it as something to be investigated.

'''Branch details'''

To view this branch at github:
https://github.com/samhemelryk/moodle/tree/output_prototype

To get a copy of this code into your own local repository run the following commands:
git checkout -b output_prototype
git fetch <nowiki>http://github.com/samhemelryk/moodle.git</nowiki> output_prototype
git reset --hard FETCH_HEAD

'''Viewing it in your browser'''

# First get a copy of the code into your local repository.
# Browse to your site and turn on allowthemechangeonurl (Settings > Appearance > Themes > Theme settings)
# To view in clean: browse to /local/output/index.php?theme=clean
# To view with Bootstrap 3: browse to /local/output/index.php?theme=output_bs3
# To view with YUI Pureio: browse to /local/output/index.php?theme=output_pureio
# To view with Zurb foundation: browse to /local/output/index.php?theme=output_zurb

=== Approach B ===
This design requires as little change to the existing code/implementations as possible. The idea, is simply to add a new list of renderables / renderer methods that implement the new things. There is no abstract class for renderables with no additional properties etc. Additionally, there are no restrictions on what can be put in a list/menu etc - it really is a just a list of renderables/strings. There is an edge case here, which is "How can a renderer method for a container modify the HTML for the elements it contains?". An example of this is that the Bootstrap 3 theme wants to put the role="menuitem" on the first link in each of the elements in it's "items" list. There are several possible approaches here - and this is one of the points of difference of this branch. One approach (too nasty) is to perform a str_replace on the first "<a" in the rendered html from the item - the downside of this approach is that it doesn't allow for differences in syntax for links, or merging with existing attributes on a link - it is doomed to fail. The approach chosen for this branch, is to parse the rendered html from the item into a DOMDocument - and use Dom manipulation to amend to the link before rendering it back to a string. There is a util method that takes this complexity out of the renderer method (and we can add more util methods as needed).
<pre>
$attributes = array('role'=>'menuitem', 'tabindex'=>'-1');
$newitemhtml = dom_utils::add_attributes_to_first_node_of_type('a', $attributes, $itemhtml);
</pre>

Branch details: git pull http://github.com/damyon/moodle.git MENU_RENDERABLE

==Documents created as part of this spec==
* [[Output element planning]] - Thoughts on initial elements that should be created.
* [[Renderer best practices]]
* [[Guide to creating output elements]]
* [[Element HTML and CSS guidelines]]

== See also ==
* [[Output API]]
* [[Migrating your code to the 2.0 rendering API#Outputting HTML specific to your module]]
* [[Output_renderers]]
* [[Overriding_a_renderer]]
* [http://moodle.org/mod/forum/discuss.php?d=177535 Forum discussion on renderers]
* [[Renderer]]

Output element planning

2014-07-22T11:38:55Z

Samhemelryk: /* See also */

{{Infobox Project
|name = Renderer consistency
|state = Specification
|tracker = https://tracker.moodle.org/browse/MDL-45829
|discussion = https://moodle.org/mod/forum/discuss.php?d=261202
|assignee = Damyon, Sam
}}
{{Work in progress|forumurl=https://moodle.org/mod/forum/discuss.php?d=261202}}
This page documents the proposed core elements, variations of them, what we expect they will contain, and the core_renderer block.

==The user action==

An action in this sense is a collection of data that all pertains to one action that can be taken by the user.
The action, once populated with data can be rendered as is required for the job it is going to fulfil, usually with some relation to the frontend framework in use.
In this way the action could be a link, or a button; it could even be interpreted into a more complex structure.

An action has the following properties:
; content [string]: text content for the link or button.
; url [moodle_url] : the url for the action to take when the user interacts with this action.
; description : a description of the action. Typically used within a title or alt attribute.
; active : True if this is the action the user is current performing.
; enabled : True if the action is possible, false if it is not possible and should be shown as disabled.
; dimmed : True if the action should be shown as dimmed, usually used to the action is hidden to other users.
; method : The preferred method of submitting this action, typically GET but can be set to POST.

It is also possible to add JavaScript actions (component_action objects) to an action. These attach a JS listener to the action that gets executed when the user interacts with the action.
Attached JavaScript actions get initialised when the properties for the action are retrieved so any events must be attached BEFORE the action is rendered, and all renderers must ensure they use the get_attributes() call.

==Grids==

We need to come up with some way to include grids in core, it is desirable to keep it framework agnostic so perhaps a grid object that allows for items to be added and a "width" specified when that occurs. The width would be either a fixed number or a percentage. Steps of 12 seems pretty common.

==Design requirements==
The following concepts need to be accounted for in core, or decisions made on how we choose to support these and where.

===Clearfix===
We have this in core already, bootstrap has it, pretty much every front end framework has it.
Clearfix is more of a design decision, should only be used when require, and only ever applied by a renderer.
This gets special mention as being important, support is already 100%.

===Floats===
Pull left, pull right etc. These are a design decisions and should be implemented by the renderer. Bootstrap caters for these and as such they will be easily catered for in bootstrapbase, however work may be required to get them operational in base.

==Discarded ideas==
The following things are ideas that came up during discussions on what elements are, and what elements we want in core that have being discarded.

==Core atoms, molecules, and organisms==

The following is the atoms, molecules and organisms we believe should be created initially. Of course there will be many more that are required - however this should give us a good grounding of elements to work with for the first conversions.

===Action {atom}===
See the section above about [[#The user action]]

Actions are special atoms the represent an action the user can make.
They can be rendered by a theme as a link, a button or I suppose anything else.
There should be a default for when it is not specified and the renderer in change of producing the current thing can decide whether to use the default and just call ''render'' or if it requires something specific ''render_link'' or ''render_button'' as required.

===Action group {molecule}===
A group of actions, to be rendered to reflect a relation. I suppose the easiest way to think about this is how buttons in the atto editor are grouped together. It is a requirement that may seem a tad absrtracted and irrelevant at first but I think will pop up in several places throughout Moodle when we start converting.

It is basically a collection of actions.

'''Markup in various frontend frameworks'''

* [http://getbootstrap.com/2.3.2/components.html#buttonGroups Bootstrap 2.3.2]
* [http://getbootstrap.com/components/#btn-groups Bootstrap 3]
* [http://foundation.zurb.com/docs/components/button_groups.html Zurb foundation]

===Block {atom}===

Unique to Moodle. This represents a block on the page, and is displayed within a [[#Block region]].
It accepts two arguments, the first is a ''block_contents'' object instance, and the second is the region name the block instance is being shown within.

At present a block is rendered using the '''''core_render::block''''' method. Internally this calls several renderer methods to produce the different parts of a block.
* core_renderer::block_header - Produces a header
** core_renderer::block_controls - Produces controls to display within the header.
* core_renderer::block_content - Produces the actual content of the block.
** core_renderer::block_controls - Used to check if block controls were rendered. PUKE!!!
** core_renderer::block_footer - Produces a footer that actually resides within the content.
* core_renderer::block_annotation - Produces an annotation, used VERY rarely.

'''Current structure'''

The following is the output when called for a navigation block with a bit of extra added to show how a footer is displayed and an annotation.
<code html5>
<a href="#sb-1" class="skip-block">Skip Navigation</a>
<div id="inst4" class="block_navigation block" role="navigation" data-block="navigation" data-instanceid="4" aria-labelledby="instance-4-header" data-dockable="1">
<div class="header">
<div class="title">
<div class="block_action">

</div>
<h2 id="instance-4-header">Navigation</h2>
</div>
</div>
<div class="content">

<div class="footer">

</div>
</div>
<div class="blockannotation">

</div>
</div>
<span id="sb-1" class="skip-block-to"></span>
</code>

===Block region {molecule}===

Unique to Moodle, the block region is a contain for all of the blocks in one location.
We currently have two methods that produce a block region within Moodle, the first is '''''core_renderer::blocks_for_region''''' which adds no surrounding content.
The preferred method '''''core_renderer::blocks''''' adds some embedded information to a common structure.

'''Current structure'''

The following is the structure of the ''core_renderer::blocks()'' method.
<code php>
public function blocks($region, $classes = array(), $tag = 'aside');
</code>

The following is the html output is $region was ''pre'' and the default tag and classes were used.
<code html5>
<aside id="block-region-pre" class="block-region" data-blockregion="pre" data-droptarget="1">

</aside>
</code>

'''Thoughts on this'''

The blocks method is a convenience method and serves an important purpose. However it should not take classes and tag as arguments.<br />
These should certainly only settable within the renderer itself, and if themes wish to change this without wrapping the call they should override the renderer.

Both the data attributes relate to servicing JavaScript functionality. Perhaps they should be moved to a component_action or somehow else integrated with JS rather than with the renderer directly.

Internally it is calling blocks for region, however this should change it should request a array of blocks, convert the array to [[#Block]] elements and call render on each.

'''Proposed HTML structure'''

Much like the current structure but with the data attributes coming through a JS mechanism.

<code html5>
<aside id="block-region-pre" class="block-region">

</aside>
</code>

===Breadcrumb {molecule}===

Currently called the navbar within Moodle, controlled by the '''''navbar''''' class located in lib/navigationlib.php and rendered by '''''core_renderer::navbar()'''''.<br />
Internally it calls moodle_page->navbar->get_items() to get an array containing navigation node items to display in the navigation bar.<br />
It produces a bit of surrounding structure before calling render on each item.

'''Current structure'''

The following shows the structure for two items in the navigation bar presently within Moodle.

<code html5>
<span class="accesshide">Page path</span>
<nav class="breadcrumb-nav">
<ul class="breadcrumb">
<li>
<a href="#">Home</a>
<span class="divider">
<span class="accesshide">
<span class="arrow_text">/</span>
 
</span>
<span class="arrow sep">►</span>
</span>
</li>
<li>
<a href="#">Here</a>
<span class="divider">
<span class="accesshide">
<span class="arrow_text">/</span>
 
</span>
<span class="arrow sep">►</span>
</span>
</li>
</ul>
</nav>
</code>

Notice the excessive amount of markup to make the separator accessible.

'''Markup in various frontend frameworks'''

[http://getbootstrap.com/2.3.2/components.html#breadcrumbs Bootstrap 2.3.2]
<code html5>
<ul class="breadcrumb">
<li>
<a href="#">Home</a>
<span class="divider">/</span>
</li>
<li>
<a href="#">Here</a>
<span class="divider">/</span>
</li>
</ul>
</code>

[http://getbootstrap.com/components/#breadcrumbs Bootstrap 3]
<code html5>
<ul class="breadcrumb">
<li>
<a href="#">Home</a>
</li>
<li>
<a href="#">Here</a>
</li>
</ul>
</code>

[http://foundation.zurb.com/docs/components/breadcrumbs.html Zurb foundation]
<code html5>
<ul class="breadcrumb">
<li>
<a href="#">Home</a>
</li>
<li>
<a href="#">Here</a>
</li>
</ul>
</code>

'''Design considerations'''

* The currently active page should be marked with a class.
* The current item should probably not be a link MDL-46037
* [http://www.w3.org/TR/2007/WD-aria-role-20070601/#breadcrumbs wia-aria breadcrumb role]
* The divider perhaps could come through CSS with these changes to avoid markup necessary to make it accessible (in combination with the above).

'''Implementation thoughts'''
* Owns an array of [#Action {atoms}]

===Buttons {atom}===

This will be both an element and a representation of a [#Action {atom}].<br />
Obviously buttons can serve different purposes and roles so have several easily reachable customisations is probably a wise idea.

'''Current structure'''
None, presently you produce a button when you need it so there are several throughout Moodle.

'''Markup in various frontend frameworks'''

[http://getbootstrap.com/2.3.2/base-css.html#buttons Bootstrap 2.3.2] and [http://getbootstrap.com/css/#buttons Bootstrap 3]
<code html5>
<button type="button" class="btn btn-default">Default</button>

<a href="#" class="btn btn-default btn-lg active" role="button">Link</a>

<input class="btn btn-default" type="button" value="Input">
</code>

Customisations available through Bootstrap:
* Purposes: default, primary, success, info, warning, danger, link
* Sizes: large, default, small, extra-small
* Block level (wider)
* States: Active, disabled.

[http://foundation.zurb.com/docs/components/buttons.html Zurb foundation]
<code html5>
<a href="#" class="button">Default Button</a>
</code>

Customisations available through Zurb Foundation:
* Purposes: default, secondary, success, alert
* Sizes: large, default, small, tiny
* Corner style: radius, round
* Expanded (wider)
* States: disabled

===Calendar {organism}===

A simple idea really, apparently not already covered by the frontend frameworks being referenced during the creation of the doc.
The display of the calendar is fixed, but it can contain content for each day shown.

The calendar should have several views, perhaps these are separate organisms, perhaps not.

* Compact month
* Month
* Week
* Day

Each day could:
* Contain an action with an icon for events, and link to the fullday display.
* Have an associated action to load and display the events in a tooltip.

===Collapsible region {molecule}===

We use these in several places within Moodle. I could not find a reference to this concept in any of the frontend frameworks I looked at.
The concept is simple - you have a heading and an icon with content. By default the content is hidden, when the user clicks the heading and/or the icon the content is revealed.

As noted we do this in several places within Moodle, it would be good to have a single way of displaying this idea of a collapsible region.

'''Design thoughts'''
* It should support an optional collapse/expand all trigger action.
* We want to be able to use it both inside and outside of forms.
* It should be usable in situations like the combo list frontpage component as well.
* Will obviously have a JS component as without JS it would not work.

===Confirmation {molecule}===

A simple concept used regularly in Moodle to confirm a users intention to perform an actions. Most commonly seeing when deleting content.
The structure is relatively basic in Moodle at present.
* A message
* A forwards button
* A back button

'''Current structure'''

The method '''''core_renderer::confirm''''' does the rendering at present. Its signature is as follows:
<code php>
public function confirm($message, $continue, $cancel);
</code>

The output it produces is like:
<code html5>
<div class="generalbox" id="notice">
<p>The message goes here</p>
<div class="buttons">

</div>
</div>
</code>

'''Design throughts'''

This component does not have a title. I believe at present some pages use ''core_renderer::heading'' to produce a title if they wish. Obviously we want consistency of style so I believe it would be wise to add a title property that can be optionally set and then in our documentation for this element recommend that a title is always provided.<br />
It will mean re-factoring our uses to set a title and if a heading is being manually added remove it.

===Continue {molecule}===

This is much like the confirmation molecule but with a single button.<br />
At present we have '''''core_renderer::continue_button''''' that produces a single button. However this design is very poor as more often than not a message is included in the page to describe the purpose of the continue button. This is really an integral part of the continue button.

'''Current structure'''

Currently we have ''core_renderer::continue_button'' to render a single continue button.
<code php>
public function continue_button($url);
</code>

Internally it creates a single_button component and then calls render on that.

'''Design thoughts'''
Our element should have a message and a button. To make it easy to migrate the constructor should accept a URL instead of a button and do the same conversion as the current method is doing.

===Choice {molecule}===
Not sure about this one quite yet.
A description with 2 or more actions allowing the user to select the next step.
Think of it like when editing a module you get: Cancel, Save and return to course, Save and display

Perhaps both [#Confirmation {molecule}] and [#Continue {molecule}] should be just instances of this.

Hmm perhaps that would not be as clear as this and we should have this separate choice molecule.

===Divider {atom}===
Think horizontal rule.

===Dropdowns {molecule}===

So this is a pretty simple concept, but you've got to think of it as a separate entity. A dropdown is a menu that appears when the user interacts with an action.

The action could take one of three forms:
* From button
* From link
* From icon

Of course that is handled by the [#Action {atom}] noted above. Worth noting is that we will need some way to toggle these actions as dropdowns. Perhaps it is worth making that a property of the action atom.

The dropdown itself will likely contain more actions, and I suppose additional dropdowns to form sub menus. Sub-menus in my mind are required. We don't use them in core, but they are functionally possible through things like the custom menu and I know for a fact that many sites have sub menus.

'''Markup in various frontend frameworks'''

[http://getbootstrap.com/2.3.2/components.html#dropdowns Bootstrap 2.3.2]

<code html5>
<div class="dropdown">

<ul class="dropdown-menu" role="menu" aria-labelledby="dLabel">
<li><a tabindex="-1" href="#">Action</a></li>
<li><a tabindex="-1" href="#">Another action</a></li>
<li><a tabindex="-1" href="#">Something else here</a></li>
<li class="divider"></li>
<li><a tabindex="-1" href="#">Separated link</a></li>
</ul>
</div>
</code>

[http://getbootstrap.com/components/#dropdowns Bootstrap 3]
<code html5>
<div class="dropdown">
<button class="btn dropdown-toggle sr-only" type="button" id="dropdownMenu1" data-toggle="dropdown">
Dropdown
<span class="caret"></span>
</button>
<ul class="dropdown-menu" role="menu" aria-labelledby="dropdownMenu1">
<li role="presentation"><a role="menuitem" tabindex="-1" href="#">Action</a></li>
<li role="presentation"><a role="menuitem" tabindex="-1" href="#">Another action</a></li>
<li role="presentation"><a role="menuitem" tabindex="-1" href="#">Something else here</a></li>
<li role="presentation" class="divider"></li>
<li role="presentation"><a role="menuitem" tabindex="-1" href="#">Separated link</a></li>
</ul>
</div>
</code>

[http://foundation.zurb.com/docs/components/dropdown.html Zurb foundation]
<code html5>
<a href="#" data-dropdown="drop1">Has Dropdown</a>
<ul id="drop1" class="f-dropdown" data-dropdown-content>
<li><a href="#">This is a link</a></li>
<li><a href="#">This is another</a></li>
<li><a href="#">Yet another</a></li>
</ul>
</code>

===Forms {organism}===

This is an advanced organism and would be quite a bit of work to create in Moodle as we'd need to translate from QuickForms to elements for rendering.
It would be worthwhile doing this however, and would be a good way of quickly showing our new work.

'''Frontend framework structures'''
* [http://getbootstrap.com/2.3.2/base-css.html#forms Bootstrap 2.3.2]
* [http://getbootstrap.com/css/#forms Bootstrap 3]
* [http://foundation.zurb.com/docs/components/forms.html Zurb foundation]

All of those are quite in-depth and offer a range of configurations.
We should carefully consider these when analysing our work here.

===Headings {atom}===

Currently handled by '''core_renderer::heading'''.

* h1 - h6
* Optional icon
* Optional help icon

'''Current structure'''

The render method is currently:
<code php>
public function heading($text, $level = 2, $classes = null, $id = null);
</code>

The output generated by this is, assuming we use the default level, classes, and id.
<code html5>
<h2>I am a heading</h2>
</code>

Whats worth noting is that the render method should not accept level and classes as arguments.
These should only be set by the render method and should not be directly influenced.

===Image {atom}===

There are really two types of images to focus on here, or really two ways to display an image to focus on here.<br />
# Standard images
# Thumbnail images

Each of these would share some common properties:
* Image
* Description (alt/title)
* Size
* Action (making it a link) - This would actually make it a molecule, we would have to consider this and either have a new element, drop the ability to wrap in an action, or simply ignore this inconsistency.

===Image - Icon {atom}===

This covers the display of an icon. Should be a separate element from image as really they should be treated individually.
Within Moodle there are a few classifications of icons to consider:
* Standard icons
* Help icon (popup, tooltip)
* Loading icon (really regular icon but worth showing separately as its only seen when required)

===Image - Logo {molecule}===

We don't have this within core Moodle at present, however just about every theme I have seen uses a logo. I think it is about time we considered having a logo element.
I imagine it would become a sort of hero element, likely with an associated action (back home by default).

===Image - Profile picture {molecule}===

We already have a user_picture component within Moodle. It can be found in lib/outputcomponents.php.<br />
It has two render methods, '''''core_renderer::user_picture''''' and '''''core_renderer::render_user_picture'''''.

'''Current structure'''

The following is the output structure for the user picture:
<code html5>
<a href="#" id="userpicture_randomid">
<img src="#" alt="Picture of Joe" title="Picture of Joe" class="userpicture" width="[35, 100, XX]" height="[35, 100, XX]" />
</a>
</code>

What you'll notice about this is that the link has no attributes marking it as a user picture link.

The PHP code for the user_picture object itself is really quite in depth and complex. The component serves the user profile fields required to render a user picture. This is good in the scope of the component but would be bad within the scope of an element.<br />
Don't you wish we had a proper user object!

===Link {atom}===
This will be both an element and a representation of a [#Action {atom}].

Theres not too much more to explain about links, they don't tend to take states other than the default active, enabled and dimmed.<br />
It is worth mentioning that devs will be encouraged to use actions and not links unless absolutely necessary.<br />
The render method for this atom must typehint an action rather than a link.

'''Prototype example'''
* The atom: https://github.com/samhemelryk/moodle/blob/output_prototype_5/local/output/classes/output/link.php
* The convenience method: https://github.com/samhemelryk/moodle/blob/output_prototype_5/local/output/classes/output/renderer.php#L149
* The render method: https://github.com/samhemelryk/moodle/blob/output_prototype_5/local/output/classes/output/renderer.php#L211

===List {molecule}===

This is a pretty simple example and something I am sure you are all familiar with. A list is simply a collection of items. Usually represented using a UL or OL tag in markup although worth noting can be styled completely differently to the default.
There are three main types of lists used within Moodle:
* Ordered list
* Unordered list
* Presentation list (currently our unlist)

The list is a molecule because it should be able to accept other elements as items. E.g. it should be content independent.

===Menu {molecule}===

A menu is a familiar concept for any site. Probably the first thing that pops to mind for many is the navbar, but I want to consider that a separate component as a navbar can consist of more than just menu items.
I think a menu should be a collection of actions the user can perform. Perhaps with some form of hierarchy.

We have different types of menus within Moodle:
* The custom menu is one users can directly create, with dropdown downs and sub dropdowns.
* The action_menu component we have in core uses icons as actions and can have a dropdown.

These should be combined into a single menu element that takes items as an argument, likely actions + dropdowns + dividers to start with would be perfect.

We would likely need to deal with the display of the menu with properties to allow constructing code to ''request'' a particular style of menu. The renderer should be what actually gets to decide, but for the purposes of re-use having properties and a single render_method is better than having multiple render methods.<br />
The following is my initial thoughts on menu structure:
* Direction: Horizontal, Vertical
* Design: Default, Tabs,
* Style: Default, Links, Buttons, Icons

===Notification {atom}===
* Info
* Success
* Warning
* Danger

===Navigation bar {organism}===
Formerly navbar, can't be called that because the render method would conflict.

The navigation bar is just that, it is becoming increasingly common on the web and usually contains a title or logo, a menu, and information pertaining to the user state (login, language etc).

===Page header {molecule}===

Currently being produced by '''core_renderer::page_heading''' this is simply a header for the page, by default the only h1 element on the page.

'''Current structure'''

The render method has the following signature:
<code php>
public function page_heading($tag = 'h1');
</code>

The output from the above method is:
<code html5>
<h1>The page heading (from moodle_page::heading)</h1>
</code>

The core_renderer method should not allow the tag to be set. The page heading should always be H1.
If its not an H1 then page header should not be used.

'''Frontend framework examples'''

[http://getbootstrap.com/2.3.2/components.html#typography Bootstrap 2.3.2]
<code html5>
<div class="hero-unit">
<h1>Heading</h1>
<p>Tagline</p>
<p>
<a class="btn btn-primary btn-large">
Learn more
</a>
</p>
</div>
</code>

[http://getbootstrap.com/components/#page-header Bootstrap 3]
<code html5>
<div class="page-header">
<h1>Example page header <small>Subtext for header</small></h1>
</div>
</code>

Foundation doesn't appear to have a page header component.

'''Design thoughts'''

* In Moodle all page headings are set as a single string, we won't be changing this.
* Usually just a plain string sometimes an icon is used, and sometimes a help icon is used.

===Pagination {molecule}===

I like the idea of this being separate to a menu, and to other navigation oriented elements because it should be something that can easily be constructed with a few basic parameters and allow us to achieve consistent pagination throughout Moodle.<br />
It also appeals because this is something that people may want to style differently to their navigation.

'''Markup in various frontend frameworks'''

* [http://getbootstrap.com/2.3.2/components.html#pagination Bootstrap 2.3.2 pagination]
* [http://getbootstrap.com/components/#pagination Bootstrap 3 pagination]
* [http://foundation.zurb.com/docs/components/pagination.html Zurb foundation pagination]

===Progress bars {molecule}===

A pretty simple concept, we already have a couple of ways of producing progress bars within Moodle.

'''Markup in various frontend frameworks'''

[http://getbootstrap.com/2.3.2/components.html#progress Bootstrap 2.3.2]
<code html5>
<div class="progress">
<div class="bar" style="width: 60%;"></div>
</div>
</code>

The following options are offered by Bootstrap 2.3.2:

* Striped
* Striped + Animated
* Stacked (multiple bars forming a single)
* Colours: default (blue), info (light blue), success (green), warning (orange), danger (red)

[http://getbootstrap.com/components/#progress Bootstrap 3]
<code html5>

<div class="progress">
<div class="progress-bar" role="progressbar" aria-valuenow="60" aria-valuemin="0" aria-valuemax="100" style="width: 60%;">
60% Complete
</div>
</div>


<div class="progress">
<div class="progress-bar" role="progressbar" aria-valuenow="60" aria-valuemin="0" aria-valuemax="100" style="width: 60%;">
60%
</div>
</div>
</code>

The following options are offered by Bootstrap 3:

* Striped
* Striped + Animated
* Stacked (multiple bars forming a single)
* Colours: default (blue), info (light blue), success (green), warning (orange), danger (red)

[http://foundation.zurb.com/docs/components/progress_bars.html Zurb foundation]

<code html5>
<div class="progress">
<span class="meter"></span>
</div>
</code>

The following options are offered by Zurb foundation:
* Width
* Colours: default (blue), secondary (grey), success (green), alert (red)
* Corner style: default (square), radius (slight rounding), round

===Search {molecule}===

A pretty common interface molecule, and in fact used as an example in the atomic design blog post we keep referencing.<br />
We don't have a component for searching yet, however we've several search boxes throughout Moodle. The admin setting search box is the first to come to mind for me, followed by the forum search box and course search box.

'''Design considerations'''

Constructed of the following items:
* Text input
* Action (must be a button for submit I imagine)
* Label or short description (optional)
* Collapsible region containing settings etc (optional)

===Table {organism}===

We've two primary table components within Moodle presently '''html_table''' and '''flexible_table''' both of which offer different advantages and disadvantages. This will be a challenge and will really require some proper research and community interaction.

===Timer {atom|molecule}===

... not sure about this one, but we do use it in a couple of places, and we use it on all core sites that have hourly resets so in a way it makes sense to support it and allow it to be styled nicely and easily.

===Tree {organism}===

===User content {organism}===

Think of this like the forum post. We need a common structure in which to display content entered by the user along with information on the user. The users name, picture, date perhaps, title, content, footer (attachments, badges, what ever).
It could be applied to things like forum posts, calendar events etc.

At present we have no abstraction for this.

==Existing renderables and what they will become==
{| class="wikitable"
! Existing renderable
! Description
! Future renderable
! Convenience method (if different)
|-
| action_menu
| UI component for a drop down edit menu
| menu
|
|-
| action_menu_link
| UI component for a menu item in an action menu
| action
|
|-
| action_menu_filler
| UI component for a filler menu item in an action menu
| action
|
|-
| action_menu_link_primary
| UI component for a primary menu item in an action menu
| action
|
|-
| action_menu_link_secondary
| UI component for a secondary menu item in an action menu
| action
|
|-
| action_link
| Link with alt text, and an icon
| action
|
|-
| single_button
| A form with a single button
| button (action with post method)
|
|-
| confirm
| A form with a message and cancel/confirm buttons
| confirmation
|
|-
| single_select
| A form with a single drop down list that submits on change
|
|
|-
| url_select
| A navigation element consisting of a single drop down list of urls that navigates on change
|
|
|-
| doc_link
| A link to the Moodle docs
|
|
|-
| pix_icon
| A small icon
| icon
|
|-
| emoticon_icon
| A small emoticon
|
|
|-
| heading_with_help
| A page heading with a link to help docs
| heading
|
|-
| help_icon
| A help icon that opens a help popup when clicked
| icon_help
|
|-
| help_icon_scale
| A help icon that opens a help popup when clicked
|
|
|-
| user_picture
| A user profile picture which links to their profile
|
|
|-
| container
| A block level element used to surround something. Can have a class to allow specific targeting with CSS.
|
|
|-
| error_text
| An error to show to the user.
|
|
|-
| notification
| A message for the user
|
|
|-
| continue_button
| A message and a button to continue to the next page
|
|
|-
| paging_bar
| A list of next previous and specific page links
|
|
|-
| skip_link_to
| A link to a section on the page
|
|
|-
| skip_link_target
| A target for a matching skip_link_to call
|
|
|-
| heading
| A page heading
| heading
|
|-
| box
| A page section with a border
|
|
|-
| rarrow
| A right arrow
|
|
|-
| larrow
| A left arrow
|
|
|-
| tabtree
| A list of tabs
| menu
|
|-
| tabobject
| A single tab panel
| action
|
|}

==See also==
* [[Render library specification]] - The original output specification for Moodle 2.8
* [[Output element planning]] - Thoughts on initial elements that should be created.
* [[Guide to creating output elements]]
* [[Renderer best practices]]
* [[Element HTML and CSS guidelines]]

User:Sam Hemelryk/Render library element planning

2014-07-22T11:36:33Z

Samhemelryk: Page has been published

This page has now been published as [[Output element planning]]

Output element planning

2014-07-22T11:36:00Z

Samhemelryk: Copy the page from my personal space.

{{Infobox Project
|name = Renderer consistency
|state = Specification
|tracker = https://tracker.moodle.org/browse/MDL-45829
|discussion = https://moodle.org/mod/forum/discuss.php?d=261202
|assignee = Damyon, Sam
}}
{{Work in progress|forumurl=https://moodle.org/mod/forum/discuss.php?d=261202}}
This page documents the proposed core elements, variations of them, what we expect they will contain, and the core_renderer block.

==The user action==

An action in this sense is a collection of data that all pertains to one action that can be taken by the user.
The action, once populated with data can be rendered as is required for the job it is going to fulfil, usually with some relation to the frontend framework in use.
In this way the action could be a link, or a button; it could even be interpreted into a more complex structure.

An action has the following properties:
; content [string]: text content for the link or button.
; url [moodle_url] : the url for the action to take when the user interacts with this action.
; description : a description of the action. Typically used within a title or alt attribute.
; active : True if this is the action the user is current performing.
; enabled : True if the action is possible, false if it is not possible and should be shown as disabled.
; dimmed : True if the action should be shown as dimmed, usually used to the action is hidden to other users.
; method : The preferred method of submitting this action, typically GET but can be set to POST.

It is also possible to add JavaScript actions (component_action objects) to an action. These attach a JS listener to the action that gets executed when the user interacts with the action.
Attached JavaScript actions get initialised when the properties for the action are retrieved so any events must be attached BEFORE the action is rendered, and all renderers must ensure they use the get_attributes() call.

==Grids==

We need to come up with some way to include grids in core, it is desirable to keep it framework agnostic so perhaps a grid object that allows for items to be added and a "width" specified when that occurs. The width would be either a fixed number or a percentage. Steps of 12 seems pretty common.

==Design requirements==
The following concepts need to be accounted for in core, or decisions made on how we choose to support these and where.

===Clearfix===
We have this in core already, bootstrap has it, pretty much every front end framework has it.
Clearfix is more of a design decision, should only be used when require, and only ever applied by a renderer.
This gets special mention as being important, support is already 100%.

===Floats===
Pull left, pull right etc. These are a design decisions and should be implemented by the renderer. Bootstrap caters for these and as such they will be easily catered for in bootstrapbase, however work may be required to get them operational in base.

==Discarded ideas==
The following things are ideas that came up during discussions on what elements are, and what elements we want in core that have being discarded.

==Core atoms, molecules, and organisms==

The following is the atoms, molecules and organisms we believe should be created initially. Of course there will be many more that are required - however this should give us a good grounding of elements to work with for the first conversions.

===Action {atom}===
See the section above about [[#The user action]]

Actions are special atoms the represent an action the user can make.
They can be rendered by a theme as a link, a button or I suppose anything else.
There should be a default for when it is not specified and the renderer in change of producing the current thing can decide whether to use the default and just call ''render'' or if it requires something specific ''render_link'' or ''render_button'' as required.

===Action group {molecule}===
A group of actions, to be rendered to reflect a relation. I suppose the easiest way to think about this is how buttons in the atto editor are grouped together. It is a requirement that may seem a tad absrtracted and irrelevant at first but I think will pop up in several places throughout Moodle when we start converting.

It is basically a collection of actions.

'''Markup in various frontend frameworks'''

* [http://getbootstrap.com/2.3.2/components.html#buttonGroups Bootstrap 2.3.2]
* [http://getbootstrap.com/components/#btn-groups Bootstrap 3]
* [http://foundation.zurb.com/docs/components/button_groups.html Zurb foundation]

===Block {atom}===

Unique to Moodle. This represents a block on the page, and is displayed within a [[#Block region]].
It accepts two arguments, the first is a ''block_contents'' object instance, and the second is the region name the block instance is being shown within.

At present a block is rendered using the '''''core_render::block''''' method. Internally this calls several renderer methods to produce the different parts of a block.
* core_renderer::block_header - Produces a header
** core_renderer::block_controls - Produces controls to display within the header.
* core_renderer::block_content - Produces the actual content of the block.
** core_renderer::block_controls - Used to check if block controls were rendered. PUKE!!!
** core_renderer::block_footer - Produces a footer that actually resides within the content.
* core_renderer::block_annotation - Produces an annotation, used VERY rarely.

'''Current structure'''

The following is the output when called for a navigation block with a bit of extra added to show how a footer is displayed and an annotation.
<code html5>
<a href="#sb-1" class="skip-block">Skip Navigation</a>
<div id="inst4" class="block_navigation block" role="navigation" data-block="navigation" data-instanceid="4" aria-labelledby="instance-4-header" data-dockable="1">
<div class="header">
<div class="title">
<div class="block_action">

</div>
<h2 id="instance-4-header">Navigation</h2>
</div>
</div>
<div class="content">

<div class="footer">

</div>
</div>
<div class="blockannotation">

</div>
</div>
<span id="sb-1" class="skip-block-to"></span>
</code>

===Block region {molecule}===

Unique to Moodle, the block region is a contain for all of the blocks in one location.
We currently have two methods that produce a block region within Moodle, the first is '''''core_renderer::blocks_for_region''''' which adds no surrounding content.
The preferred method '''''core_renderer::blocks''''' adds some embedded information to a common structure.

'''Current structure'''

The following is the structure of the ''core_renderer::blocks()'' method.
<code php>
public function blocks($region, $classes = array(), $tag = 'aside');
</code>

The following is the html output is $region was ''pre'' and the default tag and classes were used.
<code html5>
<aside id="block-region-pre" class="block-region" data-blockregion="pre" data-droptarget="1">

</aside>
</code>

'''Thoughts on this'''

The blocks method is a convenience method and serves an important purpose. However it should not take classes and tag as arguments.<br />
These should certainly only settable within the renderer itself, and if themes wish to change this without wrapping the call they should override the renderer.

Both the data attributes relate to servicing JavaScript functionality. Perhaps they should be moved to a component_action or somehow else integrated with JS rather than with the renderer directly.

Internally it is calling blocks for region, however this should change it should request a array of blocks, convert the array to [[#Block]] elements and call render on each.

'''Proposed HTML structure'''

Much like the current structure but with the data attributes coming through a JS mechanism.

<code html5>
<aside id="block-region-pre" class="block-region">

</aside>
</code>

===Breadcrumb {molecule}===

Currently called the navbar within Moodle, controlled by the '''''navbar''''' class located in lib/navigationlib.php and rendered by '''''core_renderer::navbar()'''''.<br />
Internally it calls moodle_page->navbar->get_items() to get an array containing navigation node items to display in the navigation bar.<br />
It produces a bit of surrounding structure before calling render on each item.

'''Current structure'''

The following shows the structure for two items in the navigation bar presently within Moodle.

<code html5>
<span class="accesshide">Page path</span>
<nav class="breadcrumb-nav">
<ul class="breadcrumb">
<li>
<a href="#">Home</a>
<span class="divider">
<span class="accesshide">
<span class="arrow_text">/</span>
 
</span>
<span class="arrow sep">►</span>
</span>
</li>
<li>
<a href="#">Here</a>
<span class="divider">
<span class="accesshide">
<span class="arrow_text">/</span>
 
</span>
<span class="arrow sep">►</span>
</span>
</li>
</ul>
</nav>
</code>

Notice the excessive amount of markup to make the separator accessible.

'''Markup in various frontend frameworks'''

[http://getbootstrap.com/2.3.2/components.html#breadcrumbs Bootstrap 2.3.2]
<code html5>
<ul class="breadcrumb">
<li>
<a href="#">Home</a>
<span class="divider">/</span>
</li>
<li>
<a href="#">Here</a>
<span class="divider">/</span>
</li>
</ul>
</code>

[http://getbootstrap.com/components/#breadcrumbs Bootstrap 3]
<code html5>
<ul class="breadcrumb">
<li>
<a href="#">Home</a>
</li>
<li>
<a href="#">Here</a>
</li>
</ul>
</code>

[http://foundation.zurb.com/docs/components/breadcrumbs.html Zurb foundation]
<code html5>
<ul class="breadcrumb">
<li>
<a href="#">Home</a>
</li>
<li>
<a href="#">Here</a>
</li>
</ul>
</code>

'''Design considerations'''

* The currently active page should be marked with a class.
* The current item should probably not be a link MDL-46037
* [http://www.w3.org/TR/2007/WD-aria-role-20070601/#breadcrumbs wia-aria breadcrumb role]
* The divider perhaps could come through CSS with these changes to avoid markup necessary to make it accessible (in combination with the above).

'''Implementation thoughts'''
* Owns an array of [#Action {atoms}]

===Buttons {atom}===

This will be both an element and a representation of a [#Action {atom}].<br />
Obviously buttons can serve different purposes and roles so have several easily reachable customisations is probably a wise idea.

'''Current structure'''
None, presently you produce a button when you need it so there are several throughout Moodle.

'''Markup in various frontend frameworks'''

[http://getbootstrap.com/2.3.2/base-css.html#buttons Bootstrap 2.3.2] and [http://getbootstrap.com/css/#buttons Bootstrap 3]
<code html5>
<button type="button" class="btn btn-default">Default</button>

<a href="#" class="btn btn-default btn-lg active" role="button">Link</a>

<input class="btn btn-default" type="button" value="Input">
</code>

Customisations available through Bootstrap:
* Purposes: default, primary, success, info, warning, danger, link
* Sizes: large, default, small, extra-small
* Block level (wider)
* States: Active, disabled.

[http://foundation.zurb.com/docs/components/buttons.html Zurb foundation]
<code html5>
<a href="#" class="button">Default Button</a>
</code>

Customisations available through Zurb Foundation:
* Purposes: default, secondary, success, alert
* Sizes: large, default, small, tiny
* Corner style: radius, round
* Expanded (wider)
* States: disabled

===Calendar {organism}===

A simple idea really, apparently not already covered by the frontend frameworks being referenced during the creation of the doc.
The display of the calendar is fixed, but it can contain content for each day shown.

The calendar should have several views, perhaps these are separate organisms, perhaps not.

* Compact month
* Month
* Week
* Day

Each day could:
* Contain an action with an icon for events, and link to the fullday display.
* Have an associated action to load and display the events in a tooltip.

===Collapsible region {molecule}===

We use these in several places within Moodle. I could not find a reference to this concept in any of the frontend frameworks I looked at.
The concept is simple - you have a heading and an icon with content. By default the content is hidden, when the user clicks the heading and/or the icon the content is revealed.

As noted we do this in several places within Moodle, it would be good to have a single way of displaying this idea of a collapsible region.

'''Design thoughts'''
* It should support an optional collapse/expand all trigger action.
* We want to be able to use it both inside and outside of forms.
* It should be usable in situations like the combo list frontpage component as well.
* Will obviously have a JS component as without JS it would not work.

===Confirmation {molecule}===

A simple concept used regularly in Moodle to confirm a users intention to perform an actions. Most commonly seeing when deleting content.
The structure is relatively basic in Moodle at present.
* A message
* A forwards button
* A back button

'''Current structure'''

The method '''''core_renderer::confirm''''' does the rendering at present. Its signature is as follows:
<code php>
public function confirm($message, $continue, $cancel);
</code>

The output it produces is like:
<code html5>
<div class="generalbox" id="notice">
<p>The message goes here</p>
<div class="buttons">

</div>
</div>
</code>

'''Design throughts'''

This component does not have a title. I believe at present some pages use ''core_renderer::heading'' to produce a title if they wish. Obviously we want consistency of style so I believe it would be wise to add a title property that can be optionally set and then in our documentation for this element recommend that a title is always provided.<br />
It will mean re-factoring our uses to set a title and if a heading is being manually added remove it.

===Continue {molecule}===

This is much like the confirmation molecule but with a single button.<br />
At present we have '''''core_renderer::continue_button''''' that produces a single button. However this design is very poor as more often than not a message is included in the page to describe the purpose of the continue button. This is really an integral part of the continue button.

'''Current structure'''

Currently we have ''core_renderer::continue_button'' to render a single continue button.
<code php>
public function continue_button($url);
</code>

Internally it creates a single_button component and then calls render on that.

'''Design thoughts'''
Our element should have a message and a button. To make it easy to migrate the constructor should accept a URL instead of a button and do the same conversion as the current method is doing.

===Choice {molecule}===
Not sure about this one quite yet.
A description with 2 or more actions allowing the user to select the next step.
Think of it like when editing a module you get: Cancel, Save and return to course, Save and display

Perhaps both [#Confirmation {molecule}] and [#Continue {molecule}] should be just instances of this.

Hmm perhaps that would not be as clear as this and we should have this separate choice molecule.

===Divider {atom}===
Think horizontal rule.

===Dropdowns {molecule}===

So this is a pretty simple concept, but you've got to think of it as a separate entity. A dropdown is a menu that appears when the user interacts with an action.

The action could take one of three forms:
* From button
* From link
* From icon

Of course that is handled by the [#Action {atom}] noted above. Worth noting is that we will need some way to toggle these actions as dropdowns. Perhaps it is worth making that a property of the action atom.

The dropdown itself will likely contain more actions, and I suppose additional dropdowns to form sub menus. Sub-menus in my mind are required. We don't use them in core, but they are functionally possible through things like the custom menu and I know for a fact that many sites have sub menus.

'''Markup in various frontend frameworks'''

[http://getbootstrap.com/2.3.2/components.html#dropdowns Bootstrap 2.3.2]

<code html5>
<div class="dropdown">

<ul class="dropdown-menu" role="menu" aria-labelledby="dLabel">
<li><a tabindex="-1" href="#">Action</a></li>
<li><a tabindex="-1" href="#">Another action</a></li>
<li><a tabindex="-1" href="#">Something else here</a></li>
<li class="divider"></li>
<li><a tabindex="-1" href="#">Separated link</a></li>
</ul>
</div>
</code>

[http://getbootstrap.com/components/#dropdowns Bootstrap 3]
<code html5>
<div class="dropdown">
<button class="btn dropdown-toggle sr-only" type="button" id="dropdownMenu1" data-toggle="dropdown">
Dropdown
<span class="caret"></span>
</button>
<ul class="dropdown-menu" role="menu" aria-labelledby="dropdownMenu1">
<li role="presentation"><a role="menuitem" tabindex="-1" href="#">Action</a></li>
<li role="presentation"><a role="menuitem" tabindex="-1" href="#">Another action</a></li>
<li role="presentation"><a role="menuitem" tabindex="-1" href="#">Something else here</a></li>
<li role="presentation" class="divider"></li>
<li role="presentation"><a role="menuitem" tabindex="-1" href="#">Separated link</a></li>
</ul>
</div>
</code>

[http://foundation.zurb.com/docs/components/dropdown.html Zurb foundation]
<code html5>
<a href="#" data-dropdown="drop1">Has Dropdown</a>
<ul id="drop1" class="f-dropdown" data-dropdown-content>
<li><a href="#">This is a link</a></li>
<li><a href="#">This is another</a></li>
<li><a href="#">Yet another</a></li>
</ul>
</code>

===Forms {organism}===

This is an advanced organism and would be quite a bit of work to create in Moodle as we'd need to translate from QuickForms to elements for rendering.
It would be worthwhile doing this however, and would be a good way of quickly showing our new work.

'''Frontend framework structures'''
* [http://getbootstrap.com/2.3.2/base-css.html#forms Bootstrap 2.3.2]
* [http://getbootstrap.com/css/#forms Bootstrap 3]
* [http://foundation.zurb.com/docs/components/forms.html Zurb foundation]

All of those are quite in-depth and offer a range of configurations.
We should carefully consider these when analysing our work here.

===Headings {atom}===

Currently handled by '''core_renderer::heading'''.

* h1 - h6
* Optional icon
* Optional help icon

'''Current structure'''

The render method is currently:
<code php>
public function heading($text, $level = 2, $classes = null, $id = null);
</code>

The output generated by this is, assuming we use the default level, classes, and id.
<code html5>
<h2>I am a heading</h2>
</code>

Whats worth noting is that the render method should not accept level and classes as arguments.
These should only be set by the render method and should not be directly influenced.

===Image {atom}===

There are really two types of images to focus on here, or really two ways to display an image to focus on here.<br />
# Standard images
# Thumbnail images

Each of these would share some common properties:
* Image
* Description (alt/title)
* Size
* Action (making it a link) - This would actually make it a molecule, we would have to consider this and either have a new element, drop the ability to wrap in an action, or simply ignore this inconsistency.

===Image - Icon {atom}===

This covers the display of an icon. Should be a separate element from image as really they should be treated individually.
Within Moodle there are a few classifications of icons to consider:
* Standard icons
* Help icon (popup, tooltip)
* Loading icon (really regular icon but worth showing separately as its only seen when required)

===Image - Logo {molecule}===

We don't have this within core Moodle at present, however just about every theme I have seen uses a logo. I think it is about time we considered having a logo element.
I imagine it would become a sort of hero element, likely with an associated action (back home by default).

===Image - Profile picture {molecule}===

We already have a user_picture component within Moodle. It can be found in lib/outputcomponents.php.<br />
It has two render methods, '''''core_renderer::user_picture''''' and '''''core_renderer::render_user_picture'''''.

'''Current structure'''

The following is the output structure for the user picture:
<code html5>
<a href="#" id="userpicture_randomid">
<img src="#" alt="Picture of Joe" title="Picture of Joe" class="userpicture" width="[35, 100, XX]" height="[35, 100, XX]" />
</a>
</code>

What you'll notice about this is that the link has no attributes marking it as a user picture link.

The PHP code for the user_picture object itself is really quite in depth and complex. The component serves the user profile fields required to render a user picture. This is good in the scope of the component but would be bad within the scope of an element.<br />
Don't you wish we had a proper user object!

===Link {atom}===
This will be both an element and a representation of a [#Action {atom}].

Theres not too much more to explain about links, they don't tend to take states other than the default active, enabled and dimmed.<br />
It is worth mentioning that devs will be encouraged to use actions and not links unless absolutely necessary.<br />
The render method for this atom must typehint an action rather than a link.

'''Prototype example'''
* The atom: https://github.com/samhemelryk/moodle/blob/output_prototype_5/local/output/classes/output/link.php
* The convenience method: https://github.com/samhemelryk/moodle/blob/output_prototype_5/local/output/classes/output/renderer.php#L149
* The render method: https://github.com/samhemelryk/moodle/blob/output_prototype_5/local/output/classes/output/renderer.php#L211

===List {molecule}===

This is a pretty simple example and something I am sure you are all familiar with. A list is simply a collection of items. Usually represented using a UL or OL tag in markup although worth noting can be styled completely differently to the default.
There are three main types of lists used within Moodle:
* Ordered list
* Unordered list
* Presentation list (currently our unlist)

The list is a molecule because it should be able to accept other elements as items. E.g. it should be content independent.

===Menu {molecule}===

A menu is a familiar concept for any site. Probably the first thing that pops to mind for many is the navbar, but I want to consider that a separate component as a navbar can consist of more than just menu items.
I think a menu should be a collection of actions the user can perform. Perhaps with some form of hierarchy.

We have different types of menus within Moodle:
* The custom menu is one users can directly create, with dropdown downs and sub dropdowns.
* The action_menu component we have in core uses icons as actions and can have a dropdown.

These should be combined into a single menu element that takes items as an argument, likely actions + dropdowns + dividers to start with would be perfect.

We would likely need to deal with the display of the menu with properties to allow constructing code to ''request'' a particular style of menu. The renderer should be what actually gets to decide, but for the purposes of re-use having properties and a single render_method is better than having multiple render methods.<br />
The following is my initial thoughts on menu structure:
* Direction: Horizontal, Vertical
* Design: Default, Tabs,
* Style: Default, Links, Buttons, Icons

===Notification {atom}===
* Info
* Success
* Warning
* Danger

===Navigation bar {organism}===
Formerly navbar, can't be called that because the render method would conflict.

The navigation bar is just that, it is becoming increasingly common on the web and usually contains a title or logo, a menu, and information pertaining to the user state (login, language etc).

===Page header {molecule}===

Currently being produced by '''core_renderer::page_heading''' this is simply a header for the page, by default the only h1 element on the page.

'''Current structure'''

The render method has the following signature:
<code php>
public function page_heading($tag = 'h1');
</code>

The output from the above method is:
<code html5>
<h1>The page heading (from moodle_page::heading)</h1>
</code>

The core_renderer method should not allow the tag to be set. The page heading should always be H1.
If its not an H1 then page header should not be used.

'''Frontend framework examples'''

[http://getbootstrap.com/2.3.2/components.html#typography Bootstrap 2.3.2]
<code html5>
<div class="hero-unit">
<h1>Heading</h1>
<p>Tagline</p>
<p>
<a class="btn btn-primary btn-large">
Learn more
</a>
</p>
</div>
</code>

[http://getbootstrap.com/components/#page-header Bootstrap 3]
<code html5>
<div class="page-header">
<h1>Example page header <small>Subtext for header</small></h1>
</div>
</code>

Foundation doesn't appear to have a page header component.

'''Design thoughts'''

* In Moodle all page headings are set as a single string, we won't be changing this.
* Usually just a plain string sometimes an icon is used, and sometimes a help icon is used.

===Pagination {molecule}===

I like the idea of this being separate to a menu, and to other navigation oriented elements because it should be something that can easily be constructed with a few basic parameters and allow us to achieve consistent pagination throughout Moodle.<br />
It also appeals because this is something that people may want to style differently to their navigation.

'''Markup in various frontend frameworks'''

* [http://getbootstrap.com/2.3.2/components.html#pagination Bootstrap 2.3.2 pagination]
* [http://getbootstrap.com/components/#pagination Bootstrap 3 pagination]
* [http://foundation.zurb.com/docs/components/pagination.html Zurb foundation pagination]

===Progress bars {molecule}===

A pretty simple concept, we already have a couple of ways of producing progress bars within Moodle.

'''Markup in various frontend frameworks'''

[http://getbootstrap.com/2.3.2/components.html#progress Bootstrap 2.3.2]
<code html5>
<div class="progress">
<div class="bar" style="width: 60%;"></div>
</div>
</code>

The following options are offered by Bootstrap 2.3.2:

* Striped
* Striped + Animated
* Stacked (multiple bars forming a single)
* Colours: default (blue), info (light blue), success (green), warning (orange), danger (red)

[http://getbootstrap.com/components/#progress Bootstrap 3]
<code html5>

<div class="progress">
<div class="progress-bar" role="progressbar" aria-valuenow="60" aria-valuemin="0" aria-valuemax="100" style="width: 60%;">
60% Complete
</div>
</div>


<div class="progress">
<div class="progress-bar" role="progressbar" aria-valuenow="60" aria-valuemin="0" aria-valuemax="100" style="width: 60%;">
60%
</div>
</div>
</code>

The following options are offered by Bootstrap 3:

* Striped
* Striped + Animated
* Stacked (multiple bars forming a single)
* Colours: default (blue), info (light blue), success (green), warning (orange), danger (red)

[http://foundation.zurb.com/docs/components/progress_bars.html Zurb foundation]

<code html5>
<div class="progress">
<span class="meter"></span>
</div>
</code>

The following options are offered by Zurb foundation:
* Width
* Colours: default (blue), secondary (grey), success (green), alert (red)
* Corner style: default (square), radius (slight rounding), round

===Search {molecule}===

A pretty common interface molecule, and in fact used as an example in the atomic design blog post we keep referencing.<br />
We don't have a component for searching yet, however we've several search boxes throughout Moodle. The admin setting search box is the first to come to mind for me, followed by the forum search box and course search box.

'''Design considerations'''

Constructed of the following items:
* Text input
* Action (must be a button for submit I imagine)
* Label or short description (optional)
* Collapsible region containing settings etc (optional)

===Table {organism}===

We've two primary table components within Moodle presently '''html_table''' and '''flexible_table''' both of which offer different advantages and disadvantages. This will be a challenge and will really require some proper research and community interaction.

===Timer {atom|molecule}===

... not sure about this one, but we do use it in a couple of places, and we use it on all core sites that have hourly resets so in a way it makes sense to support it and allow it to be styled nicely and easily.

===Tree {organism}===

===User content {organism}===

Think of this like the forum post. We need a common structure in which to display content entered by the user along with information on the user. The users name, picture, date perhaps, title, content, footer (attachments, badges, what ever).
It could be applied to things like forum posts, calendar events etc.

At present we have no abstraction for this.

==Existing renderables and what they will become==
{| class="wikitable"
! Existing renderable
! Description
! Future renderable
! Convenience method (if different)
|-
| action_menu
| UI component for a drop down edit menu
| menu
|
|-
| action_menu_link
| UI component for a menu item in an action menu
| action
|
|-
| action_menu_filler
| UI component for a filler menu item in an action menu
| action
|
|-
| action_menu_link_primary
| UI component for a primary menu item in an action menu
| action
|
|-
| action_menu_link_secondary
| UI component for a secondary menu item in an action menu
| action
|
|-
| action_link
| Link with alt text, and an icon
| action
|
|-
| single_button
| A form with a single button
| button (action with post method)
|
|-
| confirm
| A form with a message and cancel/confirm buttons
| confirmation
|
|-
| single_select
| A form with a single drop down list that submits on change
|
|
|-
| url_select
| A navigation element consisting of a single drop down list of urls that navigates on change
|
|
|-
| doc_link
| A link to the Moodle docs
|
|
|-
| pix_icon
| A small icon
| icon
|
|-
| emoticon_icon
| A small emoticon
|
|
|-
| heading_with_help
| A page heading with a link to help docs
| heading
|
|-
| help_icon
| A help icon that opens a help popup when clicked
| icon_help
|
|-
| help_icon_scale
| A help icon that opens a help popup when clicked
|
|
|-
| user_picture
| A user profile picture which links to their profile
|
|
|-
| container
| A block level element used to surround something. Can have a class to allow specific targeting with CSS.
|
|
|-
| error_text
| An error to show to the user.
|
|
|-
| notification
| A message for the user
|
|
|-
| continue_button
| A message and a button to continue to the next page
|
|
|-
| paging_bar
| A list of next previous and specific page links
|
|
|-
| skip_link_to
| A link to a section on the page
|
|
|-
| skip_link_target
| A target for a matching skip_link_to call
|
|
|-
| heading
| A page heading
| heading
|
|-
| box
| A page section with a border
|
|
|-
| rarrow
| A right arrow
|
|
|-
| larrow
| A left arrow
|
|
|-
| tabtree
| A list of tabs
| menu
|
|-
| tabobject
| A single tab panel
| action
|
|}

==See also==
* [[User:Sam Hemelryk/Render library element planning]]
* [[Guide to creating output elements]] ''originally written at [[User:Sam Hemelryk/Creating renderable components]]''
* [[User:Sam Hemelryk/Renderer best practices]]
* [[User:Sam Hemelryk/CSS style guidelines]]

Render library specification

2014-07-22T11:24:47Z

Samhemelryk: /* Related links */

{{Infobox Project
|name = Renderer consistency
|state = Specification
|tracker = https://tracker.moodle.org/browse/MDL-45770
|discussion = https://moodle.org/mod/forum/discuss.php?d=261202
|assignee = Damyon, Sam
}}
{{Work in progress|forumurl=https://moodle.org/mod/forum/discuss.php?d=261202}}
== Project Goals ==
* 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.

== Benefits ==
* Make it easier to create user interfaces.
* Make it easier to style the user interface.
* Make it easier for themers to customise the user interface.
* Better facilitate frontend frameworks in Themes.
* Better facilitate usable and accessible design.
* Give Moodle a more consistent look and feel.
* Improve site performance by reducing the CSS footprint.

==Understanding renderers in Moodle==

Renderers have been around since Moodle 2.0 and are now the requirement when writing any code that produces output.
Renderers come in many shapes and forms depending upon the developers take on how output should be produced.

When renderables were introduced - the API was designed to make it easy for existing code to be updated to make use of renderers and renderables. A renderable is an interface with no methods, so any existing class could be made to implement renderable. This means that the renderable class can be a mixture of data and methods that perform logic associated with the module. This also means that the renderer can call those methods on the renderable class - effectively using the API of the module. The problem with this - is that it complicates the renderer and makes it harder to override in a theme - the themer requires knowledge about the API for the module. Some renderables in core are built as separate classes - only used for the purpose of supplying data to the renderer - here there is a clear separation of the logic - and the properties of the renderable are made up of only simple types that can be checked for in the renderer - e.g. access checks are done in advance and the result is put into a boolean in the renderable. The current renderers / renderables in Moodle are a mixture of these styles.

Because there is no mandated organisation, nor has there ever been, there is immense variation in what constitutes content to a renderer.

One of the upsides to our current render system is that you are not limited to having a single renderer for a component, you can make use of language capabilities and the output framework and create layers of renderers to cut back code duplication and to aid in preparing a base for consistent structuring and output.

Into the equation we add targets and subtypes. Targets allow us to create both standard renderers and renderers specific to the needs of the output method. Standard being HTML, without output methods including CLI, AJAX, HTML email and plain text email.

People have never being constrained as to how they implement a renderer. We've being happy enough to simply guide them towards using renderers because of the benefits they provide and while there are numerous benefits there are two fundamental benefits:

; A change in thinking : It requires developers to think about their code organisation. Renderers were introduced in a time before Object Orientation was used in Moodle, and logic and output were tightly intermingled in most code. Renderers were about separating logic and design and while what was created was not always perfect it was always an improvement.

; An extensible approach to output : The render system allows for the overriding of renderers to occur. Theme designers can overwrite any renderer in their theme. The more that renderers that get implement the more of Moodle you can customise.

==Understanding themes==

Themes are without a doubt the most widely customised plugin provided by Moodle. But we are currently struggling with several problems with renderers and themes as they are being implemented currently.

1. There is no strict relationship between the HTML generated by a renderable, and the accompanying CSS that is required to make it display properly. The HTML is coded in the renderer - and then the CSS is added, either directly to the styles.css for the plugin in an unorganised way - or directly in the CSS in the theme - again in a loosely organised way. There is no systematic way to determine if any line of CSS is still in use - and there is no simple way to find the CSS that requires updating when the HTML is updated.

2. The CSS framework (bootstrap 2, bootstrap 3, zurb, pureio) specific attributes for renderables are currently being hardcoded in the HTML generated by the renderables. This prevents themers from using a different framework without creating an impossible amount of work to overwrite every renderer in Moodle.

==So what is the problem==

There are several. Lets be blunt about this. This specification is not a single task. It is about improving the state of output in Moodle and there are going to be several steps in achieving this. On a positive note these steps can in many cases be broken down into granular tasks that can be worked on asynchronously.
First lets understand some of the major problems:
* We have no established best practices, nor even documentation on what constitutes a good renderer, or considerations that should be paid mind in planning and designing of code.
* We have no established style guide, nor pattern library, nor element library, nor anything that could be referenced when someone starts building a new user interface - or creating a new theme.
* Inconsistency - because of a lack of best practice documentation and examples, there is huge variation in the design of our different modules. Different modules exhibit different problems such as a mixing of logic and output and code duplication.
* Developers are encouraged to push functionality boundaries in order to take it places observed in other projects or to challenge oneself. While consistency is often talked about it is rarely observed when designing output. We end up with numerous "similar" looking widgets all functioning slightly differently and consequently there is a feeling that this is the way to achieve a new fresh look. (E.g. we have multiple implementations of a "toolbar" - one in Atto and one in EditPDF).
* Existing renderer implementations vary widely and in many cases contain logic they should not. Access checks, database queries, object manipulations. All of which should not be present as it introduces muddling of concepts and logic that must be duplicated and then maintained for anyone overriding renderers.
* Themers have a mammoth task at present in applying a consistent style to Moodle, or in choosing to implement a new frontend framework (bootstrap, foundation, pureio etc). Our lack of organisation in the output leaves a lot to be desired. Having the theme responsible for choosing a frontend framework is the right way to handle this, however backend Moodle doesn't support themeing as well as it should be/could be.
* On top of the above it introduces a need to override several renderers should you want to create a consistent style and because of inconsistent renderer implementations this can easily lead to a maintenance nightmare. E.g. the user_picture renderable is not used in mod_forum - so there is no way to override it there.
* JavaScript introduces problems of its own. We are doing more and more with JavaScript these days. However there is a heavy dependence on the output that gets produced and the JavaScript enhancing it. In a lot of cases the relationship is ill defined and due to the complexity and structure of the JavaScript overriding the output structure of the rendered component is completely impossible for all but the most experienced developers.
* Inline with the above we lack good examples and documentation on how to deliver output templates for JavaScript User Interfaces as well as the creation, and manipulation of HTML structures that are enhanced by JavaScript.

== Identified issues==
There is a general trend in the problems noted, when looking at output we lack organisation, documentation, and consistency across the board. However the actual issues we are focusing on in this spec can be identified as below:

* Lack of a style guide / element library / pattern library.
** Leading to inconsistent output and style.
** Increased workload due to usability and accessibility thinking and testing needing to occur repetitively.
** Increased workload due to multilang (rtl) support usually coming after the designs of new output.
* Inconsistent renderer implementations.
** Lack of best practices.
** Lacking plus outdated documentation.
** Logic-full renderers greatly hinder theming.
** An unnecessarily increased requirement to understand both PHP and Moodle code as each renderer differs and are usually poorly documented.
* No abstraction from CSS framework.
** Without organised structure classes are applied in a chaotic fashion leading to the requirement to duplicate core styles.
** As there is no core styles newly created output widgets need to be styled in all base themes leaving chance of design regressions occurring in predominantly major upgrades but occasionally minor releases as well.
** Inconsistent output structure ensures CSS quickly balloons as styles need to be both created and copied to several areas.
* Poor linking between UI components and the JavaScript.
** Ill-defined link between output and the JavaScript enhancing it.
** No common technique to template UIs generated by javascript

==Manageable Tasks==
The following are the major tasks we have identified so far. These tasks can be though of as Epic's, or tasks for which we will create subtasks (if this output specification itself becomes an Epic).
Within this section will include notes and implementation ideas on the major tasks we've identified.

* [[#Define the elements that make up Moodle|Choose an output methodology and begin defining core elements]]
* [[#Element library and style guide|Create an element library and accompanying style guide]]
* [[#Style guide|Create a style guide document]]
* [[#Define and document renderer best practices|Define and document renderer best practices]]
* [[#Define and update the JS documentation|Update the JavaScript documentation]]
* [[#Update renderer documentation|Update renderer documentation]]
* [[#Update theme documentation and theme tutorials|Update theme documentation and theme tutorials]]
* [[#Progressively convert renderers|Progressively convert renderers]]

===Define the elements that make up Moodle===
There are several tasks that will go into this, but the first and most important will be deciding upon an organisational methodology. Some way to compartmentalise the Moodle output.
At present a reducing granularity system is looking the most appealing. Go and read [http://bradfrostweb.com/blog/post/atomic-web-design/ Atomic Design] written by Brad Frost - it describes very well the type of compartmentalisation we are proposing.

Once a system has being chosen the following tasks can be tackled:
* Identify the layers we require.
* Define the boundaries and responsibilities of those layers.
* Identify the initial set of elements, likely the finest granularity first as I imagine starting at the bottom and working up will be the best way to proceed.

Further elements (those relating to Moodle will be defined as part of the element library work).

===Element library and style guide===
Draft docs for element library tool: [[Element_Library]]

Add an admin tool that can show a categorised list of renderable objects for each plugin/and core - filled with test data. The goal of this tool is to:

* 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 (in a well defined structure) they can use when building their own pages

The tasks here will be:
* Spec the element library tool with regard to our chosen element methodology.
* Create the element library tool.
* Establish a definition method of elements, and compositions of elements as renderables.
* Define the core elements from the task above in code somehow and verify the element library tool reveals them.
* Finally 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, grid. These renderables should be structured into layers, starting from renderables that cannot be broken into smaller parts, up to widgets made of smaller renderables, up to layouts (and possibly up to entire pages). 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

On top of this there is functionality that would be great to add to it:

* Validate that the renderer/renderable follows best practice (no DB queries, complex types, complex logic)
* Provide responsive testing immediately within the tool. Adjusting the viewing area on queue to allow both developers and designers to experience how the individual renderables respond in varying presentation medias.
* Provide language direction testing immediately within the tool. Like the above allow designers and developers to quickly experience a renderable in a different language directions.
* Renderable linear reporting. So that you can see which other renderables make use of this renderable and which renderables get used by this renderable. This will be hugely helpful in judging impact when themeing.

===Thoughts on naming===

We will need to define useful names for the different categories of renderables so that we can effectively organise them and provide guidelines for writing each type - the names are a small part of this solution but will possibly be a point for contention. Different frameworks have different names for these things and people will prefer something that sounds like something they are already using.

(draft!) Categories for renderables - taken straight from Atomic design

http://bradfrostweb.com/blog/post/atomic-web-design/

* Atoms == Tiny reusable elements that cannot be broken down into smaller elements
* Molecules == Relatively simple combinations of atoms built for reuse
* Organisms == Organisms are groups of molecules joined together to form a relatively complex, distinct section of an interface.
* Templates == Layout files in a theme
* Pages == The actual pages in Moodle

Refs for categorizing patterns
* http://bradfrostweb.com/blog/post/atomic-web-design/
* http://oocss.org/
* http://alistapart.com/blog/post/getting-started-with-pattern-libraries
* http://style.codeforamerica.org/

===Style guide===
This has two real advantages.

# First assuming this will be developed initially while defining the elements that will make up Moodle output and will aid us in verifying what we are doing. If it can be easily documented then we are on the right track. If we start encountering to many conditions and or too much variation then we are drifting off track.
# When defining new elements we are able to use our style guide to do so and it'll provide us measure of how Moodle output evolves.

===Define and document renderer best practices===

This will be tricky and no doubt how we decide to define a best practice will have to have regard for the output methodology we choose.

===Update the JavaScript documentation===

Discuss and agree on a best practice for writing JS that depends on HTML structures in the DOM (e.g. progressive enhancement - or just ids for action listeners) (perhaps a specific renderable for a JS region)

===Update renderer documentation===
This will of course need to be done after the element library and renderer best practices but should be pretty simple at that point.
* Read and rate each of the existing docs pages (see related links below)
* Write new complete docs for everyone (at [[Output API]])
* Cross link old docs to the new ones

===Update theme documentation and theme tutorials===
There are likely the most well documented plugin type within Moodle. There are good specification docs, good 2.0 conversion docs and good tutorials on many aspects of theming.
Many of these pages will need to be updated to reflect best practices and such after we start ticking off some of the other tasks.

===Progressively convert renderers===
This is the very last task really - but we will start work on it in parallel with creating the new set of core renderables (to prove the design is usable). There is no deadline for this to be complete - and it will take a long time to convert all the existing renderers (and code not using renderers).

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

Goals for renderers - should be devoid of logic for these reasons:
* Theme overridden renderers do not need to be updated when logic is changed
* Themers can override renderers without understanding all the logic
* Renderables can be filled with mock data for display in the element library

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 not related to output
* calling the database

A “renderable” is:
* All the data required to generate the output.
* Properties should be simple data types only, or renderables, or array of those

== Evaluations of some existing renderers / renderables ==
Existing renderer styles - because there are few rules/guidelines for how renderers should be written - there are differing examples of renderers in core. Looking at the 3 of the better maintained modules to see how they are implemented will be useful in evaluating the benefits of any stricter rules for renderers.
=== Assign ===
Contains a list of renderables (in renderables.php) and a single renderer. The logic is mostly out of the renderer methods (pre-calculated and added as data to the renderer). There are some cases when renderables could be broken down further - e.g. the expand/collapse on the submission history (mod/assign/yui/src/history/js/history.js). Also the assignment sub-plugins do not use renderers (and they should).

=== Quiz ===
Uses a lot of renderers - but not renderables. The renderer methods directly call methods of the business logic to determine what to display. e.g. "attemptobj->get_access_manager(time())->attempt_must_be_in_popup()". This is not terrible for a themer trying to override a renderer method because the calls are mostly simple - but it is a grey area for when this becomes business logic in the renderer (and would e.g. need updating to fix bugs etc). If we want to add these renderer methods to the element library - it would require a way to pass mock business logic classes to the renderer methods (and a way for the generator to return a renderer and a method - instead of only a renderable).

=== Workshop ===
Very nice renderers and renderables in workshop. Would only need updating to re-use core renderables instead of using html_writer directly - and adding the existing renderables to the element library.

=== Badges ===
Mix of renderer methods and renderables. This is similar to quiz where the renderer is calling lots of methods of the business model in the renderer methods and has the same effect (harder to override, maintain etc). To add these renderer methods to the element library would require the same sort of changes as mentioned in quiz.

== Example of forum post renderer using composition ==
This is not a real example (yet), it's just a demonstration of the type of renderers we should be aiming for (using composition etc). This structure would be created in the render_form_post method of the forum renderer. This method would receive a forum_post renderable containing only data - and build up this structure of smaller renderable components, then return the result of calling render(x) on each of the smaller renderables.

[[Image:forumpost-renderer-breakdown.png|center|500px|Example forum renderer]]

== Initial thoughts on renderables and what we should provide (Draft) ==
This list is not intended to be the final list - it is more of a scoping exercise. One of the tasks from this project is to decide on the full set of required renderables.
There are several renderables within Moodle that have being included in this table and we will need to look closely at how they fit within our chosen model and whether they are still required.

{| class="nicetable"
|-
! Name
! Description
! Source (links)
|-
| action_menu
| UI component for a drop down edit menu
| Existing renderable (should be renamed "menu")
|-
| action_menu_link
| UI component for a menu item in an action menu
| Existing renderable
|-
| action_menu_filler
| UI component for a filler menu item in an action menu
| Existing renderable
|-
| action_menu_link_primary
| UI component for a primary menu item in an action menu
| Existing renderable
|-
| action_menu_link_secondary
| UI component for a secondary menu item in an action menu
| Existing renderable
|-
| action_link
| Link with alt text, and an icon
| Existing renderable
|-
| single_button
| A form with a single button
| Existing renderable
|-
| confirm
| A form with a message and cancel/confirm buttons
| Existing renderable
|-
| single_select
| A form with a single drop down list that submits on change
| Existing renderable
|-
| url_select
| A navigation element consisting of a single drop down list of urls that navigates on change
| Existing renderable
|-
| doc_link
| A link to the Moodle docs
| Existing renderer method
|-
| pix_icon
| A small icon
| Existing renderable
|-
| emoticon_icon
| A small emoticon
| Existing renderable
|-
| heading_with_help
| A page heading with a link to help docs
| Existing renderer method
|-
| help_icon
| A help icon that opens a help popup when clicked
| Existing renderable
|-
| help_icon_scale
| A help icon that opens a help popup when clicked
| Existing renderable
|-
| user_picture
| A user profile picture which links to their profile
| Existing renderable
|-
| container
| A block level element used to surround something. Can have a class to allow specific targeting with CSS.
| Existing renderable
|-
| error_text
| An error to show to the user.
| Existing renderable
|-
| notification
| A message for the user
| Existing renderable
|-
| continue_button
| A message and a button to continue to the next page
| Existing renderable
|-
| paging_bar
| A list of next previous and specific page links
| Existing renderable
|-
| skip_link_to
| A link to a section on the page
| Existing renderable
|-
| skip_link_target
| A target for a matching skip_link_to call
| Existing renderable
|-
| heading
| A page heading
| Existing renderable
|-
| box
| A page section with a border
| Existing renderable
|-
| rarrow
| A right arrow
| Existing renderable
|-
| larrow
| A left arrow
| Existing renderable
|-
| tabtree
| A list of tabs
| Existing renderable
|-
| tabobject
| A single tab panel
| Existing renderable
|-
| toolbar *new
| A container for toolbar button groups
| Bootstrap equiv btn-toolbar (needs aria support)
|-
| toolbar-group *new
| A group of toolbar buttons
| Bootstrap equiv btn-group (needs aria support)
|-
| toolbar-button *new
| A toolbar button
| Bootstrap equiv btn (needs aria support)
|-
| toolbar-menu *new
| A toolbar button that opens a drop down menu
| Bootstrap equiv nested btn-groups (needs aria support)
|-
| navbar *new
| The navigation bar that shows at the top of the page
| Bootstrap equiv navbar - There is an existing renderer method that needs converting into renderables
|-
| navbar_item *new
| Items in the navigation bar that shows at the top of the page
| Bootstrap equiv list item in a navbar - There is an existing renderer method that needs converting into renderables
|-
| navbar_item *new
| Items in the navigation bar that shows at the top of the page
| Bootstrap equiv list item in a navbar - There is an existing renderer method that needs converting into renderables
|-
| progress_bar *new
| A bar showing progress of something
| Bootstrap equiv progress_bar - There is an existing moodle class that needs converting to use renderables
|-
| progress_bar *new
| A bar showing progress of something
| Bootstrap equiv progress_bar - There is an existing moodle class that needs converting to use renderables
|-
| panel *new
| A container with a heading and borders
| Bootstrap equiv panel, panel-heading, panel-body, panel-footer
|-
| vertical-list *new
| A vertical list of items
| Bootstrap equiv - list-group
|-
| horizontal-list *new
| A horizontal list of items
| Bootstrap equiv - list-inline
|-
| Two column list *new
| Short cut for a list of pairs with the left column fixed-width and right aligned
| Similar to our current moodle forms
|-
| table (and cells headings etc) * new
| We need to convert tablelib to use renderers to output all table elements
|
|-
| forms (and labels, inputs etc) * new
| We need to convert formslib to use renderers to output all form elements
|
|-
| grids *new
| We need to support renderables for a simple responsive grid system
| Everything has grids...
|-
| floats *new
| We need to support floating elements left and right
| Bootstrap - pull-left, pull-right
|-
| clearfix *new
| If we have this simple thing as a renderable we can avoid repeating the CSS
| Bootstrap - clearfix
|-
| expandable *new
| Initially shows only a summary with an expand button to show more details
| mod_assign
|-
| dialog *new
| Tie into M.core.dialogue so it can be adjusted in a renderer
| aria
|-
| timer *new
| There is an aria role for this - so we should make sure it is used correctly if required.
| aria
|-
| tree *new
| Reusable version of the nav tree
| aria tree, tree-item, tree-grid etc
|-
| indent *new
| (eg threaded forum post)
|
|-
| media block *new
| large media element side by side with some text
| http://demo.patternlab.io/
|-
| hero *new
| content section with borders/oversized text etc designed to be a landing point
| Bootstrap jumbotron
|}

== Prototyping ==
Because there are several ways to implement a renderer/renderable - we have spent some time exploring an example renderer/renderable implementation. What we intended to achieve with these dev branches is an implementation of a "menu" and a "list" renderable in several themes, using several CSS frameworks. The frameworks chosen are: Bootstrap 2 (clean), Bootstrap 3, Zurb Foundation and YUI Pure IO. The prototypes both produce exactly the same output (and only a little effort was made to get nice output) - it's just the implementations we are interested in at this stage. Each prototype branch adds a local plugin with a test page that can be viewed at "/local/output/index.php" and viewed in several themes (clean, output_bs3, output_pureio, output_zurb).

Some different approaches were explored here:

=== Approach A ===
This design takes a strong objected oriented view of renderables and introduces some concepts of the HTML DOM to the renderables. There is an abstract class core_ui_element which implements renderable, that all the new renderables inherit from. Each core_ui_element has additional properties including a type, a chain of parent types, a list of attributes to be mixed into the html and a generic list of name/value properties. The type variable can influence which renderer method renders this core_ui_element (this requires a core change). The renderer method can adjust the output based on the chain of parent types of the current node, and the properties of the immediate parent.

'''The concepts applied in this approach:'''

; Everything is an element : Everything that forms a part of output will be represented by a class and can be interacted with in a consistent fashion.
; All elements are renderables : All elements and components inherit from a common core_ui_element class that implements the renderable interface.
; All elements are also core_ui_elements : The core_ui_element class allows for common functionality across every element and component. It facilitates ownership of one element to another (building complex elements aka components) as well as adding attributes and properties.
; Attributes : Element objects have attributes, these are of direct relation to HTML attributes, they are managed as a public array and can easily added to and worked with. There is also a helper method on the renderer that turns them into an HTML attribute string that can be put immediately within a tag for ease of use.
; Properties : These are used for non-renderable attributes of the element. For instance when producing a menu with items that are disabled, and where one item is active. Properties get assigned by the parent element allowing for properties to appear with specific relation to the context the element is appearing in. For example a link can be a menu item, when it is a menu item it has "active" as a property. When it is used elsewhere it does not have that property.
; Chained render methods : When render is called on a link that is by itself ''render_link'' gets called. When render is called on a link within a menu ''render_menu_link'' gets called, and if it doesn't exist ''render_link'' gets called. When render is called on a link that is within a menu that is within a dropdown ''render_dropdown_menu_link'' gets called, if that doesn't exist then ''render_menu_link'' gets called and so on and so forth. Through this chaining you can override the individual elements within a complex component using predictable means.

'''Pros'''
* All elements take on a predictable, consistent structure through the core_ui_element.
* The magic gets rolled into the core_ui_element class so that elements need only publish the public properties that they consist of, any any helper methods used in the construction of the object or in setting its properties. There is no need to add any more logic than that.
* Absolutely all logic not associated with producing output to the needs of the theme gets rolled into the element objects. When rendering an element in most cases you should only need to render the structure for the element and then call render on its properties in the order you want.
* It will be very easy to deem good interfaces from bad as anything that is not consisting of core_ui_elements will not be an ideal interface.
* It will be very easy to see in code when writing a renderer what elements are available as each will be a class.
* Its a clean approach - we will be able to do things as we believe is correct without concern of getting in the way of existing practises.

'''Cons'''
* There is going to be a lot of classes. I don't mean hundreds, but we may end up with over a hundred easily enough.
* Complexity of knowing PHP. In order to override a renderer you will need to know enough about PHP to understand what an object is.
* This is a completely new approach, while it provides clean separation from current practices it is yet another learning curve.
* There is a potential limitation if you have multiple elements of the same time occurring within a component each that needs to be rendered differently. I've not actually thought of a use case for this yet, but am mentioning it as something to be investigated.

'''Branch details'''

To view this branch at github:
https://github.com/samhemelryk/moodle/tree/output_prototype

To get a copy of this code into your own local repository run the following commands:
git checkout -b output_prototype
git fetch <nowiki>http://github.com/samhemelryk/moodle.git</nowiki> output_prototype
git reset --hard FETCH_HEAD

'''Viewing it in your browser'''

# First get a copy of the code into your local repository.
# Browse to your site and turn on allowthemechangeonurl (Settings > Appearance > Themes > Theme settings)
# To view in clean: browse to /local/output/index.php?theme=clean
# To view with Bootstrap 3: browse to /local/output/index.php?theme=output_bs3
# To view with YUI Pureio: browse to /local/output/index.php?theme=output_pureio
# To view with Zurb foundation: browse to /local/output/index.php?theme=output_zurb

=== Approach B ===
This design requires as little change to the existing code/implementations as possible. The idea, is simply to add a new list of renderables / renderer methods that implement the new things. There is no abstract class for renderables with no additional properties etc. Additionally, there are no restrictions on what can be put in a list/menu etc - it really is a just a list of renderables/strings. There is an edge case here, which is "How can a renderer method for a container modify the HTML for the elements it contains?". An example of this is that the Bootstrap 3 theme wants to put the role="menuitem" on the first link in each of the elements in it's "items" list. There are several possible approaches here - and this is one of the points of difference of this branch. One approach (too nasty) is to perform a str_replace on the first "<a" in the rendered html from the item - the downside of this approach is that it doesn't allow for differences in syntax for links, or merging with existing attributes on a link - it is doomed to fail. The approach chosen for this branch, is to parse the rendered html from the item into a DOMDocument - and use Dom manipulation to amend to the link before rendering it back to a string. There is a util method that takes this complexity out of the renderer method (and we can add more util methods as needed).
<pre>
$attributes = array('role'=>'menuitem', 'tabindex'=>'-1');
$newitemhtml = dom_utils::add_attributes_to_first_node_of_type('a', $attributes, $itemhtml);
</pre>

Branch details: git pull http://github.com/damyon/moodle.git MENU_RENDERABLE

==Documents created as part of this spec==
* [[Renderer best practices]]
* [[Guide to creating output elements]]
* [[Element HTML and CSS guidelines]]

== See also ==
* [[Output API]]
* [[Migrating your code to the 2.0 rendering API#Outputting HTML specific to your module]]
* [[Output_renderers]]
* [[Overriding_a_renderer]]
* [http://moodle.org/mod/forum/discuss.php?d=177535 Forum discussion on renderers]
* [[Renderer]]

Render library specification

2014-07-22T11:24:19Z

Samhemelryk: /* Related links */

{{Infobox Project
|name = Renderer consistency
|state = Specification
|tracker = https://tracker.moodle.org/browse/MDL-45770
|discussion = https://moodle.org/mod/forum/discuss.php?d=261202
|assignee = Damyon, Sam
}}
{{Work in progress|forumurl=https://moodle.org/mod/forum/discuss.php?d=261202}}
== Project Goals ==
* 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.

== Benefits ==
* Make it easier to create user interfaces.
* Make it easier to style the user interface.
* Make it easier for themers to customise the user interface.
* Better facilitate frontend frameworks in Themes.
* Better facilitate usable and accessible design.
* Give Moodle a more consistent look and feel.
* Improve site performance by reducing the CSS footprint.

==Understanding renderers in Moodle==

Renderers have been around since Moodle 2.0 and are now the requirement when writing any code that produces output.
Renderers come in many shapes and forms depending upon the developers take on how output should be produced.

When renderables were introduced - the API was designed to make it easy for existing code to be updated to make use of renderers and renderables. A renderable is an interface with no methods, so any existing class could be made to implement renderable. This means that the renderable class can be a mixture of data and methods that perform logic associated with the module. This also means that the renderer can call those methods on the renderable class - effectively using the API of the module. The problem with this - is that it complicates the renderer and makes it harder to override in a theme - the themer requires knowledge about the API for the module. Some renderables in core are built as separate classes - only used for the purpose of supplying data to the renderer - here there is a clear separation of the logic - and the properties of the renderable are made up of only simple types that can be checked for in the renderer - e.g. access checks are done in advance and the result is put into a boolean in the renderable. The current renderers / renderables in Moodle are a mixture of these styles.

Because there is no mandated organisation, nor has there ever been, there is immense variation in what constitutes content to a renderer.

One of the upsides to our current render system is that you are not limited to having a single renderer for a component, you can make use of language capabilities and the output framework and create layers of renderers to cut back code duplication and to aid in preparing a base for consistent structuring and output.

Into the equation we add targets and subtypes. Targets allow us to create both standard renderers and renderers specific to the needs of the output method. Standard being HTML, without output methods including CLI, AJAX, HTML email and plain text email.

People have never being constrained as to how they implement a renderer. We've being happy enough to simply guide them towards using renderers because of the benefits they provide and while there are numerous benefits there are two fundamental benefits:

; A change in thinking : It requires developers to think about their code organisation. Renderers were introduced in a time before Object Orientation was used in Moodle, and logic and output were tightly intermingled in most code. Renderers were about separating logic and design and while what was created was not always perfect it was always an improvement.

; An extensible approach to output : The render system allows for the overriding of renderers to occur. Theme designers can overwrite any renderer in their theme. The more that renderers that get implement the more of Moodle you can customise.

==Understanding themes==

Themes are without a doubt the most widely customised plugin provided by Moodle. But we are currently struggling with several problems with renderers and themes as they are being implemented currently.

1. There is no strict relationship between the HTML generated by a renderable, and the accompanying CSS that is required to make it display properly. The HTML is coded in the renderer - and then the CSS is added, either directly to the styles.css for the plugin in an unorganised way - or directly in the CSS in the theme - again in a loosely organised way. There is no systematic way to determine if any line of CSS is still in use - and there is no simple way to find the CSS that requires updating when the HTML is updated.

2. The CSS framework (bootstrap 2, bootstrap 3, zurb, pureio) specific attributes for renderables are currently being hardcoded in the HTML generated by the renderables. This prevents themers from using a different framework without creating an impossible amount of work to overwrite every renderer in Moodle.

==So what is the problem==

There are several. Lets be blunt about this. This specification is not a single task. It is about improving the state of output in Moodle and there are going to be several steps in achieving this. On a positive note these steps can in many cases be broken down into granular tasks that can be worked on asynchronously.
First lets understand some of the major problems:
* We have no established best practices, nor even documentation on what constitutes a good renderer, or considerations that should be paid mind in planning and designing of code.
* We have no established style guide, nor pattern library, nor element library, nor anything that could be referenced when someone starts building a new user interface - or creating a new theme.
* Inconsistency - because of a lack of best practice documentation and examples, there is huge variation in the design of our different modules. Different modules exhibit different problems such as a mixing of logic and output and code duplication.
* Developers are encouraged to push functionality boundaries in order to take it places observed in other projects or to challenge oneself. While consistency is often talked about it is rarely observed when designing output. We end up with numerous "similar" looking widgets all functioning slightly differently and consequently there is a feeling that this is the way to achieve a new fresh look. (E.g. we have multiple implementations of a "toolbar" - one in Atto and one in EditPDF).
* Existing renderer implementations vary widely and in many cases contain logic they should not. Access checks, database queries, object manipulations. All of which should not be present as it introduces muddling of concepts and logic that must be duplicated and then maintained for anyone overriding renderers.
* Themers have a mammoth task at present in applying a consistent style to Moodle, or in choosing to implement a new frontend framework (bootstrap, foundation, pureio etc). Our lack of organisation in the output leaves a lot to be desired. Having the theme responsible for choosing a frontend framework is the right way to handle this, however backend Moodle doesn't support themeing as well as it should be/could be.
* On top of the above it introduces a need to override several renderers should you want to create a consistent style and because of inconsistent renderer implementations this can easily lead to a maintenance nightmare. E.g. the user_picture renderable is not used in mod_forum - so there is no way to override it there.
* JavaScript introduces problems of its own. We are doing more and more with JavaScript these days. However there is a heavy dependence on the output that gets produced and the JavaScript enhancing it. In a lot of cases the relationship is ill defined and due to the complexity and structure of the JavaScript overriding the output structure of the rendered component is completely impossible for all but the most experienced developers.
* Inline with the above we lack good examples and documentation on how to deliver output templates for JavaScript User Interfaces as well as the creation, and manipulation of HTML structures that are enhanced by JavaScript.

== Identified issues==
There is a general trend in the problems noted, when looking at output we lack organisation, documentation, and consistency across the board. However the actual issues we are focusing on in this spec can be identified as below:

* Lack of a style guide / element library / pattern library.
** Leading to inconsistent output and style.
** Increased workload due to usability and accessibility thinking and testing needing to occur repetitively.
** Increased workload due to multilang (rtl) support usually coming after the designs of new output.
* Inconsistent renderer implementations.
** Lack of best practices.
** Lacking plus outdated documentation.
** Logic-full renderers greatly hinder theming.
** An unnecessarily increased requirement to understand both PHP and Moodle code as each renderer differs and are usually poorly documented.
* No abstraction from CSS framework.
** Without organised structure classes are applied in a chaotic fashion leading to the requirement to duplicate core styles.
** As there is no core styles newly created output widgets need to be styled in all base themes leaving chance of design regressions occurring in predominantly major upgrades but occasionally minor releases as well.
** Inconsistent output structure ensures CSS quickly balloons as styles need to be both created and copied to several areas.
* Poor linking between UI components and the JavaScript.
** Ill-defined link between output and the JavaScript enhancing it.
** No common technique to template UIs generated by javascript

==Manageable Tasks==
The following are the major tasks we have identified so far. These tasks can be though of as Epic's, or tasks for which we will create subtasks (if this output specification itself becomes an Epic).
Within this section will include notes and implementation ideas on the major tasks we've identified.

* [[#Define the elements that make up Moodle|Choose an output methodology and begin defining core elements]]
* [[#Element library and style guide|Create an element library and accompanying style guide]]
* [[#Style guide|Create a style guide document]]
* [[#Define and document renderer best practices|Define and document renderer best practices]]
* [[#Define and update the JS documentation|Update the JavaScript documentation]]
* [[#Update renderer documentation|Update renderer documentation]]
* [[#Update theme documentation and theme tutorials|Update theme documentation and theme tutorials]]
* [[#Progressively convert renderers|Progressively convert renderers]]

===Define the elements that make up Moodle===
There are several tasks that will go into this, but the first and most important will be deciding upon an organisational methodology. Some way to compartmentalise the Moodle output.
At present a reducing granularity system is looking the most appealing. Go and read [http://bradfrostweb.com/blog/post/atomic-web-design/ Atomic Design] written by Brad Frost - it describes very well the type of compartmentalisation we are proposing.

Once a system has being chosen the following tasks can be tackled:
* Identify the layers we require.
* Define the boundaries and responsibilities of those layers.
* Identify the initial set of elements, likely the finest granularity first as I imagine starting at the bottom and working up will be the best way to proceed.

Further elements (those relating to Moodle will be defined as part of the element library work).

===Element library and style guide===
Draft docs for element library tool: [[Element_Library]]

Add an admin tool that can show a categorised list of renderable objects for each plugin/and core - filled with test data. The goal of this tool is to:

* 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 (in a well defined structure) they can use when building their own pages

The tasks here will be:
* Spec the element library tool with regard to our chosen element methodology.
* Create the element library tool.
* Establish a definition method of elements, and compositions of elements as renderables.
* Define the core elements from the task above in code somehow and verify the element library tool reveals them.
* Finally 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, grid. These renderables should be structured into layers, starting from renderables that cannot be broken into smaller parts, up to widgets made of smaller renderables, up to layouts (and possibly up to entire pages). 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

On top of this there is functionality that would be great to add to it:

* Validate that the renderer/renderable follows best practice (no DB queries, complex types, complex logic)
* Provide responsive testing immediately within the tool. Adjusting the viewing area on queue to allow both developers and designers to experience how the individual renderables respond in varying presentation medias.
* Provide language direction testing immediately within the tool. Like the above allow designers and developers to quickly experience a renderable in a different language directions.
* Renderable linear reporting. So that you can see which other renderables make use of this renderable and which renderables get used by this renderable. This will be hugely helpful in judging impact when themeing.

===Thoughts on naming===

We will need to define useful names for the different categories of renderables so that we can effectively organise them and provide guidelines for writing each type - the names are a small part of this solution but will possibly be a point for contention. Different frameworks have different names for these things and people will prefer something that sounds like something they are already using.

(draft!) Categories for renderables - taken straight from Atomic design

http://bradfrostweb.com/blog/post/atomic-web-design/

* Atoms == Tiny reusable elements that cannot be broken down into smaller elements
* Molecules == Relatively simple combinations of atoms built for reuse
* Organisms == Organisms are groups of molecules joined together to form a relatively complex, distinct section of an interface.
* Templates == Layout files in a theme
* Pages == The actual pages in Moodle

Refs for categorizing patterns
* http://bradfrostweb.com/blog/post/atomic-web-design/
* http://oocss.org/
* http://alistapart.com/blog/post/getting-started-with-pattern-libraries
* http://style.codeforamerica.org/

===Style guide===
This has two real advantages.

# First assuming this will be developed initially while defining the elements that will make up Moodle output and will aid us in verifying what we are doing. If it can be easily documented then we are on the right track. If we start encountering to many conditions and or too much variation then we are drifting off track.
# When defining new elements we are able to use our style guide to do so and it'll provide us measure of how Moodle output evolves.

===Define and document renderer best practices===

This will be tricky and no doubt how we decide to define a best practice will have to have regard for the output methodology we choose.

===Update the JavaScript documentation===

Discuss and agree on a best practice for writing JS that depends on HTML structures in the DOM (e.g. progressive enhancement - or just ids for action listeners) (perhaps a specific renderable for a JS region)

===Update renderer documentation===
This will of course need to be done after the element library and renderer best practices but should be pretty simple at that point.
* Read and rate each of the existing docs pages (see related links below)
* Write new complete docs for everyone (at [[Output API]])
* Cross link old docs to the new ones

===Update theme documentation and theme tutorials===
There are likely the most well documented plugin type within Moodle. There are good specification docs, good 2.0 conversion docs and good tutorials on many aspects of theming.
Many of these pages will need to be updated to reflect best practices and such after we start ticking off some of the other tasks.

===Progressively convert renderers===
This is the very last task really - but we will start work on it in parallel with creating the new set of core renderables (to prove the design is usable). There is no deadline for this to be complete - and it will take a long time to convert all the existing renderers (and code not using renderers).

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

Goals for renderers - should be devoid of logic for these reasons:
* Theme overridden renderers do not need to be updated when logic is changed
* Themers can override renderers without understanding all the logic
* Renderables can be filled with mock data for display in the element library

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 not related to output
* calling the database

A “renderable” is:
* All the data required to generate the output.
* Properties should be simple data types only, or renderables, or array of those

== Evaluations of some existing renderers / renderables ==
Existing renderer styles - because there are few rules/guidelines for how renderers should be written - there are differing examples of renderers in core. Looking at the 3 of the better maintained modules to see how they are implemented will be useful in evaluating the benefits of any stricter rules for renderers.
=== Assign ===
Contains a list of renderables (in renderables.php) and a single renderer. The logic is mostly out of the renderer methods (pre-calculated and added as data to the renderer). There are some cases when renderables could be broken down further - e.g. the expand/collapse on the submission history (mod/assign/yui/src/history/js/history.js). Also the assignment sub-plugins do not use renderers (and they should).

=== Quiz ===
Uses a lot of renderers - but not renderables. The renderer methods directly call methods of the business logic to determine what to display. e.g. "attemptobj->get_access_manager(time())->attempt_must_be_in_popup()". This is not terrible for a themer trying to override a renderer method because the calls are mostly simple - but it is a grey area for when this becomes business logic in the renderer (and would e.g. need updating to fix bugs etc). If we want to add these renderer methods to the element library - it would require a way to pass mock business logic classes to the renderer methods (and a way for the generator to return a renderer and a method - instead of only a renderable).

=== Workshop ===
Very nice renderers and renderables in workshop. Would only need updating to re-use core renderables instead of using html_writer directly - and adding the existing renderables to the element library.

=== Badges ===
Mix of renderer methods and renderables. This is similar to quiz where the renderer is calling lots of methods of the business model in the renderer methods and has the same effect (harder to override, maintain etc). To add these renderer methods to the element library would require the same sort of changes as mentioned in quiz.

== Example of forum post renderer using composition ==
This is not a real example (yet), it's just a demonstration of the type of renderers we should be aiming for (using composition etc). This structure would be created in the render_form_post method of the forum renderer. This method would receive a forum_post renderable containing only data - and build up this structure of smaller renderable components, then return the result of calling render(x) on each of the smaller renderables.

[[Image:forumpost-renderer-breakdown.png|center|500px|Example forum renderer]]

== Initial thoughts on renderables and what we should provide (Draft) ==
This list is not intended to be the final list - it is more of a scoping exercise. One of the tasks from this project is to decide on the full set of required renderables.
There are several renderables within Moodle that have being included in this table and we will need to look closely at how they fit within our chosen model and whether they are still required.

{| class="nicetable"
|-
! Name
! Description
! Source (links)
|-
| action_menu
| UI component for a drop down edit menu
| Existing renderable (should be renamed "menu")
|-
| action_menu_link
| UI component for a menu item in an action menu
| Existing renderable
|-
| action_menu_filler
| UI component for a filler menu item in an action menu
| Existing renderable
|-
| action_menu_link_primary
| UI component for a primary menu item in an action menu
| Existing renderable
|-
| action_menu_link_secondary
| UI component for a secondary menu item in an action menu
| Existing renderable
|-
| action_link
| Link with alt text, and an icon
| Existing renderable
|-
| single_button
| A form with a single button
| Existing renderable
|-
| confirm
| A form with a message and cancel/confirm buttons
| Existing renderable
|-
| single_select
| A form with a single drop down list that submits on change
| Existing renderable
|-
| url_select
| A navigation element consisting of a single drop down list of urls that navigates on change
| Existing renderable
|-
| doc_link
| A link to the Moodle docs
| Existing renderer method
|-
| pix_icon
| A small icon
| Existing renderable
|-
| emoticon_icon
| A small emoticon
| Existing renderable
|-
| heading_with_help
| A page heading with a link to help docs
| Existing renderer method
|-
| help_icon
| A help icon that opens a help popup when clicked
| Existing renderable
|-
| help_icon_scale
| A help icon that opens a help popup when clicked
| Existing renderable
|-
| user_picture
| A user profile picture which links to their profile
| Existing renderable
|-
| container
| A block level element used to surround something. Can have a class to allow specific targeting with CSS.
| Existing renderable
|-
| error_text
| An error to show to the user.
| Existing renderable
|-
| notification
| A message for the user
| Existing renderable
|-
| continue_button
| A message and a button to continue to the next page
| Existing renderable
|-
| paging_bar
| A list of next previous and specific page links
| Existing renderable
|-
| skip_link_to
| A link to a section on the page
| Existing renderable
|-
| skip_link_target
| A target for a matching skip_link_to call
| Existing renderable
|-
| heading
| A page heading
| Existing renderable
|-
| box
| A page section with a border
| Existing renderable
|-
| rarrow
| A right arrow
| Existing renderable
|-
| larrow
| A left arrow
| Existing renderable
|-
| tabtree
| A list of tabs
| Existing renderable
|-
| tabobject
| A single tab panel
| Existing renderable
|-
| toolbar *new
| A container for toolbar button groups
| Bootstrap equiv btn-toolbar (needs aria support)
|-
| toolbar-group *new
| A group of toolbar buttons
| Bootstrap equiv btn-group (needs aria support)
|-
| toolbar-button *new
| A toolbar button
| Bootstrap equiv btn (needs aria support)
|-
| toolbar-menu *new
| A toolbar button that opens a drop down menu
| Bootstrap equiv nested btn-groups (needs aria support)
|-
| navbar *new
| The navigation bar that shows at the top of the page
| Bootstrap equiv navbar - There is an existing renderer method that needs converting into renderables
|-
| navbar_item *new
| Items in the navigation bar that shows at the top of the page
| Bootstrap equiv list item in a navbar - There is an existing renderer method that needs converting into renderables
|-
| navbar_item *new
| Items in the navigation bar that shows at the top of the page
| Bootstrap equiv list item in a navbar - There is an existing renderer method that needs converting into renderables
|-
| progress_bar *new
| A bar showing progress of something
| Bootstrap equiv progress_bar - There is an existing moodle class that needs converting to use renderables
|-
| progress_bar *new
| A bar showing progress of something
| Bootstrap equiv progress_bar - There is an existing moodle class that needs converting to use renderables
|-
| panel *new
| A container with a heading and borders
| Bootstrap equiv panel, panel-heading, panel-body, panel-footer
|-
| vertical-list *new
| A vertical list of items
| Bootstrap equiv - list-group
|-
| horizontal-list *new
| A horizontal list of items
| Bootstrap equiv - list-inline
|-
| Two column list *new
| Short cut for a list of pairs with the left column fixed-width and right aligned
| Similar to our current moodle forms
|-
| table (and cells headings etc) * new
| We need to convert tablelib to use renderers to output all table elements
|
|-
| forms (and labels, inputs etc) * new
| We need to convert formslib to use renderers to output all form elements
|
|-
| grids *new
| We need to support renderables for a simple responsive grid system
| Everything has grids...
|-
| floats *new
| We need to support floating elements left and right
| Bootstrap - pull-left, pull-right
|-
| clearfix *new
| If we have this simple thing as a renderable we can avoid repeating the CSS
| Bootstrap - clearfix
|-
| expandable *new
| Initially shows only a summary with an expand button to show more details
| mod_assign
|-
| dialog *new
| Tie into M.core.dialogue so it can be adjusted in a renderer
| aria
|-
| timer *new
| There is an aria role for this - so we should make sure it is used correctly if required.
| aria
|-
| tree *new
| Reusable version of the nav tree
| aria tree, tree-item, tree-grid etc
|-
| indent *new
| (eg threaded forum post)
|
|-
| media block *new
| large media element side by side with some text
| http://demo.patternlab.io/
|-
| hero *new
| content section with borders/oversized text etc designed to be a landing point
| Bootstrap jumbotron
|}

== Prototyping ==
Because there are several ways to implement a renderer/renderable - we have spent some time exploring an example renderer/renderable implementation. What we intended to achieve with these dev branches is an implementation of a "menu" and a "list" renderable in several themes, using several CSS frameworks. The frameworks chosen are: Bootstrap 2 (clean), Bootstrap 3, Zurb Foundation and YUI Pure IO. The prototypes both produce exactly the same output (and only a little effort was made to get nice output) - it's just the implementations we are interested in at this stage. Each prototype branch adds a local plugin with a test page that can be viewed at "/local/output/index.php" and viewed in several themes (clean, output_bs3, output_pureio, output_zurb).

Some different approaches were explored here:

=== Approach A ===
This design takes a strong objected oriented view of renderables and introduces some concepts of the HTML DOM to the renderables. There is an abstract class core_ui_element which implements renderable, that all the new renderables inherit from. Each core_ui_element has additional properties including a type, a chain of parent types, a list of attributes to be mixed into the html and a generic list of name/value properties. The type variable can influence which renderer method renders this core_ui_element (this requires a core change). The renderer method can adjust the output based on the chain of parent types of the current node, and the properties of the immediate parent.

'''The concepts applied in this approach:'''

; Everything is an element : Everything that forms a part of output will be represented by a class and can be interacted with in a consistent fashion.
; All elements are renderables : All elements and components inherit from a common core_ui_element class that implements the renderable interface.
; All elements are also core_ui_elements : The core_ui_element class allows for common functionality across every element and component. It facilitates ownership of one element to another (building complex elements aka components) as well as adding attributes and properties.
; Attributes : Element objects have attributes, these are of direct relation to HTML attributes, they are managed as a public array and can easily added to and worked with. There is also a helper method on the renderer that turns them into an HTML attribute string that can be put immediately within a tag for ease of use.
; Properties : These are used for non-renderable attributes of the element. For instance when producing a menu with items that are disabled, and where one item is active. Properties get assigned by the parent element allowing for properties to appear with specific relation to the context the element is appearing in. For example a link can be a menu item, when it is a menu item it has "active" as a property. When it is used elsewhere it does not have that property.
; Chained render methods : When render is called on a link that is by itself ''render_link'' gets called. When render is called on a link within a menu ''render_menu_link'' gets called, and if it doesn't exist ''render_link'' gets called. When render is called on a link that is within a menu that is within a dropdown ''render_dropdown_menu_link'' gets called, if that doesn't exist then ''render_menu_link'' gets called and so on and so forth. Through this chaining you can override the individual elements within a complex component using predictable means.

'''Pros'''
* All elements take on a predictable, consistent structure through the core_ui_element.
* The magic gets rolled into the core_ui_element class so that elements need only publish the public properties that they consist of, any any helper methods used in the construction of the object or in setting its properties. There is no need to add any more logic than that.
* Absolutely all logic not associated with producing output to the needs of the theme gets rolled into the element objects. When rendering an element in most cases you should only need to render the structure for the element and then call render on its properties in the order you want.
* It will be very easy to deem good interfaces from bad as anything that is not consisting of core_ui_elements will not be an ideal interface.
* It will be very easy to see in code when writing a renderer what elements are available as each will be a class.
* Its a clean approach - we will be able to do things as we believe is correct without concern of getting in the way of existing practises.

'''Cons'''
* There is going to be a lot of classes. I don't mean hundreds, but we may end up with over a hundred easily enough.
* Complexity of knowing PHP. In order to override a renderer you will need to know enough about PHP to understand what an object is.
* This is a completely new approach, while it provides clean separation from current practices it is yet another learning curve.
* There is a potential limitation if you have multiple elements of the same time occurring within a component each that needs to be rendered differently. I've not actually thought of a use case for this yet, but am mentioning it as something to be investigated.

'''Branch details'''

To view this branch at github:
https://github.com/samhemelryk/moodle/tree/output_prototype

To get a copy of this code into your own local repository run the following commands:
git checkout -b output_prototype
git fetch <nowiki>http://github.com/samhemelryk/moodle.git</nowiki> output_prototype
git reset --hard FETCH_HEAD

'''Viewing it in your browser'''

# First get a copy of the code into your local repository.
# Browse to your site and turn on allowthemechangeonurl (Settings > Appearance > Themes > Theme settings)
# To view in clean: browse to /local/output/index.php?theme=clean
# To view with Bootstrap 3: browse to /local/output/index.php?theme=output_bs3
# To view with YUI Pureio: browse to /local/output/index.php?theme=output_pureio
# To view with Zurb foundation: browse to /local/output/index.php?theme=output_zurb

=== Approach B ===
This design requires as little change to the existing code/implementations as possible. The idea, is simply to add a new list of renderables / renderer methods that implement the new things. There is no abstract class for renderables with no additional properties etc. Additionally, there are no restrictions on what can be put in a list/menu etc - it really is a just a list of renderables/strings. There is an edge case here, which is "How can a renderer method for a container modify the HTML for the elements it contains?". An example of this is that the Bootstrap 3 theme wants to put the role="menuitem" on the first link in each of the elements in it's "items" list. There are several possible approaches here - and this is one of the points of difference of this branch. One approach (too nasty) is to perform a str_replace on the first "<a" in the rendered html from the item - the downside of this approach is that it doesn't allow for differences in syntax for links, or merging with existing attributes on a link - it is doomed to fail. The approach chosen for this branch, is to parse the rendered html from the item into a DOMDocument - and use Dom manipulation to amend to the link before rendering it back to a string. There is a util method that takes this complexity out of the renderer method (and we can add more util methods as needed).
<pre>
$attributes = array('role'=>'menuitem', 'tabindex'=>'-1');
$newitemhtml = dom_utils::add_attributes_to_first_node_of_type('a', $attributes, $itemhtml);
</pre>

Branch details: git pull http://github.com/damyon/moodle.git MENU_RENDERABLE

== Related links ==
* [[Output API]]
* [[Migrating your code to the 2.0 rendering API#Outputting HTML specific to your module]]
* [[Output_renderers]]
* [[Overriding_a_renderer]]
* [http://moodle.org/mod/forum/discuss.php?d=177535 Forum discussion on renderers]
* [[Renderer]]

*Documents created as part of this spec*
* [[Renderer best practices]]
* [[Guide to creating output elements]]
* [[Element HTML and CSS guidelines]]

Renderer best practices

2014-07-22T11:22:57Z

Samhemelryk: /* See also */

{{Infobox Project
|name = Renderer consistency
|state = Specification
|tracker = https://tracker.moodle.org/browse/MDL-45853
|discussion = https://moodle.org/mod/forum/discuss.php?d=261202
|assignee = Damyon, Sam
}}
{{Work in progress|forumurl=https://moodle.org/mod/forum/discuss.php?d=261202}}

This page documents renderer best practices.

==Notes==

* Must mention atomic design and how the concept of "templates" should be applied. Relates to the next note. A forth method type for renderers?
* Within a component or plugin that has a renderer use the renderer for EVERYTHING within that area. [https://moodle.org/mod/forum/discuss.php?d=262817#p1138926 forum post that ignited this]
* Reference and probably copy the three render methods from [Guide to creating output elements]

==Renderer best practices==

This document discusses the recommended practises to follow when writing renderers for Moodle. It was created in Moodle 2.8 as part of the element library specification that took place.

Renderers provide an abstraction of logic and display. They serve Moodle to both encourage us to properly structure our code and to provide a means by which themes can take control of output to completely customise the look of Moodle.
Elements and the element library provide us a set of building blocks to use when creating output. These provide us a consistent and manageable look that also minimising the amount of customisation required by a theme to change the look and feel of Moodle.
Here we make a recommendation on how to write renderers to maximise the benefits to both yourself as a developer and to designers who have to customise the interfaces you create.

==Goals==

Its important to understand the goals for output before you start looking at renderers as they are just one part of the output plan.

'''Output in Moodle is designed to:'''
* Aid developers in properly abstracting output from logic.
* Allow designers to take complete control of output from within a theme if they wish.
* Provide a consisten look and feel for Moodle user.
* Allow developers to more rapidly create interfaces by having a set of elements at their finger tips.
* Minimise the efforts designers must extrude in order to customise the look and feel of Moodle by limiting the output to a set of elements.
* Aid designers by providing tools to support styling Moodle such as the element library.

'''Renderers in Moodle:'''
* Are the link between Moodle and a theme through which all output is generated.
* Are organised for the benefit of designers, and should be written following this document.
* Most importantly allow designers to override the HTML that wraps the data being displayed in turn allowing designers to re-design output in a theme.
* Allow designers to change the information being displayed by providing not just what is initially required but that which that may require.

==A simple set of rules for a good renderer==

Summarising what will be discussed further in this document a good renderer can be summarised as:

* Think in elements. We have an element library, when planning the output for your plugin/component start with the elements in the element library and the markup they provide.
* Containing only methods confroming to the four method types discussed below.
* Encapsulated data is given, maximising the information available to the renderer and minimising the number of arguments.
* Free of logic relating to anything except output. This includes not calculating the likes of links and capabilities.
* Uses helper methods to manipulate data where manipulate is absolutely required, essentially abstracting logic to conform to the above rule.
* Utilise the core elements as much as is possible.
* Recognise unique output needs and create element(s) for it.
* The render method should be used as often as possible to maximise consistent look.

==The don'ts==

The following are things that should not be done within a renderer.

'''DO NOT:'''
* design interfaces from scratch when desiging output for your plugin/component. Always start with the elements found in the element library.
* Use logic that isn't essential to producing output. This includes but is not limited to the following:
** Database interaction of any kind.
** Access or capability checks.
** Generation of data such as producing URL's, that should be owned by the plugin/component and made available preferably through the given arguments or failing that through a helper method.
* Generate HTML for something that should be an element, convert it to an element and call render on it.
* Create custom elements for everything you plan to output, instead try to maximise the core elements that you use.
* Write your own render methods for subelements of the elements you create. Only do this if you absolutely must change the markup from that produced by the natural render method for the element.

==Creating a renderer==

===Location and naming===
As of Moodle 2.8 renderers can be put into the output namespace. This is the recommended placement for Renderers in Moodle 2.8 and up, however the alternatives will also be listed here.

Recommended:
* Put your renderer in '''mod/yourplugin/output/renderer.php''' use the namespace '''mod_yourplugin\output''' and call your class '''renderer'''.
* To get an instance of your renderer ''$PAGE->get_renderer('mod_yourplugin')'''

This is how mod/yourplugin/output/renderer.php will look:
<code php>
<?php

namespace mod_yourplugin\output;

class renderer extends \plugin_renderer_base {
// Your renderer methods in here.
}
</code>

Also available but not recommended:
* Put your renderer in '''mod/yourplugin/renderer.php''' do NOT namespace it, and call your class '''mod_yourplugin_renderer'''.
* To get an instance of your renderer ''$PAGE->get_renderer('mod_yourplugin')'''

This was how things were done in earlier versions of Moodle (2.7 and below).

===Render methods===

Renderers can be well structured, the purpose of them is the same across all plugins and components.
There are four distinct types of render methods that you can expect to find in a renderer, and these four can be categorised into one of two categories.

The four types of render methods:
# Layout methods
# Translator methods
# Render methods
# Convenience methods

These four methods can then be categorised in two ways:
; Plugin|Component method : The layout and translator methods are plugin or component methods. They take data for a plugin or component and meld it into renderables. These methods relate to and can be said to be owned by the plugin or component.
; Element methods : The render and convenience methods relate only to elements. They take already encapsulated abstracted data and simply output HTML structure around it. They pay no regard to the plugin or component and are completely and solely bound to the output of an element.

====Layout methods====

====Translator methods====

====Render methods====
If you've spent any time working with renderers in the past you will already be familiar with the concept of a render method.
All elements within Moodle inherit the renderable interface. To produce output for them you call the renderers render method and give the element.
The render method looks at what is given and looks

====Convenience methods====
These are very simple. A convenience method is simply an easy way to build and output an element in a single step.
If you take an element, likely an atom or molecule, a convenience method would have the same arguments as the constructor for the element, build an instance of the element and call render on it.
The following is a simple example using heading:

<code php>
/**
* A convenience method to render a heading.
*/
public function heading($content, $level = 2) {
$heading = new \core\output\heading($content, $level);
return $this->render($heading);
}
</code>

==Creating output elements==
This is a big field and as such a dedicated document has been writen as a [[Guide to creating output elements]].

==Tips on properly structuring your plugin==
Talk here about OO structuring of code, ensuring a traversable heirarchy that enables maximum movement of code structure to obtain data and in turn minimises necessary arguments for layout methods.

==See also==

* [[Render library specification]]
* [[Guide to creating output elements]]
* [https://moodle.org/mod/forum/discuss.php?d=261202 Render library specification discussion]
* [[User:Sam Hemelryk/Render library element planning]]
* [[Renderer best practices]]
* [[Element HTML and CSS guidelines]]

User:Sam Hemelryk/CSS style guidelines

2014-07-22T11:22:12Z

Samhemelryk: Replaced content with "This page has now been made live. See Element HTML and CSS guidelines."

This page has now been made live. See [[Element HTML and CSS guidelines]].

Element HTML and CSS guidelines

2014-07-22T11:21:45Z

Samhemelryk: Copy the page from my personal area.

{{Infobox Project
|name = Renderer consistency
|state = Specification
|tracker = https://tracker.moodle.org/browse/MDL-45830
|discussion = https://moodle.org/mod/forum/discuss.php?d=261202
|assignee = Damyon, Sam
}}
{{Work in progress|forumurl=https://moodle.org/mod/forum/discuss.php?d=261202}}

This is a guide to writing HTML and CSS for elements within Moodle.
In the future this will likely become the HTML and CSS guide for output in Moodle as we want to move elements. However at present we don't want to enforce this for all output, just new conversions to elements.

==Why have a strict guide==

At the time of writing this CSS within Moodle (2.7) themes is in a poor state and has been for a long time. Without previously having a guide we were finding that:

* As there was no formal guide to creating id's or classes, each developer does there own thing.
* As there was no formal guide on how to write CSS there were numerous techniques used when writing CSS and no consistency.
* Majority of pages create uniuqe output and require unique CSS, there is very little re-use of design.

While those points may not sound bad to you consider that in following stats from Moodle 2.7 themes:

* Base theme contains 3802 rulesets with a total of 5800 styles.
* Bootstrapbase theme contains 5170 rulesets with a total of 9362 styles.
* Clean theme contains 5172 rulesets with a total of 9366 styles.
* More theme contains 5177 rulesets with a total of 9063 styles.

You get the picture, several thousand selectors containing nearly 10000 styles.

For Moodle 2.8 we commited to introducing a element library to aid the reuse of design and documenting all aspects of output including a guide on writing CSS for Moodle. This is that guide.

==Our goals==

Its very important to understand what we are trying to achieve with this style guide and output in general.

; Frontend framework agnostic : We want theme designers to be able to apply present and future frontend frameworks to Moodle with minimal effort.
; Consistent interfaces : We want Moodle to have consistency throughout its interfaces, minimising the amount of frontend design and development that is required in coding and styling an interface.
; Cleanly formatted HTML and CSS : to minimise both development time and to make our renderers and CSS and more maintainable.

We plan to faciliate these with the following:
; Elements : Highly re-usable objects to produce HTML, these will be used consistently and relied upon by developers creating interfaces. By having these elements we create a consistent look, interface creation will be much quicker and theme designers through the re-use of a limited number of elements.
; Element library : A tool to show samples of each element, this can be used to view and test designs. It aids the developer by showing them the elements they can select from when creating an interface, and it aids designers by giving them a test area that doesn't require them to dig through every page in Moodle.
; Documentation : We will now have proper documentation on all aspects of output. Including this CSS style guide, a renderer best practices guide, and a guide to creating elements.

==Where to put CSS in Moodle core==

CSS can reside in a number of locations depending upon what you are styling.

Remember it doesn't matter how many CSS files we end up with, on a production site with Theme designer mode switched off (default) all CSS files will be combined and minimised into a single file that is served to the client.
Excepting the case of IE where we must split the CSS into several smaller files to work around browser limitations.

===CSS for elements===
As we are moving to using elements you will find that CSS for elements is where most of the effort is going to go.

CSS for elements should reside within themes only, you will find that elements must be styled in all core base themes, this means at least Bootstrapbase and base.

CSS for elements should be located within either '''theme/themename/style/elements/elementname.css''' or '''theme/themename/less/elements/elementname.css'''

The actual CSS file should be named according to the element. As elements can be namespaced we need to ensure that that is reflected in the name of the file.
For instance:

{|
! Element
! CSS location in base
! CSS location in bootstrapbase
|-
| \core\output\button
| style/elements/core_output_button.css
| less/moodle/elements/core_output_button.css
|-
| \core\output\navigation_bar
| style/elements/core_output_navigation_bar.css
| less/moodle/elements/core_output_navigation_bar.css
|-
| \mod_assign\output\user_submission
| style/elements/mod_assign_output_user_submission.css
| less/moodle/elements/mod_assign_output_user_submission.css
|}

These will still need to be included in the theme, by which ever means is relevant.
If you are using ''.css'' files like the base theme does then you will use:

<code php>
// In your themes config.php
$THEME->sheets = array(
'elements/core_output_button',
'elements/core_output_navigation_bar',
'elements/mod_assign_output_user_submission'
);
</code>

If you are using less as bootstrapbase does then you will use:
<code css>
/** In your primary less file **/
@import "moodle/elements/core_output_button";
@import "moodle/elements/core_output_navigation_bar";
@import "moodle/elements/mod_assign_output_user_submission";
</code>

===General CSS===

This is CSS for the theme that doesn't relate to a specific element. Hopefully as we convert more and more of Moodles interfaces to use elements we should see less general CSS.

In any case nothing has changed in regards to the location of general CSS.
; CSS : If your theme is using standard CSS then it must be located within the ''style'' directory of your theme and should be in logically separated files.
; Less : If your theme is using less then it should be located in a ''less/moodle'' directory within your theme.

We recommend that you separate styles into files based upon the Moodle component being styled. Again as all CSS files get combined into a single file on production sites it doesn't matter how many files you end up with.

This would lead to files named like:
* style/core.css
* style/course.css
* style/mod_forum.css

===Where to put CSS in plugins===

It is possible in Moodle to add CSS stylesheets to all plugins (including core plugins).<br />
Moodle always looks for a ''styles.css'' file within your plugins directory, and it also looks for a styles_themename.css where themename is the name of the currect theme being used.

For instance the following could be added to the forum module:

* ''mod/forum/styles.css'': Used all the time.
* ''mod/forum/styles_base.css'' : Used when the user is using the base theme.
* ''mod/forum/styles_bootstrapbase.css'' : Used when the user is using the bootstrapbase theme.
* ''mod/forum/styles_clean.css'' : Used when the user is using the clean theme.

===CSS in core plugins===

For core plugins only styles.css is permitted and it should only ever contain styles essential to the presentation of the plugin.<br />
At present styles essential for the display of the plugin are allowed here, however when the plugin interfaces have been converted to use elements this file should be nearly empty and contain only the following:
* Images, icons and text used for visual presentation such as icons to notify state (expanded/collapsed, warnings...)
* Accessiblity orientated styles required to make the interface accessible.

'''Under no circumstances should it contain any visual stylings such as border, rounded corners, and background colours not associated with state.'''

==HTML==

The following sections detail rules in place for writing HTML.

Before we start a couple of general recommendations:

; Use hyphens rather than underscores when concatenating strings in attributes : for example ''.course-new-activity-chooser'' instead of ''.course_new_activity_chooser''. By all doing this we will have a more consistent appearance and as We use underscores as part of frankenstyle which is prominent in CSS helps us to reduce the chance of naming conflicts.
; Think semantics - but don't get caught up in it : Semantic CSS is beautiful CSS lending itself ultimately to the redesign that is going to happen. But enforcing a semantic design can be an arduous journey. Instead we encourage semantic CSS but are happy to see non-semantic CSS when it is for the greater good.

===Using the ID attribute===

The situation of having a single JavaScript driven element was considered but even then it is better to style only classes and other attributes as we can't be sure what the future holds.

There are three rules you should follow when creating an ID:

# They should only be given to elements and HTML nodes that need to be interacted with by JavaScript.
# It should always start with '''m-''' ''(see note below)''
# The actual ID should be descriptive of the node and contents as a whole unit. It must fully and concisely describe its purpose.

Keep in mind that in an ideal world ID's should not be used for styling.

'''Good'''
<code html5>
<div id="m-dock"> ... </div>

<div id="m-course-new-activity-chooser"> ... </div>
</code>

'''Bad'''
<code html5>

<div id="dock"> ... </div>


<div id="m-activity-selector"> ... </div>
</code>

'''Note:''' The requirement to use m- prefix is entirely new, this has been created as this instantly reduces the chances of conflicting with present and future frontend frameworks that may be adopted by core or third party themes. Aiding our goal of being frontend framework agnostic.<br />
It will also help reduce the chance of conflicts in any third party code that may be used either by us in core, or by outside developers in their own code.
Moodle ID's will also be much more easily recognisable which we expect will be a benefit as JavaScript use in Moodle continues to increase.

===Naming CSS classes===

This is where a bit of organisation goes a long way and we want to be reasonably thorough in a consistent naming scheme and implementation.

The very first thing to mention is that all classes in Moodle must now be prefixed by *m-*.
This instantly identifes a class as belonging to Moodle, it aids us in avoiding conflicts with any non-Moodle css that may be loaded, and it is part of our framework agnostic plan.

<blockquote>
All CSS classes must start with *m-*
</blockquote>

There are several prefix that are used within Moodle output now that should not be used as prefixs for classes unless they are serving the desired purpose.

Reserved prefixes are:

; m-element : Prefix used on element classes, where m-element preceeds the name of the element, e.g. m-element-button, m-element-search
; m-state : Prefix used for CSS classes representing the state of an item, e.g. m-state-disabled, m-state-active, m-state-expanded.
; m-grid : Prefix used for creating HTML grids.

====Elements====

Semantic design where it gives the best result, smart design where there is a better solution.

If you're not already familiar with the idea of semantic CSS then Chris Coylers artical [http://css-tricks.com/semantic-class-names/ What makes for a semantic class name] is a great starting point.

We've not commit to adopting any one strict approach for writing CSS. We have adopted atomic design for our HTML elements, a design style which fits nicely with the likes of OOCSS, however be very clear that we are not adopting the OOCSS approach in its entirety. The high level abstraction of the visual aspects of elements into highly reusable agnostic classes does not always lend itself well to the Moodle world in which the we wish to be frontend framework agnostic and support largescale completely customisable themes.<br />
The highly reusable classes that appeal to one designer, or to one frontend framework may not apply to another.<br />
This decision is also impacted by our current default theme bootstrapbase that does not use well abstracted OOCSS in its design.

Atomic design is going to see us end up with many parent child relationships in our HTML that we must carry through to our CSS. Through atomic design we start with smalled atoms and molecules that get built into larger organisms and placed within layouts.

Every element should have a single class that identifies it as element X.

For instance the button atom will have the class *m-element-button*

<code html5>
<button class="m-element-button">I am a button</button>
</code>

This is simply the prefix "m-element" plus the element name.

The purpose of this class is to allow the element to be styled with ease. The class name should be applied to the root node for the element, it should never be applied any lower.

By having one class for the element, and always and only applied to the root node it makes it very easy in HTML to see where one element belongs to another.

The following is an example of the search molecule, which in turn contains two button atoms.
<code html5>
<form class="m-element-confirmation">
<h3>Are you sure?</h3>
<p>Are you sure you want to perform this action?</p>
<input type="submit" name="cancel" class="m-element-button" value="Cancel" />
<input type="submit" name="continue" class="m-element-button" value="Continue" />
</form>
</code>

We've chosen to partially adopt BEM as a CSS standard when writing CSS for elements.
BEM isn't a new CSS standard, but its not widely known either. Its existence fills a gap in how to style elements consistently. Through two basic notation techniques you can easily notate the purpose of structures that belong to an element and notate the intent of an element that is desired if the element has multiple versions.

; Notating purpose : Here we use a suffix *__purpose*, the key being the two underscores.
; Notating intent : Here we use a suffix *--intent*, the key being the two hyphens.

You'll notice in the example above that there is no way to style the continue button differently from the cancel button without relying on its name, something we certainly don't want to do.
The solution is to wrap each button in a div and give each div a class.
The BEM standard comes into play here in naming the classes, the following shows how you would apply BEM to show the purpose of each button in a way that can be easily interpreted and styled in CSS.

<code html5>
<form class="m-element-confirmation">
<h3>Are you sure?</h3>
<p>Are you sure you want to perform this action?</p>
<div class="m-element-confirmation__cancel">
<input type="submit" name="cancel" class="m-element-button" value="Cancel" />
</div>
<div class="m-element-confirmation__continue">
<input type="submit" name="continue" class="m-element-button" value="Continue" />
</div>
</form>
</code>

You can now each button is wrapped in a div with a class, *m-element-confirmation__cancel* and *m-element-confirmation__continue*.
This class can be read by the themer and because of the __ can be easily identified as both belonging to the m-element-confirmation and serving a specific purpose, continue or cancel.

Now to explain the idea of intents.
An intent is when a single element takes on a different apprearance to convey a specific meaning. A little bit like a state, but with more meaning.
An easy example is notifications where you will no doubt be familiar with the idea of having a error notifications, warning notifications, success notification etc. Each of error, warning, and success is a intent.

The following shows how this would work:
<code html5>

<div class="m-element-notification">You have not changed your password in the past 60 days</div>


<div class="m-element-notification m-element-notification--warning">You have not changed your password in the past 60 days</div>
</div>
</code>

====Grids====

We need to adopt a single grid framework.

Personally I don't think we should use pure bootstrap or pure YUI, instead we should choose one of these and build it use our class name structures.

All grid classes should start with m-grid.

==CSS==

Before we begin lets lay down some ground level goals, things that will help us achieve clear and understandable CSS in the future.
* Formatting, ordering, alignment, and spacing are all important in having CSS that can be easily read by others.
* Don't optimise your CSS, be verbose and stick to the styles in this guide. We have tools that will handle optimisation for you.
* Never use *!important* in your CSS unless it is absolutely impossible to avoid doing so.

===Terminology===

Its important that when we are speaking about CSS we are speaking the same language.
Lets look at the following example:

<code css>
.m-page .m-selector-1,
.m-page .m-selector-2,
.m-page .m-selector-3 {
background-color: #FFF;
color: #000;
}

.m-selector-1 {
margin: 1em;
}
</code>

; Ruleset : Each of the two rules is a single *ruleset*.
; Rule: _.m-page .m-selector-1_ is a rule.
; Selector : _.m-selector-1_ is a *selector*, it is a single part of a rule.
; Declaration : _background-color: #FFF_ is a declaration.
;

===Essential formatting===

The following are the guies for writing CSS.

* Always use spaces - never use tabs. All editors can be configured to do it.
* Indent by 4 spaces - never more, never less.
* A single empty line between rulesets to maintain consistent spacing of rules.
* One rule per line.
* A single space between each selector in a rule.
* No space between a rule and the comma in a ruleset.
* A single space between a selector and the opening brace of a ruleset.
* One level of indentation before each declaration.
* A single space the colon in a declaration.
* A single space after each item in a declaration containing multiple items.

The following shows how the above rules apply:
<code css>
.m-selector-1,
.m-selector-2 .m-selector-3 {
background: #ffa800 url("background.png") no-repeat right top;
border: 1px solid #000;
display: inline-block;
font-family: arial, sans-serif;
margin: 5px 10px;
padding: 0;
}

.m-selector-4 {
border-radius: 3px;
}
</code>

===General rules===

Declaration ordering is the very first thing to discuss. There is no strict rule on how to order your declarations, however there is a recommendation.
We recommend that you order declarations within a ruleset alphabetically.
If we all start doing this then when you read CSS written by someone else you will soon learn to very quickly find your way around the declarations within a rule.
<code css>
/** Recommended **/
.m-selector {
background-color: #fff;
border: 1px solid #000;
color: #000;
display: block;
margin: 5px;
padding: 5px;
}
</code>

Do not use a measurement unit when writing a 0 value.
<code css>
/** Good **/
.m-selector {
margin: 5px 0;
}

/** Bad **/
.m-selector {
margin: 5px 0px;
}
</code>

Use lowercase and shorthand values for colours.
<code css>
/** Good **/
.m-selector {
background-color: #fff;
}

/** Bad **/
.m-selector {
background-color: #ffffff;
}
.m-selector {
background-color: #FFFFFF;
}
.m-selector {
background-color: white;
}
</code>

Always quote variable values.
<code css>
/** Good **/
.m-selector[attr="variable"] {
background-image: url("image.png");
}

/** Bad **/
.m-selector[attr=variable] {
background-image: url(image.png);
}
</code>

===Commenting===

Always comment your CSS and Less.

<code css>
/**
* Styles for the button atom.
*/
.m-element-button {
}
</code>

===Rules and exceptions for less===

Need to write some guff on Less.

==See also==
* [[User:Sam Hemelryk/Render library element planning]]
* [[Guide to creating output elements]]
* [[Renderer best practices]]
* [[Element HTML and CSS guidelines]]

Renderer best practises

2014-07-22T11:18:14Z

Samhemelryk: Replaced content with "{{obsolete}} Sorry - this page was created as a typo. Please see Renderer best practices"

{{obsolete}}
Sorry - this page was created as a typo. Please see [[Renderer best practices]]

Renderer best practices

2014-07-22T11:17:29Z

Samhemelryk: Page copied from my personal area.

{{Infobox Project
|name = Renderer consistency
|state = Specification
|tracker = https://tracker.moodle.org/browse/MDL-45853
|discussion = https://moodle.org/mod/forum/discuss.php?d=261202
|assignee = Damyon, Sam
}}
{{Work in progress|forumurl=https://moodle.org/mod/forum/discuss.php?d=261202}}

This page documents renderer best practices.

==Notes==

* Must mention atomic design and how the concept of "templates" should be applied. Relates to the next note. A forth method type for renderers?
* Within a component or plugin that has a renderer use the renderer for EVERYTHING within that area. [https://moodle.org/mod/forum/discuss.php?d=262817#p1138926 forum post that ignited this]
* Reference and probably copy the three render methods from [Guide to creating output elements]

==Renderer best practices==

This document discusses the recommended practises to follow when writing renderers for Moodle. It was created in Moodle 2.8 as part of the element library specification that took place.

Renderers provide an abstraction of logic and display. They serve Moodle to both encourage us to properly structure our code and to provide a means by which themes can take control of output to completely customise the look of Moodle.
Elements and the element library provide us a set of building blocks to use when creating output. These provide us a consistent and manageable look that also minimising the amount of customisation required by a theme to change the look and feel of Moodle.
Here we make a recommendation on how to write renderers to maximise the benefits to both yourself as a developer and to designers who have to customise the interfaces you create.

==Goals==

Its important to understand the goals for output before you start looking at renderers as they are just one part of the output plan.

'''Output in Moodle is designed to:'''
* Aid developers in properly abstracting output from logic.
* Allow designers to take complete control of output from within a theme if they wish.
* Provide a consisten look and feel for Moodle user.
* Allow developers to more rapidly create interfaces by having a set of elements at their finger tips.
* Minimise the efforts designers must extrude in order to customise the look and feel of Moodle by limiting the output to a set of elements.
* Aid designers by providing tools to support styling Moodle such as the element library.

'''Renderers in Moodle:'''
* Are the link between Moodle and a theme through which all output is generated.
* Are organised for the benefit of designers, and should be written following this document.
* Most importantly allow designers to override the HTML that wraps the data being displayed in turn allowing designers to re-design output in a theme.
* Allow designers to change the information being displayed by providing not just what is initially required but that which that may require.

==A simple set of rules for a good renderer==

Summarising what will be discussed further in this document a good renderer can be summarised as:

* Think in elements. We have an element library, when planning the output for your plugin/component start with the elements in the element library and the markup they provide.
* Containing only methods confroming to the four method types discussed below.
* Encapsulated data is given, maximising the information available to the renderer and minimising the number of arguments.
* Free of logic relating to anything except output. This includes not calculating the likes of links and capabilities.
* Uses helper methods to manipulate data where manipulate is absolutely required, essentially abstracting logic to conform to the above rule.
* Utilise the core elements as much as is possible.
* Recognise unique output needs and create element(s) for it.
* The render method should be used as often as possible to maximise consistent look.

==The don'ts==

The following are things that should not be done within a renderer.

'''DO NOT:'''
* design interfaces from scratch when desiging output for your plugin/component. Always start with the elements found in the element library.
* Use logic that isn't essential to producing output. This includes but is not limited to the following:
** Database interaction of any kind.
** Access or capability checks.
** Generation of data such as producing URL's, that should be owned by the plugin/component and made available preferably through the given arguments or failing that through a helper method.
* Generate HTML for something that should be an element, convert it to an element and call render on it.
* Create custom elements for everything you plan to output, instead try to maximise the core elements that you use.
* Write your own render methods for subelements of the elements you create. Only do this if you absolutely must change the markup from that produced by the natural render method for the element.

==Creating a renderer==

===Location and naming===
As of Moodle 2.8 renderers can be put into the output namespace. This is the recommended placement for Renderers in Moodle 2.8 and up, however the alternatives will also be listed here.

Recommended:
* Put your renderer in '''mod/yourplugin/output/renderer.php''' use the namespace '''mod_yourplugin\output''' and call your class '''renderer'''.
* To get an instance of your renderer ''$PAGE->get_renderer('mod_yourplugin')'''

This is how mod/yourplugin/output/renderer.php will look:
<code php>
<?php

namespace mod_yourplugin\output;

class renderer extends \plugin_renderer_base {
// Your renderer methods in here.
}
</code>

Also available but not recommended:
* Put your renderer in '''mod/yourplugin/renderer.php''' do NOT namespace it, and call your class '''mod_yourplugin_renderer'''.
* To get an instance of your renderer ''$PAGE->get_renderer('mod_yourplugin')'''

This was how things were done in earlier versions of Moodle (2.7 and below).

===Render methods===

Renderers can be well structured, the purpose of them is the same across all plugins and components.
There are four distinct types of render methods that you can expect to find in a renderer, and these four can be categorised into one of two categories.

The four types of render methods:
# Layout methods
# Translator methods
# Render methods
# Convenience methods

These four methods can then be categorised in two ways:
; Plugin|Component method : The layout and translator methods are plugin or component methods. They take data for a plugin or component and meld it into renderables. These methods relate to and can be said to be owned by the plugin or component.
; Element methods : The render and convenience methods relate only to elements. They take already encapsulated abstracted data and simply output HTML structure around it. They pay no regard to the plugin or component and are completely and solely bound to the output of an element.

====Layout methods====

====Translator methods====

====Render methods====
If you've spent any time working with renderers in the past you will already be familiar with the concept of a render method.
All elements within Moodle inherit the renderable interface. To produce output for them you call the renderers render method and give the element.
The render method looks at what is given and looks

====Convenience methods====
These are very simple. A convenience method is simply an easy way to build and output an element in a single step.
If you take an element, likely an atom or molecule, a convenience method would have the same arguments as the constructor for the element, build an instance of the element and call render on it.
The following is a simple example using heading:

<code php>
/**
* A convenience method to render a heading.
*/
public function heading($content, $level = 2) {
$heading = new \core\output\heading($content, $level);
return $this->render($heading);
}
</code>

==Creating output elements==
This is a big field and as such a dedicated document has been writen as a [[Guide to creating output elements]].

==Tips on properly structuring your plugin==
Talk here about OO structuring of code, ensuring a traversable heirarchy that enables maximum movement of code structure to obtain data and in turn minimises necessary arguments for layout methods.

==See also==

* [[Render library specification]]
* [[Guide to creating output elements]]
* [https://moodle.org/mod/forum/discuss.php?d=261202 Render library specification discussion]
* [[User:Sam Hemelryk/Render library element planning]]
* [[Renderer best practices]]
* [[User:Sam Hemelryk/CSS style guidelines]]

User:Sam Hemelryk/Renderer best practices

2014-07-22T11:13:16Z

Samhemelryk:

This page has now been published as [[Renderer best practices]]

User:Sam Hemelryk/Renderer best practices

2014-07-22T11:12:51Z

Samhemelryk: Replaced content with "This page has now been published as [Renderer best practices]"

This page has now been published as [Renderer best practices]

Renderer best practises

2014-07-22T11:12:04Z

Samhemelryk: Created page with "{{Infobox Project |name = Renderer consistency |state = Specification |tracker = https://tracker.moodle.org/browse/MDL-45853 |discussion = https://moodle.org/mod/forum/discuss..."

{{Infobox Project
|name = Renderer consistency
|state = Specification
|tracker = https://tracker.moodle.org/browse/MDL-45853
|discussion = https://moodle.org/mod/forum/discuss.php?d=261202
|assignee = Damyon, Sam
}}
{{Work in progress|forumurl=https://moodle.org/mod/forum/discuss.php?d=261202}}

This page documents renderer best practices.

==Notes==

* Must mention atomic design and how the concept of "templates" should be applied. Relates to the next note. A forth method type for renderers?
* Within a component or plugin that has a renderer use the renderer for EVERYTHING within that area. [https://moodle.org/mod/forum/discuss.php?d=262817#p1138926 forum post that ignited this]
* Reference and probably copy the three render methods from [Guide to creating output elements]

==Renderer best practices==

This document discusses the recommended practises to follow when writing renderers for Moodle. It was created in Moodle 2.8 as part of the element library specification that took place.

Renderers provide an abstraction of logic and display. They serve Moodle to both encourage us to properly structure our code and to provide a means by which themes can take control of output to completely customise the look of Moodle.
Elements and the element library provide us a set of building blocks to use when creating output. These provide us a consistent and manageable look that also minimising the amount of customisation required by a theme to change the look and feel of Moodle.
Here we make a recommendation on how to write renderers to maximise the benefits to both yourself as a developer and to designers who have to customise the interfaces you create.

==Goals==

Its important to understand the goals for output before you start looking at renderers as they are just one part of the output plan.

'''Output in Moodle is designed to:'''
* Aid developers in properly abstracting output from logic.
* Allow designers to take complete control of output from within a theme if they wish.
* Provide a consisten look and feel for Moodle user.
* Allow developers to more rapidly create interfaces by having a set of elements at their finger tips.
* Minimise the efforts designers must extrude in order to customise the look and feel of Moodle by limiting the output to a set of elements.
* Aid designers by providing tools to support styling Moodle such as the element library.

'''Renderers in Moodle:'''
* Are the link between Moodle and a theme through which all output is generated.
* Are organised for the benefit of designers, and should be written following this document.
* Most importantly allow designers to override the HTML that wraps the data being displayed in turn allowing designers to re-design output in a theme.
* Allow designers to change the information being displayed by providing not just what is initially required but that which that may require.

==A simple set of rules for a good renderer==

Summarising what will be discussed further in this document a good renderer can be summarised as:

* Think in elements. We have an element library, when planning the output for your plugin/component start with the elements in the element library and the markup they provide.
* Containing only methods confroming to the four method types discussed below.
* Encapsulated data is given, maximising the information available to the renderer and minimising the number of arguments.
* Free of logic relating to anything except output. This includes not calculating the likes of links and capabilities.
* Uses helper methods to manipulate data where manipulate is absolutely required, essentially abstracting logic to conform to the above rule.
* Utilise the core elements as much as is possible.
* Recognise unique output needs and create element(s) for it.
* The render method should be used as often as possible to maximise consistent look.

==The don'ts==

The following are things that should not be done within a renderer.

'''DO NOT:'''
* design interfaces from scratch when desiging output for your plugin/component. Always start with the elements found in the element library.
* Use logic that isn't essential to producing output. This includes but is not limited to the following:
** Database interaction of any kind.
** Access or capability checks.
** Generation of data such as producing URL's, that should be owned by the plugin/component and made available preferably through the given arguments or failing that through a helper method.
* Generate HTML for something that should be an element, convert it to an element and call render on it.
* Create custom elements for everything you plan to output, instead try to maximise the core elements that you use.
* Write your own render methods for subelements of the elements you create. Only do this if you absolutely must change the markup from that produced by the natural render method for the element.

==Creating a renderer==

===Location and naming===
As of Moodle 2.8 renderers can be put into the output namespace. This is the recommended placement for Renderers in Moodle 2.8 and up, however the alternatives will also be listed here.

Recommended:
* Put your renderer in '''mod/yourplugin/output/renderer.php''' use the namespace '''mod_yourplugin\output''' and call your class '''renderer'''.
* To get an instance of your renderer ''$PAGE->get_renderer('mod_yourplugin')'''

This is how mod/yourplugin/output/renderer.php will look:
<code php>
<?php

namespace mod_yourplugin\output;

class renderer extends \plugin_renderer_base {
// Your renderer methods in here.
}
</code>

Also available but not recommended:
* Put your renderer in '''mod/yourplugin/renderer.php''' do NOT namespace it, and call your class '''mod_yourplugin_renderer'''.
* To get an instance of your renderer ''$PAGE->get_renderer('mod_yourplugin')'''

This was how things were done in earlier versions of Moodle (2.7 and below).

===Render methods===

Renderers can be well structured, the purpose of them is the same across all plugins and components.
There are four distinct types of render methods that you can expect to find in a renderer, and these four can be categorised into one of two categories.

The four types of render methods:
# Layout methods
# Translator methods
# Render methods
# Convenience methods

These four methods can then be categorised in two ways:
; Plugin|Component method : The layout and translator methods are plugin or component methods. They take data for a plugin or component and meld it into renderables. These methods relate to and can be said to be owned by the plugin or component.
; Element methods : The render and convenience methods relate only to elements. They take already encapsulated abstracted data and simply output HTML structure around it. They pay no regard to the plugin or component and are completely and solely bound to the output of an element.

====Layout methods====

====Translator methods====

====Render methods====
If you've spent any time working with renderers in the past you will already be familiar with the concept of a render method.
All elements within Moodle inherit the renderable interface. To produce output for them you call the renderers render method and give the element.
The render method looks at what is given and looks

====Convenience methods====
These are very simple. A convenience method is simply an easy way to build and output an element in a single step.
If you take an element, likely an atom or molecule, a convenience method would have the same arguments as the constructor for the element, build an instance of the element and call render on it.
The following is a simple example using heading:

<code php>
/**
* A convenience method to render a heading.
*/
public function heading($content, $level = 2) {
$heading = new \core\output\heading($content, $level);
return $this->render($heading);
}
</code>

==Creating output elements==
This is a big field and as such a dedicated document has been writen as a [[Guide to creating output elements]].

==Tips on properly structuring your plugin==
Talk here about OO structuring of code, ensuring a traversable heirarchy that enables maximum movement of code structure to obtain data and in turn minimises necessary arguments for layout methods.

==See also==

* [[Render library specification]]
* [[Guide to creating output elements]]
* [https://moodle.org/mod/forum/discuss.php?d=261202 Render library specification discussion]
* [[User:Sam Hemelryk/Render library element planning]]
* [[Renderer best practices]]
* [[User:Sam Hemelryk/CSS style guidelines]]

User:Sam Hemelryk/CSS style guidelines

2014-07-22T05:27:04Z

Samhemelryk: /* Elements */

{{Infobox Project
|name = Renderer consistency
|state = Specification
|tracker = https://tracker.moodle.org/browse/MDL-45830
|discussion = https://moodle.org/mod/forum/discuss.php?d=261202
|assignee = Damyon, Sam
}}
{{Work in progress|forumurl=https://moodle.org/mod/forum/discuss.php?d=261202}}

==HTML and CSS style guide==

This is a guide to writing CSS within Moodle.

==Why have a strict guide==

At the time of writing this CSS within Moodle (2.7) themes is in a poor state and has been for a long time. Without previously having a guide we were finding that:

* As there was no formal guide to creating id's or classes, each developer does there own thing.
* As there was no formal guide on how to write CSS there were numerous techniques used when writing CSS and no consistency.
* Majority of pages create uniuqe output and require unique CSS, there is very little re-use of design.

While those points may not sound bad to you consider that in following stats from Moodle 2.7 themes:

* Base theme contains 3802 rulesets with a total of 5800 styles.
* Bootstrapbase theme contains 5170 rulesets with a total of 9362 styles.
* Clean theme contains 5172 rulesets with a total of 9366 styles.
* More theme contains 5177 rulesets with a total of 9063 styles.

You get the picture, several thousand selectors containing nearly 10000 styles.

For Moodle 2.8 we commited to introducing a element library to aid the reuse of design and documenting all aspects of output including a guide on writing CSS for Moodle. This is that guide.

==Our goals==

Its very important to understand what we are trying to achieve with this style guide and output in general.

; Frontend framework agnostic : We want theme designers to be able to apply present and future frontend frameworks to Moodle with minimal effort.
; Consistent interfaces : We want Moodle to have consistency throughout its interfaces, minimising the amount of frontend design and development that is required in coding and styling an interface.
; Cleanly formatted HTML and CSS : to minimise both development time and to make our renderers and CSS and more maintainable.

We plan to faciliate these with the following:
; Elements : Highly re-usable objects to produce HTML, these will be used consistently and relied upon by developers creating interfaces. By having these elements we create a consistent look, interface creation will be much quicker and theme designers through the re-use of a limited number of elements.
; Element library : A tool to show samples of each element, this can be used to view and test designs. It aids the developer by showing them the elements they can select from when creating an interface, and it aids designers by giving them a test area that doesn't require them to dig through every page in Moodle.
; Documentation : We will now have proper documentation on all aspects of output. Including this CSS style guide, a renderer best practices guide, and a guide to creating elements.

==Where to put CSS in Moodle core==

CSS can reside in a number of locations depending upon what you are styling.

Remember it doesn't matter how many CSS files we end up with, on a production site with Theme designer mode switched off (default) all CSS files will be combined and minimised into a single file that is served to the client.
Excepting the case of IE where we must split the CSS into several smaller files to work around browser limitations.

===CSS for elements===
As we are moving to using elements you will find that CSS for elements is where most of the effort is going to go.

CSS for elements should reside within themes only, you will find that elements must be styled in all core base themes, this means at least Bootstrapbase and base.

CSS for elements should be located within either '''theme/themename/style/elements/elementname.css''' or '''theme/themename/less/elements/elementname.css'''

The actual CSS file should be named according to the element. As elements can be namespaced we need to ensure that that is reflected in the name of the file.
For instance:

{|
! Element
! CSS location in base
! CSS location in bootstrapbase
|-
| \core\output\button
| style/elements/core_output_button.css
| less/moodle/elements/core_output_button.css
|-
| \core\output\navigation_bar
| style/elements/core_output_navigation_bar.css
| less/moodle/elements/core_output_navigation_bar.css
|-
| \mod_assign\output\user_submission
| style/elements/mod_assign_output_user_submission.css
| less/moodle/elements/mod_assign_output_user_submission.css
|}

These will still need to be included in the theme, by which ever means is relevant.
If you are using ''.css'' files like the base theme does then you will use:

<code php>
// In your themes config.php
$THEME->sheets = array(
'elements/core_output_button',
'elements/core_output_navigation_bar',
'elements/mod_assign_output_user_submission'
);
</code>

If you are using less as bootstrapbase does then you will use:
<code css>
/** In your primary less file **/
@import "moodle/elements/core_output_button";
@import "moodle/elements/core_output_navigation_bar";
@import "moodle/elements/mod_assign_output_user_submission";
</code>

===General CSS===

This is CSS for the theme that doesn't relate to a specific element. Hopefully as we convert more and more of Moodles interfaces to use elements we should see less general CSS.

In any case nothing has changed in regards to the location of general CSS.
; CSS : If your theme is using standard CSS then it must be located within the ''style'' directory of your theme and should be in logically separated files.
; Less : If your theme is using less then it should be located in a ''less/moodle'' directory within your theme.

We recommend that you separate styles into files based upon the Moodle component being styled. Again as all CSS files get combined into a single file on production sites it doesn't matter how many files you end up with.

This would lead to files named like:
* style/core.css
* style/course.css
* style/mod_forum.css

===Where to put CSS in plugins===

It is possible in Moodle to add CSS stylesheets to all plugins (including core plugins).<br />
Moodle always looks for a ''styles.css'' file within your plugins directory, and it also looks for a styles_themename.css where themename is the name of the currect theme being used.

For instance the following could be added to the forum module:

* ''mod/forum/styles.css'': Used all the time.
* ''mod/forum/styles_base.css'' : Used when the user is using the base theme.
* ''mod/forum/styles_bootstrapbase.css'' : Used when the user is using the bootstrapbase theme.
* ''mod/forum/styles_clean.css'' : Used when the user is using the clean theme.

===CSS in core plugins===

For core plugins only styles.css is permitted and it should only ever contain styles essential to the presentation of the plugin.<br />
At present styles essential for the display of the plugin are allowed here, however when the plugin interfaces have been converted to use elements this file should be nearly empty and contain only the following:
* Images, icons and text used for visual presentation such as icons to notify state (expanded/collapsed, warnings...)
* Accessiblity orientated styles required to make the interface accessible.

'''Under no circumstances should it contain any visual stylings such as border, rounded corners, and background colours not associated with state.'''

==HTML==

The following sections detail rules in place for writing HTML.

Before we start a couple of general recommendations:

; Use hyphens rather than underscores when concatenating strings in attributes : for example ''.course-new-activity-chooser'' instead of ''.course_new_activity_chooser''. By all doing this we will have a more consistent appearance and as We use underscores as part of frankenstyle which is prominent in CSS helps us to reduce the chance of naming conflicts.
; Think semantics - but don't get caught up in it : Semantic CSS is beautiful CSS lending itself ultimately to the redesign that is going to happen. But enforcing a semantic design can be an arduous journey. Instead we encourage semantic CSS but are happy to see non-semantic CSS when it is for the greater good.

===Using the ID attribute===

The situation of having a single JavaScript driven element was considered but even then it is better to style only classes and other attributes as we can't be sure what the future holds.

There are three rules you should follow when creating an ID:

# They should only be given to elements and HTML nodes that need to be interacted with by JavaScript.
# It should always start with '''m-''' ''(see note below)''
# The actual ID should be descriptive of the node and contents as a whole unit. It must fully and concisely describe its purpose.

Keep in mind that in an ideal world ID's should not be used for styling.

'''Good'''
<code html5>
<div id="m-dock"> ... </div>

<div id="m-course-new-activity-chooser"> ... </div>
</code>

'''Bad'''
<code html5>

<div id="dock"> ... </div>


<div id="m-activity-selector"> ... </div>
</code>

'''Note:''' The requirement to use m- prefix is entirely new, this has been created as this instantly reduces the chances of conflicting with present and future frontend frameworks that may be adopted by core or third party themes. Aiding our goal of being frontend framework agnostic.<br />
It will also help reduce the chance of conflicts in any third party code that may be used either by us in core, or by outside developers in their own code.
Moodle ID's will also be much more easily recognisable which we expect will be a benefit as JavaScript use in Moodle continues to increase.

===Naming CSS classes===

This is where a bit of organisation goes a long way and we want to be reasonably thorough in a consistent naming scheme and implementation.

The very first thing to mention is that all classes in Moodle must now be prefixed by *m-*.
This instantly identifes a class as belonging to Moodle, it aids us in avoiding conflicts with any non-Moodle css that may be loaded, and it is part of our framework agnostic plan.

<blockquote>
All CSS classes must start with *m-*
</blockquote>

There are several prefix that are used within Moodle output now that should not be used as prefixs for classes unless they are serving the desired purpose.

Reserved prefixes are:

; m-element : Prefix used on element classes, where m-element preceeds the name of the element, e.g. m-element-button, m-element-search
; m-state : Prefix used for CSS classes representing the state of an item, e.g. m-state-disabled, m-state-active, m-state-expanded.
; m-grid : Prefix used for creating HTML grids.

====Elements====

Semantic design where it gives the best result, smart design where there is a better solution.

If you're not already familiar with the idea of semantic CSS then Chris Coylers artical [http://css-tricks.com/semantic-class-names/ What makes for a semantic class name] is a great starting point.

We've not commit to adopting any one strict approach for writing CSS. We have adopted atomic design for our HTML elements, a design style which fits nicely with the likes of OOCSS, however be very clear that we are not adopting the OOCSS approach in its entirety. The high level abstraction of the visual aspects of elements into highly reusable agnostic classes does not always lend itself well to the Moodle world in which the we wish to be frontend framework agnostic and support largescale completely customisable themes.<br />
The highly reusable classes that appeal to one designer, or to one frontend framework may not apply to another.<br />
This decision is also impacted by our current default theme bootstrapbase that does not use well abstracted OOCSS in its design.

Atomic design is going to see us end up with many parent child relationships in our HTML that we must carry through to our CSS. Through atomic design we start with smalled atoms and molecules that get built into larger organisms and placed within layouts.

Every element should have a single class that identifies it as element X.

For instance the button atom will have the class *m-element-button*

<code html5>
<button class="m-element-button">I am a button</button>
</code>

This is simply the prefix "m-element" plus the element name.

The purpose of this class is to allow the element to be styled with ease. The class name should be applied to the root node for the element, it should never be applied any lower.

By having one class for the element, and always and only applied to the root node it makes it very easy in HTML to see where one element belongs to another.

The following is an example of the search molecule, which in turn contains two button atoms.
<code html5>
<form class="m-element-confirmation">
<h3>Are you sure?</h3>
<p>Are you sure you want to perform this action?</p>
<input type="submit" name="cancel" class="m-element-button" value="Cancel" />
<input type="submit" name="continue" class="m-element-button" value="Continue" />
</form>
</code>

We've chosen to partially adopt BEM as a CSS standard when writing CSS for elements.
BEM isn't a new CSS standard, but its not widely known either. Its existence fills a gap in how to style elements consistently. Through two basic notation techniques you can easily notate the purpose of structures that belong to an element and notate the intent of an element that is desired if the element has multiple versions.

; Notating purpose : Here we use a suffix *__purpose*, the key being the two underscores.
; Notating intent : Here we use a suffix *--intent*, the key being the two hyphens.

You'll notice in the example above that there is no way to style the continue button differently from the cancel button without relying on its name, something we certainly don't want to do.
The solution is to wrap each button in a div and give each div a class.
The BEM standard comes into play here in naming the classes, the following shows how you would apply BEM to show the purpose of each button in a way that can be easily interpreted and styled in CSS.

<code html5>
<form class="m-element-confirmation">
<h3>Are you sure?</h3>
<p>Are you sure you want to perform this action?</p>
<div class="m-element-confirmation__cancel">
<input type="submit" name="cancel" class="m-element-button" value="Cancel" />
</div>
<div class="m-element-confirmation__continue">
<input type="submit" name="continue" class="m-element-button" value="Continue" />
</div>
</form>
</code>

You can now each button is wrapped in a div with a class, *m-element-confirmation__cancel* and *m-element-confirmation__continue*.
This class can be read by the themer and because of the __ can be easily identified as both belonging to the m-element-confirmation and serving a specific purpose, continue or cancel.

Now to explain the idea of intents.
An intent is when a single element takes on a different apprearance to convey a specific meaning. A little bit like a state, but with more meaning.
An easy example is notifications where you will no doubt be familiar with the idea of having a error notifications, warning notifications, success notification etc. Each of error, warning, and success is a intent.

The following shows how this would work:
<code html5>

<div class="m-element-notification">You have not changed your password in the past 60 days</div>


<div class="m-element-notification m-element-notification--warning">You have not changed your password in the past 60 days</div>
</div>
</code>

====Grids====

We need to adopt a single grid framework.

Personally I don't think we should use pure bootstrap or pure YUI, instead we should choose one of these and build it use our class name structures.

All grid classes should start with m-grid.

==CSS==

Before we begin lets lay down some ground level goals, things that will help us achieve clear and understandable CSS in the future.
* Formatting, ordering, alignment, and spacing are all important in having CSS that can be easily read by others.
* Don't optimise your CSS, be verbose and stick to the styles in this guide. We have tools that will handle optimisation for you.
* Never use *!important* in your CSS unless it is absolutely impossible to avoid doing so.

===Terminology===

Its important that when we are speaking about CSS we are speaking the same language.
Lets look at the following example:

<code css>
.m-page .m-selector-1,
.m-page .m-selector-2,
.m-page .m-selector-3 {
background-color: #FFF;
color: #000;
}

.m-selector-1 {
margin: 1em;
}
</code>

; Ruleset : Each of the two rules is a single *ruleset*.
; Rule: _.m-page .m-selector-1_ is a rule.
; Selector : _.m-selector-1_ is a *selector*, it is a single part of a rule.
; Declaration : _background-color: #FFF_ is a declaration.
;

===Essential formatting===

The following are the guies for writing CSS.

* Always use spaces - never use tabs. All editors can be configured to do it.
* Indent by 4 spaces - never more, never less.
* A single empty line between rulesets to maintain consistent spacing of rules.
* One rule per line.
* A single space between each selector in a rule.
* No space between a rule and the comma in a ruleset.
* A single space between a selector and the opening brace of a ruleset.
* One level of indentation before each declaration.
* A single space the colon in a declaration.
* A single space after each item in a declaration containing multiple items.

The following shows how the above rules apply:
<code css>
.m-selector-1,
.m-selector-2 .m-selector-3 {
background: #ffa800 url("background.png") no-repeat right top;
border: 1px solid #000;
display: inline-block;
font-family: arial, sans-serif;
margin: 5px 10px;
padding: 0;
}

.m-selector-4 {
border-radius: 3px;
}
</code>

===General rules===

Declaration ordering is the very first thing to discuss. There is no strict rule on how to order your declarations, however there is a recommendation.
We recommend that you order declarations within a ruleset alphabetically.
If we all start doing this then when you read CSS written by someone else you will soon learn to very quickly find your way around the declarations within a rule.
<code css>
/** Recommended **/
.m-selector {
background-color: #fff;
border: 1px solid #000;
color: #000;
display: block;
margin: 5px;
padding: 5px;
}
</code>

Do not use a measurement unit when writing a 0 value.
<code css>
/** Good **/
.m-selector {
margin: 5px 0;
}

/** Bad **/
.m-selector {
margin: 5px 0px;
}
</code>

Use lowercase and shorthand values for colours.
<code css>
/** Good **/
.m-selector {
background-color: #fff;
}

/** Bad **/
.m-selector {
background-color: #ffffff;
}
.m-selector {
background-color: #FFFFFF;
}
.m-selector {
background-color: white;
}
</code>

Always quote variable values.
<code css>
/** Good **/
.m-selector[attr="variable"] {
background-image: url("image.png");
}

/** Bad **/
.m-selector[attr=variable] {
background-image: url(image.png);
}
</code>

===Commenting===

Always comment your CSS and Less.

<code css>
/**
* Styles for the button atom.
*/
.m-element-button {
}
</code>

===Rules and exceptions for less===

Need to write some guff on Less.

==See also==
* [[User:Sam Hemelryk/Render library element planning]]
* [[Guide to creating output elements]] ''originally written at [[User:Sam Hemelryk/Creating renderable components]]''
* [[User:Sam Hemelryk/Renderer best practices]]
* [[User:Sam Hemelryk/CSS style guidelines]]

User:Sam Hemelryk/CSS style guidelines

2014-07-22T05:26:32Z

Samhemelryk: /* Elements */

{{Infobox Project
|name = Renderer consistency
|state = Specification
|tracker = https://tracker.moodle.org/browse/MDL-45830
|discussion = https://moodle.org/mod/forum/discuss.php?d=261202
|assignee = Damyon, Sam
}}
{{Work in progress|forumurl=https://moodle.org/mod/forum/discuss.php?d=261202}}

==HTML and CSS style guide==

This is a guide to writing CSS within Moodle.

==Why have a strict guide==

At the time of writing this CSS within Moodle (2.7) themes is in a poor state and has been for a long time. Without previously having a guide we were finding that:

* As there was no formal guide to creating id's or classes, each developer does there own thing.
* As there was no formal guide on how to write CSS there were numerous techniques used when writing CSS and no consistency.
* Majority of pages create uniuqe output and require unique CSS, there is very little re-use of design.

While those points may not sound bad to you consider that in following stats from Moodle 2.7 themes:

* Base theme contains 3802 rulesets with a total of 5800 styles.
* Bootstrapbase theme contains 5170 rulesets with a total of 9362 styles.
* Clean theme contains 5172 rulesets with a total of 9366 styles.
* More theme contains 5177 rulesets with a total of 9063 styles.

You get the picture, several thousand selectors containing nearly 10000 styles.

For Moodle 2.8 we commited to introducing a element library to aid the reuse of design and documenting all aspects of output including a guide on writing CSS for Moodle. This is that guide.

==Our goals==

Its very important to understand what we are trying to achieve with this style guide and output in general.

; Frontend framework agnostic : We want theme designers to be able to apply present and future frontend frameworks to Moodle with minimal effort.
; Consistent interfaces : We want Moodle to have consistency throughout its interfaces, minimising the amount of frontend design and development that is required in coding and styling an interface.
; Cleanly formatted HTML and CSS : to minimise both development time and to make our renderers and CSS and more maintainable.

We plan to faciliate these with the following:
; Elements : Highly re-usable objects to produce HTML, these will be used consistently and relied upon by developers creating interfaces. By having these elements we create a consistent look, interface creation will be much quicker and theme designers through the re-use of a limited number of elements.
; Element library : A tool to show samples of each element, this can be used to view and test designs. It aids the developer by showing them the elements they can select from when creating an interface, and it aids designers by giving them a test area that doesn't require them to dig through every page in Moodle.
; Documentation : We will now have proper documentation on all aspects of output. Including this CSS style guide, a renderer best practices guide, and a guide to creating elements.

==Where to put CSS in Moodle core==

CSS can reside in a number of locations depending upon what you are styling.

Remember it doesn't matter how many CSS files we end up with, on a production site with Theme designer mode switched off (default) all CSS files will be combined and minimised into a single file that is served to the client.
Excepting the case of IE where we must split the CSS into several smaller files to work around browser limitations.

===CSS for elements===
As we are moving to using elements you will find that CSS for elements is where most of the effort is going to go.

CSS for elements should reside within themes only, you will find that elements must be styled in all core base themes, this means at least Bootstrapbase and base.

CSS for elements should be located within either '''theme/themename/style/elements/elementname.css''' or '''theme/themename/less/elements/elementname.css'''

The actual CSS file should be named according to the element. As elements can be namespaced we need to ensure that that is reflected in the name of the file.
For instance:

{|
! Element
! CSS location in base
! CSS location in bootstrapbase
|-
| \core\output\button
| style/elements/core_output_button.css
| less/moodle/elements/core_output_button.css
|-
| \core\output\navigation_bar
| style/elements/core_output_navigation_bar.css
| less/moodle/elements/core_output_navigation_bar.css
|-
| \mod_assign\output\user_submission
| style/elements/mod_assign_output_user_submission.css
| less/moodle/elements/mod_assign_output_user_submission.css
|}

These will still need to be included in the theme, by which ever means is relevant.
If you are using ''.css'' files like the base theme does then you will use:

<code php>
// In your themes config.php
$THEME->sheets = array(
'elements/core_output_button',
'elements/core_output_navigation_bar',
'elements/mod_assign_output_user_submission'
);
</code>

If you are using less as bootstrapbase does then you will use:
<code css>
/** In your primary less file **/
@import "moodle/elements/core_output_button";
@import "moodle/elements/core_output_navigation_bar";
@import "moodle/elements/mod_assign_output_user_submission";
</code>

===General CSS===

This is CSS for the theme that doesn't relate to a specific element. Hopefully as we convert more and more of Moodles interfaces to use elements we should see less general CSS.

In any case nothing has changed in regards to the location of general CSS.
; CSS : If your theme is using standard CSS then it must be located within the ''style'' directory of your theme and should be in logically separated files.
; Less : If your theme is using less then it should be located in a ''less/moodle'' directory within your theme.

We recommend that you separate styles into files based upon the Moodle component being styled. Again as all CSS files get combined into a single file on production sites it doesn't matter how many files you end up with.

This would lead to files named like:
* style/core.css
* style/course.css
* style/mod_forum.css

===Where to put CSS in plugins===

It is possible in Moodle to add CSS stylesheets to all plugins (including core plugins).<br />
Moodle always looks for a ''styles.css'' file within your plugins directory, and it also looks for a styles_themename.css where themename is the name of the currect theme being used.

For instance the following could be added to the forum module:

* ''mod/forum/styles.css'': Used all the time.
* ''mod/forum/styles_base.css'' : Used when the user is using the base theme.
* ''mod/forum/styles_bootstrapbase.css'' : Used when the user is using the bootstrapbase theme.
* ''mod/forum/styles_clean.css'' : Used when the user is using the clean theme.

===CSS in core plugins===

For core plugins only styles.css is permitted and it should only ever contain styles essential to the presentation of the plugin.<br />
At present styles essential for the display of the plugin are allowed here, however when the plugin interfaces have been converted to use elements this file should be nearly empty and contain only the following:
* Images, icons and text used for visual presentation such as icons to notify state (expanded/collapsed, warnings...)
* Accessiblity orientated styles required to make the interface accessible.

'''Under no circumstances should it contain any visual stylings such as border, rounded corners, and background colours not associated with state.'''

==HTML==

The following sections detail rules in place for writing HTML.

Before we start a couple of general recommendations:

; Use hyphens rather than underscores when concatenating strings in attributes : for example ''.course-new-activity-chooser'' instead of ''.course_new_activity_chooser''. By all doing this we will have a more consistent appearance and as We use underscores as part of frankenstyle which is prominent in CSS helps us to reduce the chance of naming conflicts.
; Think semantics - but don't get caught up in it : Semantic CSS is beautiful CSS lending itself ultimately to the redesign that is going to happen. But enforcing a semantic design can be an arduous journey. Instead we encourage semantic CSS but are happy to see non-semantic CSS when it is for the greater good.

===Using the ID attribute===

The situation of having a single JavaScript driven element was considered but even then it is better to style only classes and other attributes as we can't be sure what the future holds.

There are three rules you should follow when creating an ID:

# They should only be given to elements and HTML nodes that need to be interacted with by JavaScript.
# It should always start with '''m-''' ''(see note below)''
# The actual ID should be descriptive of the node and contents as a whole unit. It must fully and concisely describe its purpose.

Keep in mind that in an ideal world ID's should not be used for styling.

'''Good'''
<code html5>
<div id="m-dock"> ... </div>

<div id="m-course-new-activity-chooser"> ... </div>
</code>

'''Bad'''
<code html5>

<div id="dock"> ... </div>


<div id="m-activity-selector"> ... </div>
</code>

'''Note:''' The requirement to use m- prefix is entirely new, this has been created as this instantly reduces the chances of conflicting with present and future frontend frameworks that may be adopted by core or third party themes. Aiding our goal of being frontend framework agnostic.<br />
It will also help reduce the chance of conflicts in any third party code that may be used either by us in core, or by outside developers in their own code.
Moodle ID's will also be much more easily recognisable which we expect will be a benefit as JavaScript use in Moodle continues to increase.

===Naming CSS classes===

This is where a bit of organisation goes a long way and we want to be reasonably thorough in a consistent naming scheme and implementation.

The very first thing to mention is that all classes in Moodle must now be prefixed by *m-*.
This instantly identifes a class as belonging to Moodle, it aids us in avoiding conflicts with any non-Moodle css that may be loaded, and it is part of our framework agnostic plan.

<blockquote>
All CSS classes must start with *m-*
</blockquote>

There are several prefix that are used within Moodle output now that should not be used as prefixs for classes unless they are serving the desired purpose.

Reserved prefixes are:

; m-element : Prefix used on element classes, where m-element preceeds the name of the element, e.g. m-element-button, m-element-search
; m-state : Prefix used for CSS classes representing the state of an item, e.g. m-state-disabled, m-state-active, m-state-expanded.
; m-grid : Prefix used for creating HTML grids.

====Elements====

Semantic design where it gives the best result, smart design where there is a better solution.

If you're not already familiar with the idea of semantic CSS then Chris Coylers artical [http://css-tricks.com/semantic-class-names/ What makes for a semantic class name] is a great starting point.

We've not commit to adopting any one strict approach for writing CSS. We have adopted atomic design for our HTML elements, a design style which fits nicely with the likes of OOCSS, however be very clear that we are not adopting the OOCSS approach in its entirety. The high level abstraction of the visual aspects of elements into highly reusable agnostic classes does not always lend itself well to the Moodle world in which the we wish to be frontend framework agnostic and support largescale completely customisable themes.<br />
The highly reusable classes that appeal to one designer, or to one frontend framework may not apply to another.<br />
This decision is also impacted by our current default theme bootstrapbase that does not use well abstracted OOCSS in its design.

Atomic design is going to see us end up with many parent child relationships in our HTML that we must carry through to our CSS. Through atomic design we start with smalled atoms and molecules that get built into larger organisms and placed within layouts.

Every element should have a single class that identifies it as element X.

For instance the button atom will have the class *m-element-button*

<code html5>
<button class="m-element-button">I am a button</button>
</code>

This is simply the prefix "m-element" plus the element name.

The purpose of this class is to allow the element to be styled with ease. The class name should be applied to the root node for the element, it should never be applied any lower.

By having one class for the element, and always and only applied to the root node it makes it very easy in HTML to see where one element belongs to another.

The following is an example of the search molecule, which in turn contains two button atoms.
<code html5>
<form class="m-element-confirmation">
<h3>Are you sure?</h3>
<p>Are you sure you want to perform this action?</p>
<input type="submit" name="cancel" class="m-element-button" value="Cancel" />
<input type="submit" name="continue" class="m-element-button" value="Continue" />
</form>
</code>

We've chosen to partially adopt BEM as a CSS standard when writing CSS for elements.
BEM isn't a new CSS standard, but its not widely known either. Its existence fills a gap in how to style elements consistently. Through two basic notation techniques you can easily notate the purpose of structures that belong to an element and notate the intent of an element that is desired if the element has multiple versions.

; Notating purpose : Here we use a suffix *__purpose*, the key being the two underscores.
; Notating intent : Here we use a suffix *--intent*, the key being the two hyphens.

You'll notice in the example above that there is no way to style the continue button differently from the cancel button without relying on its name, something we certainly don't want to do.
The solution is to wrap each button in a div and give each div a class.
The BEM standard comes into play here in naming the classes, the following shows how you would apply BEM to show the purpose of each button in a way that can be easily interpreted and styled in CSS.

<code html5>
<form class="m-element-confirmation">
<h3>Are you sure?</h3>
<p>Are you sure you want to perform this action?</p>
<div class="m-element-confirmation__cancel">
<input type="submit" name="cancel" class="m-element-button" value="Cancel" />
</div>
<div class="m-element-confirmation__continue">
<input type="submit" name="continue" class="m-element-button" value="Continue" />
</div>
</form>
</code>

You can now each button is wrapped in a div with a class, *m-element-confirmation__cancel* and *m-element-confirmation__continue*.
This class can be read by the themer and because of the __ can be easily identified as both belonging to the m-element-confirmation and serving a specific purpose, continue or cancel.

Now to explain the idea of intents.
An intent is when a single element takes on a different apprearance to convey a specific meaning. A little bit like a state, but with more meaning.
An easy example is notifications where you will no doubt be familiar with the idea of having a error notifications, warning notifications, success notification etc. Each of error, warning, and success is a intent.

The following shows how this would work:
<code html5>

<div class="m-element-notification">You have not changed your password in the past 60 days</div>


<div class="m-element-notification m-element-notification--warning">You have not changed your password in the past 60 days</div>
</div>

====Grids====

We need to adopt a single grid framework.

Personally I don't think we should use pure bootstrap or pure YUI, instead we should choose one of these and build it use our class name structures.

All grid classes should start with m-grid.

==CSS==

Before we begin lets lay down some ground level goals, things that will help us achieve clear and understandable CSS in the future.
* Formatting, ordering, alignment, and spacing are all important in having CSS that can be easily read by others.
* Don't optimise your CSS, be verbose and stick to the styles in this guide. We have tools that will handle optimisation for you.
* Never use *!important* in your CSS unless it is absolutely impossible to avoid doing so.

===Terminology===

Its important that when we are speaking about CSS we are speaking the same language.
Lets look at the following example:

<code css>
.m-page .m-selector-1,
.m-page .m-selector-2,
.m-page .m-selector-3 {
background-color: #FFF;
color: #000;
}

.m-selector-1 {
margin: 1em;
}
</code>

; Ruleset : Each of the two rules is a single *ruleset*.
; Rule: _.m-page .m-selector-1_ is a rule.
; Selector : _.m-selector-1_ is a *selector*, it is a single part of a rule.
; Declaration : _background-color: #FFF_ is a declaration.
;

===Essential formatting===

The following are the guies for writing CSS.

* Always use spaces - never use tabs. All editors can be configured to do it.
* Indent by 4 spaces - never more, never less.
* A single empty line between rulesets to maintain consistent spacing of rules.
* One rule per line.
* A single space between each selector in a rule.
* No space between a rule and the comma in a ruleset.
* A single space between a selector and the opening brace of a ruleset.
* One level of indentation before each declaration.
* A single space the colon in a declaration.
* A single space after each item in a declaration containing multiple items.

The following shows how the above rules apply:
<code css>
.m-selector-1,
.m-selector-2 .m-selector-3 {
background: #ffa800 url("background.png") no-repeat right top;
border: 1px solid #000;
display: inline-block;
font-family: arial, sans-serif;
margin: 5px 10px;
padding: 0;
}

.m-selector-4 {
border-radius: 3px;
}
</code>

===General rules===

Declaration ordering is the very first thing to discuss. There is no strict rule on how to order your declarations, however there is a recommendation.
We recommend that you order declarations within a ruleset alphabetically.
If we all start doing this then when you read CSS written by someone else you will soon learn to very quickly find your way around the declarations within a rule.
<code css>
/** Recommended **/
.m-selector {
background-color: #fff;
border: 1px solid #000;
color: #000;
display: block;
margin: 5px;
padding: 5px;
}
</code>

Do not use a measurement unit when writing a 0 value.
<code css>
/** Good **/
.m-selector {
margin: 5px 0;
}

/** Bad **/
.m-selector {
margin: 5px 0px;
}
</code>

Use lowercase and shorthand values for colours.
<code css>
/** Good **/
.m-selector {
background-color: #fff;
}

/** Bad **/
.m-selector {
background-color: #ffffff;
}
.m-selector {
background-color: #FFFFFF;
}
.m-selector {
background-color: white;
}
</code>

Always quote variable values.
<code css>
/** Good **/
.m-selector[attr="variable"] {
background-image: url("image.png");
}

/** Bad **/
.m-selector[attr=variable] {
background-image: url(image.png);
}
</code>

===Commenting===

Always comment your CSS and Less.

<code css>
/**
* Styles for the button atom.
*/
.m-element-button {
}
</code>

===Rules and exceptions for less===

Need to write some guff on Less.

==See also==
* [[User:Sam Hemelryk/Render library element planning]]
* [[Guide to creating output elements]] ''originally written at [[User:Sam Hemelryk/Creating renderable components]]''
* [[User:Sam Hemelryk/Renderer best practices]]
* [[User:Sam Hemelryk/CSS style guidelines]]

User:Sam Hemelryk/CSS style guidelines

2014-07-22T05:25:04Z

Samhemelryk:

{{Infobox Project
|name = Renderer consistency
|state = Specification
|tracker = https://tracker.moodle.org/browse/MDL-45830
|discussion = https://moodle.org/mod/forum/discuss.php?d=261202
|assignee = Damyon, Sam
}}
{{Work in progress|forumurl=https://moodle.org/mod/forum/discuss.php?d=261202}}

==HTML and CSS style guide==

This is a guide to writing CSS within Moodle.

==Why have a strict guide==

At the time of writing this CSS within Moodle (2.7) themes is in a poor state and has been for a long time. Without previously having a guide we were finding that:

* As there was no formal guide to creating id's or classes, each developer does there own thing.
* As there was no formal guide on how to write CSS there were numerous techniques used when writing CSS and no consistency.
* Majority of pages create uniuqe output and require unique CSS, there is very little re-use of design.

While those points may not sound bad to you consider that in following stats from Moodle 2.7 themes:

* Base theme contains 3802 rulesets with a total of 5800 styles.
* Bootstrapbase theme contains 5170 rulesets with a total of 9362 styles.
* Clean theme contains 5172 rulesets with a total of 9366 styles.
* More theme contains 5177 rulesets with a total of 9063 styles.

You get the picture, several thousand selectors containing nearly 10000 styles.

For Moodle 2.8 we commited to introducing a element library to aid the reuse of design and documenting all aspects of output including a guide on writing CSS for Moodle. This is that guide.

==Our goals==

Its very important to understand what we are trying to achieve with this style guide and output in general.

; Frontend framework agnostic : We want theme designers to be able to apply present and future frontend frameworks to Moodle with minimal effort.
; Consistent interfaces : We want Moodle to have consistency throughout its interfaces, minimising the amount of frontend design and development that is required in coding and styling an interface.
; Cleanly formatted HTML and CSS : to minimise both development time and to make our renderers and CSS and more maintainable.

We plan to faciliate these with the following:
; Elements : Highly re-usable objects to produce HTML, these will be used consistently and relied upon by developers creating interfaces. By having these elements we create a consistent look, interface creation will be much quicker and theme designers through the re-use of a limited number of elements.
; Element library : A tool to show samples of each element, this can be used to view and test designs. It aids the developer by showing them the elements they can select from when creating an interface, and it aids designers by giving them a test area that doesn't require them to dig through every page in Moodle.
; Documentation : We will now have proper documentation on all aspects of output. Including this CSS style guide, a renderer best practices guide, and a guide to creating elements.

==Where to put CSS in Moodle core==

CSS can reside in a number of locations depending upon what you are styling.

Remember it doesn't matter how many CSS files we end up with, on a production site with Theme designer mode switched off (default) all CSS files will be combined and minimised into a single file that is served to the client.
Excepting the case of IE where we must split the CSS into several smaller files to work around browser limitations.

===CSS for elements===
As we are moving to using elements you will find that CSS for elements is where most of the effort is going to go.

CSS for elements should reside within themes only, you will find that elements must be styled in all core base themes, this means at least Bootstrapbase and base.

CSS for elements should be located within either '''theme/themename/style/elements/elementname.css''' or '''theme/themename/less/elements/elementname.css'''

The actual CSS file should be named according to the element. As elements can be namespaced we need to ensure that that is reflected in the name of the file.
For instance:

{|
! Element
! CSS location in base
! CSS location in bootstrapbase
|-
| \core\output\button
| style/elements/core_output_button.css
| less/moodle/elements/core_output_button.css
|-
| \core\output\navigation_bar
| style/elements/core_output_navigation_bar.css
| less/moodle/elements/core_output_navigation_bar.css
|-
| \mod_assign\output\user_submission
| style/elements/mod_assign_output_user_submission.css
| less/moodle/elements/mod_assign_output_user_submission.css
|}

These will still need to be included in the theme, by which ever means is relevant.
If you are using ''.css'' files like the base theme does then you will use:

<code php>
// In your themes config.php
$THEME->sheets = array(
'elements/core_output_button',
'elements/core_output_navigation_bar',
'elements/mod_assign_output_user_submission'
);
</code>

If you are using less as bootstrapbase does then you will use:
<code css>
/** In your primary less file **/
@import "moodle/elements/core_output_button";
@import "moodle/elements/core_output_navigation_bar";
@import "moodle/elements/mod_assign_output_user_submission";
</code>

===General CSS===

This is CSS for the theme that doesn't relate to a specific element. Hopefully as we convert more and more of Moodles interfaces to use elements we should see less general CSS.

In any case nothing has changed in regards to the location of general CSS.
; CSS : If your theme is using standard CSS then it must be located within the ''style'' directory of your theme and should be in logically separated files.
; Less : If your theme is using less then it should be located in a ''less/moodle'' directory within your theme.

We recommend that you separate styles into files based upon the Moodle component being styled. Again as all CSS files get combined into a single file on production sites it doesn't matter how many files you end up with.

This would lead to files named like:
* style/core.css
* style/course.css
* style/mod_forum.css

===Where to put CSS in plugins===

It is possible in Moodle to add CSS stylesheets to all plugins (including core plugins).<br />
Moodle always looks for a ''styles.css'' file within your plugins directory, and it also looks for a styles_themename.css where themename is the name of the currect theme being used.

For instance the following could be added to the forum module:

* ''mod/forum/styles.css'': Used all the time.
* ''mod/forum/styles_base.css'' : Used when the user is using the base theme.
* ''mod/forum/styles_bootstrapbase.css'' : Used when the user is using the bootstrapbase theme.
* ''mod/forum/styles_clean.css'' : Used when the user is using the clean theme.

===CSS in core plugins===

For core plugins only styles.css is permitted and it should only ever contain styles essential to the presentation of the plugin.<br />
At present styles essential for the display of the plugin are allowed here, however when the plugin interfaces have been converted to use elements this file should be nearly empty and contain only the following:
* Images, icons and text used for visual presentation such as icons to notify state (expanded/collapsed, warnings...)
* Accessiblity orientated styles required to make the interface accessible.

'''Under no circumstances should it contain any visual stylings such as border, rounded corners, and background colours not associated with state.'''

==HTML==

The following sections detail rules in place for writing HTML.

Before we start a couple of general recommendations:

; Use hyphens rather than underscores when concatenating strings in attributes : for example ''.course-new-activity-chooser'' instead of ''.course_new_activity_chooser''. By all doing this we will have a more consistent appearance and as We use underscores as part of frankenstyle which is prominent in CSS helps us to reduce the chance of naming conflicts.
; Think semantics - but don't get caught up in it : Semantic CSS is beautiful CSS lending itself ultimately to the redesign that is going to happen. But enforcing a semantic design can be an arduous journey. Instead we encourage semantic CSS but are happy to see non-semantic CSS when it is for the greater good.

===Using the ID attribute===

The situation of having a single JavaScript driven element was considered but even then it is better to style only classes and other attributes as we can't be sure what the future holds.

There are three rules you should follow when creating an ID:

# They should only be given to elements and HTML nodes that need to be interacted with by JavaScript.
# It should always start with '''m-''' ''(see note below)''
# The actual ID should be descriptive of the node and contents as a whole unit. It must fully and concisely describe its purpose.

Keep in mind that in an ideal world ID's should not be used for styling.

'''Good'''
<code html5>
<div id="m-dock"> ... </div>

<div id="m-course-new-activity-chooser"> ... </div>
</code>

'''Bad'''
<code html5>

<div id="dock"> ... </div>


<div id="m-activity-selector"> ... </div>
</code>

'''Note:''' The requirement to use m- prefix is entirely new, this has been created as this instantly reduces the chances of conflicting with present and future frontend frameworks that may be adopted by core or third party themes. Aiding our goal of being frontend framework agnostic.<br />
It will also help reduce the chance of conflicts in any third party code that may be used either by us in core, or by outside developers in their own code.
Moodle ID's will also be much more easily recognisable which we expect will be a benefit as JavaScript use in Moodle continues to increase.

===Naming CSS classes===

This is where a bit of organisation goes a long way and we want to be reasonably thorough in a consistent naming scheme and implementation.

The very first thing to mention is that all classes in Moodle must now be prefixed by *m-*.
This instantly identifes a class as belonging to Moodle, it aids us in avoiding conflicts with any non-Moodle css that may be loaded, and it is part of our framework agnostic plan.

<blockquote>
All CSS classes must start with *m-*
</blockquote>

There are several prefix that are used within Moodle output now that should not be used as prefixs for classes unless they are serving the desired purpose.

Reserved prefixes are:

; m-element : Prefix used on element classes, where m-element preceeds the name of the element, e.g. m-element-button, m-element-search
; m-state : Prefix used for CSS classes representing the state of an item, e.g. m-state-disabled, m-state-active, m-state-expanded.
; m-grid : Prefix used for creating HTML grids.

====Elements====

Semantic design where it gives the best result, smart design where there is a better solution.

If you're not already familiar with the idea of semantic CSS then Chris Coylers artical [http://css-tricks.com/semantic-class-names/ What makes for a semantic class name] is a great starting point.

We've not commit to adopting any one strict approach for writing CSS. We have adopted atomic design for our HTML elements, a design style which fits nicely with the likes of OOCSS, however be very clear that we are not adopting the OOCSS approach in its entirety. The high level abstraction of the visual aspects of elements into highly reusable agnostic classes does not always lend itself well to the Moodle world in which the we wish to be frontend framework agnostic and support largescale completely customisable themes.<br />
The highly reusable classes that appeal to one designer, or to one frontend framework may not apply to another.<br />
This decision is also impacted by our current default theme bootstrapbase that does not use well abstracted OOCSS in its design.

Atomic design is going to see us end up with many parent child relationships in our HTML that we must carry through to our CSS. Through atomic design we start with smalled atoms and molecules that get built into larger organisms and placed within layouts.

Every element should have a single class that identifies it as element X.

For instance the button atom will have the class *m-element-button*

<code html5>
<button class="m-element-button">I am a button</button>
</code>

This is simply the prefix "m-element" plus the element name.

The purpose of this class is to allow the element to be styled with ease. The class name should be applied to the root node for the element, it should never be applied any lower.

By having one class for the element, and always and only applied to the root node it makes it very easy in HTML to see where one element belongs to another.

The following is an example of the search molecule, which in turn contains two button atoms.
<code html5>
<form class="m-element-confirmation">
<h3>Are you sure?</h3>
<p>Are you sure you want to perform this action?</p>
<input type="submit" name="cancel" class="m-element-button" value="Cancel" />
<input type="submit" name="continue" class="m-element-button" value="Continue" />
</form>
</code>

We've chosen to partially adopt BEM as a CSS standard when writing CSS for elements.
BEM isn't a new CSS standard, but its not widely known either. Its existence fills a gap in how to style elements consistently. Through two basic notation techniques you can easily notate the purpose of structures that belong to an element and notate the intent of an element that is desired if the element has multiple versions.

; Notating purpose : Here we use a suffix *__purpose*, the key being the two underscores.
; Notating intent : Here we use a suffix *--intent*, the key being the two hyphens.

You'll notice in the example above that there is no way to style the continue button differently from the cancel button without relying on its name, something we certainly don't want to do.
The solution is to wrap each button in a div and give each div a class.
The BEM standard comes into play here in naming the classes, the following shows how you would apply BEM to show the purpose of each button in a way that can be easily interpreted and styled in CSS.

<code html5>
<form class="m-element-confirmation">
<h3>Are you sure?</h3>
<p>Are you sure you want to perform this action?</p>
<div class="m-element-confirmation__cancel">
<input type="submit" name="cancel" class="m-element-button" value="Cancel" />
</div>
<div class="m-element-confirmation__continue">
<input type="submit" name="continue" class="m-element-button" value="Continue" />
</div>
</form>
</code>

You can now each button is wrapped in a div with a class, *m-element-confirmation__cancel* and *m-element-confirmation__continue*.
This class can be read by the themer and because of the __ can be easily identified as both belonging to the m-element-confirmation and serving a specific purpose, continue or cancel.

Now to explain the idea of intents.
An intent is when a single element takes on a different apprearance to convey a specific meaning. A little bit like a state, but with more meaning.
An easy example is notifications where you will no doubt be familiar with the idea of having a error notifications, warning notifications, success notification etc. Each of error, warning, and success is a intent.

The following shows how this would work:
<code html5>

<div class="m-element-notification">You have not changed your password in the past 60 days</div>


<div class="m-element-notification m-element-notification--warning">You have not changed your password in the past 60 days</div>
</div>

====Grids====

We need to adopt a single grid framework.

Personally I don't think we should use pure bootstrap or pure YUI, instead we should choose one of these and build it use our class name structures.

All grid classes should start with m-grid.

==CSS==

Before we begin lets lay down some ground level goals, things that will help us achieve clear and understandable CSS in the future.
* Formatting, ordering, alignment, and spacing are all important in having CSS that can be easily read by others.
* Don't optimise your CSS, be verbose and stick to the styles in this guide. We have tools that will handle optimisation for you.
* Never use *!important* in your CSS unless it is absolutely impossible to avoid doing so.

===Terminology===

Its important that when we are speaking about CSS we are speaking the same language.
Lets look at the following example:

<code css>
.m-page .m-selector-1,
.m-page .m-selector-2,
.m-page .m-selector-3 {
background-color: #FFF;
color: #000;
}

.m-selector-1 {
margin: 1em;
}
</code>

; Ruleset : Each of the two rules is a single *ruleset*.
; Rule: _.m-page .m-selector-1_ is a rule.
; Selector : _.m-selector-1_ is a *selector*, it is a single part of a rule.
; Declaration : _background-color: #FFF_ is a declaration.
;

===Essential formatting===

The following are the guies for writing CSS.

* Always use spaces - never use tabs. All editors can be configured to do it.
* Indent by 4 spaces - never more, never less.
* A single empty line between rulesets to maintain consistent spacing of rules.
* One rule per line.
* A single space between each selector in a rule.
* No space between a rule and the comma in a ruleset.
* A single space between a selector and the opening brace of a ruleset.
* One level of indentation before each declaration.
* A single space the colon in a declaration.
* A single space after each item in a declaration containing multiple items.

The following shows how the above rules apply:
<code css>
.m-selector-1,
.m-selector-2 .m-selector-3 {
background: #ffa800 url("background.png") no-repeat right top;
border: 1px solid #000;
display: inline-block;
font-family: arial, sans-serif;
margin: 5px 10px;
padding: 0;
}

.m-selector-4 {
border-radius: 3px;
}
</code>

===General rules===

Declaration ordering is the very first thing to discuss. There is no strict rule on how to order your declarations, however there is a recommendation.
We recommend that you order declarations within a ruleset alphabetically.
If we all start doing this then when you read CSS written by someone else you will soon learn to very quickly find your way around the declarations within a rule.
<code css>
/** Recommended **/
.m-selector {
background-color: #fff;
border: 1px solid #000;
color: #000;
display: block;
margin: 5px;
padding: 5px;
}
</code>

Do not use a measurement unit when writing a 0 value.
<code css>
/** Good **/
.m-selector {
margin: 5px 0;
}

/** Bad **/
.m-selector {
margin: 5px 0px;
}
</code>

Use lowercase and shorthand values for colours.
<code css>
/** Good **/
.m-selector {
background-color: #fff;
}

/** Bad **/
.m-selector {
background-color: #ffffff;
}
.m-selector {
background-color: #FFFFFF;
}
.m-selector {
background-color: white;
}
</code>

Always quote variable values.
<code css>
/** Good **/
.m-selector[attr="variable"] {
background-image: url("image.png");
}

/** Bad **/
.m-selector[attr=variable] {
background-image: url(image.png);
}
</code>

===Commenting===

Always comment your CSS and Less.

<code css>
/**
* Styles for the button atom.
*/
.m-element-button {
}
</code>

===Rules and exceptions for less===

Need to write some guff on Less.

==See also==
* [[User:Sam Hemelryk/Render library element planning]]
* [[Guide to creating output elements]] ''originally written at [[User:Sam Hemelryk/Creating renderable components]]''
* [[User:Sam Hemelryk/Renderer best practices]]
* [[User:Sam Hemelryk/CSS style guidelines]]

User:Sam Hemelryk/CSS style guidelines

2014-07-22T05:07:44Z

Samhemelryk: /* CSS for elements */

{{Infobox Project
|name = Renderer consistency
|state = Specification
|tracker = https://tracker.moodle.org/browse/MDL-45830
|discussion = https://moodle.org/mod/forum/discuss.php?d=261202
|assignee = Damyon, Sam
}}
{{Work in progress|forumurl=https://moodle.org/mod/forum/discuss.php?d=261202}}

==HTML and CSS style guide==

This is a guide to writing CSS within Moodle.

==Why have a strict guide==

At the time of writing this CSS within Moodle (2.7) themes is in a poor state and has been for a long time. Without previously having a guide we were finding that:

* As there was no formal guide to creating id's or classes, each developer does there own thing.
* As there was no formal guide on how to write CSS there were numerous techniques used when writing CSS and no consistency.
* Majority of pages create uniuqe output and require unique CSS, there is very little re-use of design.

While those points may not sound bad to you consider that in following stats from Moodle 2.7 themes:

* Base theme contains 3802 rulesets with a total of 5800 styles.
* Bootstrapbase theme contains 5170 rulesets with a total of 9362 styles.
* Clean theme contains 5172 rulesets with a total of 9366 styles.
* More theme contains 5177 rulesets with a total of 9063 styles.

You get the picture, several thousand selectors containing nearly 10000 styles.

For Moodle 2.8 we commited to introducing a element library to aid the reuse of design and documenting all aspects of output including a guide on writing CSS for Moodle. This is that guide.

==Our goals==

Its very important to understand what we are trying to achieve with this style guide and output in general.

; Frontend framework agnostic : We want theme designers to be able to apply present and future frontend frameworks to Moodle with minimal effort.
; Consistent interfaces : We want Moodle to have consistency throughout its interfaces, minimising the amount of frontend design and development that is required in coding and styling an interface.
; Cleanly formatted HTML and CSS : to minimise both development time and to make our renderers and CSS and more maintainable.

We plan to faciliate these with the following:
; Elements : Highly re-usable objects to produce HTML, these will be used consistently and relied upon by developers creating interfaces. By having these elements we create a consistent look, interface creation will be much quicker and theme designers through the re-use of a limited number of elements.
; Element library : A tool to show samples of each element, this can be used to view and test designs. It aids the developer by showing them the elements they can select from when creating an interface, and it aids designers by giving them a test area that doesn't require them to dig through every page in Moodle.
; Documentation : We will now have proper documentation on all aspects of output. Including this CSS style guide, a renderer best practices guide, and a guide to creating elements.

==Where to put CSS in Moodle core==

CSS can reside in a number of locations depending upon what you are styling.

Remember it doesn't matter how many CSS files we end up with, on a production site with Theme designer mode switched off (default) all CSS files will be combined and minimised into a single file that is served to the client.
Excepting the case of IE where we must split the CSS into several smaller files to work around browser limitations.

===CSS for elements===
As we are moving to using elements you will find that CSS for elements is where most of the effort is going to go.

CSS for elements should reside within themes only, you will find that elements must be styled in all core base themes, this means at least Bootstrapbase and base.

CSS for elements should be located within either '''theme/themename/style/elements/elementname.css''' or '''theme/themename/less/elements/elementname.css'''

The actual CSS file should be named according to the element. As elements can be namespaced we need to ensure that that is reflected in the name of the file.
For instance:

{|
! Element
! CSS location in base
! CSS location in bootstrapbase
|-
| \core\output\button
| style/elements/core_output_button.css
| less/moodle/elements/core_output_button.css
|-
| \core\output\navigation_bar
| style/elements/core_output_navigation_bar.css
| less/moodle/elements/core_output_navigation_bar.css
|-
| \mod_assign\output\user_submission
| style/elements/mod_assign_output_user_submission.css
| less/moodle/elements/mod_assign_output_user_submission.css
|}

These will still need to be included in the theme, by which ever means is relevant.
If you are using ''.css'' files like the base theme does then you will use:

<code php>
// In your themes config.php
$THEME->sheets = array(
'elements/core_output_button',
'elements/core_output_navigation_bar',
'elements/mod_assign_output_user_submission'
);
</code>

If you are using less as bootstrapbase does then you will use:
<code css>
/** In your primary less file **/
@import "moodle/elements/core_output_button";
@import "moodle/elements/core_output_navigation_bar";
@import "moodle/elements/mod_assign_output_user_submission";
</code>

===General CSS===

This is CSS for the theme that doesn't relate to a specific element. Hopefully as we convert more and more of Moodles interfaces to use elements we should see less general CSS.

In any case nothing has changed in regards to the location of general CSS.
; CSS : If your theme is using standard CSS then it must be located within the ''style'' directory of your theme and should be in logically separated files.
; Less : If your theme is using less then it should be located in a ''less/moodle'' directory within your theme.

We recommend that you separate styles into files based upon the Moodle component being styled. Again as all CSS files get combined into a single file on production sites it doesn't matter how many files you end up with.

This would lead to files named like:
* style/core.css
* style/course.css
* style/mod_forum.css

===Where to put CSS in plugins===

It is possible in Moodle to add CSS stylesheets to all plugins (including core plugins).<br />
Moodle always looks for a ''styles.css'' file within your plugins directory, and it also looks for a styles_themename.css where themename is the name of the currect theme being used.

For instance the following could be added to the forum module:

* ''mod/forum/styles.css'': Used all the time.
* ''mod/forum/styles_base.css'' : Used when the user is using the base theme.
* ''mod/forum/styles_bootstrapbase.css'' : Used when the user is using the bootstrapbase theme.
* ''mod/forum/styles_clean.css'' : Used when the user is using the clean theme.

===CSS in core plugins===

For core plugins only styles.css is permitted and it should only ever contain styles essential to the presentation of the plugin.<br />
At present styles essential for the display of the plugin are allowed here, however when the plugin interfaces have been converted to use elements this file should be nearly empty and contain only the following:
* Images, icons and text used for visual presentation such as icons to notify state (expanded/collapsed, warnings...)
* Accessiblity orientated styles required to make the interface accessible.

'''Under no circumstances should it contain any visual stylings such as border, rounded corners, and background colours not associated with state.'''

==HTML==

The following sections detail rules in place for writing HTML.

Before we start a couple of general recommendations:

; Use hyphens rather than underscores when concatenating strings in attributes : for example ''.course-new-activity-chooser'' instead of ''.course_new_activity_chooser''. By all doing this we will have a more consistent appearance and as We use underscores as part of frankenstyle which is prominent in CSS helps us to reduce the chance of naming conflicts.
; Think semantics - but don't get caught up in it : Semantic CSS is beautiful CSS lending itself ultimately to the redesign that is going to happen. But enforcing a semantic design can be an arduous journey. Instead we encourage semantic CSS but are happy to see non-semantic CSS when it is for the greater good.

===Using the ID attribute===

The situation of having a single JavaScript driven element was considered but even then it is better to style only classes and other attributes as we can't be sure what the future holds.

There are three rules you should follow when creating an ID:

# They should only be given to elements and HTML nodes that need to be interacted with by JavaScript.
# It should always start with '''m-''' ''(see note below)''
# The actual ID should be descriptive of the node and contents as a whole unit. It must fully and concisely describe its purpose.

Keep in mind that in an ideal world ID's should not be used for styling.

'''Good'''
<code html5>
<div id="m-dock"> ... </div>

<div id="m-course-new-activity-chooser"> ... </div>
</code>

'''Bad'''
<code html5>

<div id="dock"> ... </div>


<div id="m-activity-selector"> ... </div>
</code>

'''Note:''' The requirement to use m- prefix is entirely new, this has been created as this instantly reduces the chances of conflicting with present and future frontend frameworks that may be adopted by core or third party themes. Aiding our goal of being frontend framework agnostic.<br />
It will also help reduce the chance of conflicts in any third party code that may be used either by us in core, or by outside developers in their own code.
Moodle ID's will also be much more easily recognisable which we expect will be a benefit as JavaScript use in Moodle continues to increase.

===Naming CSS classes===

This is where a bit of organisation goes a long way and we want to be reasonably thorough in a consistent naming scheme and implementation.

The very first thing to mention is that all classes in Moodle must now be prefixed by *m-*.
This instantly identifes a class as belonging to Moodle, it aids us in avoiding conflicts with any non-Moodle css that may be loaded, and it is part of our framework agnostic plan.

<blockquote>
All CSS classes must start with *m-*
</blockquote>

There are several prefix that are used within Moodle output now that should not be used as prefixs for classes unless they are serving the desired purpose.

Reserved prefixes are:

; m-element : Prefix used on element classes, where m-element preceeds the name of the element, e.g. m-element-button, m-element-search
; m-state : Prefix used for CSS classes representing the state of an item, e.g. m-state-disabled, m-state-active, m-state-expanded.
; m-grid : Prefix used for creating HTML grids.

====Elements

Semantic design where it gives the best result, smart design where there is a better solution.

If you're not already familiar with the idea of semantic CSS then Chris Coylers artical [http://css-tricks.com/semantic-class-names/ What makes for a semantic class name] is a great starting point.

We've not commit to adopting any one strict approach for writing CSS. We have adopted atomic design for our HTML elements, a design style which fits nicely with the likes of OOCSS, however be very clear that we are not adopting the OOCSS approach in its entirety. The high level abstraction of the visual aspects of elements into highly reusable agnostic classes does not always lend itself well to the Moodle world in which the we wish to be frontend framework agnostic and support largescale completely customisable themes.<br />
The highly reusable classes that appeal to one designer, or to one frontend framework may not apply to another.<br />
This decision is also impacted by our current default theme bootstrapbase that does not use well abstracted OOCSS in its design.

Atomic design is going to see us end up with many parent child relationships in our HTML that we must carry through to our CSS. Through atomic design we start with smalled atoms and molecules that get built into larger organisms and placed within layouts.

Every element should have a single class that identifies it as element X.

For instance the button atom will have the class *m-element-button*

<code html5>
<button class="m-element-button">I am a button</button>
</code>

This is simply the prefix "m-element" plus the element name.

The purpose of this class is to allow the element to be styled with ease. The class name should be applied to the root node for the element, it should never be applied any lower.

By having one class for the element, and always and only applied to the root node it makes it very easy in HTML to see where one element belongs to another.

The following is an example of the search molecule, which in turn contains two button atoms.
<code html5>
<form class="m-element-confirmation">
<h3>Are you sure?</h3>
<p>Are you sure you want to perform this action?</p>
<input type="submit" name="cancel" class="m-element-button" value="Cancel" />
<input type="submit" name="continue" class="m-element-button" value="Continue" />
</form>
</code>

We've chosen to partially adopt BEM as a CSS standard when writing CSS for elements.
BEM isn't a new CSS standard, but its not widely known either. Its existence fills a gap in how to style elements consistently. Through two basic notation techniques you can easily notate the purpose of structures that belong to an element and notate the intent of an element that is desired if the element has multiple versions.

; Notating purpose : Here we use a suffix *__purpose*, the key being the two underscores.
; Notating intent : Here we use a suffix *--intent*, the key being the two hyphens.

You'll notice in the example above that there is no way to style the continue button differently from the cancel button without relying on its name, something we certainly don't want to do.
The solution is to wrap each button in a div and give each div a class.
The BEM standard comes into play here in naming the classes, the following shows how you would apply BEM to show the purpose of each button in a way that can be easily interpreted and styled in CSS.

<code html5>
<form class="m-element-confirmation">
<h3>Are you sure?</h3>
<p>Are you sure you want to perform this action?</p>
<div class="m-element-confirmation__cancel">
<input type="submit" name="cancel" class="m-element-button" value="Cancel" />
</div>
<div class="m-element-confirmation__continue">
<input type="submit" name="continue" class="m-element-button" value="Continue" />
</div>
</form>
</code>

You can now each button is wrapped in a div with a class, *m-element-confirmation__cancel* and *m-element-confirmation__continue*.
This class can be read by the themer and because of the __ can be easily identified as both belonging to the m-element-confirmation and serving a specific purpose, continue or cancel.

Now to explain the idea of intents.
An intent is when a single element takes on a different apprearance to convey a specific meaning. A little bit like a state, but with more meaning.
An easy example is notifications where you will no doubt be familiar with the idea of having a error notifications, warning notifications, success notification etc. Each of error, warning, and success is a intent.

The following shows how this would work:
<code html5>

<div class="m-element-notification">You have not changed your password in the past 60 days</div>


<div class="m-element-notification m-element-notification--warning">You have not changed your password in the past 60 days</div>
</div>

====Grids

We need to adopt a single grid framework.

Personally I don't think we should use pure bootstrap or pure YUI, instead we should choose one of these and build it use our class name structures.

All grid classes should start with m-grid.

==Writing CSS==

Before we begin lets lay down some ground level goals, things that will help us achieve clear and understandable CSS in the future.
* Formatting, ordering, alignment, and spacing are all important in having CSS that can be easily read by others.
* Don't optimise your CSS, be verbose and stick to the styles in this guide. We have tools that will handle optimisation for you.
* Never use *!important* in your CSS unless it is absolutely impossible to avoid doing so.

===Terminology===

Its important that when we are speaking about CSS we are speaking the same language.
Lets look at the following example:

<code css>
.m-page .m-selector-1,
.m-page .m-selector-2,
.m-page .m-selector-3 {
background-color: #FFF;
color: #000;
}

.m-selector-1 {
margin: 1em;
}
</code>

; Ruleset : Each of the two rules is a single *ruleset*.
; Rule: _.m-page .m-selector-1_ is a rule.
; Selector : _.m-selector-1_ is a *selector*, it is a single part of a rule.
; Declaration : _background-color: #FFF_ is a declaration.
;

===Essential formatting===

The following are the guies for writing CSS.

* Always use spaces - never use tabs. All editors can be configured to do it.
* Indent by 4 spaces - never more, never less.
* A single empty line between rulesets to maintain consistent spacing of rules.
* One rule per line.
* A single space between each selector in a rule.
* No space between a rule and the comma in a ruleset.
* A single space between a selector and the opening brace of a ruleset.
* One level of indentation before each declaration.
* A single space the colon in a declaration.
* A single space after each item in a declaration containing multiple items.

The following shows how the above rules apply:
<code css>
.m-selector-1,
.m-selector-2 .m-selector-3 {
background: #ffa800 url("background.png") no-repeat right top;
border: 1px solid #000;
display: inline-block;
font-family: arial, sans-serif;
margin: 5px 10px;
padding: 0;
}

.m-selector-4 {
border-radius: 3px;
}
</code>

===General rules===

Declaration ordering is the very first thing to discuss. There is no strict rule on how to order your declarations, however there is a recommendation.
We recommend that you order declarations within a ruleset alphabetically.
If we all start doing this then when you read CSS written by someone else you will soon learn to very quickly find your way around the declarations within a rule.
<code css>
/** Recommended **/
.m-selector {
background-color: #fff;
border: 1px solid #000;
color: #000;
display: block;
margin: 5px;
padding: 5px;
}
</code>

Do not use a measurement unit when writing a 0 value.
<code css>
/** Good **/
.m-selector {
margin: 5px 0;
}

/** Bad **/
.m-selector {
margin: 5px 0px;
}
</code>

Use lowercase and shorthand values for colours.
<code css>
/** Good **/
.m-selector {
background-color: #fff;
}

/** Bad **/
.m-selector {
background-color: #ffffff;
}
.m-selector {
background-color: #FFFFFF;
}
.m-selector {
background-color: white;
}
</code>

Always quote variable values.
<code css>
/** Good **/
.m-selector[attr="variable"] {
background-image: url("image.png");
}

/** Bad **/
.m-selector[attr=variable] {
background-image: url(image.png);
}
</code>

===Commenting===

Always comment your CSS and Less.

<code css>
/**
* Styles for the button atom.
*/
.m-element-button {
}
</code>

===Rules and exceptions for less===

Need to write some guff on Less.

==See also==
* [[User:Sam Hemelryk/Render library element planning]]
* [[Guide to creating output elements]] ''originally written at [[User:Sam Hemelryk/Creating renderable components]]''
* [[User:Sam Hemelryk/Renderer best practices]]
* [[User:Sam Hemelryk/CSS style guidelines]]

User:Sam Hemelryk/CSS style guidelines

2014-07-22T05:07:09Z

Samhemelryk: /* Writing HTML */

{{Infobox Project
|name = Renderer consistency
|state = Specification
|tracker = https://tracker.moodle.org/browse/MDL-45830
|discussion = https://moodle.org/mod/forum/discuss.php?d=261202
|assignee = Damyon, Sam
}}
{{Work in progress|forumurl=https://moodle.org/mod/forum/discuss.php?d=261202}}

==HTML and CSS style guide==

This is a guide to writing CSS within Moodle.

==Why have a strict guide==

At the time of writing this CSS within Moodle (2.7) themes is in a poor state and has been for a long time. Without previously having a guide we were finding that:

* As there was no formal guide to creating id's or classes, each developer does there own thing.
* As there was no formal guide on how to write CSS there were numerous techniques used when writing CSS and no consistency.
* Majority of pages create uniuqe output and require unique CSS, there is very little re-use of design.

While those points may not sound bad to you consider that in following stats from Moodle 2.7 themes:

* Base theme contains 3802 rulesets with a total of 5800 styles.
* Bootstrapbase theme contains 5170 rulesets with a total of 9362 styles.
* Clean theme contains 5172 rulesets with a total of 9366 styles.
* More theme contains 5177 rulesets with a total of 9063 styles.

You get the picture, several thousand selectors containing nearly 10000 styles.

For Moodle 2.8 we commited to introducing a element library to aid the reuse of design and documenting all aspects of output including a guide on writing CSS for Moodle. This is that guide.

==Our goals==

Its very important to understand what we are trying to achieve with this style guide and output in general.

; Frontend framework agnostic : We want theme designers to be able to apply present and future frontend frameworks to Moodle with minimal effort.
; Consistent interfaces : We want Moodle to have consistency throughout its interfaces, minimising the amount of frontend design and development that is required in coding and styling an interface.
; Cleanly formatted HTML and CSS : to minimise both development time and to make our renderers and CSS and more maintainable.

We plan to faciliate these with the following:
; Elements : Highly re-usable objects to produce HTML, these will be used consistently and relied upon by developers creating interfaces. By having these elements we create a consistent look, interface creation will be much quicker and theme designers through the re-use of a limited number of elements.
; Element library : A tool to show samples of each element, this can be used to view and test designs. It aids the developer by showing them the elements they can select from when creating an interface, and it aids designers by giving them a test area that doesn't require them to dig through every page in Moodle.
; Documentation : We will now have proper documentation on all aspects of output. Including this CSS style guide, a renderer best practices guide, and a guide to creating elements.

==Where to put CSS in Moodle core==

CSS can reside in a number of locations depending upon what you are styling.

Remember it doesn't matter how many CSS files we end up with, on a production site with Theme designer mode switched off (default) all CSS files will be combined and minimised into a single file that is served to the client.
Excepting the case of IE where we must split the CSS into several smaller files to work around browser limitations.

===CSS for elements===
As we are moving to using elements you will find that CSS for elements is where most of the effort is going to go.

CSS for elements should reside within themes only, you will find that elements must be styled in all core base themes, this means at least Bootstrapbase and base.

CSS for elements should be located within either '''theme/themename/style/elements/elementname.css''' or '''theme/themename/less/elements/elementname.css'''

The actual CSS file should be named according to the element. As elements can be namespaced we need to ensure that that is reflected in the name of the file.
For instance:

{|
! Element
! CSS location in base
! CSS location in bootstrapbase
|-
| \core\output\button
| style/elements/core_output_button.css
| less/moodle/elements/core_output_button.css
|-
| \core\output\navigation_bar
| style/elements/core_output_navigation_bar.css
| less/moodle/elements/core_output_navigation_bar.css
|-
| \mod_assign\output\user_submission
| style/elements/mod_assign_output_user_submission.css
| less/moodle/elements/mod_assign_output_user_submission.css
|}

These will still need to be included in the theme, by which ever means is relevant.
If you are using ''.css'' files like the base theme does then you will use:

<code php>
// In your themes config.php
$THEME->sheets = array(
'elements/core_output_button',
'elements/core_output_navigation_bar',
'elements/mod_assign_output_user_submission'
);
</code>

If you are using less as bootstrapbase does then you will use:
<code CSS>
/** In your primary less file **/
@import "moodle/elements/core_output_button";
@import "moodle/elements/core_output_navigation_bar";
@import "moodle/elements/mod_assign_output_user_submission";
</code>

===General CSS===

This is CSS for the theme that doesn't relate to a specific element. Hopefully as we convert more and more of Moodles interfaces to use elements we should see less general CSS.

In any case nothing has changed in regards to the location of general CSS.
; CSS : If your theme is using standard CSS then it must be located within the ''style'' directory of your theme and should be in logically separated files.
; Less : If your theme is using less then it should be located in a ''less/moodle'' directory within your theme.

We recommend that you separate styles into files based upon the Moodle component being styled. Again as all CSS files get combined into a single file on production sites it doesn't matter how many files you end up with.

This would lead to files named like:
* style/core.css
* style/course.css
* style/mod_forum.css

===Where to put CSS in plugins===

It is possible in Moodle to add CSS stylesheets to all plugins (including core plugins).<br />
Moodle always looks for a ''styles.css'' file within your plugins directory, and it also looks for a styles_themename.css where themename is the name of the currect theme being used.

For instance the following could be added to the forum module:

* ''mod/forum/styles.css'': Used all the time.
* ''mod/forum/styles_base.css'' : Used when the user is using the base theme.
* ''mod/forum/styles_bootstrapbase.css'' : Used when the user is using the bootstrapbase theme.
* ''mod/forum/styles_clean.css'' : Used when the user is using the clean theme.

===CSS in core plugins===

For core plugins only styles.css is permitted and it should only ever contain styles essential to the presentation of the plugin.<br />
At present styles essential for the display of the plugin are allowed here, however when the plugin interfaces have been converted to use elements this file should be nearly empty and contain only the following:
* Images, icons and text used for visual presentation such as icons to notify state (expanded/collapsed, warnings...)
* Accessiblity orientated styles required to make the interface accessible.

'''Under no circumstances should it contain any visual stylings such as border, rounded corners, and background colours not associated with state.'''

==HTML==

The following sections detail rules in place for writing HTML.

Before we start a couple of general recommendations:

; Use hyphens rather than underscores when concatenating strings in attributes : for example ''.course-new-activity-chooser'' instead of ''.course_new_activity_chooser''. By all doing this we will have a more consistent appearance and as We use underscores as part of frankenstyle which is prominent in CSS helps us to reduce the chance of naming conflicts.
; Think semantics - but don't get caught up in it : Semantic CSS is beautiful CSS lending itself ultimately to the redesign that is going to happen. But enforcing a semantic design can be an arduous journey. Instead we encourage semantic CSS but are happy to see non-semantic CSS when it is for the greater good.

===Using the ID attribute===

The situation of having a single JavaScript driven element was considered but even then it is better to style only classes and other attributes as we can't be sure what the future holds.

There are three rules you should follow when creating an ID:

# They should only be given to elements and HTML nodes that need to be interacted with by JavaScript.
# It should always start with '''m-''' ''(see note below)''
# The actual ID should be descriptive of the node and contents as a whole unit. It must fully and concisely describe its purpose.

Keep in mind that in an ideal world ID's should not be used for styling.

'''Good'''
<code html5>
<div id="m-dock"> ... </div>

<div id="m-course-new-activity-chooser"> ... </div>
</code>

'''Bad'''
<code html5>

<div id="dock"> ... </div>


<div id="m-activity-selector"> ... </div>
</code>

'''Note:''' The requirement to use m- prefix is entirely new, this has been created as this instantly reduces the chances of conflicting with present and future frontend frameworks that may be adopted by core or third party themes. Aiding our goal of being frontend framework agnostic.<br />
It will also help reduce the chance of conflicts in any third party code that may be used either by us in core, or by outside developers in their own code.
Moodle ID's will also be much more easily recognisable which we expect will be a benefit as JavaScript use in Moodle continues to increase.

===Naming CSS classes===

This is where a bit of organisation goes a long way and we want to be reasonably thorough in a consistent naming scheme and implementation.

The very first thing to mention is that all classes in Moodle must now be prefixed by *m-*.
This instantly identifes a class as belonging to Moodle, it aids us in avoiding conflicts with any non-Moodle css that may be loaded, and it is part of our framework agnostic plan.

<blockquote>
All CSS classes must start with *m-*
</blockquote>

There are several prefix that are used within Moodle output now that should not be used as prefixs for classes unless they are serving the desired purpose.

Reserved prefixes are:

; m-element : Prefix used on element classes, where m-element preceeds the name of the element, e.g. m-element-button, m-element-search
; m-state : Prefix used for CSS classes representing the state of an item, e.g. m-state-disabled, m-state-active, m-state-expanded.
; m-grid : Prefix used for creating HTML grids.

====Elements

Semantic design where it gives the best result, smart design where there is a better solution.

If you're not already familiar with the idea of semantic CSS then Chris Coylers artical [http://css-tricks.com/semantic-class-names/ What makes for a semantic class name] is a great starting point.

We've not commit to adopting any one strict approach for writing CSS. We have adopted atomic design for our HTML elements, a design style which fits nicely with the likes of OOCSS, however be very clear that we are not adopting the OOCSS approach in its entirety. The high level abstraction of the visual aspects of elements into highly reusable agnostic classes does not always lend itself well to the Moodle world in which the we wish to be frontend framework agnostic and support largescale completely customisable themes.<br />
The highly reusable classes that appeal to one designer, or to one frontend framework may not apply to another.<br />
This decision is also impacted by our current default theme bootstrapbase that does not use well abstracted OOCSS in its design.

Atomic design is going to see us end up with many parent child relationships in our HTML that we must carry through to our CSS. Through atomic design we start with smalled atoms and molecules that get built into larger organisms and placed within layouts.

Every element should have a single class that identifies it as element X.

For instance the button atom will have the class *m-element-button*

<code html5>
<button class="m-element-button">I am a button</button>
</code>

This is simply the prefix "m-element" plus the element name.

The purpose of this class is to allow the element to be styled with ease. The class name should be applied to the root node for the element, it should never be applied any lower.

By having one class for the element, and always and only applied to the root node it makes it very easy in HTML to see where one element belongs to another.

The following is an example of the search molecule, which in turn contains two button atoms.
<code html5>
<form class="m-element-confirmation">
<h3>Are you sure?</h3>
<p>Are you sure you want to perform this action?</p>
<input type="submit" name="cancel" class="m-element-button" value="Cancel" />
<input type="submit" name="continue" class="m-element-button" value="Continue" />
</form>
</code>

We've chosen to partially adopt BEM as a CSS standard when writing CSS for elements.
BEM isn't a new CSS standard, but its not widely known either. Its existence fills a gap in how to style elements consistently. Through two basic notation techniques you can easily notate the purpose of structures that belong to an element and notate the intent of an element that is desired if the element has multiple versions.

; Notating purpose : Here we use a suffix *__purpose*, the key being the two underscores.
; Notating intent : Here we use a suffix *--intent*, the key being the two hyphens.

You'll notice in the example above that there is no way to style the continue button differently from the cancel button without relying on its name, something we certainly don't want to do.
The solution is to wrap each button in a div and give each div a class.
The BEM standard comes into play here in naming the classes, the following shows how you would apply BEM to show the purpose of each button in a way that can be easily interpreted and styled in CSS.

<code html5>
<form class="m-element-confirmation">
<h3>Are you sure?</h3>
<p>Are you sure you want to perform this action?</p>
<div class="m-element-confirmation__cancel">
<input type="submit" name="cancel" class="m-element-button" value="Cancel" />
</div>
<div class="m-element-confirmation__continue">
<input type="submit" name="continue" class="m-element-button" value="Continue" />
</div>
</form>
</code>

You can now each button is wrapped in a div with a class, *m-element-confirmation__cancel* and *m-element-confirmation__continue*.
This class can be read by the themer and because of the __ can be easily identified as both belonging to the m-element-confirmation and serving a specific purpose, continue or cancel.

Now to explain the idea of intents.
An intent is when a single element takes on a different apprearance to convey a specific meaning. A little bit like a state, but with more meaning.
An easy example is notifications where you will no doubt be familiar with the idea of having a error notifications, warning notifications, success notification etc. Each of error, warning, and success is a intent.

The following shows how this would work:
<code html5>

<div class="m-element-notification">You have not changed your password in the past 60 days</div>


<div class="m-element-notification m-element-notification--warning">You have not changed your password in the past 60 days</div>
</div>

====Grids

We need to adopt a single grid framework.

Personally I don't think we should use pure bootstrap or pure YUI, instead we should choose one of these and build it use our class name structures.

All grid classes should start with m-grid.

==Writing CSS==

Before we begin lets lay down some ground level goals, things that will help us achieve clear and understandable CSS in the future.
* Formatting, ordering, alignment, and spacing are all important in having CSS that can be easily read by others.
* Don't optimise your CSS, be verbose and stick to the styles in this guide. We have tools that will handle optimisation for you.
* Never use *!important* in your CSS unless it is absolutely impossible to avoid doing so.

===Terminology===

Its important that when we are speaking about CSS we are speaking the same language.
Lets look at the following example:

<code css>
.m-page .m-selector-1,
.m-page .m-selector-2,
.m-page .m-selector-3 {
background-color: #FFF;
color: #000;
}

.m-selector-1 {
margin: 1em;
}
</code>

; Ruleset : Each of the two rules is a single *ruleset*.
; Rule: _.m-page .m-selector-1_ is a rule.
; Selector : _.m-selector-1_ is a *selector*, it is a single part of a rule.
; Declaration : _background-color: #FFF_ is a declaration.
;

===Essential formatting===

The following are the guies for writing CSS.

* Always use spaces - never use tabs. All editors can be configured to do it.
* Indent by 4 spaces - never more, never less.
* A single empty line between rulesets to maintain consistent spacing of rules.
* One rule per line.
* A single space between each selector in a rule.
* No space between a rule and the comma in a ruleset.
* A single space between a selector and the opening brace of a ruleset.
* One level of indentation before each declaration.
* A single space the colon in a declaration.
* A single space after each item in a declaration containing multiple items.

The following shows how the above rules apply:
<code css>
.m-selector-1,
.m-selector-2 .m-selector-3 {
background: #ffa800 url("background.png") no-repeat right top;
border: 1px solid #000;
display: inline-block;
font-family: arial, sans-serif;
margin: 5px 10px;
padding: 0;
}

.m-selector-4 {
border-radius: 3px;
}
</code>

===General rules===

Declaration ordering is the very first thing to discuss. There is no strict rule on how to order your declarations, however there is a recommendation.
We recommend that you order declarations within a ruleset alphabetically.
If we all start doing this then when you read CSS written by someone else you will soon learn to very quickly find your way around the declarations within a rule.
<code css>
/** Recommended **/
.m-selector {
background-color: #fff;
border: 1px solid #000;
color: #000;
display: block;
margin: 5px;
padding: 5px;
}
</code>

Do not use a measurement unit when writing a 0 value.
<code css>
/** Good **/
.m-selector {
margin: 5px 0;
}

/** Bad **/
.m-selector {
margin: 5px 0px;
}
</code>

Use lowercase and shorthand values for colours.
<code css>
/** Good **/
.m-selector {
background-color: #fff;
}

/** Bad **/
.m-selector {
background-color: #ffffff;
}
.m-selector {
background-color: #FFFFFF;
}
.m-selector {
background-color: white;
}
</code>

Always quote variable values.
<code css>
/** Good **/
.m-selector[attr="variable"] {
background-image: url("image.png");
}

/** Bad **/
.m-selector[attr=variable] {
background-image: url(image.png);
}
</code>

===Commenting===

Always comment your CSS and Less.

<code css>
/**
* Styles for the button atom.
*/
.m-element-button {
}
</code>

===Rules and exceptions for less===

Need to write some guff on Less.

==See also==
* [[User:Sam Hemelryk/Render library element planning]]
* [[Guide to creating output elements]] ''originally written at [[User:Sam Hemelryk/Creating renderable components]]''
* [[User:Sam Hemelryk/Renderer best practices]]
* [[User:Sam Hemelryk/CSS style guidelines]]

User:Sam Hemelryk/CSS style guidelines

2014-07-22T05:06:52Z

Samhemelryk: /* CSS in core plugins= */

{{Infobox Project
|name = Renderer consistency
|state = Specification
|tracker = https://tracker.moodle.org/browse/MDL-45830
|discussion = https://moodle.org/mod/forum/discuss.php?d=261202
|assignee = Damyon, Sam
}}
{{Work in progress|forumurl=https://moodle.org/mod/forum/discuss.php?d=261202}}

==HTML and CSS style guide==

This is a guide to writing CSS within Moodle.

==Why have a strict guide==

At the time of writing this CSS within Moodle (2.7) themes is in a poor state and has been for a long time. Without previously having a guide we were finding that:

* As there was no formal guide to creating id's or classes, each developer does there own thing.
* As there was no formal guide on how to write CSS there were numerous techniques used when writing CSS and no consistency.
* Majority of pages create uniuqe output and require unique CSS, there is very little re-use of design.

While those points may not sound bad to you consider that in following stats from Moodle 2.7 themes:

* Base theme contains 3802 rulesets with a total of 5800 styles.
* Bootstrapbase theme contains 5170 rulesets with a total of 9362 styles.
* Clean theme contains 5172 rulesets with a total of 9366 styles.
* More theme contains 5177 rulesets with a total of 9063 styles.

You get the picture, several thousand selectors containing nearly 10000 styles.

For Moodle 2.8 we commited to introducing a element library to aid the reuse of design and documenting all aspects of output including a guide on writing CSS for Moodle. This is that guide.

==Our goals==

Its very important to understand what we are trying to achieve with this style guide and output in general.

; Frontend framework agnostic : We want theme designers to be able to apply present and future frontend frameworks to Moodle with minimal effort.
; Consistent interfaces : We want Moodle to have consistency throughout its interfaces, minimising the amount of frontend design and development that is required in coding and styling an interface.
; Cleanly formatted HTML and CSS : to minimise both development time and to make our renderers and CSS and more maintainable.

We plan to faciliate these with the following:
; Elements : Highly re-usable objects to produce HTML, these will be used consistently and relied upon by developers creating interfaces. By having these elements we create a consistent look, interface creation will be much quicker and theme designers through the re-use of a limited number of elements.
; Element library : A tool to show samples of each element, this can be used to view and test designs. It aids the developer by showing them the elements they can select from when creating an interface, and it aids designers by giving them a test area that doesn't require them to dig through every page in Moodle.
; Documentation : We will now have proper documentation on all aspects of output. Including this CSS style guide, a renderer best practices guide, and a guide to creating elements.

==Where to put CSS in Moodle core==

CSS can reside in a number of locations depending upon what you are styling.

Remember it doesn't matter how many CSS files we end up with, on a production site with Theme designer mode switched off (default) all CSS files will be combined and minimised into a single file that is served to the client.
Excepting the case of IE where we must split the CSS into several smaller files to work around browser limitations.

===CSS for elements===
As we are moving to using elements you will find that CSS for elements is where most of the effort is going to go.

CSS for elements should reside within themes only, you will find that elements must be styled in all core base themes, this means at least Bootstrapbase and base.

CSS for elements should be located within either '''theme/themename/style/elements/elementname.css''' or '''theme/themename/less/elements/elementname.css'''

The actual CSS file should be named according to the element. As elements can be namespaced we need to ensure that that is reflected in the name of the file.
For instance:

{|
! Element
! CSS location in base
! CSS location in bootstrapbase
|-
| \core\output\button
| style/elements/core_output_button.css
| less/moodle/elements/core_output_button.css
|-
| \core\output\navigation_bar
| style/elements/core_output_navigation_bar.css
| less/moodle/elements/core_output_navigation_bar.css
|-
| \mod_assign\output\user_submission
| style/elements/mod_assign_output_user_submission.css
| less/moodle/elements/mod_assign_output_user_submission.css
|}

These will still need to be included in the theme, by which ever means is relevant.
If you are using ''.css'' files like the base theme does then you will use:

<code php>
// In your themes config.php
$THEME->sheets = array(
'elements/core_output_button',
'elements/core_output_navigation_bar',
'elements/mod_assign_output_user_submission'
);
</code>

If you are using less as bootstrapbase does then you will use:
<code CSS>
/** In your primary less file **/
@import "moodle/elements/core_output_button";
@import "moodle/elements/core_output_navigation_bar";
@import "moodle/elements/mod_assign_output_user_submission";
</code>

===General CSS===

This is CSS for the theme that doesn't relate to a specific element. Hopefully as we convert more and more of Moodles interfaces to use elements we should see less general CSS.

In any case nothing has changed in regards to the location of general CSS.
; CSS : If your theme is using standard CSS then it must be located within the ''style'' directory of your theme and should be in logically separated files.
; Less : If your theme is using less then it should be located in a ''less/moodle'' directory within your theme.

We recommend that you separate styles into files based upon the Moodle component being styled. Again as all CSS files get combined into a single file on production sites it doesn't matter how many files you end up with.

This would lead to files named like:
* style/core.css
* style/course.css
* style/mod_forum.css

===Where to put CSS in plugins===

It is possible in Moodle to add CSS stylesheets to all plugins (including core plugins).<br />
Moodle always looks for a ''styles.css'' file within your plugins directory, and it also looks for a styles_themename.css where themename is the name of the currect theme being used.

For instance the following could be added to the forum module:

* ''mod/forum/styles.css'': Used all the time.
* ''mod/forum/styles_base.css'' : Used when the user is using the base theme.
* ''mod/forum/styles_bootstrapbase.css'' : Used when the user is using the bootstrapbase theme.
* ''mod/forum/styles_clean.css'' : Used when the user is using the clean theme.

===CSS in core plugins===

For core plugins only styles.css is permitted and it should only ever contain styles essential to the presentation of the plugin.<br />
At present styles essential for the display of the plugin are allowed here, however when the plugin interfaces have been converted to use elements this file should be nearly empty and contain only the following:
* Images, icons and text used for visual presentation such as icons to notify state (expanded/collapsed, warnings...)
* Accessiblity orientated styles required to make the interface accessible.

'''Under no circumstances should it contain any visual stylings such as border, rounded corners, and background colours not associated with state.'''

==Writing HTML==

The following sections detail rules in place for writing HTML.

Before we start a couple of general recommendations:

; Use hyphens rather than underscores when concatenating strings in attributes : for example ''.course-new-activity-chooser'' instead of ''.course_new_activity_chooser''. By all doing this we will have a more consistent appearance and as We use underscores as part of frankenstyle which is prominent in CSS helps us to reduce the chance of naming conflicts.
; Think semantics - but don't get caught up in it : Semantic CSS is beautiful CSS lending itself ultimately to the redesign that is going to happen. But enforcing a semantic design can be an arduous journey. Instead we encourage semantic CSS but are happy to see non-semantic CSS when it is for the greater good.

===Using the ID attribute===

The situation of having a single JavaScript driven element was considered but even then it is better to style only classes and other attributes as we can't be sure what the future holds.

There are three rules you should follow when creating an ID:

# They should only be given to elements and HTML nodes that need to be interacted with by JavaScript.
# It should always start with '''m-''' ''(see note below)''
# The actual ID should be descriptive of the node and contents as a whole unit. It must fully and concisely describe its purpose.

Keep in mind that in an ideal world ID's should not be used for styling.

'''Good'''
<code html5>
<div id="m-dock"> ... </div>

<div id="m-course-new-activity-chooser"> ... </div>
</code>

'''Bad'''
<code html5>

<div id="dock"> ... </div>


<div id="m-activity-selector"> ... </div>
</code>

'''Note:''' The requirement to use m- prefix is entirely new, this has been created as this instantly reduces the chances of conflicting with present and future frontend frameworks that may be adopted by core or third party themes. Aiding our goal of being frontend framework agnostic.<br />
It will also help reduce the chance of conflicts in any third party code that may be used either by us in core, or by outside developers in their own code.
Moodle ID's will also be much more easily recognisable which we expect will be a benefit as JavaScript use in Moodle continues to increase.

===Naming CSS classes===

This is where a bit of organisation goes a long way and we want to be reasonably thorough in a consistent naming scheme and implementation.

The very first thing to mention is that all classes in Moodle must now be prefixed by *m-*.
This instantly identifes a class as belonging to Moodle, it aids us in avoiding conflicts with any non-Moodle css that may be loaded, and it is part of our framework agnostic plan.

<blockquote>
All CSS classes must start with *m-*
</blockquote>

There are several prefix that are used within Moodle output now that should not be used as prefixs for classes unless they are serving the desired purpose.

Reserved prefixes are:

; m-element : Prefix used on element classes, where m-element preceeds the name of the element, e.g. m-element-button, m-element-search
; m-state : Prefix used for CSS classes representing the state of an item, e.g. m-state-disabled, m-state-active, m-state-expanded.
; m-grid : Prefix used for creating HTML grids.

====Elements

Semantic design where it gives the best result, smart design where there is a better solution.

If you're not already familiar with the idea of semantic CSS then Chris Coylers artical [http://css-tricks.com/semantic-class-names/ What makes for a semantic class name] is a great starting point.

We've not commit to adopting any one strict approach for writing CSS. We have adopted atomic design for our HTML elements, a design style which fits nicely with the likes of OOCSS, however be very clear that we are not adopting the OOCSS approach in its entirety. The high level abstraction of the visual aspects of elements into highly reusable agnostic classes does not always lend itself well to the Moodle world in which the we wish to be frontend framework agnostic and support largescale completely customisable themes.<br />
The highly reusable classes that appeal to one designer, or to one frontend framework may not apply to another.<br />
This decision is also impacted by our current default theme bootstrapbase that does not use well abstracted OOCSS in its design.

Atomic design is going to see us end up with many parent child relationships in our HTML that we must carry through to our CSS. Through atomic design we start with smalled atoms and molecules that get built into larger organisms and placed within layouts.

Every element should have a single class that identifies it as element X.

For instance the button atom will have the class *m-element-button*

<code html5>
<button class="m-element-button">I am a button</button>
</code>

This is simply the prefix "m-element" plus the element name.

The purpose of this class is to allow the element to be styled with ease. The class name should be applied to the root node for the element, it should never be applied any lower.

By having one class for the element, and always and only applied to the root node it makes it very easy in HTML to see where one element belongs to another.

The following is an example of the search molecule, which in turn contains two button atoms.
<code html5>
<form class="m-element-confirmation">
<h3>Are you sure?</h3>
<p>Are you sure you want to perform this action?</p>
<input type="submit" name="cancel" class="m-element-button" value="Cancel" />
<input type="submit" name="continue" class="m-element-button" value="Continue" />
</form>
</code>

We've chosen to partially adopt BEM as a CSS standard when writing CSS for elements.
BEM isn't a new CSS standard, but its not widely known either. Its existence fills a gap in how to style elements consistently. Through two basic notation techniques you can easily notate the purpose of structures that belong to an element and notate the intent of an element that is desired if the element has multiple versions.

; Notating purpose : Here we use a suffix *__purpose*, the key being the two underscores.
; Notating intent : Here we use a suffix *--intent*, the key being the two hyphens.

You'll notice in the example above that there is no way to style the continue button differently from the cancel button without relying on its name, something we certainly don't want to do.
The solution is to wrap each button in a div and give each div a class.
The BEM standard comes into play here in naming the classes, the following shows how you would apply BEM to show the purpose of each button in a way that can be easily interpreted and styled in CSS.

<code html5>
<form class="m-element-confirmation">
<h3>Are you sure?</h3>
<p>Are you sure you want to perform this action?</p>
<div class="m-element-confirmation__cancel">
<input type="submit" name="cancel" class="m-element-button" value="Cancel" />
</div>
<div class="m-element-confirmation__continue">
<input type="submit" name="continue" class="m-element-button" value="Continue" />
</div>
</form>
</code>

You can now each button is wrapped in a div with a class, *m-element-confirmation__cancel* and *m-element-confirmation__continue*.
This class can be read by the themer and because of the __ can be easily identified as both belonging to the m-element-confirmation and serving a specific purpose, continue or cancel.

Now to explain the idea of intents.
An intent is when a single element takes on a different apprearance to convey a specific meaning. A little bit like a state, but with more meaning.
An easy example is notifications where you will no doubt be familiar with the idea of having a error notifications, warning notifications, success notification etc. Each of error, warning, and success is a intent.

The following shows how this would work:
<code html5>

<div class="m-element-notification">You have not changed your password in the past 60 days</div>


<div class="m-element-notification m-element-notification--warning">You have not changed your password in the past 60 days</div>
</div>

====Grids

We need to adopt a single grid framework.

Personally I don't think we should use pure bootstrap or pure YUI, instead we should choose one of these and build it use our class name structures.

All grid classes should start with m-grid.

==Writing CSS==

Before we begin lets lay down some ground level goals, things that will help us achieve clear and understandable CSS in the future.
* Formatting, ordering, alignment, and spacing are all important in having CSS that can be easily read by others.
* Don't optimise your CSS, be verbose and stick to the styles in this guide. We have tools that will handle optimisation for you.
* Never use *!important* in your CSS unless it is absolutely impossible to avoid doing so.

===Terminology===

Its important that when we are speaking about CSS we are speaking the same language.
Lets look at the following example:

<code css>
.m-page .m-selector-1,
.m-page .m-selector-2,
.m-page .m-selector-3 {
background-color: #FFF;
color: #000;
}

.m-selector-1 {
margin: 1em;
}
</code>

; Ruleset : Each of the two rules is a single *ruleset*.
; Rule: _.m-page .m-selector-1_ is a rule.
; Selector : _.m-selector-1_ is a *selector*, it is a single part of a rule.
; Declaration : _background-color: #FFF_ is a declaration.
;

===Essential formatting===

The following are the guies for writing CSS.

* Always use spaces - never use tabs. All editors can be configured to do it.
* Indent by 4 spaces - never more, never less.
* A single empty line between rulesets to maintain consistent spacing of rules.
* One rule per line.
* A single space between each selector in a rule.
* No space between a rule and the comma in a ruleset.
* A single space between a selector and the opening brace of a ruleset.
* One level of indentation before each declaration.
* A single space the colon in a declaration.
* A single space after each item in a declaration containing multiple items.

The following shows how the above rules apply:
<code css>
.m-selector-1,
.m-selector-2 .m-selector-3 {
background: #ffa800 url("background.png") no-repeat right top;
border: 1px solid #000;
display: inline-block;
font-family: arial, sans-serif;
margin: 5px 10px;
padding: 0;
}

.m-selector-4 {
border-radius: 3px;
}
</code>

===General rules===

Declaration ordering is the very first thing to discuss. There is no strict rule on how to order your declarations, however there is a recommendation.
We recommend that you order declarations within a ruleset alphabetically.
If we all start doing this then when you read CSS written by someone else you will soon learn to very quickly find your way around the declarations within a rule.
<code css>
/** Recommended **/
.m-selector {
background-color: #fff;
border: 1px solid #000;
color: #000;
display: block;
margin: 5px;
padding: 5px;
}
</code>

Do not use a measurement unit when writing a 0 value.
<code css>
/** Good **/
.m-selector {
margin: 5px 0;
}

/** Bad **/
.m-selector {
margin: 5px 0px;
}
</code>

Use lowercase and shorthand values for colours.
<code css>
/** Good **/
.m-selector {
background-color: #fff;
}

/** Bad **/
.m-selector {
background-color: #ffffff;
}
.m-selector {
background-color: #FFFFFF;
}
.m-selector {
background-color: white;
}
</code>

Always quote variable values.
<code css>
/** Good **/
.m-selector[attr="variable"] {
background-image: url("image.png");
}

/** Bad **/
.m-selector[attr=variable] {
background-image: url(image.png);
}
</code>

===Commenting===

Always comment your CSS and Less.

<code css>
/**
* Styles for the button atom.
*/
.m-element-button {
}
</code>

===Rules and exceptions for less===

Need to write some guff on Less.

==See also==
* [[User:Sam Hemelryk/Render library element planning]]
* [[Guide to creating output elements]] ''originally written at [[User:Sam Hemelryk/Creating renderable components]]''
* [[User:Sam Hemelryk/Renderer best practices]]
* [[User:Sam Hemelryk/CSS style guidelines]]

User:Sam Hemelryk/CSS style guidelines

2014-07-22T05:06:28Z

Samhemelryk: /* Why have a strict guide */

{{Infobox Project
|name = Renderer consistency
|state = Specification
|tracker = https://tracker.moodle.org/browse/MDL-45830
|discussion = https://moodle.org/mod/forum/discuss.php?d=261202
|assignee = Damyon, Sam
}}
{{Work in progress|forumurl=https://moodle.org/mod/forum/discuss.php?d=261202}}

==HTML and CSS style guide==

This is a guide to writing CSS within Moodle.

==Why have a strict guide==

At the time of writing this CSS within Moodle (2.7) themes is in a poor state and has been for a long time. Without previously having a guide we were finding that:

* As there was no formal guide to creating id's or classes, each developer does there own thing.
* As there was no formal guide on how to write CSS there were numerous techniques used when writing CSS and no consistency.
* Majority of pages create uniuqe output and require unique CSS, there is very little re-use of design.

While those points may not sound bad to you consider that in following stats from Moodle 2.7 themes:

* Base theme contains 3802 rulesets with a total of 5800 styles.
* Bootstrapbase theme contains 5170 rulesets with a total of 9362 styles.
* Clean theme contains 5172 rulesets with a total of 9366 styles.
* More theme contains 5177 rulesets with a total of 9063 styles.

You get the picture, several thousand selectors containing nearly 10000 styles.

For Moodle 2.8 we commited to introducing a element library to aid the reuse of design and documenting all aspects of output including a guide on writing CSS for Moodle. This is that guide.

==Our goals==

Its very important to understand what we are trying to achieve with this style guide and output in general.

; Frontend framework agnostic : We want theme designers to be able to apply present and future frontend frameworks to Moodle with minimal effort.
; Consistent interfaces : We want Moodle to have consistency throughout its interfaces, minimising the amount of frontend design and development that is required in coding and styling an interface.
; Cleanly formatted HTML and CSS : to minimise both development time and to make our renderers and CSS and more maintainable.

We plan to faciliate these with the following:
; Elements : Highly re-usable objects to produce HTML, these will be used consistently and relied upon by developers creating interfaces. By having these elements we create a consistent look, interface creation will be much quicker and theme designers through the re-use of a limited number of elements.
; Element library : A tool to show samples of each element, this can be used to view and test designs. It aids the developer by showing them the elements they can select from when creating an interface, and it aids designers by giving them a test area that doesn't require them to dig through every page in Moodle.
; Documentation : We will now have proper documentation on all aspects of output. Including this CSS style guide, a renderer best practices guide, and a guide to creating elements.

==Where to put CSS in Moodle core==

CSS can reside in a number of locations depending upon what you are styling.

Remember it doesn't matter how many CSS files we end up with, on a production site with Theme designer mode switched off (default) all CSS files will be combined and minimised into a single file that is served to the client.
Excepting the case of IE where we must split the CSS into several smaller files to work around browser limitations.

===CSS for elements===
As we are moving to using elements you will find that CSS for elements is where most of the effort is going to go.

CSS for elements should reside within themes only, you will find that elements must be styled in all core base themes, this means at least Bootstrapbase and base.

CSS for elements should be located within either '''theme/themename/style/elements/elementname.css''' or '''theme/themename/less/elements/elementname.css'''

The actual CSS file should be named according to the element. As elements can be namespaced we need to ensure that that is reflected in the name of the file.
For instance:

{|
! Element
! CSS location in base
! CSS location in bootstrapbase
|-
| \core\output\button
| style/elements/core_output_button.css
| less/moodle/elements/core_output_button.css
|-
| \core\output\navigation_bar
| style/elements/core_output_navigation_bar.css
| less/moodle/elements/core_output_navigation_bar.css
|-
| \mod_assign\output\user_submission
| style/elements/mod_assign_output_user_submission.css
| less/moodle/elements/mod_assign_output_user_submission.css
|}

These will still need to be included in the theme, by which ever means is relevant.
If you are using ''.css'' files like the base theme does then you will use:

<code php>
// In your themes config.php
$THEME->sheets = array(
'elements/core_output_button',
'elements/core_output_navigation_bar',
'elements/mod_assign_output_user_submission'
);
</code>

If you are using less as bootstrapbase does then you will use:
<code CSS>
/** In your primary less file **/
@import "moodle/elements/core_output_button";
@import "moodle/elements/core_output_navigation_bar";
@import "moodle/elements/mod_assign_output_user_submission";
</code>

===General CSS===

This is CSS for the theme that doesn't relate to a specific element. Hopefully as we convert more and more of Moodles interfaces to use elements we should see less general CSS.

In any case nothing has changed in regards to the location of general CSS.
; CSS : If your theme is using standard CSS then it must be located within the ''style'' directory of your theme and should be in logically separated files.
; Less : If your theme is using less then it should be located in a ''less/moodle'' directory within your theme.

We recommend that you separate styles into files based upon the Moodle component being styled. Again as all CSS files get combined into a single file on production sites it doesn't matter how many files you end up with.

This would lead to files named like:
* style/core.css
* style/course.css
* style/mod_forum.css

===Where to put CSS in plugins===

It is possible in Moodle to add CSS stylesheets to all plugins (including core plugins).<br />
Moodle always looks for a ''styles.css'' file within your plugins directory, and it also looks for a styles_themename.css where themename is the name of the currect theme being used.

For instance the following could be added to the forum module:

* ''mod/forum/styles.css'': Used all the time.
* ''mod/forum/styles_base.css'' : Used when the user is using the base theme.
* ''mod/forum/styles_bootstrapbase.css'' : Used when the user is using the bootstrapbase theme.
* ''mod/forum/styles_clean.css'' : Used when the user is using the clean theme.

==CSS in core plugins===

For core plugins only styles.css is permitted and it should only ever contain styles essential to the presentation of the plugin.<br />
At present styles essential for the display of the plugin are allowed here, however when the plugin interfaces have been converted to use elements this file should be nearly empty and contain only the following:
* Images, icons and text used for visual presentation such as icons to notify state (expanded/collapsed, warnings...)
* Accessiblity orientated styles required to make the interface accessible.

'''Under no circumstances should it contain any visual stylings such as border, rounded corners, and background colours not associated with state.'''

==Writing HTML==

The following sections detail rules in place for writing HTML.

Before we start a couple of general recommendations:

; Use hyphens rather than underscores when concatenating strings in attributes : for example ''.course-new-activity-chooser'' instead of ''.course_new_activity_chooser''. By all doing this we will have a more consistent appearance and as We use underscores as part of frankenstyle which is prominent in CSS helps us to reduce the chance of naming conflicts.
; Think semantics - but don't get caught up in it : Semantic CSS is beautiful CSS lending itself ultimately to the redesign that is going to happen. But enforcing a semantic design can be an arduous journey. Instead we encourage semantic CSS but are happy to see non-semantic CSS when it is for the greater good.

===Using the ID attribute===

The situation of having a single JavaScript driven element was considered but even then it is better to style only classes and other attributes as we can't be sure what the future holds.

There are three rules you should follow when creating an ID:

# They should only be given to elements and HTML nodes that need to be interacted with by JavaScript.
# It should always start with '''m-''' ''(see note below)''
# The actual ID should be descriptive of the node and contents as a whole unit. It must fully and concisely describe its purpose.

Keep in mind that in an ideal world ID's should not be used for styling.

'''Good'''
<code html5>
<div id="m-dock"> ... </div>

<div id="m-course-new-activity-chooser"> ... </div>
</code>

'''Bad'''
<code html5>

<div id="dock"> ... </div>


<div id="m-activity-selector"> ... </div>
</code>

'''Note:''' The requirement to use m- prefix is entirely new, this has been created as this instantly reduces the chances of conflicting with present and future frontend frameworks that may be adopted by core or third party themes. Aiding our goal of being frontend framework agnostic.<br />
It will also help reduce the chance of conflicts in any third party code that may be used either by us in core, or by outside developers in their own code.
Moodle ID's will also be much more easily recognisable which we expect will be a benefit as JavaScript use in Moodle continues to increase.

===Naming CSS classes===

This is where a bit of organisation goes a long way and we want to be reasonably thorough in a consistent naming scheme and implementation.

The very first thing to mention is that all classes in Moodle must now be prefixed by *m-*.
This instantly identifes a class as belonging to Moodle, it aids us in avoiding conflicts with any non-Moodle css that may be loaded, and it is part of our framework agnostic plan.

<blockquote>
All CSS classes must start with *m-*
</blockquote>

There are several prefix that are used within Moodle output now that should not be used as prefixs for classes unless they are serving the desired purpose.

Reserved prefixes are:

; m-element : Prefix used on element classes, where m-element preceeds the name of the element, e.g. m-element-button, m-element-search
; m-state : Prefix used for CSS classes representing the state of an item, e.g. m-state-disabled, m-state-active, m-state-expanded.
; m-grid : Prefix used for creating HTML grids.

====Elements

Semantic design where it gives the best result, smart design where there is a better solution.

If you're not already familiar with the idea of semantic CSS then Chris Coylers artical [http://css-tricks.com/semantic-class-names/ What makes for a semantic class name] is a great starting point.

We've not commit to adopting any one strict approach for writing CSS. We have adopted atomic design for our HTML elements, a design style which fits nicely with the likes of OOCSS, however be very clear that we are not adopting the OOCSS approach in its entirety. The high level abstraction of the visual aspects of elements into highly reusable agnostic classes does not always lend itself well to the Moodle world in which the we wish to be frontend framework agnostic and support largescale completely customisable themes.<br />
The highly reusable classes that appeal to one designer, or to one frontend framework may not apply to another.<br />
This decision is also impacted by our current default theme bootstrapbase that does not use well abstracted OOCSS in its design.

Atomic design is going to see us end up with many parent child relationships in our HTML that we must carry through to our CSS. Through atomic design we start with smalled atoms and molecules that get built into larger organisms and placed within layouts.

Every element should have a single class that identifies it as element X.

For instance the button atom will have the class *m-element-button*

<code html5>
<button class="m-element-button">I am a button</button>
</code>

This is simply the prefix "m-element" plus the element name.

The purpose of this class is to allow the element to be styled with ease. The class name should be applied to the root node for the element, it should never be applied any lower.

By having one class for the element, and always and only applied to the root node it makes it very easy in HTML to see where one element belongs to another.

The following is an example of the search molecule, which in turn contains two button atoms.
<code html5>
<form class="m-element-confirmation">
<h3>Are you sure?</h3>
<p>Are you sure you want to perform this action?</p>
<input type="submit" name="cancel" class="m-element-button" value="Cancel" />
<input type="submit" name="continue" class="m-element-button" value="Continue" />
</form>
</code>

We've chosen to partially adopt BEM as a CSS standard when writing CSS for elements.
BEM isn't a new CSS standard, but its not widely known either. Its existence fills a gap in how to style elements consistently. Through two basic notation techniques you can easily notate the purpose of structures that belong to an element and notate the intent of an element that is desired if the element has multiple versions.

; Notating purpose : Here we use a suffix *__purpose*, the key being the two underscores.
; Notating intent : Here we use a suffix *--intent*, the key being the two hyphens.

You'll notice in the example above that there is no way to style the continue button differently from the cancel button without relying on its name, something we certainly don't want to do.
The solution is to wrap each button in a div and give each div a class.
The BEM standard comes into play here in naming the classes, the following shows how you would apply BEM to show the purpose of each button in a way that can be easily interpreted and styled in CSS.

<code html5>
<form class="m-element-confirmation">
<h3>Are you sure?</h3>
<p>Are you sure you want to perform this action?</p>
<div class="m-element-confirmation__cancel">
<input type="submit" name="cancel" class="m-element-button" value="Cancel" />
</div>
<div class="m-element-confirmation__continue">
<input type="submit" name="continue" class="m-element-button" value="Continue" />
</div>
</form>
</code>

You can now each button is wrapped in a div with a class, *m-element-confirmation__cancel* and *m-element-confirmation__continue*.
This class can be read by the themer and because of the __ can be easily identified as both belonging to the m-element-confirmation and serving a specific purpose, continue or cancel.

Now to explain the idea of intents.
An intent is when a single element takes on a different apprearance to convey a specific meaning. A little bit like a state, but with more meaning.
An easy example is notifications where you will no doubt be familiar with the idea of having a error notifications, warning notifications, success notification etc. Each of error, warning, and success is a intent.

The following shows how this would work:
<code html5>

<div class="m-element-notification">You have not changed your password in the past 60 days</div>


<div class="m-element-notification m-element-notification--warning">You have not changed your password in the past 60 days</div>
</div>

====Grids

We need to adopt a single grid framework.

Personally I don't think we should use pure bootstrap or pure YUI, instead we should choose one of these and build it use our class name structures.

All grid classes should start with m-grid.

==Writing CSS==

Before we begin lets lay down some ground level goals, things that will help us achieve clear and understandable CSS in the future.
* Formatting, ordering, alignment, and spacing are all important in having CSS that can be easily read by others.
* Don't optimise your CSS, be verbose and stick to the styles in this guide. We have tools that will handle optimisation for you.
* Never use *!important* in your CSS unless it is absolutely impossible to avoid doing so.

===Terminology===

Its important that when we are speaking about CSS we are speaking the same language.
Lets look at the following example:

<code css>
.m-page .m-selector-1,
.m-page .m-selector-2,
.m-page .m-selector-3 {
background-color: #FFF;
color: #000;
}

.m-selector-1 {
margin: 1em;
}
</code>

; Ruleset : Each of the two rules is a single *ruleset*.
; Rule: _.m-page .m-selector-1_ is a rule.
; Selector : _.m-selector-1_ is a *selector*, it is a single part of a rule.
; Declaration : _background-color: #FFF_ is a declaration.
;

===Essential formatting===

The following are the guies for writing CSS.

* Always use spaces - never use tabs. All editors can be configured to do it.
* Indent by 4 spaces - never more, never less.
* A single empty line between rulesets to maintain consistent spacing of rules.
* One rule per line.
* A single space between each selector in a rule.
* No space between a rule and the comma in a ruleset.
* A single space between a selector and the opening brace of a ruleset.
* One level of indentation before each declaration.
* A single space the colon in a declaration.
* A single space after each item in a declaration containing multiple items.

The following shows how the above rules apply:
<code css>
.m-selector-1,
.m-selector-2 .m-selector-3 {
background: #ffa800 url("background.png") no-repeat right top;
border: 1px solid #000;
display: inline-block;
font-family: arial, sans-serif;
margin: 5px 10px;
padding: 0;
}

.m-selector-4 {
border-radius: 3px;
}
</code>

===General rules===

Declaration ordering is the very first thing to discuss. There is no strict rule on how to order your declarations, however there is a recommendation.
We recommend that you order declarations within a ruleset alphabetically.
If we all start doing this then when you read CSS written by someone else you will soon learn to very quickly find your way around the declarations within a rule.
<code css>
/** Recommended **/
.m-selector {
background-color: #fff;
border: 1px solid #000;
color: #000;
display: block;
margin: 5px;
padding: 5px;
}
</code>

Do not use a measurement unit when writing a 0 value.
<code css>
/** Good **/
.m-selector {
margin: 5px 0;
}

/** Bad **/
.m-selector {
margin: 5px 0px;
}
</code>

Use lowercase and shorthand values for colours.
<code css>
/** Good **/
.m-selector {
background-color: #fff;
}

/** Bad **/
.m-selector {
background-color: #ffffff;
}
.m-selector {
background-color: #FFFFFF;
}
.m-selector {
background-color: white;
}
</code>

Always quote variable values.
<code css>
/** Good **/
.m-selector[attr="variable"] {
background-image: url("image.png");
}

/** Bad **/
.m-selector[attr=variable] {
background-image: url(image.png);
}
</code>

===Commenting===

Always comment your CSS and Less.

<code css>
/**
* Styles for the button atom.
*/
.m-element-button {
}
</code>

===Rules and exceptions for less===

Need to write some guff on Less.

==See also==
* [[User:Sam Hemelryk/Render library element planning]]
* [[Guide to creating output elements]] ''originally written at [[User:Sam Hemelryk/Creating renderable components]]''
* [[User:Sam Hemelryk/Renderer best practices]]
* [[User:Sam Hemelryk/CSS style guidelines]]

User:Sam Hemelryk/CSS style guidelines

2014-07-22T05:06:01Z

Samhemelryk: Share the love

{{Infobox Project
|name = Renderer consistency
|state = Specification
|tracker = https://tracker.moodle.org/browse/MDL-45830
|discussion = https://moodle.org/mod/forum/discuss.php?d=261202
|assignee = Damyon, Sam
}}
{{Work in progress|forumurl=https://moodle.org/mod/forum/discuss.php?d=261202}}

==HTML and CSS style guide==

This is a guide to writing CSS within Moodle.

==Why have a strict guide==

At the time of writing this CSS within Moodle (2.7) themes is in a poor state and has been for a long time. Without previously having a guide we were finding that:

* As there was no formal guide to creating id's or classes, each developer does there own thing.
* As there was no formal guide on how to write CSS there were numerous techniques used when writing CSS and no consistency.
* Majority of pages create uniuqe output and require unique CSS, there is very little re-use of design.

While those points may not sound bad to you consider that in following stats from Moodle 2.7 themes:

* Base theme contains 3802 selectors with a total of 5800 styles.
* Bootstrapbase theme contains 5170 selectors with a total of 9362 styles.
* Clean theme contains 5172 selectors with a total of 9366 styles.
* More theme contains 5177 selectors with a total of 9063 styles.

You get the picture, several thousand selectors containing nearly 10000 styles.

For Moodle 2.8 we commited to introducing a element library to aid the reuse of design and documenting all aspects of output including a guide on writing CSS for Moodle. This is that guide.

==Our goals==

Its very important to understand what we are trying to achieve with this style guide and output in general.

; Frontend framework agnostic : We want theme designers to be able to apply present and future frontend frameworks to Moodle with minimal effort.
; Consistent interfaces : We want Moodle to have consistency throughout its interfaces, minimising the amount of frontend design and development that is required in coding and styling an interface.
; Cleanly formatted HTML and CSS : to minimise both development time and to make our renderers and CSS and more maintainable.

We plan to faciliate these with the following:
; Elements : Highly re-usable objects to produce HTML, these will be used consistently and relied upon by developers creating interfaces. By having these elements we create a consistent look, interface creation will be much quicker and theme designers through the re-use of a limited number of elements.
; Element library : A tool to show samples of each element, this can be used to view and test designs. It aids the developer by showing them the elements they can select from when creating an interface, and it aids designers by giving them a test area that doesn't require them to dig through every page in Moodle.
; Documentation : We will now have proper documentation on all aspects of output. Including this CSS style guide, a renderer best practices guide, and a guide to creating elements.

==Where to put CSS in Moodle core==

CSS can reside in a number of locations depending upon what you are styling.

Remember it doesn't matter how many CSS files we end up with, on a production site with Theme designer mode switched off (default) all CSS files will be combined and minimised into a single file that is served to the client.
Excepting the case of IE where we must split the CSS into several smaller files to work around browser limitations.

===CSS for elements===
As we are moving to using elements you will find that CSS for elements is where most of the effort is going to go.

CSS for elements should reside within themes only, you will find that elements must be styled in all core base themes, this means at least Bootstrapbase and base.

CSS for elements should be located within either '''theme/themename/style/elements/elementname.css''' or '''theme/themename/less/elements/elementname.css'''

The actual CSS file should be named according to the element. As elements can be namespaced we need to ensure that that is reflected in the name of the file.
For instance:

{|
! Element
! CSS location in base
! CSS location in bootstrapbase
|-
| \core\output\button
| style/elements/core_output_button.css
| less/moodle/elements/core_output_button.css
|-
| \core\output\navigation_bar
| style/elements/core_output_navigation_bar.css
| less/moodle/elements/core_output_navigation_bar.css
|-
| \mod_assign\output\user_submission
| style/elements/mod_assign_output_user_submission.css
| less/moodle/elements/mod_assign_output_user_submission.css
|}

These will still need to be included in the theme, by which ever means is relevant.
If you are using ''.css'' files like the base theme does then you will use:

<code php>
// In your themes config.php
$THEME->sheets = array(
'elements/core_output_button',
'elements/core_output_navigation_bar',
'elements/mod_assign_output_user_submission'
);
</code>

If you are using less as bootstrapbase does then you will use:
<code CSS>
/** In your primary less file **/
@import "moodle/elements/core_output_button";
@import "moodle/elements/core_output_navigation_bar";
@import "moodle/elements/mod_assign_output_user_submission";
</code>

===General CSS===

This is CSS for the theme that doesn't relate to a specific element. Hopefully as we convert more and more of Moodles interfaces to use elements we should see less general CSS.

In any case nothing has changed in regards to the location of general CSS.
; CSS : If your theme is using standard CSS then it must be located within the ''style'' directory of your theme and should be in logically separated files.
; Less : If your theme is using less then it should be located in a ''less/moodle'' directory within your theme.

We recommend that you separate styles into files based upon the Moodle component being styled. Again as all CSS files get combined into a single file on production sites it doesn't matter how many files you end up with.

This would lead to files named like:
* style/core.css
* style/course.css
* style/mod_forum.css

===Where to put CSS in plugins===

It is possible in Moodle to add CSS stylesheets to all plugins (including core plugins).<br />
Moodle always looks for a ''styles.css'' file within your plugins directory, and it also looks for a styles_themename.css where themename is the name of the currect theme being used.

For instance the following could be added to the forum module:

* ''mod/forum/styles.css'': Used all the time.
* ''mod/forum/styles_base.css'' : Used when the user is using the base theme.
* ''mod/forum/styles_bootstrapbase.css'' : Used when the user is using the bootstrapbase theme.
* ''mod/forum/styles_clean.css'' : Used when the user is using the clean theme.

==CSS in core plugins===

For core plugins only styles.css is permitted and it should only ever contain styles essential to the presentation of the plugin.<br />
At present styles essential for the display of the plugin are allowed here, however when the plugin interfaces have been converted to use elements this file should be nearly empty and contain only the following:
* Images, icons and text used for visual presentation such as icons to notify state (expanded/collapsed, warnings...)
* Accessiblity orientated styles required to make the interface accessible.

'''Under no circumstances should it contain any visual stylings such as border, rounded corners, and background colours not associated with state.'''

==Writing HTML==

The following sections detail rules in place for writing HTML.

Before we start a couple of general recommendations:

; Use hyphens rather than underscores when concatenating strings in attributes : for example ''.course-new-activity-chooser'' instead of ''.course_new_activity_chooser''. By all doing this we will have a more consistent appearance and as We use underscores as part of frankenstyle which is prominent in CSS helps us to reduce the chance of naming conflicts.
; Think semantics - but don't get caught up in it : Semantic CSS is beautiful CSS lending itself ultimately to the redesign that is going to happen. But enforcing a semantic design can be an arduous journey. Instead we encourage semantic CSS but are happy to see non-semantic CSS when it is for the greater good.

===Using the ID attribute===

The situation of having a single JavaScript driven element was considered but even then it is better to style only classes and other attributes as we can't be sure what the future holds.

There are three rules you should follow when creating an ID:

# They should only be given to elements and HTML nodes that need to be interacted with by JavaScript.
# It should always start with '''m-''' ''(see note below)''
# The actual ID should be descriptive of the node and contents as a whole unit. It must fully and concisely describe its purpose.

Keep in mind that in an ideal world ID's should not be used for styling.

'''Good'''
<code html5>
<div id="m-dock"> ... </div>

<div id="m-course-new-activity-chooser"> ... </div>
</code>

'''Bad'''
<code html5>

<div id="dock"> ... </div>


<div id="m-activity-selector"> ... </div>
</code>

'''Note:''' The requirement to use m- prefix is entirely new, this has been created as this instantly reduces the chances of conflicting with present and future frontend frameworks that may be adopted by core or third party themes. Aiding our goal of being frontend framework agnostic.<br />
It will also help reduce the chance of conflicts in any third party code that may be used either by us in core, or by outside developers in their own code.
Moodle ID's will also be much more easily recognisable which we expect will be a benefit as JavaScript use in Moodle continues to increase.

===Naming CSS classes===

This is where a bit of organisation goes a long way and we want to be reasonably thorough in a consistent naming scheme and implementation.

The very first thing to mention is that all classes in Moodle must now be prefixed by *m-*.
This instantly identifes a class as belonging to Moodle, it aids us in avoiding conflicts with any non-Moodle css that may be loaded, and it is part of our framework agnostic plan.

<blockquote>
All CSS classes must start with *m-*
</blockquote>

There are several prefix that are used within Moodle output now that should not be used as prefixs for classes unless they are serving the desired purpose.

Reserved prefixes are:

; m-element : Prefix used on element classes, where m-element preceeds the name of the element, e.g. m-element-button, m-element-search
; m-state : Prefix used for CSS classes representing the state of an item, e.g. m-state-disabled, m-state-active, m-state-expanded.
; m-grid : Prefix used for creating HTML grids.

====Elements

Semantic design where it gives the best result, smart design where there is a better solution.

If you're not already familiar with the idea of semantic CSS then Chris Coylers artical [http://css-tricks.com/semantic-class-names/ What makes for a semantic class name] is a great starting point.

We've not commit to adopting any one strict approach for writing CSS. We have adopted atomic design for our HTML elements, a design style which fits nicely with the likes of OOCSS, however be very clear that we are not adopting the OOCSS approach in its entirety. The high level abstraction of the visual aspects of elements into highly reusable agnostic classes does not always lend itself well to the Moodle world in which the we wish to be frontend framework agnostic and support largescale completely customisable themes.<br />
The highly reusable classes that appeal to one designer, or to one frontend framework may not apply to another.<br />
This decision is also impacted by our current default theme bootstrapbase that does not use well abstracted OOCSS in its design.

Atomic design is going to see us end up with many parent child relationships in our HTML that we must carry through to our CSS. Through atomic design we start with smalled atoms and molecules that get built into larger organisms and placed within layouts.

Every element should have a single class that identifies it as element X.

For instance the button atom will have the class *m-element-button*

<code html5>
<button class="m-element-button">I am a button</button>
</code>

This is simply the prefix "m-element" plus the element name.

The purpose of this class is to allow the element to be styled with ease. The class name should be applied to the root node for the element, it should never be applied any lower.

By having one class for the element, and always and only applied to the root node it makes it very easy in HTML to see where one element belongs to another.

The following is an example of the search molecule, which in turn contains two button atoms.
<code html5>
<form class="m-element-confirmation">
<h3>Are you sure?</h3>
<p>Are you sure you want to perform this action?</p>
<input type="submit" name="cancel" class="m-element-button" value="Cancel" />
<input type="submit" name="continue" class="m-element-button" value="Continue" />
</form>
</code>

We've chosen to partially adopt BEM as a CSS standard when writing CSS for elements.
BEM isn't a new CSS standard, but its not widely known either. Its existence fills a gap in how to style elements consistently. Through two basic notation techniques you can easily notate the purpose of structures that belong to an element and notate the intent of an element that is desired if the element has multiple versions.

; Notating purpose : Here we use a suffix *__purpose*, the key being the two underscores.
; Notating intent : Here we use a suffix *--intent*, the key being the two hyphens.

You'll notice in the example above that there is no way to style the continue button differently from the cancel button without relying on its name, something we certainly don't want to do.
The solution is to wrap each button in a div and give each div a class.
The BEM standard comes into play here in naming the classes, the following shows how you would apply BEM to show the purpose of each button in a way that can be easily interpreted and styled in CSS.

<code html5>
<form class="m-element-confirmation">
<h3>Are you sure?</h3>
<p>Are you sure you want to perform this action?</p>
<div class="m-element-confirmation__cancel">
<input type="submit" name="cancel" class="m-element-button" value="Cancel" />
</div>
<div class="m-element-confirmation__continue">
<input type="submit" name="continue" class="m-element-button" value="Continue" />
</div>
</form>
</code>

You can now each button is wrapped in a div with a class, *m-element-confirmation__cancel* and *m-element-confirmation__continue*.
This class can be read by the themer and because of the __ can be easily identified as both belonging to the m-element-confirmation and serving a specific purpose, continue or cancel.

Now to explain the idea of intents.
An intent is when a single element takes on a different apprearance to convey a specific meaning. A little bit like a state, but with more meaning.
An easy example is notifications where you will no doubt be familiar with the idea of having a error notifications, warning notifications, success notification etc. Each of error, warning, and success is a intent.

The following shows how this would work:
<code html5>

<div class="m-element-notification">You have not changed your password in the past 60 days</div>


<div class="m-element-notification m-element-notification--warning">You have not changed your password in the past 60 days</div>
</div>

====Grids

We need to adopt a single grid framework.

Personally I don't think we should use pure bootstrap or pure YUI, instead we should choose one of these and build it use our class name structures.

All grid classes should start with m-grid.

==Writing CSS==

Before we begin lets lay down some ground level goals, things that will help us achieve clear and understandable CSS in the future.
* Formatting, ordering, alignment, and spacing are all important in having CSS that can be easily read by others.
* Don't optimise your CSS, be verbose and stick to the styles in this guide. We have tools that will handle optimisation for you.
* Never use *!important* in your CSS unless it is absolutely impossible to avoid doing so.

===Terminology===

Its important that when we are speaking about CSS we are speaking the same language.
Lets look at the following example:

<code css>
.m-page .m-selector-1,
.m-page .m-selector-2,
.m-page .m-selector-3 {
background-color: #FFF;
color: #000;
}

.m-selector-1 {
margin: 1em;
}
</code>

; Ruleset : Each of the two rules is a single *ruleset*.
; Rule: _.m-page .m-selector-1_ is a rule.
; Selector : _.m-selector-1_ is a *selector*, it is a single part of a rule.
; Declaration : _background-color: #FFF_ is a declaration.
;

===Essential formatting===

The following are the guies for writing CSS.

* Always use spaces - never use tabs. All editors can be configured to do it.
* Indent by 4 spaces - never more, never less.
* A single empty line between rulesets to maintain consistent spacing of rules.
* One rule per line.
* A single space between each selector in a rule.
* No space between a rule and the comma in a ruleset.
* A single space between a selector and the opening brace of a ruleset.
* One level of indentation before each declaration.
* A single space the colon in a declaration.
* A single space after each item in a declaration containing multiple items.

The following shows how the above rules apply:
<code css>
.m-selector-1,
.m-selector-2 .m-selector-3 {
background: #ffa800 url("background.png") no-repeat right top;
border: 1px solid #000;
display: inline-block;
font-family: arial, sans-serif;
margin: 5px 10px;
padding: 0;
}

.m-selector-4 {
border-radius: 3px;
}
</code>

===General rules===

Declaration ordering is the very first thing to discuss. There is no strict rule on how to order your declarations, however there is a recommendation.
We recommend that you order declarations within a ruleset alphabetically.
If we all start doing this then when you read CSS written by someone else you will soon learn to very quickly find your way around the declarations within a rule.
<code css>
/** Recommended **/
.m-selector {
background-color: #fff;
border: 1px solid #000;
color: #000;
display: block;
margin: 5px;
padding: 5px;
}
</code>

Do not use a measurement unit when writing a 0 value.
<code css>
/** Good **/
.m-selector {
margin: 5px 0;
}

/** Bad **/
.m-selector {
margin: 5px 0px;
}
</code>

Use lowercase and shorthand values for colours.
<code css>
/** Good **/
.m-selector {
background-color: #fff;
}

/** Bad **/
.m-selector {
background-color: #ffffff;
}
.m-selector {
background-color: #FFFFFF;
}
.m-selector {
background-color: white;
}
</code>

Always quote variable values.
<code css>
/** Good **/
.m-selector[attr="variable"] {
background-image: url("image.png");
}

/** Bad **/
.m-selector[attr=variable] {
background-image: url(image.png);
}
</code>

===Commenting===

Always comment your CSS and Less.

<code css>
/**
* Styles for the button atom.
*/
.m-element-button {
}
</code>

===Rules and exceptions for less===

Need to write some guff on Less.

==See also==
* [[User:Sam Hemelryk/Render library element planning]]
* [[Guide to creating output elements]] ''originally written at [[User:Sam Hemelryk/Creating renderable components]]''
* [[User:Sam Hemelryk/Renderer best practices]]
* [[User:Sam Hemelryk/CSS style guidelines]]

Developer meeting July 2014

2014-07-14T02:44:35Z

Samhemelryk:

User:Sam Hemelryk/Renderer best practices

2014-07-06T22:15:37Z

Samhemelryk:

{{Infobox Project
|name = Renderer consistency
|state = Specification
|tracker = https://tracker.moodle.org/browse/MDL-45853
|discussion = https://moodle.org/mod/forum/discuss.php?d=261202
|assignee = Damyon, Sam
}}
{{Work in progress|forumurl=https://moodle.org/mod/forum/discuss.php?d=261202}}

This page documents renderer best practices.

==Notes==

* Must mention atomic design and how the concept of "templates" should be applied. Relates to the next note. A forth method type for renderers?
* Within a component or plugin that has a renderer use the renderer for EVERYTHING within that area. [https://moodle.org/mod/forum/discuss.php?d=262817#p1138926 forum post that ignited this]
* Reference and probably copy the three render methods from [Guide to creating output elements]

==Renderer best practices==

This document discusses the recommended practises to follow when writing renderers for Moodle. It was created in Moodle 2.8 as part of the element library specification that took place.

Renderers provide an abstraction of logic and display. They serve Moodle to both encourage us to properly structure our code and to provide a means by which themes can take control of output to completely customise the look of Moodle.
Elements and the element library provide us a set of building blocks to use when creating output. These provide us a consistent and manageable look that also minimising the amount of customisation required by a theme to change the look and feel of Moodle.
Here we make a recommendation on how to write renderers to maximise the benefits to both yourself as a developer and to designers who have to customise the interfaces you create.

==Goals==

Its important to understand the goals for output before you start looking at renderers as they are just one part of the output plan.

'''Output in Moodle is designed to:'''
* Aid developers in properly abstracting output from logic.
* Allow designers to take complete control of output from within a theme if they wish.
* Provide a consisten look and feel for Moodle user.
* Allow developers to more rapidly create interfaces by having a set of elements at their finger tips.
* Minimise the efforts designers must extrude in order to customise the look and feel of Moodle by limiting the output to a set of elements.
* Aid designers by providing tools to support styling Moodle such as the element library.

'''Renderers in Moodle:'''
* Are the link between Moodle and a theme through which all output is generated.
* Are organised for the benefit of designers, and should be written following this document.
* Most importantly allow designers to override the HTML that wraps the data being displayed in turn allowing designers to re-design output in a theme.
* Allow designers to change the information being displayed by providing not just what is initially required but that which that may require.

==A simple set of rules for a good renderer==

Summarising what will be discussed further in this document a good renderer can be summarised as:

* Think in elements. We have an element library, when planning the output for your plugin/component start with the elements in the element library and the markup they provide.
* Containing only methods confroming to the four method types discussed below.
* Encapsulated data is given, maximising the information available to the renderer and minimising the number of arguments.
* Free of logic relating to anything except output. This includes not calculating the likes of links and capabilities.
* Uses helper methods to manipulate data where manipulate is absolutely required, essentially abstracting logic to conform to the above rule.
* Utilise the core elements as much as is possible.
* Recognise unique output needs and create element(s) for it.
* The render method should be used as often as possible to maximise consistent look.

==The don'ts==

The following are things that should not be done within a renderer.

'''DO NOT:'''
* design interfaces from scratch when desiging output for your plugin/component. Always start with the elements found in the element library.
* Use logic that isn't essential to producing output. This includes but is not limited to the following:
** Database interaction of any kind.
** Access or capability checks.
** Generation of data such as producing URL's, that should be owned by the plugin/component and made available preferably through the given arguments or failing that through a helper method.
* Generate HTML for something that should be an element, convert it to an element and call render on it.
* Create custom elements for everything you plan to output, instead try to maximise the core elements that you use.
* Write your own render methods for subelements of the elements you create. Only do this if you absolutely must change the markup from that produced by the natural render method for the element.

==Creating a renderer==

===Location and naming===
As of Moodle 2.8 renderers can be put into the output namespace. This is the recommended placement for Renderers in Moodle 2.8 and up, however the alternatives will also be listed here.

Recommended:
* Put your renderer in '''mod/yourplugin/output/renderer.php''' use the namespace '''mod_yourplugin\output''' and call your class '''renderer'''.
* To get an instance of your renderer ''$PAGE->get_renderer('mod_yourplugin')'''

This is how mod/yourplugin/output/renderer.php will look:
<code php>
<?php

namespace mod_yourplugin\output;

class renderer extends \plugin_renderer_base {
// Your renderer methods in here.
}
</code>

Also available but not recommended:
* Put your renderer in '''mod/yourplugin/renderer.php''' do NOT namespace it, and call your class '''mod_yourplugin_renderer'''.
* To get an instance of your renderer ''$PAGE->get_renderer('mod_yourplugin')'''

This was how things were done in earlier versions of Moodle (2.7 and below).

===Render methods===

Renderers can be well structured, the purpose of them is the same across all plugins and components.
There are four distinct types of render methods that you can expect to find in a renderer, and these four can be categorised into one of two categories.

The four types of render methods:
# Layout methods
# Translator methods
# Render methods
# Convenience methods

These four methods can then be categorised in two ways:
; Plugin|Component method : The layout and translator methods are plugin or component methods. They take data for a plugin or component and meld it into renderables. These methods relate to and can be said to be owned by the plugin or component.
; Element methods : The render and convenience methods relate only to elements. They take already encapsulated abstracted data and simply output HTML structure around it. They pay no regard to the plugin or component and are completely and solely bound to the output of an element.

====Layout methods====

====Translator methods====

====Render methods====
If you've spent any time working with renderers in the past you will already be familiar with the concept of a render method.
All elements within Moodle inherit the renderable interface. To produce output for them you call the renderers render method and give the element.
The render method looks at what is given and looks

====Convenience methods====
These are very simple. A convenience method is simply an easy way to build and output an element in a single step.
If you take an element, likely an atom or molecule, a convenience method would have the same arguments as the constructor for the element, build an instance of the element and call render on it.
The following is a simple example using heading:

<code php>
/**
* A convenience method to render a heading.
*/
public function heading($content, $level = 2) {
$heading = new \core\output\heading($content, $level);
return $this->render($heading);
}
</code>

==Creating output elements==
This is a big field and as such a dedicated document has been writen as a [[Guide to creating output elements]].

==Tips on properly structuring your plugin==
Talk here about OO structuring of code, ensuring a traversable heirarchy that enables maximum movement of code structure to obtain data and in turn minimises necessary arguments for layout methods.

==See also==

* [[Render library specification]]
* [[Guide to creating output elements]]
* [https://moodle.org/mod/forum/discuss.php?d=261202 Render library specification discussion]
* [[User:Sam Hemelryk/Render library element planning]]
* [[User:Sam Hemelryk/Renderer best practices]]
* [[User:Sam Hemelryk/CSS style guidelines]]

User:Sam Hemelryk/Render library element planning

2014-06-27T02:06:17Z

Samhemelryk: /* User content */

{{Infobox Project
|name = Renderer consistency
|state = Specification
|tracker = https://tracker.moodle.org/browse/MDL-45829
|discussion = https://moodle.org/mod/forum/discuss.php?d=261202
|assignee = Damyon, Sam
}}
{{Work in progress|forumurl=https://moodle.org/mod/forum/discuss.php?d=261202}}
This page documents the proposed core elements, variations of them, what we expect they will contain, and the core_renderer block.

==The user action==

An action in this sense is a collection of data that all pertains to one action that can be taken by the user.
The action, once populated with data can be rendered as is required for the job it is going to fulfil, usually with some relation to the frontend framework in use.
In this way the action could be a link, or a button; it could even be interpreted into a more complex structure.

An action has the following properties:
; content [string]: text content for the link or button.
; url [moodle_url] : the url for the action to take when the user interacts with this action.
; description : a description of the action. Typically used within a title or alt attribute.
; active : True if this is the action the user is current performing.
; enabled : True if the action is possible, false if it is not possible and should be shown as disabled.
; dimmed : True if the action should be shown as dimmed, usually used to the action is hidden to other users.
; method : The preferred method of submitting this action, typically GET but can be set to POST.

It is also possible to add JavaScript actions (component_action objects) to an action. These attach a JS listener to the action that gets executed when the user interacts with the action.
Attached JavaScript actions get initialised when the properties for the action are retrieved so any events must be attached BEFORE the action is rendered, and all renderers must ensure they use the get_attributes() call.

==Grids==

We need to come up with some way to include grids in core, it is desirable to keep it framework agnostic so perhaps a grid object that allows for items to be added and a "width" specified when that occurs. The width would be either a fixed number or a percentage. Steps of 12 seems pretty common.

==Design requirements==
The following concepts need to be accounted for in core, or decisions made on how we choose to support these and where.

===Clearfix===
We have this in core already, bootstrap has it, pretty much every front end framework has it.
Clearfix is more of a design decision, should only be used when require, and only ever applied by a renderer.
This gets special mention as being important, support is already 100%.

===Floats===
Pull left, pull right etc. These are a design decisions and should be implemented by the renderer. Bootstrap caters for these and as such they will be easily catered for in bootstrapbase, however work may be required to get them operational in base.

==Discarded ideas==
The following things are ideas that came up during discussions on what elements are, and what elements we want in core that have being discarded.

==Core atoms, molecules, and organisms==

The following is the atoms, molecules and organisms we believe should be created initially. Of course there will be many more that are required - however this should give us a good grounding of elements to work with for the first conversions.

===Action {atom}===
See the section above about [[#The user action]]

Actions are special atoms the represent an action the user can make.
They can be rendered by a theme as a link, a button or I suppose anything else.
There should be a default for when it is not specified and the renderer in change of producing the current thing can decide whether to use the default and just call ''render'' or if it requires something specific ''render_link'' or ''render_button'' as required.

===Action group {molecule}===
A group of actions, to be rendered to reflect a relation. I suppose the easiest way to think about this is how buttons in the atto editor are grouped together. It is a requirement that may seem a tad absrtracted and irrelevant at first but I think will pop up in several places throughout Moodle when we start converting.

It is basically a collection of actions.

'''Markup in various frontend frameworks'''

* [http://getbootstrap.com/2.3.2/components.html#buttonGroups Bootstrap 2.3.2]
* [http://getbootstrap.com/components/#btn-groups Bootstrap 3]
* [http://foundation.zurb.com/docs/components/button_groups.html Zurb foundation]

===Block {atom}===

Unique to Moodle. This represents a block on the page, and is displayed within a [[#Block region]].
It accepts two arguments, the first is a ''block_contents'' object instance, and the second is the region name the block instance is being shown within.

At present a block is rendered using the '''''core_render::block''''' method. Internally this calls several renderer methods to produce the different parts of a block.
* core_renderer::block_header - Produces a header
** core_renderer::block_controls - Produces controls to display within the header.
* core_renderer::block_content - Produces the actual content of the block.
** core_renderer::block_controls - Used to check if block controls were rendered. PUKE!!!
** core_renderer::block_footer - Produces a footer that actually resides within the content.
* core_renderer::block_annotation - Produces an annotation, used VERY rarely.

'''Current structure'''

The following is the output when called for a navigation block with a bit of extra added to show how a footer is displayed and an annotation.
<code html5>
<a href="#sb-1" class="skip-block">Skip Navigation</a>
<div id="inst4" class="block_navigation block" role="navigation" data-block="navigation" data-instanceid="4" aria-labelledby="instance-4-header" data-dockable="1">
<div class="header">
<div class="title">
<div class="block_action">

</div>
<h2 id="instance-4-header">Navigation</h2>
</div>
</div>
<div class="content">

<div class="footer">

</div>
</div>
<div class="blockannotation">

</div>
</div>
<span id="sb-1" class="skip-block-to"></span>
</code>

===Block region {molecule}===

Unique to Moodle, the block region is a contain for all of the blocks in one location.
We currently have two methods that produce a block region within Moodle, the first is '''''core_renderer::blocks_for_region''''' which adds no surrounding content.
The preferred method '''''core_renderer::blocks''''' adds some embedded information to a common structure.

'''Current structure'''

The following is the structure of the ''core_renderer::blocks()'' method.
<code php>
public function blocks($region, $classes = array(), $tag = 'aside');
</code>

The following is the html output is $region was ''pre'' and the default tag and classes were used.
<code html5>
<aside id="block-region-pre" class="block-region" data-blockregion="pre" data-droptarget="1">

</aside>
</code>

'''Thoughts on this'''

The blocks method is a convenience method and serves an important purpose. However it should not take classes and tag as arguments.<br />
These should certainly only settable within the renderer itself, and if themes wish to change this without wrapping the call they should override the renderer.

Both the data attributes relate to servicing JavaScript functionality. Perhaps they should be moved to a component_action or somehow else integrated with JS rather than with the renderer directly.

Internally it is calling blocks for region, however this should change it should request a array of blocks, convert the array to [[#Block]] elements and call render on each.

'''Proposed HTML structure'''

Much like the current structure but with the data attributes coming through a JS mechanism.

<code html5>
<aside id="block-region-pre" class="block-region">

</aside>
</code>

===Breadcrumb {molecule}===

Currently called the navbar within Moodle, controlled by the '''''navbar''''' class located in lib/navigationlib.php and rendered by '''''core_renderer::navbar()'''''.<br />
Internally it calls moodle_page->navbar->get_items() to get an array containing navigation node items to display in the navigation bar.<br />
It produces a bit of surrounding structure before calling render on each item.

'''Current structure'''

The following shows the structure for two items in the navigation bar presently within Moodle.

<code html5>
<span class="accesshide">Page path</span>
<nav class="breadcrumb-nav">
<ul class="breadcrumb">
<li>
<a href="#">Home</a>
<span class="divider">
<span class="accesshide">
<span class="arrow_text">/</span>
 
</span>
<span class="arrow sep">►</span>
</span>
</li>
<li>
<a href="#">Here</a>
<span class="divider">
<span class="accesshide">
<span class="arrow_text">/</span>
 
</span>
<span class="arrow sep">►</span>
</span>
</li>
</ul>
</nav>
</code>

Notice the excessive amount of markup to make the separator accessible.

'''Markup in various frontend frameworks'''

[http://getbootstrap.com/2.3.2/components.html#breadcrumbs Bootstrap 2.3.2]
<code html5>
<ul class="breadcrumb">
<li>
<a href="#">Home</a>
<span class="divider">/</span>
</li>
<li>
<a href="#">Here</a>
<span class="divider">/</span>
</li>
</ul>
</code>

[http://getbootstrap.com/components/#breadcrumbs Bootstrap 3]
<code html5>
<ul class="breadcrumb">
<li>
<a href="#">Home</a>
</li>
<li>
<a href="#">Here</a>
</li>
</ul>
</code>

[http://foundation.zurb.com/docs/components/breadcrumbs.html Zurb foundation]
<code html5>
<ul class="breadcrumb">
<li>
<a href="#">Home</a>
</li>
<li>
<a href="#">Here</a>
</li>
</ul>
</code>

'''Design considerations'''

* The currently active page should be marked with a class.
* The current item should probably not be a link MDL-46037
* [http://www.w3.org/TR/2007/WD-aria-role-20070601/#breadcrumbs wia-aria breadcrumb role]
* The divider perhaps could come through CSS with these changes to avoid markup necessary to make it accessible (in combination with the above).

'''Implementation thoughts'''
* Owns an array of [#Action {atoms}]

===Buttons {atom}===

This will be both an element and a representation of a [#Action {atom}].<br />
Obviously buttons can serve different purposes and roles so have several easily reachable customisations is probably a wise idea.

'''Current structure'''
None, presently you produce a button when you need it so there are several throughout Moodle.

'''Markup in various frontend frameworks'''

[http://getbootstrap.com/2.3.2/base-css.html#buttons Bootstrap 2.3.2] and [http://getbootstrap.com/css/#buttons Bootstrap 3]
<code html5>
<button type="button" class="btn btn-default">Default</button>

<a href="#" class="btn btn-default btn-lg active" role="button">Link</a>

<input class="btn btn-default" type="button" value="Input">
</code>

Customisations available through Bootstrap:
* Purposes: default, primary, success, info, warning, danger, link
* Sizes: large, default, small, extra-small
* Block level (wider)
* States: Active, disabled.

[http://foundation.zurb.com/docs/components/buttons.html Zurb foundation]
<code html5>
<a href="#" class="button">Default Button</a>
</code>

Customisations available through Zurb Foundation:
* Purposes: default, secondary, success, alert
* Sizes: large, default, small, tiny
* Corner style: radius, round
* Expanded (wider)
* States: disabled

===Calendar {organism}===

A simple idea really, apparently not already covered by the frontend frameworks being referenced during the creation of the doc.
The display of the calendar is fixed, but it can contain content for each day shown.

The calendar should have several views, perhaps these are separate organisms, perhaps not.

* Compact month
* Month
* Week
* Day

Each day could:
* Contain an action with an icon for events, and link to the fullday display.
* Have an associated action to load and display the events in a tooltip.

===Collapsible region {molecule}===

We use these in several places within Moodle. I could not find a reference to this concept in any of the frontend frameworks I looked at.
The concept is simple - you have a heading and an icon with content. By default the content is hidden, when the user clicks the heading and/or the icon the content is revealed.

As noted we do this in several places within Moodle, it would be good to have a single way of displaying this idea of a collapsible region.

'''Design thoughts'''
* It should support an optional collapse/expand all trigger action.
* We want to be able to use it both inside and outside of forms.
* It should be usable in situations like the combo list frontpage component as well.
* Will obviously have a JS component as without JS it would not work.

===Confirmation {molecule}===

A simple concept used regularly in Moodle to confirm a users intention to perform an actions. Most commonly seeing when deleting content.
The structure is relatively basic in Moodle at present.
* A message
* A forwards button
* A back button

'''Current structure'''

The method '''''core_renderer::confirm''''' does the rendering at present. Its signature is as follows:
<code php>
public function confirm($message, $continue, $cancel);
</code>

The output it produces is like:
<code html5>
<div class="generalbox" id="notice">
<p>The message goes here</p>
<div class="buttons">

</div>
</div>
</code>

'''Design throughts'''

This component does not have a title. I believe at present some pages use ''core_renderer::heading'' to produce a title if they wish. Obviously we want consistency of style so I believe it would be wise to add a title property that can be optionally set and then in our documentation for this element recommend that a title is always provided.<br />
It will mean re-factoring our uses to set a title and if a heading is being manually added remove it.

===Continue {molecule}===

This is much like the confirmation molecule but with a single button.<br />
At present we have '''''core_renderer::continue_button''''' that produces a single button. However this design is very poor as more often than not a message is included in the page to describe the purpose of the continue button. This is really an integral part of the continue button.

'''Current structure'''

Currently we have ''core_renderer::continue_button'' to render a single continue button.
<code php>
public function continue_button($url);
</code>

Internally it creates a single_button component and then calls render on that.

'''Design thoughts'''
Our element should have a message and a button. To make it easy to migrate the constructor should accept a URL instead of a button and do the same conversion as the current method is doing.

===Choice {molecule}===
Not sure about this one quite yet.
A description with 2 or more actions allowing the user to select the next step.
Think of it like when editing a module you get: Cancel, Save and return to course, Save and display

Perhaps both [#Confirmation {molecule}] and [#Continue {molecule}] should be just instances of this.

Hmm perhaps that would not be as clear as this and we should have this separate choice molecule.

===Divider {atom}===
Think horizontal rule.

===Dropdowns {molecule}===

So this is a pretty simple concept, but you've got to think of it as a separate entity. A dropdown is a menu that appears when the user interacts with an action.

The action could take one of three forms:
* From button
* From link
* From icon

Of course that is handled by the [#Action {atom}] noted above. Worth noting is that we will need some way to toggle these actions as dropdowns. Perhaps it is worth making that a property of the action atom.

The dropdown itself will likely contain more actions, and I suppose additional dropdowns to form sub menus. Sub-menus in my mind are required. We don't use them in core, but they are functionally possible through things like the custom menu and I know for a fact that many sites have sub menus.

'''Markup in various frontend frameworks'''

[http://getbootstrap.com/2.3.2/components.html#dropdowns Bootstrap 2.3.2]

<code html5>
<div class="dropdown">

<ul class="dropdown-menu" role="menu" aria-labelledby="dLabel">
<li><a tabindex="-1" href="#">Action</a></li>
<li><a tabindex="-1" href="#">Another action</a></li>
<li><a tabindex="-1" href="#">Something else here</a></li>
<li class="divider"></li>
<li><a tabindex="-1" href="#">Separated link</a></li>
</ul>
</div>
</code>

[http://getbootstrap.com/components/#dropdowns Bootstrap 3]
<code html5>
<div class="dropdown">
<button class="btn dropdown-toggle sr-only" type="button" id="dropdownMenu1" data-toggle="dropdown">
Dropdown
<span class="caret"></span>
</button>
<ul class="dropdown-menu" role="menu" aria-labelledby="dropdownMenu1">
<li role="presentation"><a role="menuitem" tabindex="-1" href="#">Action</a></li>
<li role="presentation"><a role="menuitem" tabindex="-1" href="#">Another action</a></li>
<li role="presentation"><a role="menuitem" tabindex="-1" href="#">Something else here</a></li>
<li role="presentation" class="divider"></li>
<li role="presentation"><a role="menuitem" tabindex="-1" href="#">Separated link</a></li>
</ul>
</div>
</code>

[http://foundation.zurb.com/docs/components/dropdown.html Zurb foundation]
<code html5>
<a href="#" data-dropdown="drop1">Has Dropdown</a>
<ul id="drop1" class="f-dropdown" data-dropdown-content>
<li><a href="#">This is a link</a></li>
<li><a href="#">This is another</a></li>
<li><a href="#">Yet another</a></li>
</ul>
</code>

===Forms {organism}===

This is an advanced organism and would be quite a bit of work to create in Moodle as we'd need to translate from QuickForms to elements for rendering.
It would be worthwhile doing this however, and would be a good way of quickly showing our new work.

'''Frontend framework structures'''
* [http://getbootstrap.com/2.3.2/base-css.html#forms Bootstrap 2.3.2]
* [http://getbootstrap.com/css/#forms Bootstrap 3]
* [http://foundation.zurb.com/docs/components/forms.html Zurb foundation]

All of those are quite in-depth and offer a range of configurations.
We should carefully consider these when analysing our work here.

===Headings {atom}===

Currently handled by '''core_renderer::heading'''.

* h1 - h6
* Optional icon
* Optional help icon

'''Current structure'''

The render method is currently:
<code php>
public function heading($text, $level = 2, $classes = null, $id = null);
</code>

The output generated by this is, assuming we use the default level, classes, and id.
<code html5>
<h2>I am a heading</h2>
</code>

Whats worth noting is that the render method should not accept level and classes as arguments.
These should only be set by the render method and should not be directly influenced.

===Image {atom}===

There are really two types of images to focus on here, or really two ways to display an image to focus on here.<br />
# Standard images
# Thumbnail images

Each of these would share some common properties:
* Image
* Description (alt/title)
* Size
* Action (making it a link) - This would actually make it a molecule, we would have to consider this and either have a new element, drop the ability to wrap in an action, or simply ignore this inconsistency.

===Image - Icon {atom}===

This covers the display of an icon. Should be a separate element from image as really they should be treated individually.
Within Moodle there are a few classifications of icons to consider:
* Standard icons
* Help icon (popup, tooltip)
* Loading icon (really regular icon but worth showing separately as its only seen when required)

===Image - Logo {molecule}===

We don't have this within core Moodle at present, however just about every theme I have seen uses a logo. I think it is about time we considered having a logo element.
I imagine it would become a sort of hero element, likely with an associated action (back home by default).

===Image - Profile picture {molecule}===

We already have a user_picture component within Moodle. It can be found in lib/outputcomponents.php.<br />
It has two render methods, '''''core_renderer::user_picture''''' and '''''core_renderer::render_user_picture'''''.

'''Current structure'''

The following is the output structure for the user picture:
<code html5>
<a href="#" id="userpicture_randomid">
<img src="#" alt="Picture of Joe" title="Picture of Joe" class="userpicture" width="[35, 100, XX]" height="[35, 100, XX]" />
</a>
</code>

What you'll notice about this is that the link has no attributes marking it as a user picture link.

The PHP code for the user_picture object itself is really quite in depth and complex. The component serves the user profile fields required to render a user picture. This is good in the scope of the component but would be bad within the scope of an element.<br />
Don't you wish we had a proper user object!

===Link {atom}===
This will be both an element and a representation of a [#Action {atom}].

Theres not too much more to explain about links, they don't tend to take states other than the default active, enabled and dimmed.<br />
It is worth mentioning that devs will be encouraged to use actions and not links unless absolutely necessary.<br />
The render method for this atom must typehint an action rather than a link.

'''Prototype example'''
* The atom: https://github.com/samhemelryk/moodle/blob/output_prototype_5/local/output/classes/output/link.php
* The convenience method: https://github.com/samhemelryk/moodle/blob/output_prototype_5/local/output/classes/output/renderer.php#L149
* The render method: https://github.com/samhemelryk/moodle/blob/output_prototype_5/local/output/classes/output/renderer.php#L211

===List {molecule}===

This is a pretty simple example and something I am sure you are all familiar with. A list is simply a collection of items. Usually represented using a UL or OL tag in markup although worth noting can be styled completely differently to the default.
There are three main types of lists used within Moodle:
* Ordered list
* Unordered list
* Presentation list (currently our unlist)

The list is a molecule because it should be able to accept other elements as items. E.g. it should be content independent.

===Menu {molecule}===

A menu is a familiar concept for any site. Probably the first thing that pops to mind for many is the navbar, but I want to consider that a separate component as a navbar can consist of more than just menu items.
I think a menu should be a collection of actions the user can perform. Perhaps with some form of hierarchy.

We have different types of menus within Moodle:
* The custom menu is one users can directly create, with dropdown downs and sub dropdowns.
* The action_menu component we have in core uses icons as actions and can have a dropdown.

These should be combined into a single menu element that takes items as an argument, likely actions + dropdowns + dividers to start with would be perfect.

We would likely need to deal with the display of the menu with properties to allow constructing code to ''request'' a particular style of menu. The renderer should be what actually gets to decide, but for the purposes of re-use having properties and a single render_method is better than having multiple render methods.<br />
The following is my initial thoughts on menu structure:
* Direction: Horizontal, Vertical
* Design: Default, Tabs,
* Style: Default, Links, Buttons, Icons

===Notification {atom}===
* Info
* Success
* Warning
* Danger

===Navigation bar {organism}===
Formerly navbar, can't be called that because the render method would conflict.

The navigation bar is just that, it is becoming increasingly common on the web and usually contains a title or logo, a menu, and information pertaining to the user state (login, language etc).

===Page header {molecule}===

Currently being produced by '''core_renderer::page_heading''' this is simply a header for the page, by default the only h1 element on the page.

'''Current structure'''

The render method has the following signature:
<code php>
public function page_heading($tag = 'h1');
</code>

The output from the above method is:
<code html5>
<h1>The page heading (from moodle_page::heading)</h1>
</code>

The core_renderer method should not allow the tag to be set. The page heading should always be H1.
If its not an H1 then page header should not be used.

'''Frontend framework examples'''

[http://getbootstrap.com/2.3.2/components.html#typography Bootstrap 2.3.2]
<code html5>
<div class="hero-unit">
<h1>Heading</h1>
<p>Tagline</p>
<p>
<a class="btn btn-primary btn-large">
Learn more
</a>
</p>
</div>
</code>

[http://getbootstrap.com/components/#page-header Bootstrap 3]
<code html5>
<div class="page-header">
<h1>Example page header <small>Subtext for header</small></h1>
</div>
</code>

Foundation doesn't appear to have a page header component.

'''Design thoughts'''

* In Moodle all page headings are set as a single string, we won't be changing this.
* Usually just a plain string sometimes an icon is used, and sometimes a help icon is used.

===Pagination {molecule}===

I like the idea of this being separate to a menu, and to other navigation oriented elements because it should be something that can easily be constructed with a few basic parameters and allow us to achieve consistent pagination throughout Moodle.<br />
It also appeals because this is something that people may want to style differently to their navigation.

'''Markup in various frontend frameworks'''

* [http://getbootstrap.com/2.3.2/components.html#pagination Bootstrap 2.3.2 pagination]
* [http://getbootstrap.com/components/#pagination Bootstrap 3 pagination]
* [http://foundation.zurb.com/docs/components/pagination.html Zurb foundation pagination]

===Progress bars {molecule}===

A pretty simple concept, we already have a couple of ways of producing progress bars within Moodle.

'''Markup in various frontend frameworks'''

[http://getbootstrap.com/2.3.2/components.html#progress Bootstrap 2.3.2]
<code html5>
<div class="progress">
<div class="bar" style="width: 60%;"></div>
</div>
</code>

The following options are offered by Bootstrap 2.3.2:

* Striped
* Striped + Animated
* Stacked (multiple bars forming a single)
* Colours: default (blue), info (light blue), success (green), warning (orange), danger (red)

[http://getbootstrap.com/components/#progress Bootstrap 3]
<code html5>

<div class="progress">
<div class="progress-bar" role="progressbar" aria-valuenow="60" aria-valuemin="0" aria-valuemax="100" style="width: 60%;">
60% Complete
</div>
</div>


<div class="progress">
<div class="progress-bar" role="progressbar" aria-valuenow="60" aria-valuemin="0" aria-valuemax="100" style="width: 60%;">
60%
</div>
</div>
</code>

The following options are offered by Bootstrap 3:

* Striped
* Striped + Animated
* Stacked (multiple bars forming a single)
* Colours: default (blue), info (light blue), success (green), warning (orange), danger (red)

[http://foundation.zurb.com/docs/components/progress_bars.html Zurb foundation]

<code html5>
<div class="progress">
<span class="meter"></span>
</div>
</code>

The following options are offered by Zurb foundation:
* Width
* Colours: default (blue), secondary (grey), success (green), alert (red)
* Corner style: default (square), radius (slight rounding), round

===Search {molecule}===

A pretty common interface molecule, and in fact used as an example in the atomic design blog post we keep referencing.<br />
We don't have a component for searching yet, however we've several search boxes throughout Moodle. The admin setting search box is the first to come to mind for me, followed by the forum search box and course search box.

'''Design considerations'''

Constructed of the following items:
* Text input
* Action (must be a button for submit I imagine)
* Label or short description (optional)
* Collapsible region containing settings etc (optional)

===Table {organism}===

We've two primary table components within Moodle presently '''html_table''' and '''flexible_table''' both of which offer different advantages and disadvantages. This will be a challenge and will really require some proper research and community interaction.

===Timer {atom|molecule}===

... not sure about this one, but we do use it in a couple of places, and we use it on all core sites that have hourly resets so in a way it makes sense to support it and allow it to be styled nicely and easily.

===Tree {organism}===

===User content {organism}===

Think of this like the forum post. We need a common structure in which to display content entered by the user along with information on the user. The users name, picture, date perhaps, title, content, footer (attachments, badges, what ever).
It could be applied to things like forum posts, calendar events etc.

At present we have no abstraction for this.

==Existing renderables and what they will become==
{| class="wikitable"
! Existing renderable
! Description
! Future renderable
! Convenience method (if different)
|-
| action_menu
| UI component for a drop down edit menu
| menu
|
|-
| action_menu_link
| UI component for a menu item in an action menu
| action
|
|-
| action_menu_filler
| UI component for a filler menu item in an action menu
| action
|
|-
| action_menu_link_primary
| UI component for a primary menu item in an action menu
| action
|
|-
| action_menu_link_secondary
| UI component for a secondary menu item in an action menu
| action
|
|-
| action_link
| Link with alt text, and an icon
| action
|
|-
| single_button
| A form with a single button
| button (action with post method)
|
|-
| confirm
| A form with a message and cancel/confirm buttons
| confirmation
|
|-
| single_select
| A form with a single drop down list that submits on change
|
|
|-
| url_select
| A navigation element consisting of a single drop down list of urls that navigates on change
|
|
|-
| doc_link
| A link to the Moodle docs
|
|
|-
| pix_icon
| A small icon
| icon
|
|-
| emoticon_icon
| A small emoticon
|
|
|-
| heading_with_help
| A page heading with a link to help docs
| heading
|
|-
| help_icon
| A help icon that opens a help popup when clicked
| icon_help
|
|-
| help_icon_scale
| A help icon that opens a help popup when clicked
|
|
|-
| user_picture
| A user profile picture which links to their profile
|
|
|-
| container
| A block level element used to surround something. Can have a class to allow specific targeting with CSS.
|
|
|-
| error_text
| An error to show to the user.
|
|
|-
| notification
| A message for the user
|
|
|-
| continue_button
| A message and a button to continue to the next page
|
|
|-
| paging_bar
| A list of next previous and specific page links
|
|
|-
| skip_link_to
| A link to a section on the page
|
|
|-
| skip_link_target
| A target for a matching skip_link_to call
|
|
|-
| heading
| A page heading
| heading
|
|-
| box
| A page section with a border
|
|
|-
| rarrow
| A right arrow
|
|
|-
| larrow
| A left arrow
|
|
|-
| tabtree
| A list of tabs
| menu
|
|-
| tabobject
| A single tab panel
| action
|
|}

==See also==
* [[User:Sam Hemelryk/Render library element planning]]
* [[Guide to creating output elements]] ''originally written at [[User:Sam Hemelryk/Creating renderable components]]''
* [[User:Sam Hemelryk/Renderer best practices]]
* [[User:Sam Hemelryk/CSS style guidelines]]

User:Sam Hemelryk/Render library element planning

2014-06-27T02:05:56Z

Samhemelryk: /* User badge */

{{Infobox Project
|name = Renderer consistency
|state = Specification
|tracker = https://tracker.moodle.org/browse/MDL-45829
|discussion = https://moodle.org/mod/forum/discuss.php?d=261202
|assignee = Damyon, Sam
}}
{{Work in progress|forumurl=https://moodle.org/mod/forum/discuss.php?d=261202}}
This page documents the proposed core elements, variations of them, what we expect they will contain, and the core_renderer block.

==The user action==

An action in this sense is a collection of data that all pertains to one action that can be taken by the user.
The action, once populated with data can be rendered as is required for the job it is going to fulfil, usually with some relation to the frontend framework in use.
In this way the action could be a link, or a button; it could even be interpreted into a more complex structure.

An action has the following properties:
; content [string]: text content for the link or button.
; url [moodle_url] : the url for the action to take when the user interacts with this action.
; description : a description of the action. Typically used within a title or alt attribute.
; active : True if this is the action the user is current performing.
; enabled : True if the action is possible, false if it is not possible and should be shown as disabled.
; dimmed : True if the action should be shown as dimmed, usually used to the action is hidden to other users.
; method : The preferred method of submitting this action, typically GET but can be set to POST.

It is also possible to add JavaScript actions (component_action objects) to an action. These attach a JS listener to the action that gets executed when the user interacts with the action.
Attached JavaScript actions get initialised when the properties for the action are retrieved so any events must be attached BEFORE the action is rendered, and all renderers must ensure they use the get_attributes() call.

==Grids==

We need to come up with some way to include grids in core, it is desirable to keep it framework agnostic so perhaps a grid object that allows for items to be added and a "width" specified when that occurs. The width would be either a fixed number or a percentage. Steps of 12 seems pretty common.

==Design requirements==
The following concepts need to be accounted for in core, or decisions made on how we choose to support these and where.

===Clearfix===
We have this in core already, bootstrap has it, pretty much every front end framework has it.
Clearfix is more of a design decision, should only be used when require, and only ever applied by a renderer.
This gets special mention as being important, support is already 100%.

===Floats===
Pull left, pull right etc. These are a design decisions and should be implemented by the renderer. Bootstrap caters for these and as such they will be easily catered for in bootstrapbase, however work may be required to get them operational in base.

==Discarded ideas==
The following things are ideas that came up during discussions on what elements are, and what elements we want in core that have being discarded.

==Core atoms, molecules, and organisms==

The following is the atoms, molecules and organisms we believe should be created initially. Of course there will be many more that are required - however this should give us a good grounding of elements to work with for the first conversions.

===Action {atom}===
See the section above about [[#The user action]]

Actions are special atoms the represent an action the user can make.
They can be rendered by a theme as a link, a button or I suppose anything else.
There should be a default for when it is not specified and the renderer in change of producing the current thing can decide whether to use the default and just call ''render'' or if it requires something specific ''render_link'' or ''render_button'' as required.

===Action group {molecule}===
A group of actions, to be rendered to reflect a relation. I suppose the easiest way to think about this is how buttons in the atto editor are grouped together. It is a requirement that may seem a tad absrtracted and irrelevant at first but I think will pop up in several places throughout Moodle when we start converting.

It is basically a collection of actions.

'''Markup in various frontend frameworks'''

* [http://getbootstrap.com/2.3.2/components.html#buttonGroups Bootstrap 2.3.2]
* [http://getbootstrap.com/components/#btn-groups Bootstrap 3]
* [http://foundation.zurb.com/docs/components/button_groups.html Zurb foundation]

===Block {atom}===

Unique to Moodle. This represents a block on the page, and is displayed within a [[#Block region]].
It accepts two arguments, the first is a ''block_contents'' object instance, and the second is the region name the block instance is being shown within.

At present a block is rendered using the '''''core_render::block''''' method. Internally this calls several renderer methods to produce the different parts of a block.
* core_renderer::block_header - Produces a header
** core_renderer::block_controls - Produces controls to display within the header.
* core_renderer::block_content - Produces the actual content of the block.
** core_renderer::block_controls - Used to check if block controls were rendered. PUKE!!!
** core_renderer::block_footer - Produces a footer that actually resides within the content.
* core_renderer::block_annotation - Produces an annotation, used VERY rarely.

'''Current structure'''

The following is the output when called for a navigation block with a bit of extra added to show how a footer is displayed and an annotation.
<code html5>
<a href="#sb-1" class="skip-block">Skip Navigation</a>
<div id="inst4" class="block_navigation block" role="navigation" data-block="navigation" data-instanceid="4" aria-labelledby="instance-4-header" data-dockable="1">
<div class="header">
<div class="title">
<div class="block_action">

</div>
<h2 id="instance-4-header">Navigation</h2>
</div>
</div>
<div class="content">

<div class="footer">

</div>
</div>
<div class="blockannotation">

</div>
</div>
<span id="sb-1" class="skip-block-to"></span>
</code>

===Block region {molecule}===

Unique to Moodle, the block region is a contain for all of the blocks in one location.
We currently have two methods that produce a block region within Moodle, the first is '''''core_renderer::blocks_for_region''''' which adds no surrounding content.
The preferred method '''''core_renderer::blocks''''' adds some embedded information to a common structure.

'''Current structure'''

The following is the structure of the ''core_renderer::blocks()'' method.
<code php>
public function blocks($region, $classes = array(), $tag = 'aside');
</code>

The following is the html output is $region was ''pre'' and the default tag and classes were used.
<code html5>
<aside id="block-region-pre" class="block-region" data-blockregion="pre" data-droptarget="1">

</aside>
</code>

'''Thoughts on this'''

The blocks method is a convenience method and serves an important purpose. However it should not take classes and tag as arguments.<br />
These should certainly only settable within the renderer itself, and if themes wish to change this without wrapping the call they should override the renderer.

Both the data attributes relate to servicing JavaScript functionality. Perhaps they should be moved to a component_action or somehow else integrated with JS rather than with the renderer directly.

Internally it is calling blocks for region, however this should change it should request a array of blocks, convert the array to [[#Block]] elements and call render on each.

'''Proposed HTML structure'''

Much like the current structure but with the data attributes coming through a JS mechanism.

<code html5>
<aside id="block-region-pre" class="block-region">

</aside>
</code>

===Breadcrumb {molecule}===

Currently called the navbar within Moodle, controlled by the '''''navbar''''' class located in lib/navigationlib.php and rendered by '''''core_renderer::navbar()'''''.<br />
Internally it calls moodle_page->navbar->get_items() to get an array containing navigation node items to display in the navigation bar.<br />
It produces a bit of surrounding structure before calling render on each item.

'''Current structure'''

The following shows the structure for two items in the navigation bar presently within Moodle.

<code html5>
<span class="accesshide">Page path</span>
<nav class="breadcrumb-nav">
<ul class="breadcrumb">
<li>
<a href="#">Home</a>
<span class="divider">
<span class="accesshide">
<span class="arrow_text">/</span>
 
</span>
<span class="arrow sep">►</span>
</span>
</li>
<li>
<a href="#">Here</a>
<span class="divider">
<span class="accesshide">
<span class="arrow_text">/</span>
 
</span>
<span class="arrow sep">►</span>
</span>
</li>
</ul>
</nav>
</code>

Notice the excessive amount of markup to make the separator accessible.

'''Markup in various frontend frameworks'''

[http://getbootstrap.com/2.3.2/components.html#breadcrumbs Bootstrap 2.3.2]
<code html5>
<ul class="breadcrumb">
<li>
<a href="#">Home</a>
<span class="divider">/</span>
</li>
<li>
<a href="#">Here</a>
<span class="divider">/</span>
</li>
</ul>
</code>

[http://getbootstrap.com/components/#breadcrumbs Bootstrap 3]
<code html5>
<ul class="breadcrumb">
<li>
<a href="#">Home</a>
</li>
<li>
<a href="#">Here</a>
</li>
</ul>
</code>

[http://foundation.zurb.com/docs/components/breadcrumbs.html Zurb foundation]
<code html5>
<ul class="breadcrumb">
<li>
<a href="#">Home</a>
</li>
<li>
<a href="#">Here</a>
</li>
</ul>
</code>

'''Design considerations'''

* The currently active page should be marked with a class.
* The current item should probably not be a link MDL-46037
* [http://www.w3.org/TR/2007/WD-aria-role-20070601/#breadcrumbs wia-aria breadcrumb role]
* The divider perhaps could come through CSS with these changes to avoid markup necessary to make it accessible (in combination with the above).

'''Implementation thoughts'''
* Owns an array of [#Action {atoms}]

===Buttons {atom}===

This will be both an element and a representation of a [#Action {atom}].<br />
Obviously buttons can serve different purposes and roles so have several easily reachable customisations is probably a wise idea.

'''Current structure'''
None, presently you produce a button when you need it so there are several throughout Moodle.

'''Markup in various frontend frameworks'''

[http://getbootstrap.com/2.3.2/base-css.html#buttons Bootstrap 2.3.2] and [http://getbootstrap.com/css/#buttons Bootstrap 3]
<code html5>
<button type="button" class="btn btn-default">Default</button>

<a href="#" class="btn btn-default btn-lg active" role="button">Link</a>

<input class="btn btn-default" type="button" value="Input">
</code>

Customisations available through Bootstrap:
* Purposes: default, primary, success, info, warning, danger, link
* Sizes: large, default, small, extra-small
* Block level (wider)
* States: Active, disabled.

[http://foundation.zurb.com/docs/components/buttons.html Zurb foundation]
<code html5>
<a href="#" class="button">Default Button</a>
</code>

Customisations available through Zurb Foundation:
* Purposes: default, secondary, success, alert
* Sizes: large, default, small, tiny
* Corner style: radius, round
* Expanded (wider)
* States: disabled

===Calendar {organism}===

A simple idea really, apparently not already covered by the frontend frameworks being referenced during the creation of the doc.
The display of the calendar is fixed, but it can contain content for each day shown.

The calendar should have several views, perhaps these are separate organisms, perhaps not.

* Compact month
* Month
* Week
* Day

Each day could:
* Contain an action with an icon for events, and link to the fullday display.
* Have an associated action to load and display the events in a tooltip.

===Collapsible region {molecule}===

We use these in several places within Moodle. I could not find a reference to this concept in any of the frontend frameworks I looked at.
The concept is simple - you have a heading and an icon with content. By default the content is hidden, when the user clicks the heading and/or the icon the content is revealed.

As noted we do this in several places within Moodle, it would be good to have a single way of displaying this idea of a collapsible region.

'''Design thoughts'''
* It should support an optional collapse/expand all trigger action.
* We want to be able to use it both inside and outside of forms.
* It should be usable in situations like the combo list frontpage component as well.
* Will obviously have a JS component as without JS it would not work.

===Confirmation {molecule}===

A simple concept used regularly in Moodle to confirm a users intention to perform an actions. Most commonly seeing when deleting content.
The structure is relatively basic in Moodle at present.
* A message
* A forwards button
* A back button

'''Current structure'''

The method '''''core_renderer::confirm''''' does the rendering at present. Its signature is as follows:
<code php>
public function confirm($message, $continue, $cancel);
</code>

The output it produces is like:
<code html5>
<div class="generalbox" id="notice">
<p>The message goes here</p>
<div class="buttons">

</div>
</div>
</code>

'''Design throughts'''

This component does not have a title. I believe at present some pages use ''core_renderer::heading'' to produce a title if they wish. Obviously we want consistency of style so I believe it would be wise to add a title property that can be optionally set and then in our documentation for this element recommend that a title is always provided.<br />
It will mean re-factoring our uses to set a title and if a heading is being manually added remove it.

===Continue {molecule}===

This is much like the confirmation molecule but with a single button.<br />
At present we have '''''core_renderer::continue_button''''' that produces a single button. However this design is very poor as more often than not a message is included in the page to describe the purpose of the continue button. This is really an integral part of the continue button.

'''Current structure'''

Currently we have ''core_renderer::continue_button'' to render a single continue button.
<code php>
public function continue_button($url);
</code>

Internally it creates a single_button component and then calls render on that.

'''Design thoughts'''
Our element should have a message and a button. To make it easy to migrate the constructor should accept a URL instead of a button and do the same conversion as the current method is doing.

===Choice {molecule}===
Not sure about this one quite yet.
A description with 2 or more actions allowing the user to select the next step.
Think of it like when editing a module you get: Cancel, Save and return to course, Save and display

Perhaps both [#Confirmation {molecule}] and [#Continue {molecule}] should be just instances of this.

Hmm perhaps that would not be as clear as this and we should have this separate choice molecule.

===Divider {atom}===
Think horizontal rule.

===Dropdowns {molecule}===

So this is a pretty simple concept, but you've got to think of it as a separate entity. A dropdown is a menu that appears when the user interacts with an action.

The action could take one of three forms:
* From button
* From link
* From icon

Of course that is handled by the [#Action {atom}] noted above. Worth noting is that we will need some way to toggle these actions as dropdowns. Perhaps it is worth making that a property of the action atom.

The dropdown itself will likely contain more actions, and I suppose additional dropdowns to form sub menus. Sub-menus in my mind are required. We don't use them in core, but they are functionally possible through things like the custom menu and I know for a fact that many sites have sub menus.

'''Markup in various frontend frameworks'''

[http://getbootstrap.com/2.3.2/components.html#dropdowns Bootstrap 2.3.2]

<code html5>
<div class="dropdown">

<ul class="dropdown-menu" role="menu" aria-labelledby="dLabel">
<li><a tabindex="-1" href="#">Action</a></li>
<li><a tabindex="-1" href="#">Another action</a></li>
<li><a tabindex="-1" href="#">Something else here</a></li>
<li class="divider"></li>
<li><a tabindex="-1" href="#">Separated link</a></li>
</ul>
</div>
</code>

[http://getbootstrap.com/components/#dropdowns Bootstrap 3]
<code html5>
<div class="dropdown">
<button class="btn dropdown-toggle sr-only" type="button" id="dropdownMenu1" data-toggle="dropdown">
Dropdown
<span class="caret"></span>
</button>
<ul class="dropdown-menu" role="menu" aria-labelledby="dropdownMenu1">
<li role="presentation"><a role="menuitem" tabindex="-1" href="#">Action</a></li>
<li role="presentation"><a role="menuitem" tabindex="-1" href="#">Another action</a></li>
<li role="presentation"><a role="menuitem" tabindex="-1" href="#">Something else here</a></li>
<li role="presentation" class="divider"></li>
<li role="presentation"><a role="menuitem" tabindex="-1" href="#">Separated link</a></li>
</ul>
</div>
</code>

[http://foundation.zurb.com/docs/components/dropdown.html Zurb foundation]
<code html5>
<a href="#" data-dropdown="drop1">Has Dropdown</a>
<ul id="drop1" class="f-dropdown" data-dropdown-content>
<li><a href="#">This is a link</a></li>
<li><a href="#">This is another</a></li>
<li><a href="#">Yet another</a></li>
</ul>
</code>

===Forms {organism}===

This is an advanced organism and would be quite a bit of work to create in Moodle as we'd need to translate from QuickForms to elements for rendering.
It would be worthwhile doing this however, and would be a good way of quickly showing our new work.

'''Frontend framework structures'''
* [http://getbootstrap.com/2.3.2/base-css.html#forms Bootstrap 2.3.2]
* [http://getbootstrap.com/css/#forms Bootstrap 3]
* [http://foundation.zurb.com/docs/components/forms.html Zurb foundation]

All of those are quite in-depth and offer a range of configurations.
We should carefully consider these when analysing our work here.

===Headings {atom}===

Currently handled by '''core_renderer::heading'''.

* h1 - h6
* Optional icon
* Optional help icon

'''Current structure'''

The render method is currently:
<code php>
public function heading($text, $level = 2, $classes = null, $id = null);
</code>

The output generated by this is, assuming we use the default level, classes, and id.
<code html5>
<h2>I am a heading</h2>
</code>

Whats worth noting is that the render method should not accept level and classes as arguments.
These should only be set by the render method and should not be directly influenced.

===Image {atom}===

There are really two types of images to focus on here, or really two ways to display an image to focus on here.<br />
# Standard images
# Thumbnail images

Each of these would share some common properties:
* Image
* Description (alt/title)
* Size
* Action (making it a link) - This would actually make it a molecule, we would have to consider this and either have a new element, drop the ability to wrap in an action, or simply ignore this inconsistency.

===Image - Icon {atom}===

This covers the display of an icon. Should be a separate element from image as really they should be treated individually.
Within Moodle there are a few classifications of icons to consider:
* Standard icons
* Help icon (popup, tooltip)
* Loading icon (really regular icon but worth showing separately as its only seen when required)

===Image - Logo {molecule}===

We don't have this within core Moodle at present, however just about every theme I have seen uses a logo. I think it is about time we considered having a logo element.
I imagine it would become a sort of hero element, likely with an associated action (back home by default).

===Image - Profile picture {molecule}===

We already have a user_picture component within Moodle. It can be found in lib/outputcomponents.php.<br />
It has two render methods, '''''core_renderer::user_picture''''' and '''''core_renderer::render_user_picture'''''.

'''Current structure'''

The following is the output structure for the user picture:
<code html5>
<a href="#" id="userpicture_randomid">
<img src="#" alt="Picture of Joe" title="Picture of Joe" class="userpicture" width="[35, 100, XX]" height="[35, 100, XX]" />
</a>
</code>

What you'll notice about this is that the link has no attributes marking it as a user picture link.

The PHP code for the user_picture object itself is really quite in depth and complex. The component serves the user profile fields required to render a user picture. This is good in the scope of the component but would be bad within the scope of an element.<br />
Don't you wish we had a proper user object!

===Link {atom}===
This will be both an element and a representation of a [#Action {atom}].

Theres not too much more to explain about links, they don't tend to take states other than the default active, enabled and dimmed.<br />
It is worth mentioning that devs will be encouraged to use actions and not links unless absolutely necessary.<br />
The render method for this atom must typehint an action rather than a link.

'''Prototype example'''
* The atom: https://github.com/samhemelryk/moodle/blob/output_prototype_5/local/output/classes/output/link.php
* The convenience method: https://github.com/samhemelryk/moodle/blob/output_prototype_5/local/output/classes/output/renderer.php#L149
* The render method: https://github.com/samhemelryk/moodle/blob/output_prototype_5/local/output/classes/output/renderer.php#L211

===List {molecule}===

This is a pretty simple example and something I am sure you are all familiar with. A list is simply a collection of items. Usually represented using a UL or OL tag in markup although worth noting can be styled completely differently to the default.
There are three main types of lists used within Moodle:
* Ordered list
* Unordered list
* Presentation list (currently our unlist)

The list is a molecule because it should be able to accept other elements as items. E.g. it should be content independent.

===Menu {molecule}===

A menu is a familiar concept for any site. Probably the first thing that pops to mind for many is the navbar, but I want to consider that a separate component as a navbar can consist of more than just menu items.
I think a menu should be a collection of actions the user can perform. Perhaps with some form of hierarchy.

We have different types of menus within Moodle:
* The custom menu is one users can directly create, with dropdown downs and sub dropdowns.
* The action_menu component we have in core uses icons as actions and can have a dropdown.

These should be combined into a single menu element that takes items as an argument, likely actions + dropdowns + dividers to start with would be perfect.

We would likely need to deal with the display of the menu with properties to allow constructing code to ''request'' a particular style of menu. The renderer should be what actually gets to decide, but for the purposes of re-use having properties and a single render_method is better than having multiple render methods.<br />
The following is my initial thoughts on menu structure:
* Direction: Horizontal, Vertical
* Design: Default, Tabs,
* Style: Default, Links, Buttons, Icons

===Notification {atom}===
* Info
* Success
* Warning
* Danger

===Navigation bar {organism}===
Formerly navbar, can't be called that because the render method would conflict.

The navigation bar is just that, it is becoming increasingly common on the web and usually contains a title or logo, a menu, and information pertaining to the user state (login, language etc).

===Page header {molecule}===

Currently being produced by '''core_renderer::page_heading''' this is simply a header for the page, by default the only h1 element on the page.

'''Current structure'''

The render method has the following signature:
<code php>
public function page_heading($tag = 'h1');
</code>

The output from the above method is:
<code html5>
<h1>The page heading (from moodle_page::heading)</h1>
</code>

The core_renderer method should not allow the tag to be set. The page heading should always be H1.
If its not an H1 then page header should not be used.

'''Frontend framework examples'''

[http://getbootstrap.com/2.3.2/components.html#typography Bootstrap 2.3.2]
<code html5>
<div class="hero-unit">
<h1>Heading</h1>
<p>Tagline</p>
<p>
<a class="btn btn-primary btn-large">
Learn more
</a>
</p>
</div>
</code>

[http://getbootstrap.com/components/#page-header Bootstrap 3]
<code html5>
<div class="page-header">
<h1>Example page header <small>Subtext for header</small></h1>
</div>
</code>

Foundation doesn't appear to have a page header component.

'''Design thoughts'''

* In Moodle all page headings are set as a single string, we won't be changing this.
* Usually just a plain string sometimes an icon is used, and sometimes a help icon is used.

===Pagination {molecule}===

I like the idea of this being separate to a menu, and to other navigation oriented elements because it should be something that can easily be constructed with a few basic parameters and allow us to achieve consistent pagination throughout Moodle.<br />
It also appeals because this is something that people may want to style differently to their navigation.

'''Markup in various frontend frameworks'''

* [http://getbootstrap.com/2.3.2/components.html#pagination Bootstrap 2.3.2 pagination]
* [http://getbootstrap.com/components/#pagination Bootstrap 3 pagination]
* [http://foundation.zurb.com/docs/components/pagination.html Zurb foundation pagination]

===Progress bars {molecule}===

A pretty simple concept, we already have a couple of ways of producing progress bars within Moodle.

'''Markup in various frontend frameworks'''

[http://getbootstrap.com/2.3.2/components.html#progress Bootstrap 2.3.2]
<code html5>
<div class="progress">
<div class="bar" style="width: 60%;"></div>
</div>
</code>

The following options are offered by Bootstrap 2.3.2:

* Striped
* Striped + Animated
* Stacked (multiple bars forming a single)
* Colours: default (blue), info (light blue), success (green), warning (orange), danger (red)

[http://getbootstrap.com/components/#progress Bootstrap 3]
<code html5>

<div class="progress">
<div class="progress-bar" role="progressbar" aria-valuenow="60" aria-valuemin="0" aria-valuemax="100" style="width: 60%;">
60% Complete
</div>
</div>


<div class="progress">
<div class="progress-bar" role="progressbar" aria-valuenow="60" aria-valuemin="0" aria-valuemax="100" style="width: 60%;">
60%
</div>
</div>
</code>

The following options are offered by Bootstrap 3:

* Striped
* Striped + Animated
* Stacked (multiple bars forming a single)
* Colours: default (blue), info (light blue), success (green), warning (orange), danger (red)

[http://foundation.zurb.com/docs/components/progress_bars.html Zurb foundation]

<code html5>
<div class="progress">
<span class="meter"></span>
</div>
</code>

The following options are offered by Zurb foundation:
* Width
* Colours: default (blue), secondary (grey), success (green), alert (red)
* Corner style: default (square), radius (slight rounding), round

===Search {molecule}===

A pretty common interface molecule, and in fact used as an example in the atomic design blog post we keep referencing.<br />
We don't have a component for searching yet, however we've several search boxes throughout Moodle. The admin setting search box is the first to come to mind for me, followed by the forum search box and course search box.

'''Design considerations'''

Constructed of the following items:
* Text input
* Action (must be a button for submit I imagine)
* Label or short description (optional)
* Collapsible region containing settings etc (optional)

===Table {organism}===

We've two primary table components within Moodle presently '''html_table''' and '''flexible_table''' both of which offer different advantages and disadvantages. This will be a challenge and will really require some proper research and community interaction.

===Timer {atom|molecule}===

... not sure about this one, but we do use it in a couple of places, and we use it on all core sites that have hourly resets so in a way it makes sense to support it and allow it to be styled nicely and easily.

===Tree {organism}===

===User content===

Think of this like the forum post. We need a common structure in which to display content entered by the user along with information on the user. The users name, picture, date perhaps, title, content, footer (attachments, badges, what ever).
It could be applied to things like forum posts, calendar events etc.

At present we have no abstraction for this.

==Existing renderables and what they will become==
{| class="wikitable"
! Existing renderable
! Description
! Future renderable
! Convenience method (if different)
|-
| action_menu
| UI component for a drop down edit menu
| menu
|
|-
| action_menu_link
| UI component for a menu item in an action menu
| action
|
|-
| action_menu_filler
| UI component for a filler menu item in an action menu
| action
|
|-
| action_menu_link_primary
| UI component for a primary menu item in an action menu
| action
|
|-
| action_menu_link_secondary
| UI component for a secondary menu item in an action menu
| action
|
|-
| action_link
| Link with alt text, and an icon
| action
|
|-
| single_button
| A form with a single button
| button (action with post method)
|
|-
| confirm
| A form with a message and cancel/confirm buttons
| confirmation
|
|-
| single_select
| A form with a single drop down list that submits on change
|
|
|-
| url_select
| A navigation element consisting of a single drop down list of urls that navigates on change
|
|
|-
| doc_link
| A link to the Moodle docs
|
|
|-
| pix_icon
| A small icon
| icon
|
|-
| emoticon_icon
| A small emoticon
|
|
|-
| heading_with_help
| A page heading with a link to help docs
| heading
|
|-
| help_icon
| A help icon that opens a help popup when clicked
| icon_help
|
|-
| help_icon_scale
| A help icon that opens a help popup when clicked
|
|
|-
| user_picture
| A user profile picture which links to their profile
|
|
|-
| container
| A block level element used to surround something. Can have a class to allow specific targeting with CSS.
|
|
|-
| error_text
| An error to show to the user.
|
|
|-
| notification
| A message for the user
|
|
|-
| continue_button
| A message and a button to continue to the next page
|
|
|-
| paging_bar
| A list of next previous and specific page links
|
|
|-
| skip_link_to
| A link to a section on the page
|
|
|-
| skip_link_target
| A target for a matching skip_link_to call
|
|
|-
| heading
| A page heading
| heading
|
|-
| box
| A page section with a border
|
|
|-
| rarrow
| A right arrow
|
|
|-
| larrow
| A left arrow
|
|
|-
| tabtree
| A list of tabs
| menu
|
|-
| tabobject
| A single tab panel
| action
|
|}

==See also==
* [[User:Sam Hemelryk/Render library element planning]]
* [[Guide to creating output elements]] ''originally written at [[User:Sam Hemelryk/Creating renderable components]]''
* [[User:Sam Hemelryk/Renderer best practices]]
* [[User:Sam Hemelryk/CSS style guidelines]]

User:Sam Hemelryk/Render library element planning

2014-06-27T02:05:40Z

Samhemelryk: /* Tree */

{{Infobox Project
|name = Renderer consistency
|state = Specification
|tracker = https://tracker.moodle.org/browse/MDL-45829
|discussion = https://moodle.org/mod/forum/discuss.php?d=261202
|assignee = Damyon, Sam
}}
{{Work in progress|forumurl=https://moodle.org/mod/forum/discuss.php?d=261202}}
This page documents the proposed core elements, variations of them, what we expect they will contain, and the core_renderer block.

==The user action==

An action in this sense is a collection of data that all pertains to one action that can be taken by the user.
The action, once populated with data can be rendered as is required for the job it is going to fulfil, usually with some relation to the frontend framework in use.
In this way the action could be a link, or a button; it could even be interpreted into a more complex structure.

An action has the following properties:
; content [string]: text content for the link or button.
; url [moodle_url] : the url for the action to take when the user interacts with this action.
; description : a description of the action. Typically used within a title or alt attribute.
; active : True if this is the action the user is current performing.
; enabled : True if the action is possible, false if it is not possible and should be shown as disabled.
; dimmed : True if the action should be shown as dimmed, usually used to the action is hidden to other users.
; method : The preferred method of submitting this action, typically GET but can be set to POST.

It is also possible to add JavaScript actions (component_action objects) to an action. These attach a JS listener to the action that gets executed when the user interacts with the action.
Attached JavaScript actions get initialised when the properties for the action are retrieved so any events must be attached BEFORE the action is rendered, and all renderers must ensure they use the get_attributes() call.

==Grids==

We need to come up with some way to include grids in core, it is desirable to keep it framework agnostic so perhaps a grid object that allows for items to be added and a "width" specified when that occurs. The width would be either a fixed number or a percentage. Steps of 12 seems pretty common.

==Design requirements==
The following concepts need to be accounted for in core, or decisions made on how we choose to support these and where.

===Clearfix===
We have this in core already, bootstrap has it, pretty much every front end framework has it.
Clearfix is more of a design decision, should only be used when require, and only ever applied by a renderer.
This gets special mention as being important, support is already 100%.

===Floats===
Pull left, pull right etc. These are a design decisions and should be implemented by the renderer. Bootstrap caters for these and as such they will be easily catered for in bootstrapbase, however work may be required to get them operational in base.

==Discarded ideas==
The following things are ideas that came up during discussions on what elements are, and what elements we want in core that have being discarded.

==Core atoms, molecules, and organisms==

The following is the atoms, molecules and organisms we believe should be created initially. Of course there will be many more that are required - however this should give us a good grounding of elements to work with for the first conversions.

===Action {atom}===
See the section above about [[#The user action]]

Actions are special atoms the represent an action the user can make.
They can be rendered by a theme as a link, a button or I suppose anything else.
There should be a default for when it is not specified and the renderer in change of producing the current thing can decide whether to use the default and just call ''render'' or if it requires something specific ''render_link'' or ''render_button'' as required.

===Action group {molecule}===
A group of actions, to be rendered to reflect a relation. I suppose the easiest way to think about this is how buttons in the atto editor are grouped together. It is a requirement that may seem a tad absrtracted and irrelevant at first but I think will pop up in several places throughout Moodle when we start converting.

It is basically a collection of actions.

'''Markup in various frontend frameworks'''

* [http://getbootstrap.com/2.3.2/components.html#buttonGroups Bootstrap 2.3.2]
* [http://getbootstrap.com/components/#btn-groups Bootstrap 3]
* [http://foundation.zurb.com/docs/components/button_groups.html Zurb foundation]

===Block {atom}===

Unique to Moodle. This represents a block on the page, and is displayed within a [[#Block region]].
It accepts two arguments, the first is a ''block_contents'' object instance, and the second is the region name the block instance is being shown within.

At present a block is rendered using the '''''core_render::block''''' method. Internally this calls several renderer methods to produce the different parts of a block.
* core_renderer::block_header - Produces a header
** core_renderer::block_controls - Produces controls to display within the header.
* core_renderer::block_content - Produces the actual content of the block.
** core_renderer::block_controls - Used to check if block controls were rendered. PUKE!!!
** core_renderer::block_footer - Produces a footer that actually resides within the content.
* core_renderer::block_annotation - Produces an annotation, used VERY rarely.

'''Current structure'''

The following is the output when called for a navigation block with a bit of extra added to show how a footer is displayed and an annotation.
<code html5>
<a href="#sb-1" class="skip-block">Skip Navigation</a>
<div id="inst4" class="block_navigation block" role="navigation" data-block="navigation" data-instanceid="4" aria-labelledby="instance-4-header" data-dockable="1">
<div class="header">
<div class="title">
<div class="block_action">

</div>
<h2 id="instance-4-header">Navigation</h2>
</div>
</div>
<div class="content">

<div class="footer">

</div>
</div>
<div class="blockannotation">

</div>
</div>
<span id="sb-1" class="skip-block-to"></span>
</code>

===Block region {molecule}===

Unique to Moodle, the block region is a contain for all of the blocks in one location.
We currently have two methods that produce a block region within Moodle, the first is '''''core_renderer::blocks_for_region''''' which adds no surrounding content.
The preferred method '''''core_renderer::blocks''''' adds some embedded information to a common structure.

'''Current structure'''

The following is the structure of the ''core_renderer::blocks()'' method.
<code php>
public function blocks($region, $classes = array(), $tag = 'aside');
</code>

The following is the html output is $region was ''pre'' and the default tag and classes were used.
<code html5>
<aside id="block-region-pre" class="block-region" data-blockregion="pre" data-droptarget="1">

</aside>
</code>

'''Thoughts on this'''

The blocks method is a convenience method and serves an important purpose. However it should not take classes and tag as arguments.<br />
These should certainly only settable within the renderer itself, and if themes wish to change this without wrapping the call they should override the renderer.

Both the data attributes relate to servicing JavaScript functionality. Perhaps they should be moved to a component_action or somehow else integrated with JS rather than with the renderer directly.

Internally it is calling blocks for region, however this should change it should request a array of blocks, convert the array to [[#Block]] elements and call render on each.

'''Proposed HTML structure'''

Much like the current structure but with the data attributes coming through a JS mechanism.

<code html5>
<aside id="block-region-pre" class="block-region">

</aside>
</code>

===Breadcrumb {molecule}===

Currently called the navbar within Moodle, controlled by the '''''navbar''''' class located in lib/navigationlib.php and rendered by '''''core_renderer::navbar()'''''.<br />
Internally it calls moodle_page->navbar->get_items() to get an array containing navigation node items to display in the navigation bar.<br />
It produces a bit of surrounding structure before calling render on each item.

'''Current structure'''

The following shows the structure for two items in the navigation bar presently within Moodle.

<code html5>
<span class="accesshide">Page path</span>
<nav class="breadcrumb-nav">
<ul class="breadcrumb">
<li>
<a href="#">Home</a>
<span class="divider">
<span class="accesshide">
<span class="arrow_text">/</span>
 
</span>
<span class="arrow sep">►</span>
</span>
</li>
<li>
<a href="#">Here</a>
<span class="divider">
<span class="accesshide">
<span class="arrow_text">/</span>
 
</span>
<span class="arrow sep">►</span>
</span>
</li>
</ul>
</nav>
</code>

Notice the excessive amount of markup to make the separator accessible.

'''Markup in various frontend frameworks'''

[http://getbootstrap.com/2.3.2/components.html#breadcrumbs Bootstrap 2.3.2]
<code html5>
<ul class="breadcrumb">
<li>
<a href="#">Home</a>
<span class="divider">/</span>
</li>
<li>
<a href="#">Here</a>
<span class="divider">/</span>
</li>
</ul>
</code>

[http://getbootstrap.com/components/#breadcrumbs Bootstrap 3]
<code html5>
<ul class="breadcrumb">
<li>
<a href="#">Home</a>
</li>
<li>
<a href="#">Here</a>
</li>
</ul>
</code>

[http://foundation.zurb.com/docs/components/breadcrumbs.html Zurb foundation]
<code html5>
<ul class="breadcrumb">
<li>
<a href="#">Home</a>
</li>
<li>
<a href="#">Here</a>
</li>
</ul>
</code>

'''Design considerations'''

* The currently active page should be marked with a class.
* The current item should probably not be a link MDL-46037
* [http://www.w3.org/TR/2007/WD-aria-role-20070601/#breadcrumbs wia-aria breadcrumb role]
* The divider perhaps could come through CSS with these changes to avoid markup necessary to make it accessible (in combination with the above).

'''Implementation thoughts'''
* Owns an array of [#Action {atoms}]

===Buttons {atom}===

This will be both an element and a representation of a [#Action {atom}].<br />
Obviously buttons can serve different purposes and roles so have several easily reachable customisations is probably a wise idea.

'''Current structure'''
None, presently you produce a button when you need it so there are several throughout Moodle.

'''Markup in various frontend frameworks'''

[http://getbootstrap.com/2.3.2/base-css.html#buttons Bootstrap 2.3.2] and [http://getbootstrap.com/css/#buttons Bootstrap 3]
<code html5>
<button type="button" class="btn btn-default">Default</button>

<a href="#" class="btn btn-default btn-lg active" role="button">Link</a>

<input class="btn btn-default" type="button" value="Input">
</code>

Customisations available through Bootstrap:
* Purposes: default, primary, success, info, warning, danger, link
* Sizes: large, default, small, extra-small
* Block level (wider)
* States: Active, disabled.

[http://foundation.zurb.com/docs/components/buttons.html Zurb foundation]
<code html5>
<a href="#" class="button">Default Button</a>
</code>

Customisations available through Zurb Foundation:
* Purposes: default, secondary, success, alert
* Sizes: large, default, small, tiny
* Corner style: radius, round
* Expanded (wider)
* States: disabled

===Calendar {organism}===

A simple idea really, apparently not already covered by the frontend frameworks being referenced during the creation of the doc.
The display of the calendar is fixed, but it can contain content for each day shown.

The calendar should have several views, perhaps these are separate organisms, perhaps not.

* Compact month
* Month
* Week
* Day

Each day could:
* Contain an action with an icon for events, and link to the fullday display.
* Have an associated action to load and display the events in a tooltip.

===Collapsible region {molecule}===

We use these in several places within Moodle. I could not find a reference to this concept in any of the frontend frameworks I looked at.
The concept is simple - you have a heading and an icon with content. By default the content is hidden, when the user clicks the heading and/or the icon the content is revealed.

As noted we do this in several places within Moodle, it would be good to have a single way of displaying this idea of a collapsible region.

'''Design thoughts'''
* It should support an optional collapse/expand all trigger action.
* We want to be able to use it both inside and outside of forms.
* It should be usable in situations like the combo list frontpage component as well.
* Will obviously have a JS component as without JS it would not work.

===Confirmation {molecule}===

A simple concept used regularly in Moodle to confirm a users intention to perform an actions. Most commonly seeing when deleting content.
The structure is relatively basic in Moodle at present.
* A message
* A forwards button
* A back button

'''Current structure'''

The method '''''core_renderer::confirm''''' does the rendering at present. Its signature is as follows:
<code php>
public function confirm($message, $continue, $cancel);
</code>

The output it produces is like:
<code html5>
<div class="generalbox" id="notice">
<p>The message goes here</p>
<div class="buttons">

</div>
</div>
</code>

'''Design throughts'''

This component does not have a title. I believe at present some pages use ''core_renderer::heading'' to produce a title if they wish. Obviously we want consistency of style so I believe it would be wise to add a title property that can be optionally set and then in our documentation for this element recommend that a title is always provided.<br />
It will mean re-factoring our uses to set a title and if a heading is being manually added remove it.

===Continue {molecule}===

This is much like the confirmation molecule but with a single button.<br />
At present we have '''''core_renderer::continue_button''''' that produces a single button. However this design is very poor as more often than not a message is included in the page to describe the purpose of the continue button. This is really an integral part of the continue button.

'''Current structure'''

Currently we have ''core_renderer::continue_button'' to render a single continue button.
<code php>
public function continue_button($url);
</code>

Internally it creates a single_button component and then calls render on that.

'''Design thoughts'''
Our element should have a message and a button. To make it easy to migrate the constructor should accept a URL instead of a button and do the same conversion as the current method is doing.

===Choice {molecule}===
Not sure about this one quite yet.
A description with 2 or more actions allowing the user to select the next step.
Think of it like when editing a module you get: Cancel, Save and return to course, Save and display

Perhaps both [#Confirmation {molecule}] and [#Continue {molecule}] should be just instances of this.

Hmm perhaps that would not be as clear as this and we should have this separate choice molecule.

===Divider {atom}===
Think horizontal rule.

===Dropdowns {molecule}===

So this is a pretty simple concept, but you've got to think of it as a separate entity. A dropdown is a menu that appears when the user interacts with an action.

The action could take one of three forms:
* From button
* From link
* From icon

Of course that is handled by the [#Action {atom}] noted above. Worth noting is that we will need some way to toggle these actions as dropdowns. Perhaps it is worth making that a property of the action atom.

The dropdown itself will likely contain more actions, and I suppose additional dropdowns to form sub menus. Sub-menus in my mind are required. We don't use them in core, but they are functionally possible through things like the custom menu and I know for a fact that many sites have sub menus.

'''Markup in various frontend frameworks'''

[http://getbootstrap.com/2.3.2/components.html#dropdowns Bootstrap 2.3.2]

<code html5>
<div class="dropdown">

<ul class="dropdown-menu" role="menu" aria-labelledby="dLabel">
<li><a tabindex="-1" href="#">Action</a></li>
<li><a tabindex="-1" href="#">Another action</a></li>
<li><a tabindex="-1" href="#">Something else here</a></li>
<li class="divider"></li>
<li><a tabindex="-1" href="#">Separated link</a></li>
</ul>
</div>
</code>

[http://getbootstrap.com/components/#dropdowns Bootstrap 3]
<code html5>
<div class="dropdown">
<button class="btn dropdown-toggle sr-only" type="button" id="dropdownMenu1" data-toggle="dropdown">
Dropdown
<span class="caret"></span>
</button>
<ul class="dropdown-menu" role="menu" aria-labelledby="dropdownMenu1">
<li role="presentation"><a role="menuitem" tabindex="-1" href="#">Action</a></li>
<li role="presentation"><a role="menuitem" tabindex="-1" href="#">Another action</a></li>
<li role="presentation"><a role="menuitem" tabindex="-1" href="#">Something else here</a></li>
<li role="presentation" class="divider"></li>
<li role="presentation"><a role="menuitem" tabindex="-1" href="#">Separated link</a></li>
</ul>
</div>
</code>

[http://foundation.zurb.com/docs/components/dropdown.html Zurb foundation]
<code html5>
<a href="#" data-dropdown="drop1">Has Dropdown</a>
<ul id="drop1" class="f-dropdown" data-dropdown-content>
<li><a href="#">This is a link</a></li>
<li><a href="#">This is another</a></li>
<li><a href="#">Yet another</a></li>
</ul>
</code>

===Forms {organism}===

This is an advanced organism and would be quite a bit of work to create in Moodle as we'd need to translate from QuickForms to elements for rendering.
It would be worthwhile doing this however, and would be a good way of quickly showing our new work.

'''Frontend framework structures'''
* [http://getbootstrap.com/2.3.2/base-css.html#forms Bootstrap 2.3.2]
* [http://getbootstrap.com/css/#forms Bootstrap 3]
* [http://foundation.zurb.com/docs/components/forms.html Zurb foundation]

All of those are quite in-depth and offer a range of configurations.
We should carefully consider these when analysing our work here.

===Headings {atom}===

Currently handled by '''core_renderer::heading'''.

* h1 - h6
* Optional icon
* Optional help icon

'''Current structure'''

The render method is currently:
<code php>
public function heading($text, $level = 2, $classes = null, $id = null);
</code>

The output generated by this is, assuming we use the default level, classes, and id.
<code html5>
<h2>I am a heading</h2>
</code>

Whats worth noting is that the render method should not accept level and classes as arguments.
These should only be set by the render method and should not be directly influenced.

===Image {atom}===

There are really two types of images to focus on here, or really two ways to display an image to focus on here.<br />
# Standard images
# Thumbnail images

Each of these would share some common properties:
* Image
* Description (alt/title)
* Size
* Action (making it a link) - This would actually make it a molecule, we would have to consider this and either have a new element, drop the ability to wrap in an action, or simply ignore this inconsistency.

===Image - Icon {atom}===

This covers the display of an icon. Should be a separate element from image as really they should be treated individually.
Within Moodle there are a few classifications of icons to consider:
* Standard icons
* Help icon (popup, tooltip)
* Loading icon (really regular icon but worth showing separately as its only seen when required)

===Image - Logo {molecule}===

We don't have this within core Moodle at present, however just about every theme I have seen uses a logo. I think it is about time we considered having a logo element.
I imagine it would become a sort of hero element, likely with an associated action (back home by default).

===Image - Profile picture {molecule}===

We already have a user_picture component within Moodle. It can be found in lib/outputcomponents.php.<br />
It has two render methods, '''''core_renderer::user_picture''''' and '''''core_renderer::render_user_picture'''''.

'''Current structure'''

The following is the output structure for the user picture:
<code html5>
<a href="#" id="userpicture_randomid">
<img src="#" alt="Picture of Joe" title="Picture of Joe" class="userpicture" width="[35, 100, XX]" height="[35, 100, XX]" />
</a>
</code>

What you'll notice about this is that the link has no attributes marking it as a user picture link.

The PHP code for the user_picture object itself is really quite in depth and complex. The component serves the user profile fields required to render a user picture. This is good in the scope of the component but would be bad within the scope of an element.<br />
Don't you wish we had a proper user object!

===Link {atom}===
This will be both an element and a representation of a [#Action {atom}].

Theres not too much more to explain about links, they don't tend to take states other than the default active, enabled and dimmed.<br />
It is worth mentioning that devs will be encouraged to use actions and not links unless absolutely necessary.<br />
The render method for this atom must typehint an action rather than a link.

'''Prototype example'''
* The atom: https://github.com/samhemelryk/moodle/blob/output_prototype_5/local/output/classes/output/link.php
* The convenience method: https://github.com/samhemelryk/moodle/blob/output_prototype_5/local/output/classes/output/renderer.php#L149
* The render method: https://github.com/samhemelryk/moodle/blob/output_prototype_5/local/output/classes/output/renderer.php#L211

===List {molecule}===

This is a pretty simple example and something I am sure you are all familiar with. A list is simply a collection of items. Usually represented using a UL or OL tag in markup although worth noting can be styled completely differently to the default.
There are three main types of lists used within Moodle:
* Ordered list
* Unordered list
* Presentation list (currently our unlist)

The list is a molecule because it should be able to accept other elements as items. E.g. it should be content independent.

===Menu {molecule}===

A menu is a familiar concept for any site. Probably the first thing that pops to mind for many is the navbar, but I want to consider that a separate component as a navbar can consist of more than just menu items.
I think a menu should be a collection of actions the user can perform. Perhaps with some form of hierarchy.

We have different types of menus within Moodle:
* The custom menu is one users can directly create, with dropdown downs and sub dropdowns.
* The action_menu component we have in core uses icons as actions and can have a dropdown.

These should be combined into a single menu element that takes items as an argument, likely actions + dropdowns + dividers to start with would be perfect.

We would likely need to deal with the display of the menu with properties to allow constructing code to ''request'' a particular style of menu. The renderer should be what actually gets to decide, but for the purposes of re-use having properties and a single render_method is better than having multiple render methods.<br />
The following is my initial thoughts on menu structure:
* Direction: Horizontal, Vertical
* Design: Default, Tabs,
* Style: Default, Links, Buttons, Icons

===Notification {atom}===
* Info
* Success
* Warning
* Danger

===Navigation bar {organism}===
Formerly navbar, can't be called that because the render method would conflict.

The navigation bar is just that, it is becoming increasingly common on the web and usually contains a title or logo, a menu, and information pertaining to the user state (login, language etc).

===Page header {molecule}===

Currently being produced by '''core_renderer::page_heading''' this is simply a header for the page, by default the only h1 element on the page.

'''Current structure'''

The render method has the following signature:
<code php>
public function page_heading($tag = 'h1');
</code>

The output from the above method is:
<code html5>
<h1>The page heading (from moodle_page::heading)</h1>
</code>

The core_renderer method should not allow the tag to be set. The page heading should always be H1.
If its not an H1 then page header should not be used.

'''Frontend framework examples'''

[http://getbootstrap.com/2.3.2/components.html#typography Bootstrap 2.3.2]
<code html5>
<div class="hero-unit">
<h1>Heading</h1>
<p>Tagline</p>
<p>
<a class="btn btn-primary btn-large">
Learn more
</a>
</p>
</div>
</code>

[http://getbootstrap.com/components/#page-header Bootstrap 3]
<code html5>
<div class="page-header">
<h1>Example page header <small>Subtext for header</small></h1>
</div>
</code>

Foundation doesn't appear to have a page header component.

'''Design thoughts'''

* In Moodle all page headings are set as a single string, we won't be changing this.
* Usually just a plain string sometimes an icon is used, and sometimes a help icon is used.

===Pagination {molecule}===

I like the idea of this being separate to a menu, and to other navigation oriented elements because it should be something that can easily be constructed with a few basic parameters and allow us to achieve consistent pagination throughout Moodle.<br />
It also appeals because this is something that people may want to style differently to their navigation.

'''Markup in various frontend frameworks'''

* [http://getbootstrap.com/2.3.2/components.html#pagination Bootstrap 2.3.2 pagination]
* [http://getbootstrap.com/components/#pagination Bootstrap 3 pagination]
* [http://foundation.zurb.com/docs/components/pagination.html Zurb foundation pagination]

===Progress bars {molecule}===

A pretty simple concept, we already have a couple of ways of producing progress bars within Moodle.

'''Markup in various frontend frameworks'''

[http://getbootstrap.com/2.3.2/components.html#progress Bootstrap 2.3.2]
<code html5>
<div class="progress">
<div class="bar" style="width: 60%;"></div>
</div>
</code>

The following options are offered by Bootstrap 2.3.2:

* Striped
* Striped + Animated
* Stacked (multiple bars forming a single)
* Colours: default (blue), info (light blue), success (green), warning (orange), danger (red)

[http://getbootstrap.com/components/#progress Bootstrap 3]
<code html5>

<div class="progress">
<div class="progress-bar" role="progressbar" aria-valuenow="60" aria-valuemin="0" aria-valuemax="100" style="width: 60%;">
60% Complete
</div>
</div>


<div class="progress">
<div class="progress-bar" role="progressbar" aria-valuenow="60" aria-valuemin="0" aria-valuemax="100" style="width: 60%;">
60%
</div>
</div>
</code>

The following options are offered by Bootstrap 3:

* Striped
* Striped + Animated
* Stacked (multiple bars forming a single)
* Colours: default (blue), info (light blue), success (green), warning (orange), danger (red)

[http://foundation.zurb.com/docs/components/progress_bars.html Zurb foundation]

<code html5>
<div class="progress">
<span class="meter"></span>
</div>
</code>

The following options are offered by Zurb foundation:
* Width
* Colours: default (blue), secondary (grey), success (green), alert (red)
* Corner style: default (square), radius (slight rounding), round

===Search {molecule}===

A pretty common interface molecule, and in fact used as an example in the atomic design blog post we keep referencing.<br />
We don't have a component for searching yet, however we've several search boxes throughout Moodle. The admin setting search box is the first to come to mind for me, followed by the forum search box and course search box.

'''Design considerations'''

Constructed of the following items:
* Text input
* Action (must be a button for submit I imagine)
* Label or short description (optional)
* Collapsible region containing settings etc (optional)

===Table {organism}===

We've two primary table components within Moodle presently '''html_table''' and '''flexible_table''' both of which offer different advantages and disadvantages. This will be a challenge and will really require some proper research and community interaction.

===Timer {atom|molecule}===

... not sure about this one, but we do use it in a couple of places, and we use it on all core sites that have hourly resets so in a way it makes sense to support it and allow it to be styled nicely and easily.

===Tree {organism}===

===User badge===

===User content===

Think of this like the forum post. We need a common structure in which to display content entered by the user along with information on the user. The users name, picture, date perhaps, title, content, footer (attachments, badges, what ever).
It could be applied to things like forum posts, calendar events etc.

At present we have no abstraction for this.

==Existing renderables and what they will become==
{| class="wikitable"
! Existing renderable
! Description
! Future renderable
! Convenience method (if different)
|-
| action_menu
| UI component for a drop down edit menu
| menu
|
|-
| action_menu_link
| UI component for a menu item in an action menu
| action
|
|-
| action_menu_filler
| UI component for a filler menu item in an action menu
| action
|
|-
| action_menu_link_primary
| UI component for a primary menu item in an action menu
| action
|
|-
| action_menu_link_secondary
| UI component for a secondary menu item in an action menu
| action
|
|-
| action_link
| Link with alt text, and an icon
| action
|
|-
| single_button
| A form with a single button
| button (action with post method)
|
|-
| confirm
| A form with a message and cancel/confirm buttons
| confirmation
|
|-
| single_select
| A form with a single drop down list that submits on change
|
|
|-
| url_select
| A navigation element consisting of a single drop down list of urls that navigates on change
|
|
|-
| doc_link
| A link to the Moodle docs
|
|
|-
| pix_icon
| A small icon
| icon
|
|-
| emoticon_icon
| A small emoticon
|
|
|-
| heading_with_help
| A page heading with a link to help docs
| heading
|
|-
| help_icon
| A help icon that opens a help popup when clicked
| icon_help
|
|-
| help_icon_scale
| A help icon that opens a help popup when clicked
|
|
|-
| user_picture
| A user profile picture which links to their profile
|
|
|-
| container
| A block level element used to surround something. Can have a class to allow specific targeting with CSS.
|
|
|-
| error_text
| An error to show to the user.
|
|
|-
| notification
| A message for the user
|
|
|-
| continue_button
| A message and a button to continue to the next page
|
|
|-
| paging_bar
| A list of next previous and specific page links
|
|
|-
| skip_link_to
| A link to a section on the page
|
|
|-
| skip_link_target
| A target for a matching skip_link_to call
|
|
|-
| heading
| A page heading
| heading
|
|-
| box
| A page section with a border
|
|
|-
| rarrow
| A right arrow
|
|
|-
| larrow
| A left arrow
|
|
|-
| tabtree
| A list of tabs
| menu
|
|-
| tabobject
| A single tab panel
| action
|
|}

==See also==
* [[User:Sam Hemelryk/Render library element planning]]
* [[Guide to creating output elements]] ''originally written at [[User:Sam Hemelryk/Creating renderable components]]''
* [[User:Sam Hemelryk/Renderer best practices]]
* [[User:Sam Hemelryk/CSS style guidelines]]

User:Sam Hemelryk/Render library element planning

2014-06-27T02:05:22Z

Samhemelryk: /* Timer */

{{Infobox Project
|name = Renderer consistency
|state = Specification
|tracker = https://tracker.moodle.org/browse/MDL-45829
|discussion = https://moodle.org/mod/forum/discuss.php?d=261202
|assignee = Damyon, Sam
}}
{{Work in progress|forumurl=https://moodle.org/mod/forum/discuss.php?d=261202}}
This page documents the proposed core elements, variations of them, what we expect they will contain, and the core_renderer block.

==The user action==

An action in this sense is a collection of data that all pertains to one action that can be taken by the user.
The action, once populated with data can be rendered as is required for the job it is going to fulfil, usually with some relation to the frontend framework in use.
In this way the action could be a link, or a button; it could even be interpreted into a more complex structure.

An action has the following properties:
; content [string]: text content for the link or button.
; url [moodle_url] : the url for the action to take when the user interacts with this action.
; description : a description of the action. Typically used within a title or alt attribute.
; active : True if this is the action the user is current performing.
; enabled : True if the action is possible, false if it is not possible and should be shown as disabled.
; dimmed : True if the action should be shown as dimmed, usually used to the action is hidden to other users.
; method : The preferred method of submitting this action, typically GET but can be set to POST.

It is also possible to add JavaScript actions (component_action objects) to an action. These attach a JS listener to the action that gets executed when the user interacts with the action.
Attached JavaScript actions get initialised when the properties for the action are retrieved so any events must be attached BEFORE the action is rendered, and all renderers must ensure they use the get_attributes() call.

==Grids==

We need to come up with some way to include grids in core, it is desirable to keep it framework agnostic so perhaps a grid object that allows for items to be added and a "width" specified when that occurs. The width would be either a fixed number or a percentage. Steps of 12 seems pretty common.

==Design requirements==
The following concepts need to be accounted for in core, or decisions made on how we choose to support these and where.

===Clearfix===
We have this in core already, bootstrap has it, pretty much every front end framework has it.
Clearfix is more of a design decision, should only be used when require, and only ever applied by a renderer.
This gets special mention as being important, support is already 100%.

===Floats===
Pull left, pull right etc. These are a design decisions and should be implemented by the renderer. Bootstrap caters for these and as such they will be easily catered for in bootstrapbase, however work may be required to get them operational in base.

==Discarded ideas==
The following things are ideas that came up during discussions on what elements are, and what elements we want in core that have being discarded.

==Core atoms, molecules, and organisms==

The following is the atoms, molecules and organisms we believe should be created initially. Of course there will be many more that are required - however this should give us a good grounding of elements to work with for the first conversions.

===Action {atom}===
See the section above about [[#The user action]]

Actions are special atoms the represent an action the user can make.
They can be rendered by a theme as a link, a button or I suppose anything else.
There should be a default for when it is not specified and the renderer in change of producing the current thing can decide whether to use the default and just call ''render'' or if it requires something specific ''render_link'' or ''render_button'' as required.

===Action group {molecule}===
A group of actions, to be rendered to reflect a relation. I suppose the easiest way to think about this is how buttons in the atto editor are grouped together. It is a requirement that may seem a tad absrtracted and irrelevant at first but I think will pop up in several places throughout Moodle when we start converting.

It is basically a collection of actions.

'''Markup in various frontend frameworks'''

* [http://getbootstrap.com/2.3.2/components.html#buttonGroups Bootstrap 2.3.2]
* [http://getbootstrap.com/components/#btn-groups Bootstrap 3]
* [http://foundation.zurb.com/docs/components/button_groups.html Zurb foundation]

===Block {atom}===

Unique to Moodle. This represents a block on the page, and is displayed within a [[#Block region]].
It accepts two arguments, the first is a ''block_contents'' object instance, and the second is the region name the block instance is being shown within.

At present a block is rendered using the '''''core_render::block''''' method. Internally this calls several renderer methods to produce the different parts of a block.
* core_renderer::block_header - Produces a header
** core_renderer::block_controls - Produces controls to display within the header.
* core_renderer::block_content - Produces the actual content of the block.
** core_renderer::block_controls - Used to check if block controls were rendered. PUKE!!!
** core_renderer::block_footer - Produces a footer that actually resides within the content.
* core_renderer::block_annotation - Produces an annotation, used VERY rarely.

'''Current structure'''

The following is the output when called for a navigation block with a bit of extra added to show how a footer is displayed and an annotation.
<code html5>
<a href="#sb-1" class="skip-block">Skip Navigation</a>
<div id="inst4" class="block_navigation block" role="navigation" data-block="navigation" data-instanceid="4" aria-labelledby="instance-4-header" data-dockable="1">
<div class="header">
<div class="title">
<div class="block_action">

</div>
<h2 id="instance-4-header">Navigation</h2>
</div>
</div>
<div class="content">

<div class="footer">

</div>
</div>
<div class="blockannotation">

</div>
</div>
<span id="sb-1" class="skip-block-to"></span>
</code>

===Block region {molecule}===

Unique to Moodle, the block region is a contain for all of the blocks in one location.
We currently have two methods that produce a block region within Moodle, the first is '''''core_renderer::blocks_for_region''''' which adds no surrounding content.
The preferred method '''''core_renderer::blocks''''' adds some embedded information to a common structure.

'''Current structure'''

The following is the structure of the ''core_renderer::blocks()'' method.
<code php>
public function blocks($region, $classes = array(), $tag = 'aside');
</code>

The following is the html output is $region was ''pre'' and the default tag and classes were used.
<code html5>
<aside id="block-region-pre" class="block-region" data-blockregion="pre" data-droptarget="1">

</aside>
</code>

'''Thoughts on this'''

The blocks method is a convenience method and serves an important purpose. However it should not take classes and tag as arguments.<br />
These should certainly only settable within the renderer itself, and if themes wish to change this without wrapping the call they should override the renderer.

Both the data attributes relate to servicing JavaScript functionality. Perhaps they should be moved to a component_action or somehow else integrated with JS rather than with the renderer directly.

Internally it is calling blocks for region, however this should change it should request a array of blocks, convert the array to [[#Block]] elements and call render on each.

'''Proposed HTML structure'''

Much like the current structure but with the data attributes coming through a JS mechanism.

<code html5>
<aside id="block-region-pre" class="block-region">

</aside>
</code>

===Breadcrumb {molecule}===

Currently called the navbar within Moodle, controlled by the '''''navbar''''' class located in lib/navigationlib.php and rendered by '''''core_renderer::navbar()'''''.<br />
Internally it calls moodle_page->navbar->get_items() to get an array containing navigation node items to display in the navigation bar.<br />
It produces a bit of surrounding structure before calling render on each item.

'''Current structure'''

The following shows the structure for two items in the navigation bar presently within Moodle.

<code html5>
<span class="accesshide">Page path</span>
<nav class="breadcrumb-nav">
<ul class="breadcrumb">
<li>
<a href="#">Home</a>
<span class="divider">
<span class="accesshide">
<span class="arrow_text">/</span>
 
</span>
<span class="arrow sep">►</span>
</span>
</li>
<li>
<a href="#">Here</a>
<span class="divider">
<span class="accesshide">
<span class="arrow_text">/</span>
 
</span>
<span class="arrow sep">►</span>
</span>
</li>
</ul>
</nav>
</code>

Notice the excessive amount of markup to make the separator accessible.

'''Markup in various frontend frameworks'''

[http://getbootstrap.com/2.3.2/components.html#breadcrumbs Bootstrap 2.3.2]
<code html5>
<ul class="breadcrumb">
<li>
<a href="#">Home</a>
<span class="divider">/</span>
</li>
<li>
<a href="#">Here</a>
<span class="divider">/</span>
</li>
</ul>
</code>

[http://getbootstrap.com/components/#breadcrumbs Bootstrap 3]
<code html5>
<ul class="breadcrumb">
<li>
<a href="#">Home</a>
</li>
<li>
<a href="#">Here</a>
</li>
</ul>
</code>

[http://foundation.zurb.com/docs/components/breadcrumbs.html Zurb foundation]
<code html5>
<ul class="breadcrumb">
<li>
<a href="#">Home</a>
</li>
<li>
<a href="#">Here</a>
</li>
</ul>
</code>

'''Design considerations'''

* The currently active page should be marked with a class.
* The current item should probably not be a link MDL-46037
* [http://www.w3.org/TR/2007/WD-aria-role-20070601/#breadcrumbs wia-aria breadcrumb role]
* The divider perhaps could come through CSS with these changes to avoid markup necessary to make it accessible (in combination with the above).

'''Implementation thoughts'''
* Owns an array of [#Action {atoms}]

===Buttons {atom}===

This will be both an element and a representation of a [#Action {atom}].<br />
Obviously buttons can serve different purposes and roles so have several easily reachable customisations is probably a wise idea.

'''Current structure'''
None, presently you produce a button when you need it so there are several throughout Moodle.

'''Markup in various frontend frameworks'''

[http://getbootstrap.com/2.3.2/base-css.html#buttons Bootstrap 2.3.2] and [http://getbootstrap.com/css/#buttons Bootstrap 3]
<code html5>
<button type="button" class="btn btn-default">Default</button>

<a href="#" class="btn btn-default btn-lg active" role="button">Link</a>

<input class="btn btn-default" type="button" value="Input">
</code>

Customisations available through Bootstrap:
* Purposes: default, primary, success, info, warning, danger, link
* Sizes: large, default, small, extra-small
* Block level (wider)
* States: Active, disabled.

[http://foundation.zurb.com/docs/components/buttons.html Zurb foundation]
<code html5>
<a href="#" class="button">Default Button</a>
</code>

Customisations available through Zurb Foundation:
* Purposes: default, secondary, success, alert
* Sizes: large, default, small, tiny
* Corner style: radius, round
* Expanded (wider)
* States: disabled

===Calendar {organism}===

A simple idea really, apparently not already covered by the frontend frameworks being referenced during the creation of the doc.
The display of the calendar is fixed, but it can contain content for each day shown.

The calendar should have several views, perhaps these are separate organisms, perhaps not.

* Compact month
* Month
* Week
* Day

Each day could:
* Contain an action with an icon for events, and link to the fullday display.
* Have an associated action to load and display the events in a tooltip.

===Collapsible region {molecule}===

We use these in several places within Moodle. I could not find a reference to this concept in any of the frontend frameworks I looked at.
The concept is simple - you have a heading and an icon with content. By default the content is hidden, when the user clicks the heading and/or the icon the content is revealed.

As noted we do this in several places within Moodle, it would be good to have a single way of displaying this idea of a collapsible region.

'''Design thoughts'''
* It should support an optional collapse/expand all trigger action.
* We want to be able to use it both inside and outside of forms.
* It should be usable in situations like the combo list frontpage component as well.
* Will obviously have a JS component as without JS it would not work.

===Confirmation {molecule}===

A simple concept used regularly in Moodle to confirm a users intention to perform an actions. Most commonly seeing when deleting content.
The structure is relatively basic in Moodle at present.
* A message
* A forwards button
* A back button

'''Current structure'''

The method '''''core_renderer::confirm''''' does the rendering at present. Its signature is as follows:
<code php>
public function confirm($message, $continue, $cancel);
</code>

The output it produces is like:
<code html5>
<div class="generalbox" id="notice">
<p>The message goes here</p>
<div class="buttons">

</div>
</div>
</code>

'''Design throughts'''

This component does not have a title. I believe at present some pages use ''core_renderer::heading'' to produce a title if they wish. Obviously we want consistency of style so I believe it would be wise to add a title property that can be optionally set and then in our documentation for this element recommend that a title is always provided.<br />
It will mean re-factoring our uses to set a title and if a heading is being manually added remove it.

===Continue {molecule}===

This is much like the confirmation molecule but with a single button.<br />
At present we have '''''core_renderer::continue_button''''' that produces a single button. However this design is very poor as more often than not a message is included in the page to describe the purpose of the continue button. This is really an integral part of the continue button.

'''Current structure'''

Currently we have ''core_renderer::continue_button'' to render a single continue button.
<code php>
public function continue_button($url);
</code>

Internally it creates a single_button component and then calls render on that.

'''Design thoughts'''
Our element should have a message and a button. To make it easy to migrate the constructor should accept a URL instead of a button and do the same conversion as the current method is doing.

===Choice {molecule}===
Not sure about this one quite yet.
A description with 2 or more actions allowing the user to select the next step.
Think of it like when editing a module you get: Cancel, Save and return to course, Save and display

Perhaps both [#Confirmation {molecule}] and [#Continue {molecule}] should be just instances of this.

Hmm perhaps that would not be as clear as this and we should have this separate choice molecule.

===Divider {atom}===
Think horizontal rule.

===Dropdowns {molecule}===

So this is a pretty simple concept, but you've got to think of it as a separate entity. A dropdown is a menu that appears when the user interacts with an action.

The action could take one of three forms:
* From button
* From link
* From icon

Of course that is handled by the [#Action {atom}] noted above. Worth noting is that we will need some way to toggle these actions as dropdowns. Perhaps it is worth making that a property of the action atom.

The dropdown itself will likely contain more actions, and I suppose additional dropdowns to form sub menus. Sub-menus in my mind are required. We don't use them in core, but they are functionally possible through things like the custom menu and I know for a fact that many sites have sub menus.

'''Markup in various frontend frameworks'''

[http://getbootstrap.com/2.3.2/components.html#dropdowns Bootstrap 2.3.2]

<code html5>
<div class="dropdown">

<ul class="dropdown-menu" role="menu" aria-labelledby="dLabel">
<li><a tabindex="-1" href="#">Action</a></li>
<li><a tabindex="-1" href="#">Another action</a></li>
<li><a tabindex="-1" href="#">Something else here</a></li>
<li class="divider"></li>
<li><a tabindex="-1" href="#">Separated link</a></li>
</ul>
</div>
</code>

[http://getbootstrap.com/components/#dropdowns Bootstrap 3]
<code html5>
<div class="dropdown">
<button class="btn dropdown-toggle sr-only" type="button" id="dropdownMenu1" data-toggle="dropdown">
Dropdown
<span class="caret"></span>
</button>
<ul class="dropdown-menu" role="menu" aria-labelledby="dropdownMenu1">
<li role="presentation"><a role="menuitem" tabindex="-1" href="#">Action</a></li>
<li role="presentation"><a role="menuitem" tabindex="-1" href="#">Another action</a></li>
<li role="presentation"><a role="menuitem" tabindex="-1" href="#">Something else here</a></li>
<li role="presentation" class="divider"></li>
<li role="presentation"><a role="menuitem" tabindex="-1" href="#">Separated link</a></li>
</ul>
</div>
</code>

[http://foundation.zurb.com/docs/components/dropdown.html Zurb foundation]
<code html5>
<a href="#" data-dropdown="drop1">Has Dropdown</a>
<ul id="drop1" class="f-dropdown" data-dropdown-content>
<li><a href="#">This is a link</a></li>
<li><a href="#">This is another</a></li>
<li><a href="#">Yet another</a></li>
</ul>
</code>

===Forms {organism}===

This is an advanced organism and would be quite a bit of work to create in Moodle as we'd need to translate from QuickForms to elements for rendering.
It would be worthwhile doing this however, and would be a good way of quickly showing our new work.

'''Frontend framework structures'''
* [http://getbootstrap.com/2.3.2/base-css.html#forms Bootstrap 2.3.2]
* [http://getbootstrap.com/css/#forms Bootstrap 3]
* [http://foundation.zurb.com/docs/components/forms.html Zurb foundation]

All of those are quite in-depth and offer a range of configurations.
We should carefully consider these when analysing our work here.

===Headings {atom}===

Currently handled by '''core_renderer::heading'''.

* h1 - h6
* Optional icon
* Optional help icon

'''Current structure'''

The render method is currently:
<code php>
public function heading($text, $level = 2, $classes = null, $id = null);
</code>

The output generated by this is, assuming we use the default level, classes, and id.
<code html5>
<h2>I am a heading</h2>
</code>

Whats worth noting is that the render method should not accept level and classes as arguments.
These should only be set by the render method and should not be directly influenced.

===Image {atom}===

There are really two types of images to focus on here, or really two ways to display an image to focus on here.<br />
# Standard images
# Thumbnail images

Each of these would share some common properties:
* Image
* Description (alt/title)
* Size
* Action (making it a link) - This would actually make it a molecule, we would have to consider this and either have a new element, drop the ability to wrap in an action, or simply ignore this inconsistency.

===Image - Icon {atom}===

This covers the display of an icon. Should be a separate element from image as really they should be treated individually.
Within Moodle there are a few classifications of icons to consider:
* Standard icons
* Help icon (popup, tooltip)
* Loading icon (really regular icon but worth showing separately as its only seen when required)

===Image - Logo {molecule}===

We don't have this within core Moodle at present, however just about every theme I have seen uses a logo. I think it is about time we considered having a logo element.
I imagine it would become a sort of hero element, likely with an associated action (back home by default).

===Image - Profile picture {molecule}===

We already have a user_picture component within Moodle. It can be found in lib/outputcomponents.php.<br />
It has two render methods, '''''core_renderer::user_picture''''' and '''''core_renderer::render_user_picture'''''.

'''Current structure'''

The following is the output structure for the user picture:
<code html5>
<a href="#" id="userpicture_randomid">
<img src="#" alt="Picture of Joe" title="Picture of Joe" class="userpicture" width="[35, 100, XX]" height="[35, 100, XX]" />
</a>
</code>

What you'll notice about this is that the link has no attributes marking it as a user picture link.

The PHP code for the user_picture object itself is really quite in depth and complex. The component serves the user profile fields required to render a user picture. This is good in the scope of the component but would be bad within the scope of an element.<br />
Don't you wish we had a proper user object!

===Link {atom}===
This will be both an element and a representation of a [#Action {atom}].

Theres not too much more to explain about links, they don't tend to take states other than the default active, enabled and dimmed.<br />
It is worth mentioning that devs will be encouraged to use actions and not links unless absolutely necessary.<br />
The render method for this atom must typehint an action rather than a link.

'''Prototype example'''
* The atom: https://github.com/samhemelryk/moodle/blob/output_prototype_5/local/output/classes/output/link.php
* The convenience method: https://github.com/samhemelryk/moodle/blob/output_prototype_5/local/output/classes/output/renderer.php#L149
* The render method: https://github.com/samhemelryk/moodle/blob/output_prototype_5/local/output/classes/output/renderer.php#L211

===List {molecule}===

This is a pretty simple example and something I am sure you are all familiar with. A list is simply a collection of items. Usually represented using a UL or OL tag in markup although worth noting can be styled completely differently to the default.
There are three main types of lists used within Moodle:
* Ordered list
* Unordered list
* Presentation list (currently our unlist)

The list is a molecule because it should be able to accept other elements as items. E.g. it should be content independent.

===Menu {molecule}===

A menu is a familiar concept for any site. Probably the first thing that pops to mind for many is the navbar, but I want to consider that a separate component as a navbar can consist of more than just menu items.
I think a menu should be a collection of actions the user can perform. Perhaps with some form of hierarchy.

We have different types of menus within Moodle:
* The custom menu is one users can directly create, with dropdown downs and sub dropdowns.
* The action_menu component we have in core uses icons as actions and can have a dropdown.

These should be combined into a single menu element that takes items as an argument, likely actions + dropdowns + dividers to start with would be perfect.

We would likely need to deal with the display of the menu with properties to allow constructing code to ''request'' a particular style of menu. The renderer should be what actually gets to decide, but for the purposes of re-use having properties and a single render_method is better than having multiple render methods.<br />
The following is my initial thoughts on menu structure:
* Direction: Horizontal, Vertical
* Design: Default, Tabs,
* Style: Default, Links, Buttons, Icons

===Notification {atom}===
* Info
* Success
* Warning
* Danger

===Navigation bar {organism}===
Formerly navbar, can't be called that because the render method would conflict.

The navigation bar is just that, it is becoming increasingly common on the web and usually contains a title or logo, a menu, and information pertaining to the user state (login, language etc).

===Page header {molecule}===

Currently being produced by '''core_renderer::page_heading''' this is simply a header for the page, by default the only h1 element on the page.

'''Current structure'''

The render method has the following signature:
<code php>
public function page_heading($tag = 'h1');
</code>

The output from the above method is:
<code html5>
<h1>The page heading (from moodle_page::heading)</h1>
</code>

The core_renderer method should not allow the tag to be set. The page heading should always be H1.
If its not an H1 then page header should not be used.

'''Frontend framework examples'''

[http://getbootstrap.com/2.3.2/components.html#typography Bootstrap 2.3.2]
<code html5>
<div class="hero-unit">
<h1>Heading</h1>
<p>Tagline</p>
<p>
<a class="btn btn-primary btn-large">
Learn more
</a>
</p>
</div>
</code>

[http://getbootstrap.com/components/#page-header Bootstrap 3]
<code html5>
<div class="page-header">
<h1>Example page header <small>Subtext for header</small></h1>
</div>
</code>

Foundation doesn't appear to have a page header component.

'''Design thoughts'''

* In Moodle all page headings are set as a single string, we won't be changing this.
* Usually just a plain string sometimes an icon is used, and sometimes a help icon is used.

===Pagination {molecule}===

I like the idea of this being separate to a menu, and to other navigation oriented elements because it should be something that can easily be constructed with a few basic parameters and allow us to achieve consistent pagination throughout Moodle.<br />
It also appeals because this is something that people may want to style differently to their navigation.

'''Markup in various frontend frameworks'''

* [http://getbootstrap.com/2.3.2/components.html#pagination Bootstrap 2.3.2 pagination]
* [http://getbootstrap.com/components/#pagination Bootstrap 3 pagination]
* [http://foundation.zurb.com/docs/components/pagination.html Zurb foundation pagination]

===Progress bars {molecule}===

A pretty simple concept, we already have a couple of ways of producing progress bars within Moodle.

'''Markup in various frontend frameworks'''

[http://getbootstrap.com/2.3.2/components.html#progress Bootstrap 2.3.2]
<code html5>
<div class="progress">
<div class="bar" style="width: 60%;"></div>
</div>
</code>

The following options are offered by Bootstrap 2.3.2:

* Striped
* Striped + Animated
* Stacked (multiple bars forming a single)
* Colours: default (blue), info (light blue), success (green), warning (orange), danger (red)

[http://getbootstrap.com/components/#progress Bootstrap 3]
<code html5>

<div class="progress">
<div class="progress-bar" role="progressbar" aria-valuenow="60" aria-valuemin="0" aria-valuemax="100" style="width: 60%;">
60% Complete
</div>
</div>


<div class="progress">
<div class="progress-bar" role="progressbar" aria-valuenow="60" aria-valuemin="0" aria-valuemax="100" style="width: 60%;">
60%
</div>
</div>
</code>

The following options are offered by Bootstrap 3:

* Striped
* Striped + Animated
* Stacked (multiple bars forming a single)
* Colours: default (blue), info (light blue), success (green), warning (orange), danger (red)

[http://foundation.zurb.com/docs/components/progress_bars.html Zurb foundation]

<code html5>
<div class="progress">
<span class="meter"></span>
</div>
</code>

The following options are offered by Zurb foundation:
* Width
* Colours: default (blue), secondary (grey), success (green), alert (red)
* Corner style: default (square), radius (slight rounding), round

===Search {molecule}===

A pretty common interface molecule, and in fact used as an example in the atomic design blog post we keep referencing.<br />
We don't have a component for searching yet, however we've several search boxes throughout Moodle. The admin setting search box is the first to come to mind for me, followed by the forum search box and course search box.

'''Design considerations'''

Constructed of the following items:
* Text input
* Action (must be a button for submit I imagine)
* Label or short description (optional)
* Collapsible region containing settings etc (optional)

===Table {organism}===

We've two primary table components within Moodle presently '''html_table''' and '''flexible_table''' both of which offer different advantages and disadvantages. This will be a challenge and will really require some proper research and community interaction.

===Timer {atom|molecule}===

... not sure about this one, but we do use it in a couple of places, and we use it on all core sites that have hourly resets so in a way it makes sense to support it and allow it to be styled nicely and easily.

===Tree===

===User badge===

===User content===

Think of this like the forum post. We need a common structure in which to display content entered by the user along with information on the user. The users name, picture, date perhaps, title, content, footer (attachments, badges, what ever).
It could be applied to things like forum posts, calendar events etc.

At present we have no abstraction for this.

==Existing renderables and what they will become==
{| class="wikitable"
! Existing renderable
! Description
! Future renderable
! Convenience method (if different)
|-
| action_menu
| UI component for a drop down edit menu
| menu
|
|-
| action_menu_link
| UI component for a menu item in an action menu
| action
|
|-
| action_menu_filler
| UI component for a filler menu item in an action menu
| action
|
|-
| action_menu_link_primary
| UI component for a primary menu item in an action menu
| action
|
|-
| action_menu_link_secondary
| UI component for a secondary menu item in an action menu
| action
|
|-
| action_link
| Link with alt text, and an icon
| action
|
|-
| single_button
| A form with a single button
| button (action with post method)
|
|-
| confirm
| A form with a message and cancel/confirm buttons
| confirmation
|
|-
| single_select
| A form with a single drop down list that submits on change
|
|
|-
| url_select
| A navigation element consisting of a single drop down list of urls that navigates on change
|
|
|-
| doc_link
| A link to the Moodle docs
|
|
|-
| pix_icon
| A small icon
| icon
|
|-
| emoticon_icon
| A small emoticon
|
|
|-
| heading_with_help
| A page heading with a link to help docs
| heading
|
|-
| help_icon
| A help icon that opens a help popup when clicked
| icon_help
|
|-
| help_icon_scale
| A help icon that opens a help popup when clicked
|
|
|-
| user_picture
| A user profile picture which links to their profile
|
|
|-
| container
| A block level element used to surround something. Can have a class to allow specific targeting with CSS.
|
|
|-
| error_text
| An error to show to the user.
|
|
|-
| notification
| A message for the user
|
|
|-
| continue_button
| A message and a button to continue to the next page
|
|
|-
| paging_bar
| A list of next previous and specific page links
|
|
|-
| skip_link_to
| A link to a section on the page
|
|
|-
| skip_link_target
| A target for a matching skip_link_to call
|
|
|-
| heading
| A page heading
| heading
|
|-
| box
| A page section with a border
|
|
|-
| rarrow
| A right arrow
|
|
|-
| larrow
| A left arrow
|
|
|-
| tabtree
| A list of tabs
| menu
|
|-
| tabobject
| A single tab panel
| action
|
|}

==See also==
* [[User:Sam Hemelryk/Render library element planning]]
* [[Guide to creating output elements]] ''originally written at [[User:Sam Hemelryk/Creating renderable components]]''
* [[User:Sam Hemelryk/Renderer best practices]]
* [[User:Sam Hemelryk/CSS style guidelines]]

User:Sam Hemelryk/Render library element planning

2014-06-27T01:58:49Z

Samhemelryk: /* Table {organism} */

{{Infobox Project
|name = Renderer consistency
|state = Specification
|tracker = https://tracker.moodle.org/browse/MDL-45829
|discussion = https://moodle.org/mod/forum/discuss.php?d=261202
|assignee = Damyon, Sam
}}
{{Work in progress|forumurl=https://moodle.org/mod/forum/discuss.php?d=261202}}
This page documents the proposed core elements, variations of them, what we expect they will contain, and the core_renderer block.

==The user action==

An action in this sense is a collection of data that all pertains to one action that can be taken by the user.
The action, once populated with data can be rendered as is required for the job it is going to fulfil, usually with some relation to the frontend framework in use.
In this way the action could be a link, or a button; it could even be interpreted into a more complex structure.

An action has the following properties:
; content [string]: text content for the link or button.
; url [moodle_url] : the url for the action to take when the user interacts with this action.
; description : a description of the action. Typically used within a title or alt attribute.
; active : True if this is the action the user is current performing.
; enabled : True if the action is possible, false if it is not possible and should be shown as disabled.
; dimmed : True if the action should be shown as dimmed, usually used to the action is hidden to other users.
; method : The preferred method of submitting this action, typically GET but can be set to POST.

It is also possible to add JavaScript actions (component_action objects) to an action. These attach a JS listener to the action that gets executed when the user interacts with the action.
Attached JavaScript actions get initialised when the properties for the action are retrieved so any events must be attached BEFORE the action is rendered, and all renderers must ensure they use the get_attributes() call.

==Grids==

We need to come up with some way to include grids in core, it is desirable to keep it framework agnostic so perhaps a grid object that allows for items to be added and a "width" specified when that occurs. The width would be either a fixed number or a percentage. Steps of 12 seems pretty common.

==Design requirements==
The following concepts need to be accounted for in core, or decisions made on how we choose to support these and where.

===Clearfix===
We have this in core already, bootstrap has it, pretty much every front end framework has it.
Clearfix is more of a design decision, should only be used when require, and only ever applied by a renderer.
This gets special mention as being important, support is already 100%.

===Floats===
Pull left, pull right etc. These are a design decisions and should be implemented by the renderer. Bootstrap caters for these and as such they will be easily catered for in bootstrapbase, however work may be required to get them operational in base.

==Discarded ideas==
The following things are ideas that came up during discussions on what elements are, and what elements we want in core that have being discarded.

==Core atoms, molecules, and organisms==

The following is the atoms, molecules and organisms we believe should be created initially. Of course there will be many more that are required - however this should give us a good grounding of elements to work with for the first conversions.

===Action {atom}===
See the section above about [[#The user action]]

Actions are special atoms the represent an action the user can make.
They can be rendered by a theme as a link, a button or I suppose anything else.
There should be a default for when it is not specified and the renderer in change of producing the current thing can decide whether to use the default and just call ''render'' or if it requires something specific ''render_link'' or ''render_button'' as required.

===Action group {molecule}===
A group of actions, to be rendered to reflect a relation. I suppose the easiest way to think about this is how buttons in the atto editor are grouped together. It is a requirement that may seem a tad absrtracted and irrelevant at first but I think will pop up in several places throughout Moodle when we start converting.

It is basically a collection of actions.

'''Markup in various frontend frameworks'''

* [http://getbootstrap.com/2.3.2/components.html#buttonGroups Bootstrap 2.3.2]
* [http://getbootstrap.com/components/#btn-groups Bootstrap 3]
* [http://foundation.zurb.com/docs/components/button_groups.html Zurb foundation]

===Block {atom}===

Unique to Moodle. This represents a block on the page, and is displayed within a [[#Block region]].
It accepts two arguments, the first is a ''block_contents'' object instance, and the second is the region name the block instance is being shown within.

At present a block is rendered using the '''''core_render::block''''' method. Internally this calls several renderer methods to produce the different parts of a block.
* core_renderer::block_header - Produces a header
** core_renderer::block_controls - Produces controls to display within the header.
* core_renderer::block_content - Produces the actual content of the block.
** core_renderer::block_controls - Used to check if block controls were rendered. PUKE!!!
** core_renderer::block_footer - Produces a footer that actually resides within the content.
* core_renderer::block_annotation - Produces an annotation, used VERY rarely.

'''Current structure'''

The following is the output when called for a navigation block with a bit of extra added to show how a footer is displayed and an annotation.
<code html5>
<a href="#sb-1" class="skip-block">Skip Navigation</a>
<div id="inst4" class="block_navigation block" role="navigation" data-block="navigation" data-instanceid="4" aria-labelledby="instance-4-header" data-dockable="1">
<div class="header">
<div class="title">
<div class="block_action">

</div>
<h2 id="instance-4-header">Navigation</h2>
</div>
</div>
<div class="content">

<div class="footer">

</div>
</div>
<div class="blockannotation">

</div>
</div>
<span id="sb-1" class="skip-block-to"></span>
</code>

===Block region {molecule}===

Unique to Moodle, the block region is a contain for all of the blocks in one location.
We currently have two methods that produce a block region within Moodle, the first is '''''core_renderer::blocks_for_region''''' which adds no surrounding content.
The preferred method '''''core_renderer::blocks''''' adds some embedded information to a common structure.

'''Current structure'''

The following is the structure of the ''core_renderer::blocks()'' method.
<code php>
public function blocks($region, $classes = array(), $tag = 'aside');
</code>

The following is the html output is $region was ''pre'' and the default tag and classes were used.
<code html5>
<aside id="block-region-pre" class="block-region" data-blockregion="pre" data-droptarget="1">

</aside>
</code>

'''Thoughts on this'''

The blocks method is a convenience method and serves an important purpose. However it should not take classes and tag as arguments.<br />
These should certainly only settable within the renderer itself, and if themes wish to change this without wrapping the call they should override the renderer.

Both the data attributes relate to servicing JavaScript functionality. Perhaps they should be moved to a component_action or somehow else integrated with JS rather than with the renderer directly.

Internally it is calling blocks for region, however this should change it should request a array of blocks, convert the array to [[#Block]] elements and call render on each.

'''Proposed HTML structure'''

Much like the current structure but with the data attributes coming through a JS mechanism.

<code html5>
<aside id="block-region-pre" class="block-region">

</aside>
</code>

===Breadcrumb {molecule}===

Currently called the navbar within Moodle, controlled by the '''''navbar''''' class located in lib/navigationlib.php and rendered by '''''core_renderer::navbar()'''''.<br />
Internally it calls moodle_page->navbar->get_items() to get an array containing navigation node items to display in the navigation bar.<br />
It produces a bit of surrounding structure before calling render on each item.

'''Current structure'''

The following shows the structure for two items in the navigation bar presently within Moodle.

<code html5>
<span class="accesshide">Page path</span>
<nav class="breadcrumb-nav">
<ul class="breadcrumb">
<li>
<a href="#">Home</a>
<span class="divider">
<span class="accesshide">
<span class="arrow_text">/</span>
 
</span>
<span class="arrow sep">►</span>
</span>
</li>
<li>
<a href="#">Here</a>
<span class="divider">
<span class="accesshide">
<span class="arrow_text">/</span>
 
</span>
<span class="arrow sep">►</span>
</span>
</li>
</ul>
</nav>
</code>

Notice the excessive amount of markup to make the separator accessible.

'''Markup in various frontend frameworks'''

[http://getbootstrap.com/2.3.2/components.html#breadcrumbs Bootstrap 2.3.2]
<code html5>
<ul class="breadcrumb">
<li>
<a href="#">Home</a>
<span class="divider">/</span>
</li>
<li>
<a href="#">Here</a>
<span class="divider">/</span>
</li>
</ul>
</code>

[http://getbootstrap.com/components/#breadcrumbs Bootstrap 3]
<code html5>
<ul class="breadcrumb">
<li>
<a href="#">Home</a>
</li>
<li>
<a href="#">Here</a>
</li>
</ul>
</code>

[http://foundation.zurb.com/docs/components/breadcrumbs.html Zurb foundation]
<code html5>
<ul class="breadcrumb">
<li>
<a href="#">Home</a>
</li>
<li>
<a href="#">Here</a>
</li>
</ul>
</code>

'''Design considerations'''

* The currently active page should be marked with a class.
* The current item should probably not be a link MDL-46037
* [http://www.w3.org/TR/2007/WD-aria-role-20070601/#breadcrumbs wia-aria breadcrumb role]
* The divider perhaps could come through CSS with these changes to avoid markup necessary to make it accessible (in combination with the above).

'''Implementation thoughts'''
* Owns an array of [#Action {atoms}]

===Buttons {atom}===

This will be both an element and a representation of a [#Action {atom}].<br />
Obviously buttons can serve different purposes and roles so have several easily reachable customisations is probably a wise idea.

'''Current structure'''
None, presently you produce a button when you need it so there are several throughout Moodle.

'''Markup in various frontend frameworks'''

[http://getbootstrap.com/2.3.2/base-css.html#buttons Bootstrap 2.3.2] and [http://getbootstrap.com/css/#buttons Bootstrap 3]
<code html5>
<button type="button" class="btn btn-default">Default</button>

<a href="#" class="btn btn-default btn-lg active" role="button">Link</a>

<input class="btn btn-default" type="button" value="Input">
</code>

Customisations available through Bootstrap:
* Purposes: default, primary, success, info, warning, danger, link
* Sizes: large, default, small, extra-small
* Block level (wider)
* States: Active, disabled.

[http://foundation.zurb.com/docs/components/buttons.html Zurb foundation]
<code html5>
<a href="#" class="button">Default Button</a>
</code>

Customisations available through Zurb Foundation:
* Purposes: default, secondary, success, alert
* Sizes: large, default, small, tiny
* Corner style: radius, round
* Expanded (wider)
* States: disabled

===Calendar {organism}===

A simple idea really, apparently not already covered by the frontend frameworks being referenced during the creation of the doc.
The display of the calendar is fixed, but it can contain content for each day shown.

The calendar should have several views, perhaps these are separate organisms, perhaps not.

* Compact month
* Month
* Week
* Day

Each day could:
* Contain an action with an icon for events, and link to the fullday display.
* Have an associated action to load and display the events in a tooltip.

===Collapsible region {molecule}===

We use these in several places within Moodle. I could not find a reference to this concept in any of the frontend frameworks I looked at.
The concept is simple - you have a heading and an icon with content. By default the content is hidden, when the user clicks the heading and/or the icon the content is revealed.

As noted we do this in several places within Moodle, it would be good to have a single way of displaying this idea of a collapsible region.

'''Design thoughts'''
* It should support an optional collapse/expand all trigger action.
* We want to be able to use it both inside and outside of forms.
* It should be usable in situations like the combo list frontpage component as well.
* Will obviously have a JS component as without JS it would not work.

===Confirmation {molecule}===

A simple concept used regularly in Moodle to confirm a users intention to perform an actions. Most commonly seeing when deleting content.
The structure is relatively basic in Moodle at present.
* A message
* A forwards button
* A back button

'''Current structure'''

The method '''''core_renderer::confirm''''' does the rendering at present. Its signature is as follows:
<code php>
public function confirm($message, $continue, $cancel);
</code>

The output it produces is like:
<code html5>
<div class="generalbox" id="notice">
<p>The message goes here</p>
<div class="buttons">

</div>
</div>
</code>

'''Design throughts'''

This component does not have a title. I believe at present some pages use ''core_renderer::heading'' to produce a title if they wish. Obviously we want consistency of style so I believe it would be wise to add a title property that can be optionally set and then in our documentation for this element recommend that a title is always provided.<br />
It will mean re-factoring our uses to set a title and if a heading is being manually added remove it.

===Continue {molecule}===

This is much like the confirmation molecule but with a single button.<br />
At present we have '''''core_renderer::continue_button''''' that produces a single button. However this design is very poor as more often than not a message is included in the page to describe the purpose of the continue button. This is really an integral part of the continue button.

'''Current structure'''

Currently we have ''core_renderer::continue_button'' to render a single continue button.
<code php>
public function continue_button($url);
</code>

Internally it creates a single_button component and then calls render on that.

'''Design thoughts'''
Our element should have a message and a button. To make it easy to migrate the constructor should accept a URL instead of a button and do the same conversion as the current method is doing.

===Choice {molecule}===
Not sure about this one quite yet.
A description with 2 or more actions allowing the user to select the next step.
Think of it like when editing a module you get: Cancel, Save and return to course, Save and display

Perhaps both [#Confirmation {molecule}] and [#Continue {molecule}] should be just instances of this.

Hmm perhaps that would not be as clear as this and we should have this separate choice molecule.

===Divider {atom}===
Think horizontal rule.

===Dropdowns {molecule}===

So this is a pretty simple concept, but you've got to think of it as a separate entity. A dropdown is a menu that appears when the user interacts with an action.

The action could take one of three forms:
* From button
* From link
* From icon

Of course that is handled by the [#Action {atom}] noted above. Worth noting is that we will need some way to toggle these actions as dropdowns. Perhaps it is worth making that a property of the action atom.

The dropdown itself will likely contain more actions, and I suppose additional dropdowns to form sub menus. Sub-menus in my mind are required. We don't use them in core, but they are functionally possible through things like the custom menu and I know for a fact that many sites have sub menus.

'''Markup in various frontend frameworks'''

[http://getbootstrap.com/2.3.2/components.html#dropdowns Bootstrap 2.3.2]

<code html5>
<div class="dropdown">

<ul class="dropdown-menu" role="menu" aria-labelledby="dLabel">
<li><a tabindex="-1" href="#">Action</a></li>
<li><a tabindex="-1" href="#">Another action</a></li>
<li><a tabindex="-1" href="#">Something else here</a></li>
<li class="divider"></li>
<li><a tabindex="-1" href="#">Separated link</a></li>
</ul>
</div>
</code>

[http://getbootstrap.com/components/#dropdowns Bootstrap 3]
<code html5>
<div class="dropdown">
<button class="btn dropdown-toggle sr-only" type="button" id="dropdownMenu1" data-toggle="dropdown">
Dropdown
<span class="caret"></span>
</button>
<ul class="dropdown-menu" role="menu" aria-labelledby="dropdownMenu1">
<li role="presentation"><a role="menuitem" tabindex="-1" href="#">Action</a></li>
<li role="presentation"><a role="menuitem" tabindex="-1" href="#">Another action</a></li>
<li role="presentation"><a role="menuitem" tabindex="-1" href="#">Something else here</a></li>
<li role="presentation" class="divider"></li>
<li role="presentation"><a role="menuitem" tabindex="-1" href="#">Separated link</a></li>
</ul>
</div>
</code>

[http://foundation.zurb.com/docs/components/dropdown.html Zurb foundation]
<code html5>
<a href="#" data-dropdown="drop1">Has Dropdown</a>
<ul id="drop1" class="f-dropdown" data-dropdown-content>
<li><a href="#">This is a link</a></li>
<li><a href="#">This is another</a></li>
<li><a href="#">Yet another</a></li>
</ul>
</code>

===Forms {organism}===

This is an advanced organism and would be quite a bit of work to create in Moodle as we'd need to translate from QuickForms to elements for rendering.
It would be worthwhile doing this however, and would be a good way of quickly showing our new work.

'''Frontend framework structures'''
* [http://getbootstrap.com/2.3.2/base-css.html#forms Bootstrap 2.3.2]
* [http://getbootstrap.com/css/#forms Bootstrap 3]
* [http://foundation.zurb.com/docs/components/forms.html Zurb foundation]

All of those are quite in-depth and offer a range of configurations.
We should carefully consider these when analysing our work here.

===Headings {atom}===

Currently handled by '''core_renderer::heading'''.

* h1 - h6
* Optional icon
* Optional help icon

'''Current structure'''

The render method is currently:
<code php>
public function heading($text, $level = 2, $classes = null, $id = null);
</code>

The output generated by this is, assuming we use the default level, classes, and id.
<code html5>
<h2>I am a heading</h2>
</code>

Whats worth noting is that the render method should not accept level and classes as arguments.
These should only be set by the render method and should not be directly influenced.

===Image {atom}===

There are really two types of images to focus on here, or really two ways to display an image to focus on here.<br />
# Standard images
# Thumbnail images

Each of these would share some common properties:
* Image
* Description (alt/title)
* Size
* Action (making it a link) - This would actually make it a molecule, we would have to consider this and either have a new element, drop the ability to wrap in an action, or simply ignore this inconsistency.

===Image - Icon {atom}===

This covers the display of an icon. Should be a separate element from image as really they should be treated individually.
Within Moodle there are a few classifications of icons to consider:
* Standard icons
* Help icon (popup, tooltip)
* Loading icon (really regular icon but worth showing separately as its only seen when required)

===Image - Logo {molecule}===

We don't have this within core Moodle at present, however just about every theme I have seen uses a logo. I think it is about time we considered having a logo element.
I imagine it would become a sort of hero element, likely with an associated action (back home by default).

===Image - Profile picture {molecule}===

We already have a user_picture component within Moodle. It can be found in lib/outputcomponents.php.<br />
It has two render methods, '''''core_renderer::user_picture''''' and '''''core_renderer::render_user_picture'''''.

'''Current structure'''

The following is the output structure for the user picture:
<code html5>
<a href="#" id="userpicture_randomid">
<img src="#" alt="Picture of Joe" title="Picture of Joe" class="userpicture" width="[35, 100, XX]" height="[35, 100, XX]" />
</a>
</code>

What you'll notice about this is that the link has no attributes marking it as a user picture link.

The PHP code for the user_picture object itself is really quite in depth and complex. The component serves the user profile fields required to render a user picture. This is good in the scope of the component but would be bad within the scope of an element.<br />
Don't you wish we had a proper user object!

===Link {atom}===
This will be both an element and a representation of a [#Action {atom}].

Theres not too much more to explain about links, they don't tend to take states other than the default active, enabled and dimmed.<br />
It is worth mentioning that devs will be encouraged to use actions and not links unless absolutely necessary.<br />
The render method for this atom must typehint an action rather than a link.

'''Prototype example'''
* The atom: https://github.com/samhemelryk/moodle/blob/output_prototype_5/local/output/classes/output/link.php
* The convenience method: https://github.com/samhemelryk/moodle/blob/output_prototype_5/local/output/classes/output/renderer.php#L149
* The render method: https://github.com/samhemelryk/moodle/blob/output_prototype_5/local/output/classes/output/renderer.php#L211

===List {molecule}===

This is a pretty simple example and something I am sure you are all familiar with. A list is simply a collection of items. Usually represented using a UL or OL tag in markup although worth noting can be styled completely differently to the default.
There are three main types of lists used within Moodle:
* Ordered list
* Unordered list
* Presentation list (currently our unlist)

The list is a molecule because it should be able to accept other elements as items. E.g. it should be content independent.

===Menu {molecule}===

A menu is a familiar concept for any site. Probably the first thing that pops to mind for many is the navbar, but I want to consider that a separate component as a navbar can consist of more than just menu items.
I think a menu should be a collection of actions the user can perform. Perhaps with some form of hierarchy.

We have different types of menus within Moodle:
* The custom menu is one users can directly create, with dropdown downs and sub dropdowns.
* The action_menu component we have in core uses icons as actions and can have a dropdown.

These should be combined into a single menu element that takes items as an argument, likely actions + dropdowns + dividers to start with would be perfect.

We would likely need to deal with the display of the menu with properties to allow constructing code to ''request'' a particular style of menu. The renderer should be what actually gets to decide, but for the purposes of re-use having properties and a single render_method is better than having multiple render methods.<br />
The following is my initial thoughts on menu structure:
* Direction: Horizontal, Vertical
* Design: Default, Tabs,
* Style: Default, Links, Buttons, Icons

===Notification {atom}===
* Info
* Success
* Warning
* Danger

===Navigation bar {organism}===
Formerly navbar, can't be called that because the render method would conflict.

The navigation bar is just that, it is becoming increasingly common on the web and usually contains a title or logo, a menu, and information pertaining to the user state (login, language etc).

===Page header {molecule}===

Currently being produced by '''core_renderer::page_heading''' this is simply a header for the page, by default the only h1 element on the page.

'''Current structure'''

The render method has the following signature:
<code php>
public function page_heading($tag = 'h1');
</code>

The output from the above method is:
<code html5>
<h1>The page heading (from moodle_page::heading)</h1>
</code>

The core_renderer method should not allow the tag to be set. The page heading should always be H1.
If its not an H1 then page header should not be used.

'''Frontend framework examples'''

[http://getbootstrap.com/2.3.2/components.html#typography Bootstrap 2.3.2]
<code html5>
<div class="hero-unit">
<h1>Heading</h1>
<p>Tagline</p>
<p>
<a class="btn btn-primary btn-large">
Learn more
</a>
</p>
</div>
</code>

[http://getbootstrap.com/components/#page-header Bootstrap 3]
<code html5>
<div class="page-header">
<h1>Example page header <small>Subtext for header</small></h1>
</div>
</code>

Foundation doesn't appear to have a page header component.

'''Design thoughts'''

* In Moodle all page headings are set as a single string, we won't be changing this.
* Usually just a plain string sometimes an icon is used, and sometimes a help icon is used.

===Pagination {molecule}===

I like the idea of this being separate to a menu, and to other navigation oriented elements because it should be something that can easily be constructed with a few basic parameters and allow us to achieve consistent pagination throughout Moodle.<br />
It also appeals because this is something that people may want to style differently to their navigation.

'''Markup in various frontend frameworks'''

* [http://getbootstrap.com/2.3.2/components.html#pagination Bootstrap 2.3.2 pagination]
* [http://getbootstrap.com/components/#pagination Bootstrap 3 pagination]
* [http://foundation.zurb.com/docs/components/pagination.html Zurb foundation pagination]

===Progress bars {molecule}===

A pretty simple concept, we already have a couple of ways of producing progress bars within Moodle.

'''Markup in various frontend frameworks'''

[http://getbootstrap.com/2.3.2/components.html#progress Bootstrap 2.3.2]
<code html5>
<div class="progress">
<div class="bar" style="width: 60%;"></div>
</div>
</code>

The following options are offered by Bootstrap 2.3.2:

* Striped
* Striped + Animated
* Stacked (multiple bars forming a single)
* Colours: default (blue), info (light blue), success (green), warning (orange), danger (red)

[http://getbootstrap.com/components/#progress Bootstrap 3]
<code html5>

<div class="progress">
<div class="progress-bar" role="progressbar" aria-valuenow="60" aria-valuemin="0" aria-valuemax="100" style="width: 60%;">
60% Complete
</div>
</div>


<div class="progress">
<div class="progress-bar" role="progressbar" aria-valuenow="60" aria-valuemin="0" aria-valuemax="100" style="width: 60%;">
60%
</div>
</div>
</code>

The following options are offered by Bootstrap 3:

* Striped
* Striped + Animated
* Stacked (multiple bars forming a single)
* Colours: default (blue), info (light blue), success (green), warning (orange), danger (red)

[http://foundation.zurb.com/docs/components/progress_bars.html Zurb foundation]

<code html5>
<div class="progress">
<span class="meter"></span>
</div>
</code>

The following options are offered by Zurb foundation:
* Width
* Colours: default (blue), secondary (grey), success (green), alert (red)
* Corner style: default (square), radius (slight rounding), round

===Search {molecule}===

A pretty common interface molecule, and in fact used as an example in the atomic design blog post we keep referencing.<br />
We don't have a component for searching yet, however we've several search boxes throughout Moodle. The admin setting search box is the first to come to mind for me, followed by the forum search box and course search box.

'''Design considerations'''

Constructed of the following items:
* Text input
* Action (must be a button for submit I imagine)
* Label or short description (optional)
* Collapsible region containing settings etc (optional)

===Table {organism}===

We've two primary table components within Moodle presently '''html_table''' and '''flexible_table''' both of which offer different advantages and disadvantages. This will be a challenge and will really require some proper research and community interaction.

===Timer===

===Tree===

===User badge===

===User content===

Think of this like the forum post. We need a common structure in which to display content entered by the user along with information on the user. The users name, picture, date perhaps, title, content, footer (attachments, badges, what ever).
It could be applied to things like forum posts, calendar events etc.

At present we have no abstraction for this.

==Existing renderables and what they will become==
{| class="wikitable"
! Existing renderable
! Description
! Future renderable
! Convenience method (if different)
|-
| action_menu
| UI component for a drop down edit menu
| menu
|
|-
| action_menu_link
| UI component for a menu item in an action menu
| action
|
|-
| action_menu_filler
| UI component for a filler menu item in an action menu
| action
|
|-
| action_menu_link_primary
| UI component for a primary menu item in an action menu
| action
|
|-
| action_menu_link_secondary
| UI component for a secondary menu item in an action menu
| action
|
|-
| action_link
| Link with alt text, and an icon
| action
|
|-
| single_button
| A form with a single button
| button (action with post method)
|
|-
| confirm
| A form with a message and cancel/confirm buttons
| confirmation
|
|-
| single_select
| A form with a single drop down list that submits on change
|
|
|-
| url_select
| A navigation element consisting of a single drop down list of urls that navigates on change
|
|
|-
| doc_link
| A link to the Moodle docs
|
|
|-
| pix_icon
| A small icon
| icon
|
|-
| emoticon_icon
| A small emoticon
|
|
|-
| heading_with_help
| A page heading with a link to help docs
| heading
|
|-
| help_icon
| A help icon that opens a help popup when clicked
| icon_help
|
|-
| help_icon_scale
| A help icon that opens a help popup when clicked
|
|
|-
| user_picture
| A user profile picture which links to their profile
|
|
|-
| container
| A block level element used to surround something. Can have a class to allow specific targeting with CSS.
|
|
|-
| error_text
| An error to show to the user.
|
|
|-
| notification
| A message for the user
|
|
|-
| continue_button
| A message and a button to continue to the next page
|
|
|-
| paging_bar
| A list of next previous and specific page links
|
|
|-
| skip_link_to
| A link to a section on the page
|
|
|-
| skip_link_target
| A target for a matching skip_link_to call
|
|
|-
| heading
| A page heading
| heading
|
|-
| box
| A page section with a border
|
|
|-
| rarrow
| A right arrow
|
|
|-
| larrow
| A left arrow
|
|
|-
| tabtree
| A list of tabs
| menu
|
|-
| tabobject
| A single tab panel
| action
|
|}

==See also==
* [[User:Sam Hemelryk/Render library element planning]]
* [[Guide to creating output elements]] ''originally written at [[User:Sam Hemelryk/Creating renderable components]]''
* [[User:Sam Hemelryk/Renderer best practices]]
* [[User:Sam Hemelryk/CSS style guidelines]]