Main  /  Edit version 2  /  Edit version 3  /   /  Users Area

Difference "Templates: Rendering Commands" ver. 2 versus ver. 3

Content:

## 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++ } %>`

About

CppCMS is a web development framework for performance demanding applications.

Support This Project

SourceForge.net Logo

Поддержать проект

CppCMS needs You


Navigation

Main Page


Valid CSS | Valid XHTML 1.0