WPart Templates

Overview

The Template engine is a tool for faster and easier building of html pages for your application. It allows you to create a common layout of your html pages from little html bricks - using parts of html code. The most common situation is when you have a header, a menu , content and a footer. Writing each html file with all of these pieces can be a very boring job. Moreover, what if at some point in time you decide to change one of those pieces? You will need to change every occurrence in all of your html files. And in the instance of a larger site, potentially many hundreds of files.

The Template engine is in fact a set of three wtpl tags: wtpl:parent, wtpl:include and wtpl:content.

wtpl tags

<wtpl:include name=Name /> - tag specifies the location, where the content of the corresponding wtpl:content tag (with the same attribute Name) will be inserted.
<wtpl:parent path=Path /> - tag specifies which template will be filled with wtpl:content contents. It must be the root element of each child template (template, which contains at least one wtpl:content).
<wtpl:content name=Name /> - tag in which content will replace the corresponding (with the same Name attribute) wtpl:include tag in the wtpl:parent file.

To display the page properly, all the wtpl:include tags must be substituted with corresponding wtpl:content tags.

Control flow

During operation, when the template engine encounters the wtpl:parent tag - the template engine begins. The control flow is as follows:

collecting the inside of all wtpl:content tags
loading the file pointed to by Path attribute in wtpl:parent
fill the possible wtpl:include slots with the corresponding wtpl:content values
if the root element of the loaded file is wtpl:parent the expander goes to first step

Example

This is an example of nested template html files:

base.html

  <html>
    ...
    <body>
      <wtpl:include name="header"/>
      <wtpl:include name="content"/>
      <wtpl:include name="footer"/>
    </body>
  </html>

half_filled.html

   <wtpl:parent path="base.html">
     <wtpl:content name="header">
       This is the header of the service
     </wtpl:content>

     <wtpl:include name="menu"/>

     <wtpl:content name="footer">
       This is the footer!
       <img src="footer.jpg"/>
     </wtpl:content>
   </wtpl:parent>

filled.html

  <wtpl:parent path="half_filled.html">
    <wtpl:content name="menu">
      Here we will place our menu
    </wtpl:content>

    <wtpl:content name="content">
      And here will be the content of the page
    </wtpl:content>
  </wtpl:parent>

After expanding, the final page (filled.html) will look like:

   <html>
     ...
     <body>
       This is the header of the service
       Here we will place our menu
       And here will be the content of the page
       This is the footer!
       <img src="footer.jpg"/>
     </body>
   </html>

wpart_gen

The wpart_gen module has been created because of the need to build the HTML code efficiently within the Erlang modules. The general idea is to remove all the HTML tags in the separate files, with extension .tpl, and to load and fill them in with the controller.

The usage of the wpart_gen module is very simple. In the beginning you need to load your HTML snippets into memory in order to access them as fast as possible. That can be accomplished by running:

wpart_gen:load_tpl(Namespace, Name, Path).

This call will load the file from the Path and place it in the memory under the key {Namespace, Name}. Namespaces has been implemented because some names are very common, like the html list item: li - so recognizing them in the controller is important. Loading needs to be performed only once - during the startup of your system.

The template snippets are standard HTML files, but are marked where you want to inject your content. There are two ways for specifying templates.

named slots

These are used when you do not want to remember the exact order and number of the parameters. The slots are specified by their names. If you do not pass all the names during the template filling, the unfilled slots will be replaced with empty strings. The syntax is as follows:

...
<!-- HTMLCode -->
<% name_of_the_slot %>
<!-- HTMLCode -->
...

anonymous slots

This has been implemented in order to achieve better efficiency. You must remember the exact number of the slots and their order:

...
<!-- HTMLCode -->
<% slot %>
<!-- HTMLCode -->
...

When you have the snippets prepared and loaded, they are immediately ready for use. In order to get the snippet, call:

wpart_gen:tpl_get(Namespace, Name)

Next, to fill the template with your values, call:

wpart_gen:build_html(Tpl, Values)

where Tpl is a template loaded in the previous call and Values is a list of your specific values. The Values list format depends on the type of the slots you used:

named slots - you should pass the proplist:
[{"name_of_the_slot", Value} | ...]
The slot with the specified name will be substituted with the corresponding Value which is a string. You do not have to pass all the values - the unfilled slots will remain empty.
anonymous slots - you should pass a list of values:
[Value | ...]
The length of the list must be the same as the number of the slots defined in the snippet. If the lengths differ, the erlang:error function will be called. And remember, the order is important - you must build the list of values in the correct sequence.

The properly prepared HTML code is returned as the value of the #xmlText record from the handle call function.

While wpart:include is not part of the template engine itself, wpart:include can be used to insert files within other files. You can create a common section of code and include it within another file, saving programming time. See the Wparts section under the Application Description section for further information about wpart:include.