<?php
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
/**
* Load template source strings.
*
* @package core
* @category output
* @copyright 2018 Ryan Wyllie <ryan@moodle.com>
* @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 <ryan@moodle.com>
* @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 {
> global $CFG;
// 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);
}
<
> if (!empty($CFG->debugtemplateinfo)) {
> return "<!-- template(JS): $name -->" . $source . "<!-- /template(JS): $name -->";
> }
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.
* @param string|null $lang moodle translation language, null means use current.
* @return array
*/
public function load_with_dependencies(
string $templatecomponent,
string $templatename,
string $themename,
bool $includecomments = false,
array $seentemplates = [],
array $seenstrings = [],
string $lang = null
) : 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) use ($lang) {
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) use ($lang) {
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, $lang) {
$string = get_string_manager()->get_string($id, $component, null, $lang);
// 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,
$lang
) {
// 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,
$lang
);
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, 2);
$templates = $addtodependencies($templates, $component, $id);
break;
case Mustache_Tokenizer::T_PARENT:
list($component, $id) = explode('/', $name, 2);
$templates = $addtodependencies($templates, $component, $id);
break;
case Mustache_Tokenizer::T_SECTION:
if ($name == 'str') {
list($id, $component) = $this->get_string_identifiers($tokens, $index);
if ($id) {
$strings = $addtodependencies($strings, $component, $id);
}
}
break;
}
}
}
return [
'templates' => $templates,
'strings' => $strings
];
}
/**
* Gets the identifier and component of the string.
*
* The string could be defined on one, or multiple lines.
*
* @param array $tokens The templates token.
* @param int $start The index of the start of the string token.
* @return array A list of the string identifier and component.
*/
protected function get_string_identifiers(array $tokens, int $start): array {
$current = $start + 1;
$parts = [];
// Get the contents of the string tag.
while ($tokens[$current]['type'] !== Mustache_Tokenizer::T_END_SECTION) {
if (!isset($tokens[$current]['value']) || empty(trim($tokens[$current]['value']))) {
// An empty line, so we should ignore it.
$current++;
continue;
}
// We need to remove any spaces before and after the string.
$nospaces = trim($tokens[$current]['value']);
// We need to remove any trailing commas so that the explode will not add an
// empty entry where two paramters are on multiple lines.
$clean = rtrim($nospaces, ',');
// We separate the parts of a string with commas.
$subparts = explode(',', $clean);
// Store the parts.
$parts = array_merge($parts, $subparts);
$current++;
}
// The first text should be the first part of a str tag.
$id = isset($parts[0]) ? trim($parts[0]) : null;
// Default to 'core' for the component, if not specified.
$component = isset($parts[1]) ? trim($parts[1]) : 'core';
return [$id, $component];
}
}