Provided by: libtntnet-dev_1.6.3-3build1_i386 bug

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.conf(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
       cxxtools::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.

   <& 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 names-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.conf.  Variablenames ended with a semicolon are
       defined as static std::string-variables and filled from tntnet.conf.  A
       variable can be prepended by a type. The value from tntnet.conf 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.conf:
              dburl = "postgresql:dbname=mydb";

   <%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.

   <%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.

   <%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.

   <%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 paramters 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
              <%application>
              unsigned count = 0;
              </%application>

       Specify  a  application-specific  global variable, which is initialized
       with 0.

              <%session>
              MyClass sessionState;
              </%session>

       Specify a variable with a user-defined type, which holds the  state  of
       the session.

              <%thread scope="global">
              tntdb::Connection conn(dburl);
              </%thread>

       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.

AUTHOR

       This manual page was written by Tommi Mäkitalo <tommi@tntnet.org>.

SEE ALSO

       tntnet(1), ecppc(1),