Part 4 - Using the Template

In the previous posts, I created and used a renderer, and created a simple mustache template for my plugin. In part four of the "Adding renderers and templates to your Moodle plugin" series, I will present how to code the template classes and then use them in the renderer.

To use a template, I need a few different constructs.

Firstly, I need a new class that implements the core renderable and templatable classes. The file and class name should be the same as the template file name to make things easier. And the file must be located in the classes/output/ directory.

Since my template file is called indexpage.mustache, I create a new file called indexpage.php in the classes/output directory, and add a class called indexpage that implements \renderable and \templatable.  The class declaration must look like this (the entire file is available here):

    class indexpage implements \renderable, \templatable {
    }

The purpose of this script is to collect the output data for the template and make it available to the renderer. The only real required function is the export_for_template function, as renderers require that function to retrieve the data structure that is passed into the template. Other functions can be provided as necessary including those that process the data for the template. The code for the export function looks like this:

    public function export_for_template(\renderer_base $output) {
        $data = ['headings' => [], 'rows' => []];
        foreach ($this->headings as $key => $heading) {
            $data['headings'][$key] = $heading;
        }
        foreach ($this->rows as $row) {
            list($topic, $name, $responses, $type) = $row;
            $data['rows'][] =['topic' => $topic, 'name' => $name,
                'responses' => $responses, 'type' => $type];
        }
        return $data;
    }

For my version, I pass all the necessary data for the template to the constructor, and then process it for output in the export function. The class contains two property variables, $headings and $rows, which will hold the table headings and each row of content for the index page based on what is passed into the constructor. My export_for_template function processes these variables and creates the expected data construct for the template.

If you recall from the last post, my template expects a data structure with two top level elements: #headings and #rows. In the export_for_template function, I create a PHP array called $data, and add the keys 'headings' and 'rows' to it, each of which is initialized to an array. Then, I load up the headings array with a value for each 'title[n]' index and the rows array with an array for each content row containing the topic, name, responses and type elements. So after processing, the function returns a structure that looks something like this (for example):

    $data['headings' =>
             ['title1' => 'Topic',
              'title2' => 'Name',
              'title3' => 'Responses',
              'title4' => 'Questionnaire Type'
             ],
          'rows' =>
             [0 =>
                 ['topic' => 'Topic1',
                  'name' => 'Questionnaire1',
                  'responses' => 42,
                  'type' => 'Private'
                 ],
             [1 =>
                 ['topic' => 'Topic2',
                  'name' => 'Questionnaire2',
                  'responses' => 11,
                  'type' => 'Private'
                 ]

             ]

         ];

This structure is what gets sent to the template to meet its requirements for data.

Now that I have the necessary implementation of the core \templatable class, and a template, I need to code the renderer to use them. Currently, the renderer's render_index function, creates the HTML output from Moodle core helper functions, specifically the \html_table class. I need to change that so it uses the template and template class.

To do that, I change the declaration of the function to take one argument, a \templatable object. And I get rid of the current code, and replace it with the object's export_for_template function and a call to the renderer class function render_from_template. The new function looks like this (you can see the entire file here):

    public function render_indexpage(\templatable $indexpage) {
        $data = $indexpage->export_for_template($this);
        return $this->render_from_template('mod_questionnaire/indexpage', $data);
    }

The new render_index function expects an object created from the classes/output/indexpage.php::indexpage class. With that object, it will call the export_for_template function to get the data necessary to pass into the template. Then it will pass that data to the template to get the HTML output from the core render_from_template function. The render_from_template function takes two arguments: the template to use and the data to pass the template. In my case, the template to use is defined by the argument 'mod_questionnaire/indexpage'. The 'mod_questionnaire' portion tells the function that this is for an activity module plugin, and therefore the template should be found in the directory '/mod/questionnaire/templates/'. The 'indexpage' portion indicates that there should be file named 'indexpage.mustache' in that directory. After that, the function executes the necessary magic to pass the data into the template and return the final formatted HTML.

The final step I need to do in order to use all of this new template code is change the way I am using the renderer in the index.php file. In this case, I only need to change the code where I am actually using the renderer to output to the screen. I need to do two things: change the arguments being passed to the render_index function and create an indexpage templatable object for that function to use.

The old code looks like this:
    echo $output->render_index($headings, $align, $content);

The new code looks like this:
    $indexpage = new \mod_questionnaire\output\indexpage($headings, $content);
    echo $output->render_indexpage($indexpage);

Note, although I changed the function name from render_index to render_indexpage, it was not necessary. I changed the name only because I felt it better reflected the functionality.

I now have everything I need to output my plugin's index page using renderers and templates. And, other developers can now easily change the way that page display looks using alternate templates or renderers in their themes without having to change any of the plugin's code. The entire plugin's code using this template can be viewed here.

In my next post I will look at alternate coding strategies and how I used renderers and templates for the rest of the plugin's output code.