POCO C++ Server Page Compiler User Guide
POCO PageCompiler
!!!Introduction
PageCompiler is a command line tool that translates HTML files (and other kinds of files) into
C++ code, more precisely, subclasses of Poco::Net::HTTPRequestHandler.
The source files can contain special directives that allow embedding of C++ code.
The syntax of these directives is based on the syntax used for
Java Server Pages (JSP), Active Server Pages (ASP) or Embedded JavaScript (EJS) templating.
This makes PageCompiler a C++-based HTML templating system. Since the translation of
the HTML template into a C++ class happens at compile time, runtime performance is
excellent.
The following introductory sample shows the code for a simple page that displays the
current date and time.
<%@ page class="TimeHandler" %>
<%!
#include "Poco/DateTime.h"
#include "Poco/DateTimeFormatter.h"
#include "Poco/DateTimeFormat.h"
using Poco::DateTime;
using Poco::DateTimeFormatter;
using Poco::DateTimeFormat;
%>
<%
DateTime now;
std::string dt(DateTimeFormatter::format(now, DateTimeFormat::SORTABLE_FORMAT));
%>
Time Sample
Time Sample
<%= dt %>
----
Sending the above code to the page compiler will generate two files, a header file
(<[TimeHandler.h]>) and an implementation file (<[TimeHandler.cpp]>).
The files define a subclass of Poco::Net::HTTPRequestHandler named <[TimeHandler]>.
The generated <[handleRequest]> member function contains code to send the HTML
code contained in the source file to the client, as well as the C++ code fragments found
in between the Scriptlet tags.
!!!C++ Server Page Syntax
The following special tags are supported in a C++ server page (CPSP) file.
!!Hidden Comment
A hidden comment documents the CPSP file, but is not sent to the client.
<%-- --%>
----
!!Implementation Declaration
An implementation declaration is copied to the implementation file immediately after
the block containing the standard <[#include]> directives.
It is used to include additional header files and <[using]> declarations,
as well as to define classes needed later on.
<%!
...
%>
----
!!Header Declaration
A header declaration is copied to the header file immediately after the
block containing the standard <[#include]> directives.
It is usually used to include the header file containing the definition
of the base class for the request handler, if a custom base class
is required.
<%!!
...
%>
----
!!Expression
The result of any valid C++ expression can be directly inserted into the page,
provided the result can be written to an output stream. Note that the expression
must not end with a semicolon. If HTML escape mode is enabled (new in POCO C++ Libraries
release 1.10.0), HTML special characters < > " &
will be replaced with corresponding character entities.
<%= %>
----
An alternative form of this is:
<%- %>
----
The latter form always copies the result of expression to the page verbatim,
without escaping special HTML characters.
Note that if escape mode is disabled, both forms are equivalent.
!!Scriptlet
Arbitrary C++ code fragments can be included using the Scriptlet directive.
<%
...
%>
----
!!Pre-Response Scriptlet
This is similar to an ordinary scriptlet, except that it will be executed
before the HTTP response is sent. This can be used to manipulate the HTTP response
object.
<%%
...
%>
The main feature of this directive is that it allows to send a redirect response to
the client if a certain condition is true.
Example:
<%%
if (!loggedIn)
{
return response.redirect("/");
}
%>
!!Include Directive
Another CPSP file can be included into the current file using the Include
Directive.
<%@ include file="" %>
----
Alternatively, this can also be written as:
<%@ include page="" %>
----
!!C++ Header Include Directive
Include a C++ header file in the generated header file.
<%@ header include="" %>
This corresponds to:
<%!! #include "" %>
A variant of this directive is:
<%@ header sinclude="" %>
This corresponds to:
<%!! #include <> %>
!!C++ Implementation Include Directive
Include a C++ header file in the generated implementation file.
<%@ impl include="" %>
This corresponds to:
<%! #include "" %>
A variant of this directive is:
<%@ impl sinclude="" %>
This corresponds to:
<%! #include <> %>
!!Page Directive
The Page Directive allows the definition of attributes that control
various aspects of C++ code generation.
<%@ page ="" ... %>
----
The following page attributes are supported:
!class
Specifies the name of the generated class.
Defaults to the base name of the source file with the word "Handler" appended.
!namespace
If specified, sets the namespace where the generated classes will be in.
No namespace will be used if omitted.
!baseClass
Specifies the name of the class used as the base class for the generated
request handler class.
Defaults to Poco::Net::HTTPRequestHandler. Do not forget to add a Header Declaration
containing an <[#include]> directive for the header file containing the definition
of that class, otherwise the generated code won't compile.
!context
Allows passing of a context object to the request handler's constructor.
The context object is stored in the request handler object and can be
obtained by calling the context() object.
The class of the context object must be specified.
Cannot be used together with <[ctorArg]>.
!ctorArg
Allows to specify the type of a single argument being passed to the constructor
of the generated request handler class. Can only be used together with <[baseClass]>.
The argument is passed on to the constructor of the base class, therefore, one of the
constructors of the base class must also accept a single argument of the specified type.
Cannot be used together with <[context]>.
!escape
Enable (set to <[true]>) or disable (<[false]>, default) HTML escape mode.
If enabled, the result of any expression enclosed in <%= %> tags will be HTML-escaped,
which means HTML special characters < > " & will be replaced by corresponding
character entities.
!export
Allows to specify a DLL import/export directive that is being added to the request
handler class definition. Useful for exporting a request handler class from a
Windows DLL.
!form
Enable or disable automatic form handling. If enabled, which is the default,
a Poco::Net::HTMLForm object is automatically created in the request handler
and accessible through a variable named <[form]>.
Set the value to <[false]> to disable form handling.
!formPartHandler
Allows you to pass a Poco::Net::PartHandler object to the form object for
processing file uploads. A subclass of Poco::Net::PartHandler must be
defined (using an Implementation Declaration), and the constructor of the part
handler must take a (const) reference to the request handler instance as argument.
!contentType
Allows you to specify the MIME content type for the page. Defaults to text/html.
!contentLanguage
Allows to specify a language tag (e.g., "en") that will be sent in the
response Content-Language header if the client sends an Accept-Language
header in the request.
!contentSecurityPolicy
Allows to specify the value of the HTTP Content-Security-Policy header.
!chunked
Allows you to specify whether the response is sent using chunked transfer encoding.
Defaults to <[true]>.
Set the value to <[false]> to disable chunked transfer encoding.
!compressed
Enables or disables response body compression. If set to <[true]>, and the client supports
the "gzip" content encoding (indicated by the "Accept-Encoding" header),
the response body will be compressed using the "gzip" format and the
"Content-Encoding" header will be set accordingly.
Defaults to <[false]>. Cannot be enabled together with response buffering.
!compressionLevel
Specify the compression level, if response body compression is enabled.
Valid values are 1 (fastest) to 9 (best compression). Defaults to 1.
!buffered
Enables or disables response buffering. Response buffering is disabled by default.
Set to <[true]> to enable buffering, or to <[false]> to disable it.
If response buffering is enabled, everything written to the response stream
is actually written to a string stream (<[std::ostringstream]>).
Sending of the HTTP response back to the client is deferred to
when the page is complete.
!cacheControl
If set to a non-empty string (e.g., "no-cache, no-store"), adds a "Cache-Control"
header to the response with the given argument as value.
!session (OSP only)
For use with the POCO Open Service Platform only.
Specifies the identifier of the session obtained from the OSP Web Session Manager.
If specified, a Poco::OSP::Web::WebSession object will be available in the
request handler through a variable named <[session]>. The variable is of type
Poco::OSP::Web::WebSession::Ptr. If the identifier starts with an asterisk
('@'), the identifier is considered to be a bundle property name, and the
session identifier is read from the respective bundle property.
!sessionTimeout (OSP only)
For use with the POCO Open Service Platform only.
Specifies the session timeout in minutes.
If the argument is a string, it is considered to be a bundle property name
and the timeout value is read from the respective bundle property.
!createSession (OSP only)
For use with the POCO Open Service Platform only.
If set to <[true]>, which is the default if the attribute is not specified,
a new session will be created if the request does not contain a (valid) session cookie.
If set to <[false]> and there is no existing session that matches the session
cookie. the <[session]> variable will be null.
!precondition
Allows to specify a C++ boolean expression which will be evaluated before processing
of the page begins. If the expression evaluates to false, processing of the
page is immediately terminated and no response is sent to the client.
The expression can be a call to a member function defined in the handler base class.
If that function returns false, it can send its own response to the client.
Example:
<%@ page precondition="checkCredentials(request, response)" %>
----
!path
Specify a server path for the page. If specified, the generated handler class
will contain a public static <[const std::string]> member variable named <[PATH]>
containing the specified path.
Example:
<%@ page path="/index.html" %>
----
!!Implicit Objects
The following objects are available in the handler code.
!request
The HTTP request object - an instance of Poco::Net::HTTPServerRequest.
!response
The HTTP response object - an instance of Poco::Net::HTTPServerRequest.
!responseStream
The output stream where the response body is written to.
!form
An instance of Poco::Net::HTMLForm for processing form arguments.
Only available if form processing has not been disabled by
setting the <[form]> page attribute to <[false]>.
!session (OSP only)
An instance of Poco::OSP::Web::WebSession::Ptr for accessing the
Poco::OSP::Web::WebSession object for the current session.
Only available with the POCO Open Service Platform, and if the
<[session]> page attribute has been specified. May be null if
the <[createSession]> attribute is false and no session exists.
!!!Invoking the Page Compiler
The Page Compiler is invoked from the command line. The file names of the
CPSP files to be compiled are specified as arguments.
A number of options control the code generation. Options are specified
using the usual command-line option syntax for the current operating
system (e.g., <[/help]> on Windows, <[--help]> or <[-h]> on Unix).
* help (h): display usage information
* define (D): define a configuration property
* config-file (f): load configuration properties from a file
* osp (O): add factory class definition/implementation for use with OSP
* apache (A): add factory class definition/implementation and shared library manifest for use with ApacheConnector
* escape (e): make HTML-escape mode default for all pages
Run the PageCompiler with the --help option to see all available options.
!!Configuration Properties
The Page Compiler supports one configuration property, named
<[PageCompiler.fileHeader]>, to optionally specify a header that is
included in every generated file.
The file header can contain references to other configuration properties,
using the usual property syntax: <[${property}]>.
For example, invoking the Page Compiler with the following configuration
file:
PageCompiler.fileHeader = //\n// ${outputFileName}\n//\n
----
places the following header at the beginning of each generated file
(<[]> is replaced with the actual name of the file):
//
//
//
----
The following pre-defined properties can be used in the file header:
* <[${inputFileName}]>: the name of the input file (with directories removed)
* <[${inputFilePath}]>: the complete path of the input file
* <[${dateTime}]>: the current date and time (YYYY-MM-DD HH:MM:SS)
* <[${outputFileName}]>: the name of the current output file (header or implementation file), with
directories removed
* <[${outputFilePath}]>: the complete path of the current output file