## Table Of Contents |
|
- [Variable](#var) |
- [Variable with Filters](#varflt) |
- [Internationalization with `gettext`](#gettext) |
- [Including other Templates](#incl) |
- [Rendering Forms](#forms) |
- [HTML/XHTML Selection](#xhtml) |
- [C++ Code Injection](#cpp) |
<!--toc--> |
|
## <span id="var"></span>Variable |
## Variable |
|
The simplest templates command is showing variable. The syntax is trivial: |
|
NAME |
|
For example, if you want to show a content value `message` just write: |
|
<% message %> |
|
It is actually translated to C++ code: |
|
cout<<escape(message); |
|
Where `escape` template function is defined as |
|
if parameter is std::string |
perform HTML escaping and return it. |
else if parameter is std::tm |
render it to string |
else |
render it using `std::ostringstram`, like cout<<v |
|
Thus, the shown variable can be from any type that can be written to `std::ostream`. |
|
## <span id="varflt"></span>Variable with filters |
## Variable with filters |
|
You can add arbitrary filters to the variable you show. The syntax is following: |
|
VARIABLE [ '|' filter [ '|' filter ] ... ] |
|
Where `filter` is |
|
[ 'ext' ] NAME [ '(' ( VARIABLE | STRING | NUMBER ) [ ',' ( VARIABLE | STRING | NUMBER ) ] ... ] |
|
### Description |
|
If no filters, are given the variable is automatically escaped, but if you provide any filter they are used instead |
of escaping. |
|
Each variable is actually function call with given parameters, where first parameter is the "filtered" variable and |
others are filter parameters. For example: |
|
<% birthday | strftime("%d/%m/%Y") %> |
|
Is translated into: |
|
cout<<strftime(content.birthday,"%d/%m/%Y"); |
|
Where `strftime(std::tm const &date,string format)` is a member function of `base_view` class, that every |
view class is derived from it. |
|
You can also concatenate filters using pipe symbol: |
|
<% birthday | strftime("%d %m %Y") | urlencode %> |
|
Would be rendered as: |
|
cout<<urlencode(strftime(content.birthday,"%d/%m/%Y")); |
|
You can specify arbitrary external filters that are defined in `content` class. For example: |
|
namespace data { |
struct page { |
... |
virtual string toupper(string const &); |
... |
}; |
} |
|
Then in template we can specify: |
|
<% class page uses data::page %> |
<% template render() %> |
<% message | escape | ext toupper %> |
<% end %> |
<% end %> |
|
__Note:__ Under Windows platform, dynamically loaded libraries (dll) do not allow undefined symbols. |
Thus, if you want to support Windows, you should create your filters as virtual functions or |
callbacks like `boost::function<string(string)>` in order to prevent referring to external symbol. |
|
### Predefined filters |
|
There is a set of filters predefined for you in `base_view` class. |
|
- **`template<typename T> string escape(T const &v)`** |
This filters performs HTML escaping for `std::string`, rendering to string of `std::tm` or converting to string of |
any other "ostream writeable" object. This filter is applied by default if no other filters are given. |
- **`string raw(string s)`** |
Does nothing, returns `s`. It is used for bypassing default filter; |
- **`string intf(int value,string f)`** |
Format integer using `boost::format`. For example: |
|
<% n %> in decimal is <% n | intf("%x") %> in hexadecimal. |
- **`string strftime(std::tm const &time,string format)`** |
Convert `time` to string using strftime(3) function. |
- **`string data(std::tm const &v)`** |
Same as strftime(v,"%Y-%m-%d") -- display ISO date like, 2008-12-32 |
- **`string time(std:;tm const &v)`** |
Same as strftime(v,"%H:%M"), display 24 hours clock like, 21:00 |
- **`string timesec(std::tm const &v)`** |
Same as strftime(v,"%T"), display 24 hours clock like, 21:59:59 |
- **`string urlencode(string const &s)`** |
Encode string `s` for URL. |
|
|
## <span id="gettext"></span>Internationalization with `gettext` |
## Internationalization with `gettext` |
|
### Syntax |
|
'gt' STRING [ 'using' using-options ] |
'ngt' STRING ',' STRING ',' VARIABLE [ 'using' using-options |
|
Where `using-options` is: |
|
display-variable-block [ ',' display-variable-block [ ',' ... ] ] |
|
Where `display-variable-block` is any variable is optional filters as described above. For example: |
|
<% gt "Press the button" %> |
<% gt "Hello Dear %1%, we are glad to see you!" using name %> |
<% gt "Hello <a href=\"%1%\">%2%</a> you have %3%" using link | urlencode , name , something %> |
<% ngt "You have one apple","You have %2% apples",n using n %> |
|
### Description |
|
`gt` -- `gettext` translates given string according to locale defined in current worker thread. For example: |
|
<% gt "Press the button" %> |
|
Would be translated as "Press the button" in English locale and "Нажмите кнопку" under Russian locale. |
|
You can specify additional parameters using `using` option. You provide a list of comma separated values |
as you would display a variable. You can use any other filters as usual. "%1%", "%2%" etc, specify the order of |
input variables. It uses `boost::format` for such substitutions. |
|
|
`ngt` -- `ngettext` translate plural form for given integer. Where first parameter is single form, second plural and the |
third should be the variable is used. |
|
_Notes:_ |
|
1. When you use `ngt` you encouraged to use `using` syntax, because you should provide an actual number to display. |
2. Exceptions are disables for boost::format in context of `gettext`. So you may provide not matching number of parameters -- this is important for plural `ngettext` forms. |
3. You may use `<% if rtl %>` or `<% if not rtl %>` in order to test direction of text. This is actually equivalent to: |
|
<% if (strcmp(gettext("LTR"),"RTL")==0) %> |
|
See `if` statement for further description. |
|
## <span id="incl"></span>Including other templates |
## Including other templates |
|
### Syntax |
|
'include' IDENTIFIER '(' [ parameter [ ',' parameter ...] ] ')' |
|
Where `parameter` is one of VARIABLE, STRING or NUMBER. For example: |
|
<% include title() %> |
<% include parent::foo() %> |
<% include bar(x,"test",-1.0) %> |
|
### Description |
|
This command allows inclusion of other functions in place. You can include existing implementation in parent templates |
in order to extend them. For example: |
|
<% class master uses data::master %> |
<% template menu() %> |
<li><a href="#1">Main</a></li> |
<li><a href="#2">Products</a></li> |
<% end template %> |
<% template render() %> |
<ul><% include menu() %></ul> |
<% end template %> |
<% end class %> |
<% class sales uses data::sales extends master %> |
<% template menu() %> |
<% include master::menu() %> |
<li><a href="#3">Orders</a></li> |
<% end %> |
<% end %> |
|
The above code extends menu for class `sales` with an additional option. |
|
## <span id="forms"></span>Rendering Forms |
## Rendering Forms |
|
### Syntax |
|
'form' ('as_p' | 'as_table' | 'as_ul' | 'as_dl' | 'as_space' ) ['no' 'error'] VARIABLE |
|
Render `cppcms::form`, `widget` or `cppcms::widgetset` with selected delimiter. `no error` disables rendering of error |
marks for invalidated form fields. |
|
'form' 'error' VARIABLE |
|
Render widget error message. Used for custom rendering method for widgets. |
|
'form' 'input' VARIABLE |
|
Render HTML input of given widget. Used for custom rendering of widgets. |
|
### Description |
|
Forms are organized as form object or sets of widgets. Each set can be rendered using different delimiters: |
|
- `as_p` -- use HTML paragraphs. |
- `as_table` -- use table. _Note_: `<table>...</table>` tags are not added user should specify them. |
- `as_ul` -- as list (using `<li>..</li>`). `<ul>..</ul>` are not specified. |
- `as_dl` -- as definition list. `<dl>` tags are not specified, `<dt>..</dt>` and `<dd>..</dd>` are used. |
- `as_space` -- put blanks between elements. |
|
For example: |
|
<table> |
<% form as_table form.fields %> |
</table> |
<p><% form as_space form.submit_buttons %></p> |
|
May be rendered as: |
|
<table> |
<tr><th>User Name:</th><td><input ... /></td></tr> |
<tr><th>Password: </th><td><input ... /></td></tr> |
</table> |
<p><input ... value="Login" /> <input ... value="Forgot Password" /></p> |
|
Usually when certain field is invalid, error message (or '*') is displayed near problematic widget. If you |
want provide your own messages at your own position, you may specify `no error` and disable automatic error |
messages generation. |
|
You may also render each specific widget in form as you want. You can render only its input filed using: |
|
<% form input some_widget %> |
|
You may generate only error message using: |
|
<% form error some_widget %> |
|
## <span id="xhtml"></span>Selecting HTML/XHTML |
## Selecting HTML/XHTML |
|
You may request generation HTML or XHTML code in forms using following command: |
|
( 'xhtml' | 'html' ) |
|
Note, this command has global effect on all template without connection to specific class. You should include it |
in the topmost class of your view. |
|
<% c++ #include "all_data.h" %> |
<% xhtml %> |
<% namespace vary %> |
<% class master uses data::master %> |
<% template render() %> |
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" |
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> |
|
Currently, this option affects only forms code generation. |
|
## <span id="cpp"></span>Injecting C++ Code |
## Injecting C++ Code |
|
You can always inject any kind of C++ code using: |
|
"c++" any-c++-statement |
|
For example: |
|
<% c++ #include "all_content.h" %> |
|
__Notes:__ |
|
1. If you want to refer to content variables in your code, do not forget to use `content` member of your class. For example: |
|
<% a %> + <% b %> = <% c++ cout<<content.a+content.b; %> |
2. Generally you should not use C++ code in template, use it if it is absolutely necessary. |
3. If you want use special conditions prefer specialized if statement over `<% c++ if() { %>...<% c++ } %>` |
|
|
|
