From 0664130b883679096f9df0f456a1ff5ce2bc6108 Mon Sep 17 00:00:00 2001 From: Ryan Wyllie Date: Mon, 10 Dec 2018 14:47:44 +0800 Subject: [PATCH] MDL-64348 templates: add mustache_template_source_loader class --- .../mustache_template_source_loader.php | 342 ++++++++++++++ .../mustache_template_source_loader_test.php | 445 ++++++++++++++++++ 2 files changed, 787 insertions(+) create mode 100644 lib/classes/output/mustache_template_source_loader.php create mode 100644 lib/tests/mustache_template_source_loader_test.php diff --git a/lib/classes/output/mustache_template_source_loader.php b/lib/classes/output/mustache_template_source_loader.php new file mode 100644 index 00000000000..6be12750e22 --- /dev/null +++ b/lib/classes/output/mustache_template_source_loader.php @@ -0,0 +1,342 @@ +. + +/** + * Load template source strings. + * + * @package core + * @category output + * @copyright 2018 Ryan Wyllie + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ + +namespace core\output; + +defined('MOODLE_INTERNAL') || die(); + +use \Mustache_Tokenizer; + +/** + * Load template source strings. + * + * @copyright 2018 Ryan Wyllie + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ +class mustache_template_source_loader { + + /** @var $gettemplatesource Callback function to load the template source from full name */ + private $gettemplatesource = null; + + /** + * Constructor that takes a callback to allow the calling code to specify how to retrieve + * the source for a template name. + * + * If no callback is provided then default to the load from disk implementation. + * + * @param callable|null $gettemplatesource Callback to load template source by template name + */ + public function __construct(callable $gettemplatesource = null) { + if ($gettemplatesource) { + // The calling code has specified a function for retrieving the template source + // code by name and theme. + $this->gettemplatesource = $gettemplatesource; + } else { + // By default we will pull the template from disk. + $this->gettemplatesource = function($component, $name, $themename) { + $fulltemplatename = $component . '/' . $name; + $filename = mustache_template_finder::get_template_filepath($fulltemplatename, $themename); + return file_get_contents($filename); + }; + } + } + + /** + * Remove comments from mustache template. + * + * @param string $templatestr + * @return string + */ + protected function strip_template_comments($templatestr) : string { + return preg_replace('/(?={{!)(.*)(}})/sU', '', $templatestr); + } + + /** + * Load the template source from the component and template name. + * + * @param string $component The moodle component (e.g. core_message) + * @param string $name The template name (e.g. message_drawer) + * @param string $themename The theme to load the template for (e.g. boost) + * @param bool $includecomments If the comments should be stripped from the source before returning + * @return string The template source + */ + public function load( + string $component, + string $name, + string $themename, + bool $includecomments = false + ) : string { + // Get the template source from the callback. + $source = ($this->gettemplatesource)($component, $name, $themename); + + // Remove comments from template. + if (!$includecomments) { + $source = $this->strip_template_comments($source); + } + + return $source; + } + + /** + * Load a template and some of the dependencies that will be needed in order to render + * the template. + * + * The current implementation will return all of the templates and all of the strings in + * each of those templates (excluding string substitutions). + * + * The return format is an array indexed with the dependency type (e.g. templates / strings) then + * the component (e.g. core_message), and then the id (e.g. message_drawer). + * + * For example: + * * We have 3 templates in core named foo, bar, and baz. + * * foo includes bar and bar includes baz. + * * foo uses the string 'home' from core + * * baz uses the string 'help' from core + * + * If we load the template foo this function would return: + * [ + * 'templates' => [ + * 'core' => [ + * 'foo' => '... template source ...', + * 'bar' => '... template source ...', + * 'baz' => '... template source ...', + * ] + * ], + * 'strings' => [ + * 'core' => [ + * 'home' => 'Home', + * 'help' => 'Help' + * ] + * ] + * ] + * + * @param string $templatecomponent The moodle component (e.g. core_message) + * @param string $templatename The template name (e.g. message_drawer) + * @param string $themename The theme to load the template for (e.g. boost) + * @param bool $includecomments If the comments should be stripped from the source before returning + * @param array $seentemplates List of templates already processed / to be skipped. + * @param array $seenstrings List of strings already processed / to be skipped. + * @return array + */ + public function load_with_dependencies( + string $templatecomponent, + string $templatename, + string $themename, + bool $includecomments = false, + array $seentemplates = [], + array $seenstrings = [] + ) : array { + // Initialise the return values. + $templates = []; + $strings = []; + $templatecomponent = trim($templatecomponent); + $templatename = trim($templatename); + // Get the requested template source. + $templatesource = $this->load($templatecomponent, $templatename, $themename, $includecomments); + // This is a helper function to save a value in one of the result arrays (either $templates or $strings). + $save = function(array $results, array $seenlist, string $component, string $id, $value) { + if (!isset($results[$component])) { + // If the results list doesn't already contain this component then initialise it. + $results[$component] = []; + } + + // Save the value. + $results[$component][$id] = $value; + // Record that this item has been processed. + array_push($seenlist, "$component/$id"); + // Return the updated results and seen list. + return [$results, $seenlist]; + }; + // This is a helper function for processing a dependency. Does stuff like ignore duplicate processing, + // common result formatting etc. + $handler = function(array $dependency, array $ignorelist, callable $processcallback) { + foreach ($dependency as $component => $ids) { + foreach ($ids as $id) { + $dependencyid = "$component/$id"; + if (array_search($dependencyid, $ignorelist) === false) { + $processcallback($component, $id); + // Add this to our ignore list now that we've processed it so that we don't + // process it again. + array_push($ignorelist, $dependencyid); + } + } + } + + return $ignorelist; + }; + + // Save this template as the first result in the $templates result array. + list($templates, $seentemplates) = $save($templates, $seentemplates, $templatecomponent, $templatename, $templatesource); + + // Check the template for any dependencies that need to be loaded. + $dependencies = $this->scan_template_source_for_dependencies($templatesource); + + // Load all of the lang strings that this template requires and add them to the + // returned values. + $seenstrings = $handler( + $dependencies['strings'], + $seenstrings, + // Include $strings and $seenstrings by reference so that their values can be updated + // outside of this anonymous function. + function($component, $id) use ($save, &$strings, &$seenstrings) { + $string = get_string($id, $component); + // Save the string in the $strings results array. + list($strings, $seenstrings) = $save($strings, $seenstrings, $component, $id, $string); + } + ); + + // Load any child templates that we've found in this template and add them to + // the return list of dependencies. + $seentemplates = $handler( + $dependencies['templates'], + $seentemplates, + // Include $strings, $seenstrings, $templates, and $seentemplates by reference so that their values can be updated + // outside of this anonymous function. + function($component, $id) use ( + $themename, + $includecomments, + &$seentemplates, + &$seenstrings, + &$templates, + &$strings, + $save + ) { + // We haven't seen this template yet so load it and it's dependencies. + $subdependencies = $this->load_with_dependencies( + $component, + $id, + $themename, + $includecomments, + $seentemplates, + $seenstrings + ); + + foreach ($subdependencies['templates'] as $component => $ids) { + foreach ($ids as $id => $value) { + // Include the child themes in our results. + list($templates, $seentemplates) = $save($templates, $seentemplates, $component, $id, $value); + } + }; + + foreach ($subdependencies['strings'] as $component => $ids) { + foreach ($ids as $id => $value) { + // Include any strings that the child templates need in our results. + list($strings, $seenstrings) = $save($strings, $seenstrings, $component, $id, $value); + } + } + } + ); + + return [ + 'templates' => $templates, + 'strings' => $strings + ]; + } + + /** + * Scan over a template source string and return a list of dependencies it requires. + * At the moment the list will only include other templates and strings. + * + * The return format is an array indexed with the dependency type (e.g. templates / strings) then + * the component (e.g. core_message) with it's value being an array of the items required + * in that component. + * + * For example: + * If we have a template foo that includes 2 templates, bar and baz, and also 2 strings + * 'home' and 'help' from the core component then the return value would look like: + * + * [ + * 'templates' => [ + * 'core' => ['foo', 'bar', 'baz'] + * ], + * 'strings' => [ + * 'core' => ['home', 'help'] + * ] + * ] + * + * @param string $source The template source + * @return array + */ + protected function scan_template_source_for_dependencies(string $source) : array { + $tokenizer = new Mustache_Tokenizer(); + $tokens = $tokenizer->scan($source); + $templates = []; + $strings = []; + $addtodependencies = function($dependencies, $component, $id) { + $id = trim($id); + $component = trim($component); + + if (!isset($dependencies[$component])) { + // Initialise the component if we haven't seen it before. + $dependencies[$component] = []; + } + + // Add this id to the list of dependencies. + array_push($dependencies[$component], $id); + + return $dependencies; + }; + + foreach ($tokens as $index => $token) { + $type = $token['type']; + $name = isset($token['name']) ? $token['name'] : null; + + if ($name) { + switch ($type) { + case Mustache_Tokenizer::T_PARTIAL: + list($component, $id) = explode('/', $name); + $templates = $addtodependencies($templates, $component, $id); + break; + case Mustache_Tokenizer::T_PARENT: + list($component, $id) = explode('/', $name); + $templates = $addtodependencies($templates, $component, $id); + break; + case Mustache_Tokenizer::T_SECTION: + if ($name == 'str') { + // The token that containts the string identifiers (key and component) should + // immediately follow the #str token. + $identifiertoken = isset($tokens[$index + 1]) ? $tokens[$index + 1] : null; + + if ($identifiertoken) { + // The string identifier is the key and component comma separated. + $identifierstring = $identifiertoken['value']; + $parts = explode(',', $identifierstring); + $id = $parts[0]; + // Default to 'core' for the component, if not specified. + $component = isset($parts[1]) ? $parts[1] : 'core'; + $strings = $addtodependencies($strings, $component, $id); + } + } + break; + } + } + } + + return [ + 'templates' => $templates, + 'strings' => $strings + ]; + } +} diff --git a/lib/tests/mustache_template_source_loader_test.php b/lib/tests/mustache_template_source_loader_test.php new file mode 100644 index 00000000000..1ccac41b1e5 --- /dev/null +++ b/lib/tests/mustache_template_source_loader_test.php @@ -0,0 +1,445 @@ +. + +/** + * Unit tests for lib/classes/output/mustache_template_source_loader.php + * + * @package core + * @copyright 2018 Ryan Wyllie + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ + +defined('MOODLE_INTERNAL') || die(); + +use core\output\mustache_template_source_loader; + +/** + * Unit tests for the Mustache source loader class. + * + * @package core + * @copyright 2018 Ryan Wyllie + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ +class core_output_mustache_template_source_loader_testcase extends advanced_testcase { + /** + * Ensure that stripping comments from templates does not mutilate the template body. + */ + public function test_strip_template_comments() { + + $templatebody = <<<'TBD' +

{{# str }} pluginname, mod_lemmings {{/ str }}

+
{{test}}
+
{{{unescapedtest}}}
+ {{#lemmings}} +
+

{{name}}

+ {{> mod_lemmings/lemmingprofile }} + {{# pix }} t/edit, core, Edit Lemming {{/ pix }} +
+ {{/lemmings}} + {{^lemmings}}Sorry, no lemmings today{{/lemmings}} +
+ {{# tabheader }} +
    + {{# iconlist }} + {{# icons }} + {{> core/pix_icon }} + {{/ icons }} + {{/ iconlist }} +
+ {{/ tabheader }} + {{# tabbody }} +
+ {{# tabcontent }} + {{# tabs }} + {{> core/notification_info}} + {{/ tabs }} + {{/ tabcontent }} +
+ {{/ tabbody }} +
+ {{#js}} + require(['jquery','core/tabs'], function($, tabs) { + + var container = $("#{{ uniqid }}-tab-container"); + tabs.create(container); + }); + {{/js}} +TBD; + $templatewithcomment = <<. + }} + {{! + @template mod_lemmings/lemmings + + Lemmings template. + + The purpose of this template is to render a lot of lemmings. + + Classes required for JS: + * none + + Data attributes required for JS: + * none + + Context variables required for this template: + * attributes Array of name / value pairs. + + Example context (json): + { + "lemmings": [ + { "name": "Lemmy Winks", "age" : 1, "size" : "big" }, + { "name": "Rocky", "age" : 2, "size" : "small" } + ] + } + + }} + $templatebody + {{! + Here's some more comment text + Note, there is no need to test bracketed variables inside comments as gherkin does not support that! + See this issue: https://github.com/mustache/spec/issues/8 + }} +TBC; + + $loader = new mustache_template_source_loader(); + $actual = phpunit_util::call_internal_method( + $loader, + 'strip_template_comments', + [$templatewithcomment], + \core\output\mustache_template_source_loader::class + ); + $this->assertEquals(trim($templatebody), trim($actual)); + } + + /** + * Data provider for the test_load function. + */ + public function test_load_test_cases() { + $cache = [ + 'core' => [ + 'test' => '{{! a comment }}The rest of the template' + ] + ]; + $loader = $this->build_loader_from_static_cache($cache); + + return [ + 'with comments' => [ + 'loader' => $loader, + 'component' => 'core', + 'name' => 'test', + 'includecomments' => true, + 'expected' => '{{! a comment }}The rest of the template' + ], + 'without comments' => [ + 'loader' => $loader, + 'component' => 'core', + 'name' => 'test', + 'includecomments' => false, + 'expected' => 'The rest of the template' + ], + ]; + } + + /** + * Test the load function. + * + * @dataProvider test_load_test_cases() + * @param mustache_template_source_loader $loader The loader + * @param string $component The moodle component + * @param string $name The template name + * @param bool $includecomments Whether to strip comments + * @param string $expected The expected output + */ + public function test_load($loader, $component, $name, $includecomments, $expected) { + $this->assertEquals($expected, $loader->load($component, $name, 'boost', $includecomments)); + } + + /** + * Data provider for the load_with_dependencies function. + */ + public function test_load_with_dependencies_test_cases() { + // Create a bunch of templates that include one another in various ways. There is + // multiple instances of recursive inclusions to test that the code doensn't get + // stuck in an infinite loop. + $foo = '{{! a comment }}{{> core/bar }}{{< test/bop }}{{/ test/bop}}{{#str}} help, core {{/str}}'; + $foo2 = '{{! a comment }}hello'; + $bar = '{{! a comment }}{{> core/baz }}'; + $baz = '{{! a comment }}{{#str}} hide, core {{/str}}'; + $bop = '{{! a comment }}{{< test/bim }}{{/ test/bim }}{{> core/foo }}'; + $bim = '{{! a comment }}{{< core/foo }}{{/ core/foo}}{{> test/foo }}'; + $foonocomment = '{{> core/bar }}{{< test/bop }}{{/ test/bop}}{{#str}} help, core {{/str}}'; + $foo2nocomment = 'hello'; + $barnocomment = '{{> core/baz }}'; + $baznocomment = '{{#str}} hide, core {{/str}}'; + $bopnocomment = '{{< test/bim }}{{/ test/bim }}{{> core/foo }}'; + $bimnocomment = '{{< core/foo }}{{/ core/foo}}{{> test/foo }}'; + $cache = [ + 'core' => [ + 'foo' => $foo, + 'bar' => $bar, + 'baz' => $baz, + ], + 'test' => [ + 'foo' => $foo2, + 'bop' => $bop, + 'bim' => $bim + ] + ]; + $loader = $this->build_loader_from_static_cache($cache); + + return [ + 'no template includes w comments' => [ + 'loader' => $loader, + 'component' => 'test', + 'name' => 'foo', + 'includecomments' => true, + 'expected' => [ + 'templates' => [ + 'test' => [ + 'foo' => $foo2 + ] + ], + 'strings' => [] + ] + ], + 'no template includes w/o comments' => [ + 'loader' => $loader, + 'component' => 'test', + 'name' => 'foo', + 'includecomments' => false, + 'expected' => [ + 'templates' => [ + 'test' => [ + 'foo' => $foo2nocomment + ] + ], + 'strings' => [] + ] + ], + 'no template includes with string w comments' => [ + 'loader' => $loader, + 'component' => 'core', + 'name' => 'baz', + 'includecomments' => true, + 'expected' => [ + 'templates' => [ + 'core' => [ + 'baz' => $baz + ] + ], + 'strings' => [ + 'core' => [ + 'hide' => 'Hide' + ] + ] + ] + ], + 'no template includes with string w/o comments' => [ + 'loader' => $loader, + 'component' => 'core', + 'name' => 'baz', + 'includecomments' => false, + 'expected' => [ + 'templates' => [ + 'core' => [ + 'baz' => $baznocomment + ] + ], + 'strings' => [ + 'core' => [ + 'hide' => 'Hide' + ] + ] + ] + ], + 'full with comments' => [ + 'loader' => $loader, + 'component' => 'core', + 'name' => 'foo', + 'includecomments' => true, + 'expected' => [ + 'templates' => [ + 'core' => [ + 'foo' => $foo, + 'bar' => $bar, + 'baz' => $baz + ], + 'test' => [ + 'foo' => $foo2, + 'bop' => $bop, + 'bim' => $bim + ] + ], + 'strings' => [ + 'core' => [ + 'help' => 'Help', + 'hide' => 'Hide' + ] + ] + ] + ], + 'full without comments' => [ + 'loader' => $loader, + 'component' => 'core', + 'name' => 'foo', + 'includecomments' => false, + 'expected' => [ + 'templates' => [ + 'core' => [ + 'foo' => $foonocomment, + 'bar' => $barnocomment, + 'baz' => $baznocomment + ], + 'test' => [ + 'foo' => $foo2nocomment, + 'bop' => $bopnocomment, + 'bim' => $bimnocomment + ] + ], + 'strings' => [ + 'core' => [ + 'help' => 'Help', + 'hide' => 'Hide' + ] + ] + ] + ] + ]; + } + + /** + * Test the load_with_dependencies function. + * + * @dataProvider test_load_with_dependencies_test_cases() + * @param mustache_template_source_loader $loader The loader + * @param string $component The moodle component + * @param string $name The template name + * @param bool $includecomments Whether to strip comments + * @param string $expected The expected output + */ + public function test_load_with_dependencies($loader, $component, $name, $includecomments, $expected) { + $actual = $loader->load_with_dependencies($component, $name, 'boost', $includecomments); + $this->assertEquals($expected, $actual); + } + /** + * Data provider for the test_load function. + */ + public function test_scan_template_source_for_dependencies_test_cases() { + $foo = '{{! a comment }}{{> core/bar }}{{< test/bop }}{{/ test/bop}}{{#str}} help, core {{/str}}'; + $bar = '{{! a comment }}{{> core/baz }}'; + $baz = '{{! a comment }}{{#str}} hide, core {{/str}}'; + $bop = '{{! a comment }}hello'; + $cache = [ + 'core' => [ + 'foo' => $foo, + 'bar' => $bar, + 'baz' => $baz, + 'bop' => $bop + ] + ]; + $loader = $this->build_loader_from_static_cache($cache); + + return [ + 'single template include' => [ + 'loader' => $loader, + 'source' => $bar, + 'expected' => [ + 'templates' => [ + 'core' => ['baz'] + ], + 'strings' => [] + ] + ], + 'single string include' => [ + 'loader' => $loader, + 'source' => $baz, + 'expected' => [ + 'templates' => [], + 'strings' => [ + 'core' => ['hide'] + ] + ] + ], + 'no include' => [ + 'loader' => $loader, + 'source' => $bop, + 'expected' => [ + 'templates' => [], + 'strings' => [] + ] + ], + 'all include' => [ + 'loader' => $loader, + 'source' => $foo, + 'expected' => [ + 'templates' => [ + 'core' => ['bar'], + 'test' => ['bop'] + ], + 'strings' => [ + 'core' => ['help'] + ] + ] + ], + ]; + } + + /** + * Test the scan_template_source_for_dependencies function. + * + * @dataProvider test_scan_template_source_for_dependencies_test_cases() + * @param mustache_template_source_loader $loader The loader + * @param string $source The template to test + * @param string $expected The expected output + */ + public function test_scan_template_source_for_dependencies($loader, $source, $expected) { + $actual = phpunit_util::call_internal_method( + $loader, + 'scan_template_source_for_dependencies', + [$source], + \core\output\mustache_template_source_loader::class + ); + $this->assertEquals($expected, $actual); + } + + /** + * Create an instance of mustache_template_source_loader which loads its templates + * from the given cache rather than disk. + * + * @param array $cache A cache of templates + * @return mustache_template_source_loader + */ + private function build_loader_from_static_cache(array $cache) : mustache_template_source_loader { + return new mustache_template_source_loader(function($component, $name, $themename) use ($cache) { + return $cache[$component][$name]; + }); + } +}