<!--toc--> |
|
## Basic Structure of 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 example `skin_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 %> |
|
|
<!--toc-->
|
|
## 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 example `skin_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 %>
|
|
|
|
