<!--toc--> |
|
## Variable |
|
The simplest templates command is showing variable. The syntax is trivial: |
|
'=' VARIABLE |
|
For example, if you want to show a content value `message` just write: |
|
<%= message %> |
|
It is actually translated to C++ code: |
|
out()<<cppcms::filters::escape(content.message); |
|
Where `escape` function writes the `message` member variable |
of the content to the stream and escapes special HTML |
characters `<`, `>`, `&`, `"` with their HTML representations like `<` |
|
If you want to get a value of some property, you just write. |
|
<%= some_property() %> |
|
Which is translated to: |
|
out()<<cppcms::filters::escape(content.some_property()); |
|
|
## 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 a creation or call |
of special filter object 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: |
|
out()<<cppcms::filters::strftime(content.birthday,"%d/%m/%Y"); |
|
You can also concatenate filters using pipe symbol: |
|
<%= birthday | strftime("%d %m %Y") | urlencode %> |
|
Would be rendered as: |
out()<<cppcms::filters::urlencode(cppcms::filters::strftime(content.birthday,"%d/%m/%Y")); |
|
There is a set of filters predefined available for you, see [cppcms::filters](/cppcms_ref/latest/namespacecppcms_1_1filters.html) namespace reference. |
|
One of the filters that is worth to noticing is `raw`: it allows to write a variable as-is, without any |
HTML escaping. |
|
<%= ready_html | raw %> |
|
The `ready_html` variable will be written as-is to the output stream without escaping HTML symbols like `<`. |
|
You can specify arbitrary external filters that are defined in `content` class. For example: |
|
namespace data { |
struct page { |
... |
virtual string bbcode(string const &); |
... |
}; |
} |
|
Then in template we can specify: |
|
<% class page uses data::page %> |
<% template render() %> |
<%= message | ext bbcode %> |
<% 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 `booster::function<>` in order to prevent referring to external symbol. |
|
## Variable - Deprecated Syntax |
|
CppCMS supports older deprecated syntax (without "="): |
|
VARIABLE [ '|' filter [ '|' filter ] ... ] |
|
However it is not recommended due to fact that new |
template keywords may be introduced that would hide the existing variable and cause syntax error. |
|
## Internationalization |
|
### 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 of 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 the output stream. 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 [`booster::locale::format`](/cppcms_ref/latest/classbooster_1_1locale_1_1basic__format.html) or [`cppcms::locale::format`](/cppcms_ref/latest/classcppcms_1_1locale_1_1basic__format.html) for such substitutions (according to localization backend |
CppCMS compiled with.) |
|
|
`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. |
3. You may use `<% if rtl %>` or `<% if not rtl %>` in order to test direction of text. This is actually equivalent to: |
|
<% if (cppcms::locale::gettext("LTR",out().getloc())=="RTL") %> |
|
See `if` statement for further description. |
|
## URL Mapping |
|
### Syntax |
|
'url' STRING [ 'using' using-options ] |
|
Where `using-options` is: |
|
display-variable-block [ ',' display-variable-block [ ',' ... ] ] |
|
Where `display-variable-block` is any variable of optional filters as described above. For example: |
|
For example: |
|
<% url "/blog/summary" %> |
<% url "../summary" %> |
<% url "/blog/post" using post_id %> |
<% url "/blog/post" using post_id , slug | ext filter_for_url %> |
|
### Description |
|
The `url` tag is a templates interface to [`cppcms::url_mapper`](http://cppcms.com/cppcms_ref/latest/classcppcms_1_1url__mapper.html) interface accessible |
from the `cppcms::application` |
|
This tag allows to access to abstract URLs of the |
application with given parameters. To learn how |
to use URL mapping read the description of `url_mapper` |
class given above. |
|
The `using` parameters are passes for the formatting |
of the URL parameters. |
|
_Note:_ unlike the variable rendering the default escaping |
for the parameters is `urlencode` and not `escape` |
|
For example |
|
<% url "/blog/post" using slug %> |
|
Where `slug` is "Hi <you>" would generate something |
like |
|
"/myblog/Hi%20%3cyou%3e/" |
|
and not |
|
"/myblog/Hi <you>/" |
|
|
## Including other templates |
|
### Syntax |
|
'include' IDENTIFIER '(' [ parameter [ ',' parameter ...] ] ')' [ 'from' IDENTIFIER | 'using' IDENTIFIER [ 'with' VARIABLE ] ] |
|
Where `parameter` is one of VARIABLE, STRING or NUMBER. For example: |
|
<% include title() %> |
<% include parent::foo() %> |
<% include bar(x,"test",-1.0) from foo %> |
<% include bar(x,"test",-1.0) using baz %> |
|
### Description |
|
This command allows inclusion of other templates in place (actually calling other member functions.) You can include existing implementation in parent views |
in order to extend them. For example: |
|
<% view 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 view %> |
<% view 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 view `sales` with an additional option. |
|
The `from` option allows to include templates from |
locally initialized views withing `using` blocks. |
|
For more details read [Views Helpers](#Views.Helpers) section |
|
## Rendering Forms |
|
### Syntax |
|
'form' ('as_p' | 'as_table' | 'as_ul' | 'as_dl' | 'as_space' | 'input' | 'block' | 'begin' | 'end' ) VARIABLE |
|
`as_*` flags allow you to render `cppcms::form`, with |
specific delimiters, when `input`, `begin`, `end` and `block` flags |
allow you to render single part of the widget. |
|
### 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> |
|
Sometimes you want to perform custom rendering |
of widgets that is not predefined by this list. |
In such case you may render only `<input ...>` field |
of the widget by calling |
|
<% form input some_button %> |
|
Which would be rendered like this: |
|
<input type="submit" name="_3" value="Press" /> |
|
Note, `input` does not strictly means that it is limited |
for widgets using HTML `input` tag, it works for |
any other widget just limited to actual content rendering |
without "help" messages, for example, for widget |
`cppcms::widgets::textarea` it would be `<textarea ...>some text</textarea>` |
|
Sometimes you need even more fine grained access |
to widget rendering parts, for example you may |
want to add some attributes to the widget in the view. |
|
You may render `begin` or `end` part of the widget, such that you can insert HTML attributes between them or even JavaScript. |
|
<% form begin some_button %> onclick="return foo()" <% form end some_button %> |
|
Which would be rendered as |
|
<input type="submit" name="_3" onclick="return foo()" value="Press" /> |
|
Alternatively it can be shortened to |
|
<% form block some_button %> onclick="return foo()" <% end %> |
|
Which is much shorter and more clear syntax that is recommended for the use. It is implemented starting |
from CppCMS 0.99.12. |
|
For generation of custom HTML for widgets you can |
always use widget properties directly: |
|
<input type="submit" name="<% button.name() %>" value="Press" /> ( <% button.help() %> ) |
|
See: [`cppcms::widgets` namespace](/cppcms_ref/latest/namespacecppcms_1_1widgets.html) for documentation of |
each specific widget properties. |
|
## CSRF Prevention |
|
When using forms it is important to prevent an |
attempts of CSRF. It is possible by setting |
`security.csrf.enable` settings value to true |
and by including a special CSRF token. |
|
### Syntax |
|
'csrf' ['token' | 'cookie' | 'script' ] |
|
Options: |
|
- None - inject the hidden input form that keeps the CSRF token. |
- `token` - inject the token itself rather then input form |
- `cookie` - inject the cookie name that keeps the token |
- `script` - create a javascript code that injects the input form reading the token from the cookie. |
|
|
### Description |
|
By default `<% csrf %>` inject a hidden form input |
that contains a session specific token. It is used like |
this: |
|
<form method="post" action="/path/to"><% csrf %> |
<% form as_p my_form %> |
</form> |
|
It creates a hidden input that keeps this token. |
|
**Notes:** |
|
1. it must be used only on POST forms and _never_ |
on GET forms as it would disclose the token |
in the referrer url. |
2. Caching pages the generated token would be invalid as it would be cached for some used and would not be session specific. |
|
In such case it is possible to set security.csrf.exposed |
settings value to true and it would keep the CSRF token |
in a special cookie, this cookie value |
should be used as CSRF token. |
|
The cookie name can be fetched using `cookie` option. |
|
It is also possible to inject a short javascript |
code that would read the cookie and dynamically |
generate the input form. This way it would be |
safe to use it with cached pages. |
|
## Rendering other views |
|
_Implemented in CppCMS 0.99.12_ |
|
### Syntax |
|
'render' [ ( VARIABLE | STRING ) , ] ( VARIABLE | STRING ) [ 'with' VARIABLE ] |
|
- First optional parameter - template name |
- Second parameter view name |
- `with` optional parameter content name |
|
### Description |
|
This function allows to render different views |
by their names that can be defined in constant |
strings or in variables allowing dynamic selection |
of views/skins. |
|
If the skin name is not provided current skin |
is used. |
|
The optional parameter is the content that is rendered. |
If no content given current "this" content is used. |
|
For example: |
|
<% render "sidebar" with sidebar_data %> |
<% render skin_name, "sidebar" with sidebar_data %> |
|
## Views Helpers |
|
_Implemented in CppCMS 0.99.12_ |
|
### Syntax |
|
This command is block command that comes in pair with `<% end %>` block. |
|
'using' IDENTIFIER [ 'with' VARIABLE ] as IDENTIFIER |
|
### Description |
|
For example: |
|
<% using foo with some_content as bar %> |
<% include baz() from bar %> |
<% include beep(10) from bar %> |
<% end using %> |
|
The `using` block creates local view object `bar` of |
a type `foo` that uses `some_content` as the content |
for the rendering. |
|
This local object `bar` can be accessed using `include` |
command with `from` syntax. So technically the example |
above is something like (after removing some details) |
|
{ |
foo bar(content.some_content); |
bar.baz(); |
bar.beep(10); |
} |
|
This is very useful for creating "helper" views that |
include common routines or patterns. |
|
If `with` part is not defined the current content |
is used as the content that should be rendered. |
|
If you need to call only a single function of some |
helper view there is a simple shortcut: |
|
<% include baz() using foo with some_content %> |
|
Which is equivalent to: |
|
<% using foo with some_content as _some_variable %> |
<% include baz() from _some_variable %> |
<% end using %> |
|
|
## 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 %> |
<% skin %> |
<% view 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. |
|
## 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++ out()<<content.a+content.b; %> |
2. Generally you should not use C++ code in template, use it if it is absolutely necessary. |
<!--toc-->
|
|
## Variable
|
|
The simplest templates command is showing variable. The syntax is trivial:
|
|
'=' VARIABLE
|
|
For example, if you want to show a content value `message` just write:
|
|
<%= message %>
|
|
It is actually translated to C++ code:
|
|
out()<<cppcms::filters::escape(content.message);
|
|
Where `escape` function writes the `message` member variable
|
of the content to the stream and escapes special HTML
|
characters `<`, `>`, `&`, `"` with their HTML representations like `<`
|
|
If you want to get a value of some property, you just write.
|
|
<%= some_property() %>
|
|
Which is translated to:
|
|
out()<<cppcms::filters::escape(content.some_property());
|
|
Note: since CppCMS 1.1 it is possible to change default filter using [filter block](#Default.Escape.Filter.Block).
|
|
## 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 a creation or call
|
of special filter object 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:
|
|
out()<<cppcms::filters::strftime(content.birthday,"%d/%m/%Y");
|
|
You can also concatenate filters using pipe symbol:
|
|
<%= birthday | strftime("%d %m %Y") | urlencode %>
|
|
Would be rendered as:
|
out()<<cppcms::filters::urlencode(cppcms::filters::strftime(content.birthday,"%d/%m/%Y"));
|
|
There is a set of filters predefined available for you, see [cppcms::filters](/cppcms_ref/latest/namespacecppcms_1_1filters.html) namespace reference.
|
|
One of the filters that is worth to noticing is `raw`: it allows to write a variable as-is, without any
|
HTML escaping.
|
|
<%= ready_html | raw %>
|
|
The `ready_html` variable will be written as-is to the output stream without escaping HTML symbols like `<`.
|
|
You can specify arbitrary external filters that are defined in `content` class. For example:
|
|
namespace data {
|
struct page {
|
...
|
virtual string bbcode(string const &);
|
...
|
};
|
}
|
|
Then in template we can specify:
|
|
<% class page uses data::page %>
|
<% template render() %>
|
<%= message | ext bbcode %>
|
<% 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 `booster::function<>` in order to prevent referring to external symbol.
|
|
## Variable - Deprecated Syntax
|
|
CppCMS supports older deprecated syntax (without "="):
|
|
VARIABLE [ '|' filter [ '|' filter ] ... ]
|
|
However it is not recommended due to fact that new
|
template keywords may be introduced that would hide the existing variable and cause syntax error.
|
|
## Default Escape Filter Block
|
|
Since: CppCMS 1.1
|
|
Block command filter allows in its current scope to change the default escape filter to a different one:
|
|
filter [ ext ] VARIABLE
|
|
For example
|
|
<p>Hello <%= name %></p>
|
<% filter jsescape %>
|
<script>
|
var name = "<%= name %>";
|
alert('Hello ' + name);
|
</script>
|
<% end %>
|
<p>You work at <%= job %></p>
|
|
First appearance of `name` would be escaped using standard HTML escape filter and the second one would allow safely include the text in JavaScript or JSON strings.
|
|
Upon end of filter block the filter is reverted to previous thus `job` would be escaped again using default HTML filter.
|
|
By pre-pending the filter name with `ext` it is possible to use a filter defined at content level - custom external filter.
|
|
Note: it does not change default `urlencode` filter for `<% url ... %>` commands
|
|
## Internationalization
|
|
### 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 of 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 the output stream. 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 [`booster::locale::format`](/cppcms_ref/latest/classbooster_1_1locale_1_1basic__format.html) or [`cppcms::locale::format`](/cppcms_ref/latest/classcppcms_1_1locale_1_1basic__format.html) for such substitutions (according to localization backend
|
CppCMS compiled with.)
|
|
|
`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.
|
3. You may use `<% if rtl %>` or `<% if not rtl %>` in order to test direction of text. This is actually equivalent to:
|
|
<% if (cppcms::locale::gettext("LTR",out().getloc())=="RTL") %>
|
|
See `if` statement for further description.
|
|
## URL Mapping
|
|
### Syntax
|
|
'url' STRING [ 'using' using-options ]
|
|
Where `using-options` is:
|
|
display-variable-block [ ',' display-variable-block [ ',' ... ] ]
|
|
Where `display-variable-block` is any variable of optional filters as described above. For example:
|
|
For example:
|
|
<% url "/blog/summary" %>
|
<% url "../summary" %>
|
<% url "/blog/post" using post_id %>
|
<% url "/blog/post" using post_id , slug | ext filter_for_url %>
|
|
### Description
|
|
The `url` tag is a templates interface to [`cppcms::url_mapper`](http://cppcms.com/cppcms_ref/latest/classcppcms_1_1url__mapper.html) interface accessible
|
from the `cppcms::application`
|
|
This tag allows to access to abstract URLs of the
|
application with given parameters. To learn how
|
to use URL mapping read the description of `url_mapper`
|
class given above.
|
|
The `using` parameters are passes for the formatting
|
of the URL parameters.
|
|
_Note:_ unlike the variable rendering the default escaping
|
for the parameters is `urlencode` and not `escape`
|
|
For example
|
|
<% url "/blog/post" using slug %>
|
|
Where `slug` is "Hi <you>" would generate something
|
like
|
|
"/myblog/Hi%20%3cyou%3e/"
|
|
and not
|
|
"/myblog/Hi <you>/"
|
|
|
## Including other templates
|
|
### Syntax
|
|
'include' IDENTIFIER '(' [ parameter [ ',' parameter ...] ] ')' [ 'from' IDENTIFIER | 'using' IDENTIFIER [ 'with' VARIABLE ] ]
|
|
Where `parameter` is one of VARIABLE, STRING or NUMBER. For example:
|
|
<% include title() %>
|
<% include parent::foo() %>
|
<% include bar(x,"test",-1.0) from foo %>
|
<% include bar(x,"test",-1.0) using baz %>
|
|
### Description
|
|
This command allows inclusion of other templates in place (actually calling other member functions.) You can include existing implementation in parent views
|
in order to extend them. For example:
|
|
<% view 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 view %>
|
<% view 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 view `sales` with an additional option.
|
|
The `from` option allows to include templates from
|
locally initialized views withing `using` blocks.
|
|
For more details read [Views Helpers](#Views.Helpers) section
|
|
## Rendering Forms
|
|
### Syntax
|
|
'form' ('as_p' | 'as_table' | 'as_ul' | 'as_dl' | 'as_space' | 'input' | 'block' | 'begin' | 'end' ) VARIABLE
|
|
`as_*` flags allow you to render `cppcms::form`, with
|
specific delimiters, when `input`, `begin`, `end` and `block` flags
|
allow you to render single part of the widget.
|
|
### 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>
|
|
Sometimes you want to perform custom rendering
|
of widgets that is not predefined by this list.
|
In such case you may render only `<input ...>` field
|
of the widget by calling
|
|
<% form input some_button %>
|
|
Which would be rendered like this:
|
|
<input type="submit" name="_3" value="Press" />
|
|
Note, `input` does not strictly means that it is limited
|
for widgets using HTML `input` tag, it works for
|
any other widget just limited to actual content rendering
|
without "help" messages, for example, for widget
|
`cppcms::widgets::textarea` it would be `<textarea ...>some text</textarea>`
|
|
Sometimes you need even more fine grained access
|
to widget rendering parts, for example you may
|
want to add some attributes to the widget in the view.
|
|
You may render `begin` or `end` part of the widget, such that you can insert HTML attributes between them or even JavaScript.
|
|
<% form begin some_button %> onclick="return foo()" <% form end some_button %>
|
|
Which would be rendered as
|
|
<input type="submit" name="_3" onclick="return foo()" value="Press" />
|
|
Alternatively it can be shortened to
|
|
<% form block some_button %> onclick="return foo()" <% end %>
|
|
Which is much shorter and more clear syntax that is recommended for the use. It is implemented starting
|
from CppCMS 0.99.12.
|
|
For generation of custom HTML for widgets you can
|
always use widget properties directly:
|
|
<input type="submit" name="<% button.name() %>" value="Press" /> ( <% button.help() %> )
|
|
See: [`cppcms::widgets` namespace](/cppcms_ref/latest/namespacecppcms_1_1widgets.html) for documentation of
|
each specific widget properties.
|
|
## CSRF Prevention
|
|
When using forms it is important to prevent an
|
attempts of CSRF. It is possible by setting
|
`security.csrf.enable` settings value to true
|
and by including a special CSRF token.
|
|
### Syntax
|
|
'csrf' ['token' | 'cookie' | 'script' ]
|
|
Options:
|
|
- None - inject the hidden input form that keeps the CSRF token.
|
- `token` - inject the token itself rather then input form
|
- `cookie` - inject the cookie name that keeps the token
|
- `script` - create a javascript code that injects the input form reading the token from the cookie.
|
|
|
### Description
|
|
By default `<% csrf %>` inject a hidden form input
|
that contains a session specific token. It is used like
|
this:
|
|
<form method="post" action="/path/to"><% csrf %>
|
<% form as_p my_form %>
|
</form>
|
|
It creates a hidden input that keeps this token.
|
|
**Notes:**
|
|
1. it must be used only on POST forms and _never_
|
on GET forms as it would disclose the token
|
in the referrer url.
|
2. Caching pages the generated token would be invalid as it would be cached for some used and would not be session specific.
|
|
In such case it is possible to set security.csrf.exposed
|
settings value to true and it would keep the CSRF token
|
in a special cookie, this cookie value
|
should be used as CSRF token.
|
|
The cookie name can be fetched using `cookie` option.
|
|
It is also possible to inject a short javascript
|
code that would read the cookie and dynamically
|
generate the input form. This way it would be
|
safe to use it with cached pages.
|
|
## Rendering other views
|
|
_Implemented in CppCMS 0.99.12_
|
|
### Syntax
|
|
'render' [ ( VARIABLE | STRING ) , ] ( VARIABLE | STRING ) [ 'with' VARIABLE ]
|
|
- First optional parameter - template name
|
- Second parameter view name
|
- `with` optional parameter content name
|
|
### Description
|
|
This function allows to render different views
|
by their names that can be defined in constant
|
strings or in variables allowing dynamic selection
|
of views/skins.
|
|
If the skin name is not provided current skin
|
is used.
|
|
The optional parameter is the content that is rendered.
|
If no content given current "this" content is used.
|
|
For example:
|
|
<% render "sidebar" with sidebar_data %>
|
<% render skin_name, "sidebar" with sidebar_data %>
|
|
## Views Helpers
|
|
_Implemented in CppCMS 0.99.12_
|
|
### Syntax
|
|
This command is block command that comes in pair with `<% end %>` block.
|
|
'using' IDENTIFIER [ 'with' VARIABLE ] as IDENTIFIER
|
|
### Description
|
|
For example:
|
|
<% using foo with some_content as bar %>
|
<% include baz() from bar %>
|
<% include beep(10) from bar %>
|
<% end using %>
|
|
The `using` block creates local view object `bar` of
|
a type `foo` that uses `some_content` as the content
|
for the rendering.
|
|
This local object `bar` can be accessed using `include`
|
command with `from` syntax. So technically the example
|
above is something like (after removing some details)
|
|
{
|
foo bar(content.some_content);
|
bar.baz();
|
bar.beep(10);
|
}
|
|
This is very useful for creating "helper" views that
|
include common routines or patterns.
|
|
If `with` part is not defined the current content
|
is used as the content that should be rendered.
|
|
If you need to call only a single function of some
|
helper view there is a simple shortcut:
|
|
<% include baz() using foo with some_content %>
|
|
Which is equivalent to:
|
|
<% using foo with some_content as _some_variable %>
|
<% include baz() from _some_variable %>
|
<% end using %>
|
|
|
## 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 %>
|
<% skin %>
|
<% view 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.
|
|
## 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++ out()<<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++ } %>` |
|
|
|
