Module Templates

Last edit:

This section contains information about a new feature, processing module templates.

Problem

When you install a module, there is no way to parametrize it other than by using backend API's (through GraphQL, by creating customization, etc.). This is problematic because:

That's a lot of work to configure basic things like Page#slug.
Installing the module immediately makes it available on the website with default values, which might have to be configured.

Additional requirements

A solution is needed that:

will work both from the pos-cli and the Partner Portal
will work before configuration records are created in the back-end
will allow unchanged development flow (sync and deploy)
will be configurable

Solution

A solution that is partially implemented uses the pos-cli (Partner Portal internally uses the pos-cli for module deployment, so internally it's commonplace). In pos-cli, there is a piece of code run on the file before it gets synced or deployed that handles additional layer of templating.

Technical details

The implementation uses mustache.js which is a lib with logicless templates for JavaScript. Some pros of this option:

The code is based on a descending parser and quite solid.
Tags used can be configured (examples below use <%= and %>).
It handles error checking in the template format (missing/unmatched tags, etc.).
It handles error checking in values provided for rendering.
It has optional HTML escaping built in.

Examples

Given a template like this:

---
slug: <%= &blog_root %>
max_deep_level: 3
layout: community
authorization_policies:
  - modules/blog/blog_post_page
metadata_title: <%= blog_title %>
---


{% include 'shared/common' %}

{%- if context.params.slug3 == blank %}
  {% include 'blog/index' %}
{%- else -%}
  {% include 'blog/show' %}
{% endif %}

After the processing, the result will look something like this:

This example also demonstrates how easy it is to do HTML unescape by prefixing the variable name with &. It is also easy to add additional helper functions, if they are needed in the future.

Code for rendering this output is also quite easy to understand:

render(template2, { blog_root: "/blog", blog_title: "My awesome blog!"});

The K/V hash could be easily loaded from the *.json file

Summary

Benefits of this solution:

It will not change the current workflow.
It will be easy to support.
The configuration for template values can be placed anywhere and can be passed in as a parameter to the pos-cli (possibility of multiple configurations in development).
It is easy to use from the Partner Portal where upon clicking "Install", the user would be asked to provide values for keys registered by the module creator, who will be able to provide defaults.