Templates: Top Level Blocks (v 1.x)
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
<a name="Syntax:"></a>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_cccompilation.
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
<a name="Syntax:"></a>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 ... ] ] ')'
'template' NAME '(' [ parameter [',' parameter ... ] ] ')' [ = 0 ] // since 1.2
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.
Since 1.2: it is possible to create pure virtual template by adding = 0. The template that must be implemented by derived view to be creatable. Note: the view should be defined as abstract
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)
{
...
}
