project: Moodle
summary: Moving from renderers to templates
description: First we need to add some more features to the templating system so that we can be productive writing templates, then we need to work on the generic reusable templates, then start converting existing renderers to the new system.

1.summary: Create core template "Tabs"
description: Needs aria support.
2.summary: Create core template "media"
description: This is an image followed by text. See bootstrap.
3.summary: New mustache-powered search select box
description: Moodle has many searchable select boxes, but: they dont share common underpinnings they arent powered by templates Because of this, the surface area we can cover with searchable select boxes is both spotty and internally inconsistent. Unifying on one searchable select box powered by templates should: improve consistency in and around Moodle improve performance (no more rendering on server! just get the data and pass it to client-side Mustache) allow us to easily add new searchable select boxes
4.summary: Docs for devs working on core templates
description: This should include how to include javascript, naming conventions, etc.
5.summary: Add "Blocks" feature to JS and PHP mustache engines
description: This is a critical feature for building reusable templates. See: and and
6.summary: Add a way to rename variables in a mustache template
description: e.g. if my context does not have the exact variable names required for a partial I want to include, allowing me to rename the variables in my context will let me re-use the partial without manipulating the context in php.
7.summary: Add a way to pass arguments to mustache helpers (php and js)
description: right now - a helper will only receive the block of text from a section. Handlebars, (and others) allow helpers to receive arguments - e.g. str error filenotfound vs strerror filenotfound/str if we want to implement a conditional helper it will require this e.g. if contextvara "eq" "5" /if This allows us to have presentation logic in the templates, which will make the templates more re-usable.
8.summary: Add a conditional helper to mustache (php and js)
description: This would be a set of generic helpers that will evaluate a conditional and either print a section, or skip it. Example code lt replyCount "3" "Less than 3 replies" /lt code Full set of new conditionals are: eq, neq, lt, gt, lte, gte, and, or The arguments for these conditionals are resolved to variables in the current context by default, but strings, numbers and booleans are recognised and passed as their correct types.
9.summary: Add a hook so renderers can override export_for_template.
description: Currently, renderers can override the render method for a renderable, but not the export_for_template. render is only called for the outermost renderable - so things like pix_icons etc will only use the template and cannot be overridden in any other way but by changing the template. If some extra data needs to be added to the context for the overridden template, it is currently not possible. Instead of calling renderable->export_for_template() we should call renderer->export_for_template(renderable) which in turn calls renderable->export_for_template, this will allow renderers a hook to manipulate the data passed to the template. When creating external functions to export data for rendering in JS, we should use the same technique so that the one overridden export_for_template function will apply for php and js templates.
10.summary: New mustache-powered paging_bar
description: Split out into an improvement from so 2.8 can get some love over there. This improvement involves: moving paging_bar into its own file in lib/classes/output/paging_bar.php adjusting every use of paging_bar to \core\output\paging_bar in order to account for the namespace change adding a new Mustache template as lib/paging_bar.mustache adding the ability to hint the paging bar with regards to its display size (a new \core\output\paging_bar::displaysize option, which can be mini, small, or large The structure that the mustache template expects is: noformat "type": "Page", "links": "href": " "text": "<3 Moodle", "attrs": , "first": "href": " "text": "0", "attrs": , "last": "href": " "text": "120", "attrs": noformat
11.summary: Write a spec how/which core templates to create
description: We need to provide a comprehensive set of core template that devs can use to built interfaces without having to write a lot of custom HTML every time. Places to get ideas for templates: Bootstrap features mforms :D
12.summary: Allow some ajax external functions to be called without a session
description: There are some external functions that return static data that is completely public. Examples are language strings and templates. If we create a second entry point for these scripts, and introduce a new field to the services.php array to mark the functions that are safe to call this way, we can improve performance. This new script would not lock the session, so it could handle parallel requests - and it would be able to verify whether or not to allow calling this external function in this way. An alternative design that was discussed was to have a second ajax.php file in db/ for each component and bypass the webservices for these ajax functions - but I (Damo) would like to encourage/test the webservices framework alongside the ajax external functions.
13.summary: Create core template "Hero"
description: This is based on the bootstrap "Jumbotron". It has a title, and content sections.
14.summary: Create core template "Toolbar"
description: List of buttons with support for button groups. Needs full aria support.
15.summary: Create core template "list"
description: A list of things.
16.summary: Create core template "Panel"
description: A panel is a visually distinctive section of the page used to group related things together.
17.summary: Create core template "2 columns, 2:1"
description: The first column is twice the width of the second. On mobile, the second column collapses underneath.
18.summary: Create core template "2 columns 1:2"
description: The second column is twice as wide as the first. On mobile the second column collapses underneath the first.
19.summary: Create core template 3 columns manual
description: 3 column template where the items are manually placed in columns. On mobile the columns stack underneath each other.
20.summary: Create core template "3 columns auto"
description: 3 column template where the content automatically flows from one column to the next in order to balance all 3 columns. Based on CSS3.
21.summary: Create core template 2 columns centered.
description: This is used in e.g. forms where the labels and inputs are right/left aligned. On mobile the items in the right column should collapse under each of the items from the left column.
22.summary: Create core template "collapsible region"
description: This is a region with a toggle to show/hide it.
23.summary: Create core template "dialog"
description: And hook it in wherever possible.
24.summary: Create core template inline list.
description: E.g. for a horizontal list of buttons.
25.summary: Show raw template source in template library
description: Itd be nice to allow users to toggle the example template block from the rendered HTML to the raw mustache template source. At the moment the page only shows the rendered template and you cant see what it looks like as a raw mustache source without going into the code to view it. The template library page is here: admin/tool/templatelibrary/index.php
26.summary: Display path to override template in the template library
description: Users that are viewing templates in the template library (admin/tool/templatelibrary/index.php) should be given the path in Moodle to create a custom template that overrides the one they are viewing. The code attempts to find templates in the current themes directory, so if someone wants to override one of the core templates then they need to do so in their themes directly. Displaying exactly where to create the file will make it easier for them.
27.summary: Move example contexts out of comment block
description: At the moment the example contexts for templates in a comment block along side the documentation. The template lib page will parse the comment and look for "Example context (json):" to extract the context. It would be nice to move this out of the comment block and have it loaded from disk by the template lib. Well need to update the template library pages javascript so that it retrieves the context with an ajax request (similar to how it retrieves the templates), rather than by parsing the comment block, in order to render the example. The example contexts could be identified by convention, we could say that each example must be located in the same directory as the template and must be the template name followed by ".example.json" or something. E.g. template: lib/templates/notification_message.mustache example context: lib/templates/notification_message.example.json
28.summary: Create unique id helper for guaranteed unique section
description: We need to add a helper for a template section that indicates that the "uniqid" keyword should generate a new globally unique value inside that block while not effecting the unique id outside the section. This can be achieved by having the template engine keep a stack of unique ids, when it hits this tag it can create a new id and add it to the stack, when it hits the closing tag it can pop it back off the stack. The javascript unique id will likely need to be changed to a hash, rather than an incrementing integer, to allow the stack to work correctly. To illustrate the point, a sample template might look like noformat Link 1 reset-uniqid Link 2 / reset-uniqid Link 3 noformat In the above example the "Link 1" and "Link 3" elements should receive the same value for "uniqid" while the value for "uniqid" for "Link 2" should be a new and different globally unique value, since its inside the "reset-uniqid" section. Im not sure that "reset-uniqid" is the best name, but you get the idea...

Below is an instruction that describes a task, paired with an input that provides an epic with this format: 
"project": "Name of the project" 
"summary": "Summary of the epic user story" 
"description": "Description of the epic user story". Write a response that appropriately completes the request.### Instruction:
Break this epic user story into smaller tasks to help the developers understand the epic better, you can divide this epic into as much as you want depending on the complexity of the epic.
### Input:
project: Moodle
summary: Moving from renderers to templates
description: First we need to add some more features to the templating system so that we can be productive writing templates, then we need to work on the generic reusable templates, then start converting existing renderers to the new system.

### Response:
1.summary: Create core template "Tabs"
description: Needs aria support.
2.summary: Create core template "media"
description: This is an image followed by text. See bootstrap.
3.summary: New mustache-powered search select box
description: Moodle has many searchable select boxes, but: they dont share common underpinnings they arent powered by templates Because of this, the surface area we can cover with searchable select boxes is both spotty and internally inconsistent. Unifying on one searchable select box powered by templates should: improve consistency in and around Moodle improve performance (no more rendering on server! just get the data and pass it to client-side Mustache) allow us to easily add new searchable select boxes
4.summary: Docs for devs working on core templates
description: This should include how to include javascript, naming conventions, etc.
5.summary: Add "Blocks" feature to JS and PHP mustache engines
description: This is a critical feature for building reusable templates. See: and and
6.summary: Add a way to rename variables in a mustache template
description: e.g. if my context does not have the exact variable names required for a partial I want to include, allowing me to rename the variables in my context will let me re-use the partial without manipulating the context in php.
7.summary: Add a way to pass arguments to mustache helpers (php and js)
description: right now - a helper will only receive the block of text from a section. Handlebars, (and others) allow helpers to receive arguments - e.g. str error filenotfound vs strerror filenotfound/str if we want to implement a conditional helper it will require this e.g. if contextvara "eq" "5" /if This allows us to have presentation logic in the templates, which will make the templates more re-usable.
8.summary: Add a conditional helper to mustache (php and js)
description: This would be a set of generic helpers that will evaluate a conditional and either print a section, or skip it. Example code lt replyCount "3" "Less than 3 replies" /lt code Full set of new conditionals are: eq, neq, lt, gt, lte, gte, and, or The arguments for these conditionals are resolved to variables in the current context by default, but strings, numbers and booleans are recognised and passed as their correct types.
9.summary: Add a hook so renderers can override export_for_template.
description: Currently, renderers can override the render method for a renderable, but not the export_for_template. render is only called for the outermost renderable - so things like pix_icons etc will only use the template and cannot be overridden in any other way but by changing the template. If some extra data needs to be added to the context for the overridden template, it is currently not possible. Instead of calling renderable->export_for_template() we should call renderer->export_for_template(renderable) which in turn calls renderable->export_for_template, this will allow renderers a hook to manipulate the data passed to the template. When creating external functions to export data for rendering in JS, we should use the same technique so that the one overridden export_for_template function will apply for php and js templates.
10.summary: New mustache-powered paging_bar
description: Split out into an improvement from so 2.8 can get some love over there. This improvement involves: moving paging_bar into its own file in lib/classes/output/paging_bar.php adjusting every use of paging_bar to \core\output\paging_bar in order to account for the namespace change adding a new Mustache template as lib/paging_bar.mustache adding the ability to hint the paging bar with regards to its display size (a new \core\output\paging_bar::displaysize option, which can be mini, small, or large The structure that the mustache template expects is: noformat "type": "Page", "links": "href": " "text": "<3 Moodle", "attrs": , "first": "href": " "text": "0", "attrs": , "last": "href": " "text": "120", "attrs": noformat
11.summary: Write a spec how/which core templates to create
description: We need to provide a comprehensive set of core template that devs can use to built interfaces without having to write a lot of custom HTML every time. Places to get ideas for templates: Bootstrap features mforms :D
12.summary: Allow some ajax external functions to be called without a session
description: There are some external functions that return static data that is completely public. Examples are language strings and templates. If we create a second entry point for these scripts, and introduce a new field to the services.php array to mark the functions that are safe to call this way, we can improve performance. This new script would not lock the session, so it could handle parallel requests - and it would be able to verify whether or not to allow calling this external function in this way. An alternative design that was discussed was to have a second ajax.php file in db/ for each component and bypass the webservices for these ajax functions - but I (Damo) would like to encourage/test the webservices framework alongside the ajax external functions.
13.summary: Create core template "Hero"
description: This is based on the bootstrap "Jumbotron". It has a title, and content sections.
14.summary: Create core template "Toolbar"
description: List of buttons with support for button groups. Needs full aria support.
15.summary: Create core template "list"
description: A list of things.
16.summary: Create core template "Panel"
description: A panel is a visually distinctive section of the page used to group related things together.
17.summary: Create core template "2 columns, 2:1"
description: The first column is twice the width of the second. On mobile, the second column collapses underneath.
18.summary: Create core template "2 columns 1:2"
description: The second column is twice as wide as the first. On mobile the second column collapses underneath the first.
19.summary: Create core template 3 columns manual
description: 3 column template where the items are manually placed in columns. On mobile the columns stack underneath each other.
20.summary: Create core template "3 columns auto"
description: 3 column template where the content automatically flows from one column to the next in order to balance all 3 columns. Based on CSS3.
21.summary: Create core template 2 columns centered.
description: This is used in e.g. forms where the labels and inputs are right/left aligned. On mobile the items in the right column should collapse under each of the items from the left column.
22.summary: Create core template "collapsible region"
description: This is a region with a toggle to show/hide it.
23.summary: Create core template "dialog"
description: And hook it in wherever possible.
24.summary: Create core template inline list.
description: E.g. for a horizontal list of buttons.
25.summary: Show raw template source in template library
description: Itd be nice to allow users to toggle the example template block from the rendered HTML to the raw mustache template source. At the moment the page only shows the rendered template and you cant see what it looks like as a raw mustache source without going into the code to view it. The template library page is here: admin/tool/templatelibrary/index.php
26.summary: Display path to override template in the template library
description: Users that are viewing templates in the template library (admin/tool/templatelibrary/index.php) should be given the path in Moodle to create a custom template that overrides the one they are viewing. The code attempts to find templates in the current themes directory, so if someone wants to override one of the core templates then they need to do so in their themes directly. Displaying exactly where to create the file will make it easier for them.
27.summary: Move example contexts out of comment block
description: At the moment the example contexts for templates in a comment block along side the documentation. The template lib page will parse the comment and look for "Example context (json):" to extract the context. It would be nice to move this out of the comment block and have it loaded from disk by the template lib. Well need to update the template library pages javascript so that it retrieves the context with an ajax request (similar to how it retrieves the templates), rather than by parsing the comment block, in order to render the example. The example contexts could be identified by convention, we could say that each example must be located in the same directory as the template and must be the template name followed by ".example.json" or something. E.g. template: lib/templates/notification_message.mustache example context: lib/templates/notification_message.example.json
28.summary: Create unique id helper for guaranteed unique section
description: We need to add a helper for a template section that indicates that the "uniqid" keyword should generate a new globally unique value inside that block while not effecting the unique id outside the section. This can be achieved by having the template engine keep a stack of unique ids, when it hits this tag it can create a new id and add it to the stack, when it hits the closing tag it can pop it back off the stack. The javascript unique id will likely need to be changed to a hash, rather than an incrementing integer, to allow the stack to work correctly. To illustrate the point, a sample template might look like noformat Link 1 reset-uniqid Link 2 / reset-uniqid Link 3 noformat In the above example the "Link 1" and "Link 3" elements should receive the same value for "uniqid" while the value for "uniqid" for "Link 2" should be a new and different globally unique value, since its inside the "reset-uniqid" section. Im not sure that "reset-uniqid" is the best name, but you get the idea...
