<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>POCO C++ Server Page Compiler User Guide</title>
<meta http-equiv="content-type" content="text/html; charset=utf-8"/>
<meta name="author" content="Applied Informatics Software Engineering GmbH and Contributors"/>
<meta name="publisher" content="Applied Informatics Software Engineering GmbH and Contributors"/>
<meta name="copyright" content="Copyright (c) 2009, Applied Informatics Software Engineering GmbH and Contributors"/>
<meta name="language" content="en"/>
<meta name="date" content="2009-11-24"/>
<meta name="generator" content="PocoDoc"/>
<link rel="stylesheet" href="css/styles.css" type="text/css"/>
</head>
<body bgcolor="#ffffff" leftmargin="0" topmargin="0">
<div class="header">
<h1 class="category">POCO PageCompiler</h1>
<h1 class="title">POCO C++ Server Page Compiler User Guide</h1>
</div>
<div class="body">
<h2>Contents</h2>
<div class="toc"><ul>
<li class="level1"><a href="#0">Introduction</a></li>
<li class="level1"><a href="#1">C++ Server Page Syntax</a></li>
<li class="level2"><a href="#2">Hidden Comment</a></li>
<li class="level2"><a href="#3">Implementation Declaration</a></li>
<li class="level2"><a href="#4">Header Declaration</a></li>
<li class="level2"><a href="#5">Expression</a></li>
<li class="level2"><a href="#6">Scriptlet</a></li>
<li class="level2"><a href="#7">Pre-Response Scriptlet</a></li>
<li class="level2"><a href="#8">Include Directive</a></li>
<li class="level2"><a href="#9">C++ Header Include Directive</a></li>
<li class="level2"><a href="#10">C++ Implementation Include Directive</a></li>
<li class="level2"><a href="#11">Page Directive</a></li>
<li class="level3"><a href="#12">class</a></li>
<li class="level3"><a href="#13">namespace</a></li>
<li class="level3"><a href="#14">baseClass</a></li>
<li class="level3"><a href="#15">ctorArg</a></li>
<li class="level3"><a href="#16">export</a></li>
<li class="level3"><a href="#17">form</a></li>
<li class="level3"><a href="#18">formPartHandler</a></li>
<li class="level3"><a href="#19">contentType</a></li>
<li class="level3"><a href="#20">chunked</a></li>
<li class="level3"><a href="#21">session (OSP only)</a></li>
<li class="level3"><a href="#22">sessionTimeout (OSP only)</a></li>
<li class="level3"><a href="#23">buffered</a></li>
<li class="level3"><a href="#24">precondition</a></li>
<li class="level2"><a href="#25">Implicit Objects</a></li>
<li class="level3"><a href="#26">request</a></li>
<li class="level3"><a href="#27">response</a></li>
<li class="level3"><a href="#28">responseStream</a></li>
<li class="level3"><a href="#29">form</a></li>
<li class="level3"><a href="#30">session (OSP only)</a></li>
<li class="level1"><a href="#31">Invoking the Page Compiler</a></li>
<li class="level2"><a href="#32">Configuration Properties</a></li>
</ul></div>
<div class="description">
<p></p><h2><a name="0">Introduction</a></h2><p>
PageCompiler is a command line tool that translates HTML files (and other kinds of files) into C++ code, more precisely, subclasses of <a href="Poco.Net.HTTPRequestHandler.html" title="class Poco::Net::HTTPRequestHandler">Poco::Net::HTTPRequestHandler</a>. The source files can contain special directives that allow it to include C++ code into the source file. The syntax of this directives is based on the syntax used for Java Server Pages (JSP) and Active Server Pages. </p>
<p>The following introductory sample shows the code for a simple page that displays the current date and time. </p>
<p></p>
<pre><%@ 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));
%>
<html>
<head>
<title>Time Sample</title>
</head>
<body>
<h1>Time Sample</h1>
<p><%= dt %></p>
</body>
</html>
</pre>
<p> </p>
<p>Sending the above code to the page compiler will generate two files, a header file (<tt>TimeHandler.h</tt>) and an implementation file (<tt>TimeHandler.cpp</tt>). The files define a subclass of <a href="Poco.Net.HTTPRequestHandler.html" title="class Poco::Net::HTTPRequestHandler">Poco::Net::HTTPRequestHandler</a> named <tt>TimeHandler</tt>. The generated <tt>handleRequest</tt> 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. </p>
<p></p>
<p></p><h2><a name="1">C++ Server Page Syntax</a></h2><p>
</p>
<p>The following special tags are supported in a C++ server page (CPSP) file. </p>
<p></p><h3><a name="2">Hidden Comment</a></h3><p>
</p>
<p>A hidden comment documents the CPSP file, but is not sent to the client. </p>
<p></p>
<pre><%-- <comment> --%>
</pre>
<p> </p>
<p></p><h3><a name="3">Implementation Declaration</a></h3><p>
</p>
<p>An implementation declaration is copied to the implementation file immediately after the block containing the standard <tt>#include</tt> directives. It is used to include additional header files and <tt>using</tt> declarations, as well as to define classes needed later on. </p>
<p></p>
<pre><%!
<declaration>
...
%>
</pre>
<p> </p>
<p></p><h3><a name="4">Header Declaration</a></h3><p>
</p>
<p>A header declaration is copied to the header file immediately after the block containing the standard <tt>#include</tt> 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. </p>
<p></p>
<pre><%!!
<declaration>
...
%>
</pre>
<p> </p>
<p></p><h3><a name="5">Expression</a></h3><p>
</p>
<p>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. </p>
<p></p>
<pre><%= <expression> %>
</pre>
<p> </p>
<p></p><h3><a name="6">Scriptlet</a></h3><p>
</p>
<p>Arbitrary C++ code fragments can be included using the Scriptlet directive. </p>
<p></p>
<pre><%
<statement>
...
%>
</pre>
<p> </p>
<p></p><h3><a name="7">Pre-Response Scriptlet</a></h3><p>
</p>
<p>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. </p>
<p></p>
<pre><%%
<statement>
...
%>
</pre>
<p>The main feature of this directive is that it allows to send a redirect response to the client if a certain condition is true. </p>
<p>Example: </p>
<pre><%%
if (!loggedIn)
{
return response.redirect("/");
}
%>
</pre>
<p></p><h3><a name="8">Include Directive</a></h3><p>
</p>
<p>Another CPSP file can be included into the current file using the Include Directive. </p>
<p></p>
<pre><%@ include page="<path>" %>
</pre>
<p> </p>
<p></p><h3><a name="9">C++ Header Include Directive</a></h3><p>
</p>
<p>Include a C++ header file in the generated header file. </p>
<pre><%@ header include="<path>" %>
</pre>
<p>This corresponds to: </p>
<pre><%!! #include "<path>" %>
</pre>
<p>A variant of this directive is: </p>
<pre><%@ header sinclude="<path>" %>
</pre>
<p>This corresponds to: </p>
<pre><%!! #include <<path>> %>
</pre>
<p></p><h3><a name="10">C++ Implementation Include Directive</a></h3><p>
</p>
<p>Include a C++ header file in the generated implementation file. </p>
<pre><%@ impl include="<path>" %>
</pre>
<p>This corresponds to: </p>
<pre><%! #include "<path>" %>
</pre>
<p>A variant of this directive is: </p>
<pre><%@ impl sinclude="<path>" %>
</pre>
<p>This corresponds to: </p>
<pre><%! #include <<path>> %>
</pre>
<p></p><h3><a name="11">Page Directive</a></h3><p>
</p>
<p>The Page Directive allows the definition of attributes that control various aspects of C++ code generation. </p>
<p></p>
<pre><%@ page <attr>="<value>" ... %>
</pre>
<p> </p>
<p>The following page attributes are supported: </p>
<p></p><h4><a name="12">class</a></h4><p>
</p>
<p>Specifies the name of the generated class. Defaults to the base name of the source file with the word "Handler" appended. </p>
<p></p><h4><a name="13">namespace</a></h4><p>
</p>
<p>If specified, sets the namespace where the generated classes will be in. No namespace will be used if omitted. </p>
<p></p><h4><a name="14">baseClass</a></h4><p>
</p>
<p>Specifies the name of the class used as the base class for the generated request handler class. Defaults to <a href="Poco.Net.HTTPRequestHandler.html" title="class Poco::Net::HTTPRequestHandler">Poco::Net::HTTPRequestHandler</a>. Do not forget to add a Header Declaration containing an <tt>#include</tt> directive for the header file containing the definition of that class, otherwise the generated code won't compile. </p>
<p></p><h4><a name="15">ctorArg</a></h4><p>
</p>
<p>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 <tt>baseClass</tt>. 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. </p>
<p></p><h4><a name="16">export</a></h4><p>
</p>
<p>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. </p>
<p></p><h4><a name="17">form</a></h4><p>
</p>
<p>Enable or disable automatic form handling. If enabled, which is the default, a <a href="Poco.Net.HTMLForm.html" title="class Poco::Net::HTMLForm">Poco::Net::HTMLForm</a> object is automatically created in the request handler and accessible through a variable named <tt>form</tt>. Set the value to <tt>false</tt> to disable form handling. </p>
<p></p><h4><a name="18">formPartHandler</a></h4><p>
</p>
<p>Allows you to pass a <a href="Poco.Net.PartHandler.html" title="class Poco::Net::PartHandler">Poco::Net::PartHandler</a> object to the form object for processing file uploads. A subclass of <a href="Poco.Net.PartHandler.html" title="class Poco::Net::PartHandler">Poco::Net::PartHandler</a> 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. </p>
<p></p><h4><a name="19">contentType</a></h4><p>
</p>
<p>Allows you to specify the MIME content type for the page. Defaults to text/html. </p>
<p></p><h4><a name="20">chunked</a></h4><p>
</p>
<p>Allows you to specify whether the response is sent using chunked transfer encoding. Defaults to <tt>true</tt>. Set the value to <tt>false</tt> to disable chunked transfer encoding. </p>
<p></p><h4><a name="21">session (OSP only)</a></h4><p>
</p>
<p>For use with the POCO Open Service Platform only. </p>
<p>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 <tt>session</tt>. The variable is of type Poco::OSP::Web::WebSession::Ptr. </p>
<p></p><h4><a name="22">sessionTimeout (OSP only)</a></h4><p>
</p>
<p>For use with the POCO Open Service Platform only. </p>
<p>Specifies the session timeout in minutes. </p>
<p></p><h4><a name="23">buffered</a></h4><p>
</p>
<p>Enables or disables response buffering. Response buffering is disabled by default. Set to <tt>true</tt> to enable buffering, or to <tt>false</tt> to disable it. If response buffering is enabled, everything written to the response stream is actually written to a string stream (<tt>std::ostringstream</tt>). Sending of the HTTP response back to the client is deferred to when the page is complete. </p>
<p></p><h4><a name="24">precondition</a></h4><p>
</p>
<p>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. </p>
<p>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. </p>
<p>Example: </p>
<pre><%@ page precondition="checkCredentials(request, response)" %>
</pre>
<p> </p>
<p></p><h3><a name="25">Implicit Objects</a></h3><p>
</p>
<p>The following objects are available in the handler code. </p>
<p></p><h4><a name="26">request</a></h4><p>
</p>
<p>The HTTP request object - an instance of <a href="Poco.Net.HTTPServerRequest.html" title="class Poco::Net::HTTPServerRequest">Poco::Net::HTTPServerRequest</a>. </p>
<p></p><h4><a name="27">response</a></h4><p>
</p>
<p>The HTTP response object - an instance of <a href="Poco.Net.HTTPServerRequest.html" title="class Poco::Net::HTTPServerRequest">Poco::Net::HTTPServerRequest</a>. </p>
<p></p><h4><a name="28">responseStream</a></h4><p>
</p>
<p>The output stream where the response body is written to. </p>
<p></p><h4><a name="29">form</a></h4><p>
</p>
<p>An instance of <a href="Poco.Net.HTMLForm.html" title="class Poco::Net::HTMLForm">Poco::Net::HTMLForm</a> for processing form arguments. Only available if form processing has not been disabled by setting the <tt>form</tt> page attribute to <tt>false</tt>. </p>
<p></p><h4><a name="30">session (OSP only)</a></h4><p>
</p>
<p>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 <tt>session</tt> page attribute has been specified. </p>
<p></p>
<p></p><h2><a name="31">Invoking the Page Compiler</a></h2><p>
</p>
<p>The Page Compiler is invoked from the command line. The file names of the CPSP files to be compiled are specified as arguments. </p>
<p>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., <tt>/help</tt> on Windows, <tt>--help</tt> or <tt>-h</tt> on Unix). </p>
<p></p>
<ul>
<li>help (h): display usage information </li>
<li>define (D): define a configuration property </li>
<li>config-file (f): load configuration properties from a file </li>
<li>osp (O): add factory class definition/implementation for use with OSP </li>
<li>apache (A): add factory class definition/implementation and shared library manifest for use with ApacheConnector </li>
</ul>
<p></p><h3><a name="32">Configuration Properties</a></h3><p>
</p>
<p>The Page Compiler supports one configuration property, named <tt>PageCompiler.fileHeader</tt>, to optionally specify a header that is included in every generated file. </p>
<p>The file header can contain references to other configuration properties, using the usual property syntax: <tt>${property}</tt>. </p>
<p>For example, invoking the Page Compiler with the following configuration file: </p>
<p></p>
<pre>PageCompiler.fileHeader = //\n// ${outputFileName}\n//\n
</pre>
<p> </p>
<p>places the following header at the beginning of each generated file (<tt><filename></tt> is replaced with the actual name of the file): </p>
<p></p>
<pre>//
// <filename>
//
</pre>
<p> </p>
<p>The following pre-defined properties can be used in the file header: </p>
<p></p>
<ul>
<li><tt>${inputFileName}</tt>: the name of the input file (with directories removed) </li>
<li><tt>${inputFilePath}</tt>: the complete path of the input file </li>
<li><tt>${dateTime}</tt>: the current date and time (YYYY-MM-DD HH:MM:SS) </li>
<li><tt>${outputFileName}</tt>: the name of the current output file (header or implementation file), with directories removed </li>
<li><tt>${outputFilePath}</tt>: the complete path of the current output file </li>
</ul>
<p></p>
<p></p>
</div>
<p class="footer">POCO C++ Libraries 1.3.6-all<br />
Copyright © 2009, <a href="http://pocoproject.org/" target="_blank">Applied Informatics Software Engineering GmbH and Contributors</a></p>
</body>
</html>
