Element Library

Warning: This page is no longer in use. The information contained on the page should NOT be seen as relevant or reliable.

Element Library
Project state	Specification
Tracker issue	https://tracker.moodle.org/browse/MDL-45770
Discussion	https://moodle.org/mod/forum/discuss.php?d=261202
Assignee	Damyon, Sam

Note: This page relates to an abandoned project.

The element library will be a new admin tool that will display the output from a list of renderer methods / renderables. The target users for the tool are:

• Themers, used to test all the existing renderables in a newly developed theme
• Developers, used to see an organized list of all the renderables that can be used when building new pages (and the docs for them)

The requirements for this tool are:

• Show a list of renderables / renderer methods for a specific component
• Show the same renderable / renderer method rendered with different test data
• Show designer docs on the recommended usage of a specific element
• Allow easy testing in LTR/RTL and different screen sizes
• Direct links to the documentation for renderers / renderables
• Report on the list of renderables used by a renderable / renderer method
• Testing with different language directions

Some optional requirements:

• Perform some checks on the renderer to verify it contains no db queries etc
• Responsive testing in the tool (short-cuts to adjust the window size)

This tool will work by querying a core api for getting a list of renderer_sample_base instances from each plugin. The renderer_sample_base is an abstract class that provides documentation and an example rendering of either a renderer method or a renderable.

How to add something to the element library (for developers)

Each "thing" in the element library - is rendered by an instance of a \core\output\renderer_sample_base class.

For a plugin (or core) to add a new "thing" they must:

A) Implement the tests in subclasses of "\core\output\renderer_sample_base". These classes can have any name, but it is recommended to name them as "\{plugin namespace}\output\XXX_renderer_sample". Each test must define a "execute()" method which produces the output, as well as supply developer docs, a name for the test and a category.

Note: the renderer should be able to produce it's output relying completely on the data contained in its own arguments or the renderable. If it is performing additional DB queries etc - it will probably fail when provided with "mock" data. In this situation, you should consider refactoring the renderer so it does not perform DB queries.

B) Extend the abstract class "\core\output\renderer_sample_generator_base" with a new class named "\{plugin namespace}\output\renderer_sample_generator". This class needs to extend "\core\output\renderer_sample_generator_base". There is one function to implement, which is the "create_samples" function which accepts no arguments and returns a list of subclasses of "\core\output\renderer_sample_base" (implemented in step A).

Note - the non-namespaced class name "{plugin name}_output_renderer_sample_generator" is also supported.

Example: Adding "Assign user summary" (TODO - change this example to a core renderable)

A) Add a new class "\mod_assign\output\assign_user_summary_renderer_sample" which extends "\core\output\renderer_sample_base".

This class should set the "name, docs and category" class variables in it's constructor. The "execute" method should create a "assign_user_summary" instance filled with dummy data, get a 'mod_assign' renderer and call render on the "assign_user_dummy" class.

File: mod/assign/classes/output/assign_user_summary_renderer_sample.php
<?php

namespace mod_assign\output;

class assign_user_summary_renderer_sample extends \core\output\renderer_sample_base {

    public function __construct() {
        $this->name = 'Assign user summary';
        $this->docs = 'A user summary object that is used to display information about a user in multiple places in mod_assign.';
        $this->category = \core\output\renderer_sample_base::CATEGORY_COMPONENT;
    }

    public function execute() {
        global $CFG, $PAGE;

        require_once($CFG->dirroot . '/mod/assign/renderable.php');

        $renderer = $PAGE->get_renderer('mod_assign');
        $mockuser = guest_user();
        $mockcourseid = 5;
        $viewfullnames = true;
        $blindmarking = false;
        $mockuniqueidforuser = 5;
        $mockextrauserfields = array();
        $suspendeduser = false;

        $renderable = new \assign_user_summary($mockuser,
                                              $mockcourseid,
                                              $viewfullnames,
                                              $blindmarking,
                                              $mockuniqueidforuser,
                                              $mockextrauserfields,
                                              $suspendeduser);

        return $renderer->render($renderable);
    }
}

B) Implement the renderable_sample_generator for mod_assign

File: mod/assign/classes/output/renderable_sample_generator.php
<?php
namespace mod_assign\output;

class renderer_sample_generator extends \core\output\renderer_sample_generator_base {
    public function create_samples() {
        $tests = array(new assign_user_summary_renderer_sample());
        return $tests;
    }
}

Related links

• Render library specification