<!--toc-->
|
|
## General notes
|
|
Each block begins with its definition and ends with the special command `end`.
|
|
'end' [ 'skin' | 'view' | 'template' ]
|
|
This command may optionally include the block type after it. For example:
|
|
<% skin myskin %>
|
<% view master uses data %>
|
...
|
<% end view %>
|
<% end %>
|
|
Above, we closed `view` using its specification but we closed `skin` without specifying its block type.
|
|
## skin
|
|
### Syntax:
|
|
'skin' [NAME]
|
|
It is the topmost command in every template.
|
The name of the `skin` can be specified or omitted in which case its name should be defined externally during the build process using the switch `-s`.
|
|
### Notes
|
|
- If all the templates you create within one skin will not share any parts with other skin, specify the skin's name, otherwise use blank and pass its name using the switch.
|
- If you pass the skin name using the switch `-s`, it should
|
match the name of the skin you use in the skin command.
|
- You can't use more then one skin name in the same `cppcms_tmpl_cc` compilation.
|
|
|
**For example:**
|
|
Correct Example 1:
|
|
foo.tmpl:
|
<% skin foo %>
|
...
|
<% end %>
|
|
cppcms_tmpl_cc foo.tmpl -s foo
|
|
Correct Example 2:
|
|
|
foo.tmpl:
|
<% skin foo %>
|
...
|
<% end %>
|
|
cppcms_tmpl_cc foo.tmpl
|
|
Correct Example 3:
|
|
|
foo.tmpl:
|
<% skin %>
|
...
|
<% end %>
|
|
cppcms_tmpl_cc foo.tmpl -s foo
|
|
|
Correct Example 4:
|
|
|
foo.tmpl:
|
<% skin %>
|
...
|
<% end %>
|
bar.tmpl:
|
<% skin foo %>
|
...
|
<% end %>
|
|
|
cppcms_tmpl_cc foo.tmpl bar.tmpl -s foo
|
|
Wrong - two different skins in the same compilation:
|
|
foo.tmpl:
|
<% skin foo %>
|
...
|
<% end %>
|
bar.tmpl
|
<% skin bar %>
|
...
|
<% end %>
|
|
cppcms_tmpl_cc foo.tmpl bar.tmpl
|
|
Wrong - unknown skin name:
|
|
foo.tmpl:
|
<% skin %>
|
...
|
<% end %>
|
|
cppcms_tmpl_cc foo.tmpl foo.tmpl
|
|
|
|
## view
|
|
### Syntax:
|
|
'view' NAME 'uses' IDENTIFIER ['extends' NAME]
|
'view' NAME 'uses' IDENTIFIER ['extends' NAME] [ 'abstract' ] [ 'inline' ] // since 1.2
|
|
Creates a new view (C++ class) that is responsible for rendering a specific type of content pages. `'uses' IDENTIFIER` specifies the type of the content (some object derived from `cppcms::base_content`) that this view should render. It actually defines `content` reference member of this type.
|
|
Note: in some cases, you may have to access `content` members directly.
|
|
You can specify `'extends' NAME` if you want the view to inherit from another view.
|
|
_Since 1.2_:
|
|
- `abstract` - this view or its parent contains pure virtual templates - it is impossible to create one - used for plugins.
|
- `inline` - put the code of the C++ class in the header - useful for deriving from this view in plugins
|
|
### Derivation restrictions
|
|
When you create a derived view, the content of the child should be derived from the content of its parent as well.
|
|
For example:
|
|
<% view master uses data::master %>
|
..
|
<% end view %>
|
<% view page uses data::page extends master %>
|
...
|
<% end view %>
|
|
Then, `data::page` _must_ be derived from `data::master`.
|
|
_Rationale:_
|
|
When you create the `master` parent you need to provide its own content as well. It also receives its child content, thus it works only if the child content is derived from the parent content.
|
|
### Generated Code
|
|
The generated code for the above two examples would approximately look like this:
|
|
struct master :public cppcms::base_view
|
{
|
data::master &content;
|
master(std::ostream &_s,data::master &_content):
|
cppcms::base_view(_s),
|
content(_content)
|
{
|
}
|
...
|
}; // end of class master
|
struct page :public master
|
{
|
data::page &content;
|
page(std::ostream &_s,data::page &_content):
|
master(_s,_content),
|
content(_content)
|
{
|
}
|
...
|
}; // end of class page
|
|
## template
|
|
A template corresponds to a member function of a view class.
|
|
### Syntax
|
|
The definition of template consists of its name, round brackets and an optional, comma separated list of parameters:
|
|
'template' NAME '(' [ parameter [',' parameter ... ] ] ')'
|
|
Where each `parameter` is:
|
|
IDENTIFIER ['const' ] ['&'] NAME
|
|
For example:
|
|
<% template render() %>
|
<% template show_list(data::list_t const &list) %>
|
<% template show_numbers(int x,int y, double z) %>
|
|
Note: you can not specify template parameters like `list<int>`. You should define a type for them.
|
|
### Generated Code
|
|
Each template is translated to a virtual member function of the class it is defined in. This function
|
returns `void` and receives defined parameters, thus, `show_list` in the above example would be
|
translated to:
|
|
virtual void show_list(data::list_t const &list)
|
{
|
...
|
}
|
|
|
|
