<!--toc--> |
|
## General notes |
|
Each block begins with its definition and ends with special command `end`. |
|
'end' [ 'skin' | 'view' | 'template' ] |
|
This command may optionally include block type after it. For example: |
|
<% skin myskin %> |
<% view master uses data %> |
... |
<% end view %> |
<% end %> |
|
So we closed `skin` without block type and `view` with specification. |
It may be used as additional checking of order of blocks. |
|
|
## skin |
|
### Syntax: |
|
'skin' [NAME] |
|
It is topmost command in every template. |
`skin` can be specified by specific name, or omitted that means that its name should be defined |
externally during build process using switch `-s`. |
|
### Notes |
|
- If all the skin you create would not share any part with other skin, specify its name, otherwise use blank and pass |
its name using switch. |
- if you pass skin name using a 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 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 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] |
|
Creates new class that responsible on rendering specific type of content pages. `'uses' IDENTIFIER` specifies the type of the content that this class should render. It actually defines `content` reference member of this type. |
Creates new view (C++ class) that responsible on rendering 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. |
|
Remember this note, in some cases, you would have to access `content` member directly. |
|
You can specify `'extends' NAME` if you want that new created class would inherit from other template class. |
You can specify `'extends' NAME` if you want that new created view would inherit other view. |
|
### Derivation restrictions |
|
When you create derived class the content of the child should be derived from the content of its parent as well. |
When you create derived view, the content of the child should be derived from the content of its parent as well. |
For example: |
|
<% class master uses data::master %> |
<% view master uses data::master %> |
.. |
<% end class %> |
<% class page uses data::page extends master %> |
<% end view %> |
<% view page uses data::page extends master %> |
... |
<% end class %> |
<% end view %> |
|
Then, `data::page` _must_ be derived from `data::master`. |
|
_Rationale:_ |
|
When you create `master` parent you need provide for it a content as well. It receives its child content, thus it |
may work if its child content derived from its parent content. |
|
### Generated Code |
|
The generated code for the above two examples would look like this (approximately): |
|
class master : public base_view { |
data::master &content; |
master(settings s,data::master cnt) : |
base_view(settings), |
content(cnt) |
{ |
... |
} |
... |
}; |
class page : public master { |
data::page &content; |
page(settings s,data::page cnt) : |
master(s,cnt), |
content(cnt) |
{ |
... |
} |
... |
}; |
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 |
|
### Syntax |
|
Definition of template consists of its name, round brackets and optional, comma separated list of parameters: |
|
'template' NAME '(' [ parameter [',' parameter ... ] ] ')' |
|
Where `parameters` 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 virtual member function of the class it 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) |
{ |
... |
} |
|
|
|
