Templates: General Concepts (v 1.x)
Basic Structure of a CppCMS template file
When we build templates, we put their content into their own skin. Thus when we build any template, we specify its skin name as the first level command. Each skin is represented by a separate namespace at the C++ level. So the skin name is actually the C++ namespace name.
The second level is view (representing a C++ class). Each view within its skin represents certain pages that should be rendered. Each view should implement the virtual function render(), unless it is already implemented in its parent. Each view is represented by a separate class that is derived from cppcms::base_view by the topmost parent.
Example:
<% skin purple %>
<% view master uses data::master %>
<% template render() %>
...
<% end template %>
<% end view %>
<% end skin %>
All views may be organized to inheritance hierarchy. For example, we can have the following hierarchy for a typical blog application:
[master]
/ \
[page] [summary]
/ \ / \
[post] [info.] [archive] [recent_posts]
Where master defines the general appearance of the page --- theme. page uses for displaying general page
in blog that can be post or info -- information page. On the other hand summary represents a list of recent posts or the archive by category.
Each inherited view may redefine its parent templates that are actually virtual functions.
Syntax
HTML and Controls separation
The template system of CppCMS is based on HTML pages with injected flow control commands between <% %> tags.
Each template command starts with <% and should be closed with %> on the same line.
Each template command should be closed with these "brackets".
For example --- correct code:
<% if not empty Name %> Hello <% Name %> <% else %> Hello Visitor <% end %>
It is incorrect to "merge different commands. For example (incorrect):
Hello <% if not empty name ; name ; else %>Visitor<% end %>
You should not split command on different rows as well. The following is incorrect:
<% if not empty name %> Not empty <% end %>
Symbols inside commands can not include % or >. You may include them inside double quotes using C++/C escaping
rules. For example:
<% number | intf("<%04x>") %>
Syntax Description Rules
The description of the syntax of template commands is done in the following way:
- All keywords will be shown in small caps in single quotes. For example 'skin'
- NAME is a sequence of Latin letters, digits and underscore starting with a letter. They represent identifiers and can be defined by regular expression such as:
[a-zA-Z][a-zA-Z0-9_]*. For exampleskin_1. - VARIABLE is non-empty sequence of NAMES separated by dot "
." or "->" that may optionally end with()or begin with*for identification of function call result. No blanks are allowed. For example:data->point.x,something.else()*foo.bar. - STRING is standard C++/C string with standard escape characters like
"Hello \"World\"". Note: No string concatenation is allowed like"Hello " "World" when"Hello World" is meant`. - NUMBER is a number -- sequence of digits that may start with
-and include.. It can be defined by the regular expression:\-?\d+(\.\d*)? - IDENTIFIER is a sequence of NAME separated by the symbol
::. No blanks are allowed. For example:data::page - All punctuation symbols are enclosed with single quotes. Like
','. - Non-mandatory elements are displayed within square brackets
[]and mandatory ones within round brackets(). Options are separated by the symbol|. There is no limit on blanks between the words.
For example:
'view' NAME 'uses' IDENTIFIER ['extends' NAME]
Means that the following definitions are legal:
<% view page uses data::page extends master %> <% view test uses data::test %> <% view test uses data_test %>
And these are not:
<% view 1page uses data::page extends master %> <% view page %> <% view page uses data::page extends other::master %>
