Provided by: libtntnet-dev_2.2.1-2_amd64 
NAME
ecpp - template-language for tntnet(8)
DESCRIPTION
ecpp is the template-language used by the tntnet-system to generate dynamic content.
A template consists of normal content (normally html-data) enriched with special tags,
which trigger some special handling.
One ecpp-file is compiled into a C++-class. The C++-class is placed into the namespace
component. A ecpp-file compiled into a C++-class is called component. The name of the
class is the basename of the file.
request, reply, qparam
Each component has 3 parameters: request, reply and qparam. request holds information
about the client-request like http headers and the url, but also additional parameters
specified in the config-file tntnet.xml(7). The type of request is tnt::HttpRequest.
reply receives the answer from the component. The component can set additional
http-headers here, set cookies and - most important - generate output. The most important
methods here are reply.out() and reply.sout(). Both return a std::ostream, which receives
the output of the component. reply.sout() has a filter installed, which translates some
characters, whith special meanings in html to the corresponding html-entities. The
characters are <, >, &, " and '. This is useful for printing values from variables to the
html-code.
qparam holds the query-parameters parsed from GET- or POST-parameters or received from
other components. The type of qparam is tnt::query_params. Normally you use a
<%args>-block to specify the parameters, but there are special cases, where it is useful
to access these directly.
component adressing
Each component has a unique name. The name is composed from the class-name, the character
'@' and the name of the shared library, it is located. Components can have internal
subcomponents. The name of the internal subcomponent is appended to the classname
separated by a dot (.).
special rule for line feeds after a </%something>-tag
A line feed immediately after a closing tag for all <%something>-blocks are ignored. Hence
blocks followed immediately one after another does not generate white space in output,
which is often undesirable.
error-handling
Error-handling is done by exception. Tntnet catches all exceptions thrown by components
and handles them properly. Exceptions must be derived from std::exception. Exceptions
derived from tnt::HttpError, are handled separately. They carry a http-return-code, which
is sent to the client. Other exceptions derived from std::exception, result in a http
error code 500 (Internal Server Error).
TAGS
<$ expr $>
Print expressions expr to the outputstream. The characters <, >, &, " and ', which
have special meanings in html, are translated to the corresponding html-entities.
<$$ expr $>
Print expressions expr without translating characters with special meaning in html
to html entities to the output stream.
<? cond ? expr ?>
Conditional output. Print expression expr to the outputstream, if cond evaluates to
true. Characters with special meaning in html are translated to the corresponding
html-entities.
<?? cond ? expr ?>
Conditional output. Print expression expr to the outputstream, if cond evaluates to
true. Characters with special meaning in html are not translated to the
corresponding html-entities.
<& component [ arguments ] >
Call the specified component. The output of the component is printed into the
outputstream. If the component-name does not start with a letter, the ecpp-compiler
treats it as a expression, which returns the name of the component. You must
surround the expression in brackets, if it contains spaces.
The arguments-part specify the parameters, the component will receive. Arguments
are name-value-pairs separated by '='. They are put in the qparam-parameter of the
component and are normally declared in the <%args>-block. Values can be specified
in 3 forms:
As a plain word without spaces
As a string enclosed in quotation marks
As a expression enclosed in brackets
A single plain word in the argumentlist is treated as a variable of type
cxxtools::query_params and a copy is passed to the component. Other parameters are
added to this copy. If you want to pass all parameters of the current component put
the variable qparam as a plain word in the argument list.
</&component>
Closing-tag for a component-call. When components are called, this closing-tag
might occur later. The code in <%close>-block is placed here.
<{...}>
C++-inline-processing-block. The code in this block is copied into the C++-class
unchanged.
A linefeed after the closing tag is not ignored.
<#...#>
Comment-block. Everything in this block is ignored.
<%application [ scope="component|page|global" ] >...</%application>
Variables defined here, have the lifetime of the application.
Application-scope is automatically locked.
<%args>...</%args>
Defines GET- or POST-parameters recieved by the component.
Each argument has a name and optionally a defaul-value. The default-value is
delimited by '=' from the name. A single argument-definition followed by a
semicolon (;). In the component a variable with the same name of type std::string
is defined, which receives the value.
A argument-name can be prefixed by a type-definition. The ecpp-compiler generates
code, which tries to convert the value with the input-stream-operator. This means,
that each type, which can be read from a input-stream (std::istream) can be used.
If the argument can't be converted, a exception is thrown.
Argumentnames can be postfixed by empty square-brackets. This defines a std::vector
with the specified type or std::string, if no type is specified. This way multiple
values with the same name can be received. If a type is specified, each value is
converted to the target-type.
<%close>...</%close>
Code in these tags is placed into the calling component, when a closing tag
</&component> is found.
The <%close> receives the same parameters like the corresponding normal component
call.
<%config>...</%config>
Often webapplications need some configuration like database-names or
login-information to the database. These configuratioin-variables can be read from
the tntnet.xml. Variablenames ended with a semicolon are defined as static
std::string-variables and filled from tntnet.xml. A variable can be prepended by a
type. The value from tntnet.xml is then converted with a std::istream.
You can also specify a default value by appending a '=' and the value to the
variable.
Example:
<%config>
dburl = "sqlite:db=mydbfile.sqlite";
int maxvalue = 10;
</%config>
tntnet.xml:
<dburl>postgresql:dbname=mydb</dburl>
<%cpp>...</%cpp>
C++-processing-block. The code between these tags are copied into the C++-class
unchanged.
A linefeed after the closing tag is ignored.
<%def name>...</%def>
Defines a internal subcomponent with the name name, which can be called like other
components.
<%doc>...</%doc>
Comment-block. Everything in this block is ignored.
A linefeed after the closing tag is ignored.
<%get>...</%get>
Works like a <%args> block but receives only GET parameters.
<%i18n>...</%i18n>
Encloses a block of text-data, which is to be translated. See ecppl(1) and
ecppll(1) for details.
<%include>filename</%include>
The specified file is read and compiled.
<%param>...</%param>
Defines parameter received from calling components. In contrast to query-parameters
these variables can be of any type. The syntax (and the underlying technology) is
the same like in scoped variables. See the description about scoped variables to
see how to define parameters. The main difference is, that a parameter variable has
no scope, since the parameter is always local to the component.
<%out> expr </%out>
Same as <$$ ... $>. Prints the contained C++ expression expr.
<%post>...</%post>
Works like a <%args> block but receives only POST parameters.
<%pre>...</%pre>
Defines C++-code, which is placed outside the C++-class and outside the
namespace-definition. This is a good place to define #include-directives.
<%request [ scope="component|page|global" ] >...</%request>
Define request-scope variables. Variables defined here, has the lifetime of the
request.
<%session [ scope="component|page|global" ] >...</%session>
Variables defined here, has the lifetime of the session.
Sessions are identified with cookies. If a <%session>-block is defined somewhere in
a component, a session-cookie is sent to the client.
Sessions are automatically locked.
<%securesession [ scope="component|page|global" ] >...</%securesession>
Secure session is just like session but a secure cookie is used to identify the
session. Secure cookies are transfered only over a ssl connection from the browser
and hence the variables are only kept in a ssl secured application.
If a variable defined here is used in a non ssl page, the variable values are lost
after the current request.
<%sout> expr </%sout>
Same as <$ ... $>. Prints the contained C++ expression expr. The characters <, >,
&, " and ', which have special meanings in html, are translated to the
corresponding html-entities.
<%thread [ scope="component|page|global" ] >...</%thread>
Variables defined here, has the lifetime of the thread. Each thread has his own
instance of these variables.
Thread-scope-variables do not need to be locked at all, because they are only valid
in the current thread.
SCOPED VARIABLES
Scoped variables are c++-variables, whose lifetime is handled by tntnet. These variables
has a lifetime and a scope. The lifetime is defined by the tag, used to declare the
variable and the scope is passed as a parameter to the tag.
There are 5 different lifetimes for scoped variables:
request
The variable is valid in the current request. The tag is <%request>.
application
The variable is valid in the application. The tag is <%application>. The
application is specified by the shared-library of the top-level component.
session
The variable is valid for the current session. The tag is <%session>. If at least
session-variable is declared in the current request, a session-cookie is sent to
the client.
thread The variable is valid in the current thread. The tag is <%thread>.
param The variable receives parameters. The tag is <%param>.
And 3 scopes:
component
The variable is only valid in the same component. This is the default scope.
page The variable is shared between the components in a single ecpp-file. You can
specify multiple internal subcomponents in a %def-block. Variables, defined in
page-scope are shared between these subcomponents.
global Variables are shared between all components. If you define the same variable with
global-scope in different components, they must have the same type. This is
achieved most easily defining them in a separate file and include them with a
<%include>-block.
Variables are automatically locked as needed. If you use session-variables, tntnet
ensures, that all requests of the same session are serialized. If you use
application-variables, tntnet serializes all requests to the same
application-scope. Request- and thread-scope variables do not need to be locked at
all, because they are not shared between threads.
Syntax of scoped variables
Scoped variables are declared with exactly the same syntax as normal variables in
c++-code. They can be of any type and are instantiated, when needed. Objects, which do
not have default constructors, need to be specified with proper constructor-parameters in
brackets or separated by '='. The parameters are only used, if the variable need to be
instantiated. This means, that parameters to e.g. application-scope variables are only
used once. When the same component is called later in the same or another request, the
parameters are not used any more.
Examples
Specify a application-specific global variable, which is initialized with 0:
<%application>
unsigned count = 0;
</%application>
Specify a variable with a user-defined type, which holds the state of the session:
<%session>
MyClass sessionState;
</%session>
Specify a persistent databaseconnection, which is initialized, when first needed and hold
for the lifetime of the current thread. This variable may be used in other components:
<%thread scope="global">
tntdb::Connection conn(dburl);
</%thread>
AUTHOR
This manual page was written by Tommi Mäkitalo ⟨tommi@tntnet.org⟩.
SEE ALSO
tntnet(1), ecppc(1)