Wednesday, January 11, 2017

Part 3 - Setting up Templates

In part three of the "Adding renderers and templates to your Moodle plugin" series, I will present how to set up and begin using templates with your plugin renderer.

At this point, in parts one and two, I have created a renderer for my plugin's index page, and modified the output code for the index page to use the renderer.

There are a number of parts to implementing templates. I need a renderer. I did this in the earlier parts of the series. I need output classes based on Moodle's \renderable and \templatable classes. And I need Mustache templates to define the actual HTML output.

The first thing I am going to do is construct the mustache template. A mustache template is a file that looks very much like an HTML file. This makes it easy for designer/developers, familiar with HTML to create a layout display. They do not need knowledge of PHP or Moodle internals.

In my plugin, I need to create a new subdirectory called "templates" to hold the mustache templates I create.  Any template file I create requires the ".mustache" extension. Moodle's output system is set up to use the component name and the templates subdirectory name to locate any templates I specify in the specific functions. Since I am creating one for the index page, I create a file called templates/indexpage.mustache.

If you recall from the renderer posts, my index page was essentially an HTML table, listing the questionnaire instances in the course it was being accessed for. I used the html_writer::table function to generate the HTML of this table with the data I loaded. My new template needs to do something similar, except I will have to write the HTML for the table listing using HTML code in the mustache file.

The file I create contains the following HTML/Mustache code (you can see the whole file here):

<table class="generaltable">
      <th class="header" style="text-align:left;" scope="col">{{title1}}</th>
      <th class="header" style="text-align:left;" scope="col">{{title2}}</th>
      <th class="header" style="text-align:center;" scope="col">{{title3}}</th>
      <th class="header" style="text-align:left;" scope="col">{{title4}}</th>
      <td class="cell" style="text-align:left;" scope="col">{{topic}}</td>
      <td class="cell" style="text-align:left;" scope="col">{{{name}}}</td>
      <td class="cell" style="text-align:center;" scope="col">{{responses}}</td>
      <td class="cell" style="text-align:left;" scope="col">{{type}}</td>

You can see from this that the mustache template file looks very much like part of an HTML file, except for the portions contained within multiple brace brackets ("{{ }}"). Anything contained within the brace bracket structures, are mustache constructs that will be replaced by real data when the template is executed.

When a template is executed, it is passed a data structure. The data structure is where the template gets the real data to substitute in place of its brace tagged variables. Deconstructing this template, I have two main data structures: headings and rows. These structures are contained within opening and closing tag pairs, specifically:
    {{#headings}} {{/headings}}
    {{#rows}} {{/rows}}

Each of these structures contains other data defined by tags. The headings structure contains
{{title1}}, {{title2}}, {{title3}} and {{title4}}. The rows structure contains {{topic}}, {{name}}, {{responses}} and {{type}}. This level of the structure is the actual data. When the template is executed, it will expect a data structure that contains these structures passed into it.

Putting the data into section tags allows for some logic to occur within the template. If the section tag exists as a variable in the passed in data, then the output contained within the tag will be displayed. If the section tag does not exist, then the output contained within the tag will not be displayed. Additionally, if the section tag variable is an array, then the output within it will be repeated for each item of the section tag array. For my template, this is important for the rows variable, since there may be multiple rows of data.

In the case of the headings section, if the data contains no headings variable, a table row with no columns will be displayed in the <thead> section. In the case of the rows section, one row containing four columns each (one each of topic, name, responses and type) will be displayed for each element of the rows array. If rows is not present in the data, then no content rows will be displayed.

For this template, since I know I am always going to be passing in the table headings, I really don't need the #header section and structure at all. I could simply pass in the title variables as standalone variables in the template data structure. In that case, I would rewrite the table header section without the opening and closing header tags.

While I haven't discussed the code that constructs the data to be sent to the template yet, I just want to point out some details about how that data can look. For this, assume $data is the data variable I am constructing to pass to the template.

The template will expect the data that is passed in to be either an object with each template tag defined as a property (object variable), or as an array with each template tag defined as an array index. In the case of this template, the data structure expected will consist of either:
or a combination of both.

The headings variable, likewise can be either an object or an array. So for example, either
headings['title1'] or headings->title1 will work successfully with the template data.

For this template, if there are multiple rows of data to be displayed, then the rows variable must be an array structure. Each array item can be either another array or an object however. So, for this template for example, we expect either rows[0]['topic'] or rows[0]->topic. If rows is not an array, there will only ever be one row displayed.

The data structure required is documented as a JSON structure in the template file as comments before the code.

One other thing to point out before I move on. You may have noticed that all of the template variable tags are enclosed in two brace brackets, except for one. The name variable is enclosed in three brace brackets - {{{name}}}.  When a variable enclosed in two brace brackets is substituted for the real data, it is HTML escaped. That means only text will be displayed, and any HTML constructs contained in that variable will be converted to escaped text and displayed verbatim rather than interpreted. When a variable is enclosed in three brace brackets is substituted for the real data, the data is included raw. That means the HTML will be interpreted and displayed accordingly. This is useful when you want to display a block of HTML formatted content.

In the case of my template, the name variable also contains a link to the actual questionnaire instance, so I want the HTML to be displayed as I passed it. In actuality, I should probably rewrite the template so that the pieces of the link are passed instead of the entire HTML structure. Generally speaking, it is safer and better practice to pass only unformatted text.

In the next post, I will begin modifying the renderer code to use the template.


  1. I am really enjoying reading your well written articles.
    It looks like you spend a lot of effort and time on your blog.
    I have bookmarked it and I am looking forward to reading new articles. Keep up the good work..
    PHP Training in Chennai
    PHP Course in Chennai
    Angularjs Training in Chennai
    CCNA Training in Chennai
    Salesforce Training in Chennai
    PHP Training in Chennai
    PHP Course in Chennai

  2. شرکت تلکا هاست پیشرو در میزبانی انواع وب سایت و هم چنین دارای انواع خرید هاست ارزان با کنترل پنل سی پنل میباشد.حتما از سایت ما دیدن کنید و از قیمت های مناسب برای انواع سرویس های وب و ثبت انواع دامنه شگفت زده شوید.

  3. You actually make it seem like it's really easy with your acting, but I think it's something I think I would never understand. I find that too complicated and extremely broad. I look forward to your next message. I'll try to figure it out!

    Business Analytics Course in Bangalore

  4. Happy to chat on your blog, I feel like I can't wait to read more reliable posts and think we all want to thank many blog posts to share with us.

    Data Analytics Course in Bangalore

  5. I am glad to post a worthy article about the German Language Course and IELTS Coaching from KCR consultants, this may change your career growth and language skill.

  6. Attend The Data Analyst Course From ExcelR. Practical Data Analyst Course Sessions With Assured Placement Support From Experienced Faculty. ExcelR Offers The Data Analyst Course.
    Data Analyst Course

  7. wonderful article contains lot of valuable information. Very interesting to read this article.I would like to thank you for the efforts you had made for writing this awesome article.
    This article resolved my all queries.good luck an best wishes to the team members.continue posting.learn digital marketing use these following link
    Digital Marketing Course in Chennai

  8. Happy to chat on your blog, I feel like I can't wait to read more reliable posts and think we all want to thank many blog posts to share with us.

    Data Science Training in Bangalore

  9. Really wonderful blog completely enjoyed reading and learning to gain vast knowledge. Eventually, this blog helps in developing certain skills which in turn helpful in implementing those skills. Thanking the blogger for delivering such beautiful content and keep posting the contents in the upcoming days.

    Digital Marketing Training in Bangalore

  10. I wanted to leave a little comment to support you and wish you the best of luck. We wish you the best of luck in all of your blogging endeavors.

    Artificial Intelligence Training in Bangalore

  11. Truly incredible blog found to be very impressive due to which the learners who go through it will try to explore themselves with the content to develop the skills to an extreme level. Eventually, thanking the blogger to come up with such phenomenal content. Hope you arrive with similar content in the future as well.

    Machine Learning Course in Bangalore

  12. I am glad to discover this page. I have to thank you for the time I spent on this especially great reading.
    I really liked each part and also bookmarked you for new information on your site.
    Reactjs Training in Chennai |
    Best Reactjs Training Institute in Chennai |
    Reactjs course in Chennai |