Element Library: Difference between revisions
Damyon Wiese (talk | contribs) No edit summary |
(Mark project as abandoned.) |
||
(15 intermediate revisions by 4 users not shown) | |||
Line 1: | Line 1: | ||
{{Infobox Project | {{Infobox Project | ||
|name = Element Library | |name = Element Library | ||
Line 7: | Line 6: | ||
|assignee = Damyon, Sam | |assignee = Damyon, Sam | ||
}} | }} | ||
{{Abandoned|forumurl=https://moodle.org/mod/forum/discuss.php?d=261202}} | |||
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: | 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 | * Themers, used to test all the existing renderables in a newly developed theme | ||
Line 18: | Line 17: | ||
* Allow easy testing in LTR/RTL and different screen sizes | * Allow easy testing in LTR/RTL and different screen sizes | ||
* Direct links to the documentation for renderers / renderables | * 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: | Some optional requirements: | ||
* Perform some checks on the renderer to verify it contains no db queries etc | * 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) | * 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 | |||
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) == | == 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. | |||
<syntaxhighlight lang="php"> | |||
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); | |||
} | |||
} | |||
</syntaxhighlight> | |||
B) Implement the renderable_sample_generator for mod_assign | |||
<syntaxhighlight lang="php"> | |||
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; | |||
} | |||
} | |||
</syntaxhighlight> | |||
== Related links == | == Related links == | ||
* [[Render library specification]] | * [[Render library specification]] |
Latest revision as of 07:48, 21 September 2021
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;
}
}