Apache2-PageKit
view release on metacpan or search on metacpan
docsrc/reference.xml view on Meta::CPAN
<!--
emphasis
filename
computeroutput
constant
literal
replaceable
varname
informalexample
programlisting
-->
<chapter><?dbhtml filename="reference.html"?>
<chapterinfo>
<releaseinfo role="meta">
$Id: reference.xml,v 1.68 2004/04/06 09:18:30 borisz Exp $
</releaseinfo>
</chapterinfo>
<title>Reference</title>
<sect1>
<title>Configuration Options</title>
<sect2>
<title>Global Attributes</title>
<para>
These settings are global in the sense that they apply over all servers, views, and pages.
They are attributes of the <GLOBAL> tag in <filename>Config/Config.xml</filename>.
</para>
<variablelist>
<varlistentry id="config.global.cache_dir">
<term>cache_dir</term>
<listitem>
<para>
Specifies the directory where the PageKit Template cache files are stored.
Defaults to <filename>View/pkit_cache</filename>.
</para>
</listitem>
</varlistentry>
<varlistentry id="config.global.cookies_not_set_page">
<term>cookies_not_set_page</term>
<listitem>
<para>
This is the page that gets displayed if the user attempts to log in,
but their cookies are not enabled. Defaults to <literal><link linkend="config.global.login_page">login_page</link></literal>.
</para>
</listitem>
</varlistentry>
<varlistentry id="config.global.default_errorstr">
<term>default_errorstr</term>
<listitem>
<para>
Default errorstr, that PageKit use for <link linkend="pkit.errorstr">PKIT_ERRORSTR</link>,
<link linkend="model.api.pkit_set_errorspan">pkit_set_errorspan</link> and the obsolete
<link linkend="model.api.pkit_set_errorfont">pkit_set_errorfont</link>.
</para>
<para>
Defaults to <emphasis>#ff0000</emphasis>.
</para>
</listitem>
</varlistentry>
<varlistentry id="config.global.default_input_charset">
<term>default_input_charset</term>
<listitem>
<para>
Default charset that PageKit Templates and Model output are encoded in.
Defaults to
<emphasis>ISO-8859-1</emphasis>. PageKit uses this to convert the
PageKit templates and output from <link linkend="model.api.output_convert">output_convert</link> to UTF-8.
</para>
</listitem>
</varlistentry>
<varlistentry id="config.global.default_output_charset">
<term>default_output_charset</term>
<listitem>
<para>
Default charset that PageKit templates compiled to.
Defaults to
<emphasis>ISO-8859-1</emphasis>. This should be the charset that
supports your <link linkend="config.global.default_input_charset">default_input_charset</link> and has good support among the client's browsers.
</para>
</listitem>
</varlistentry>
<varlistentry id="config.global.default_lang">
<term>default_lang</term>
<listitem>
<para>
Default language outputed when no language is specified
or request language is not available. Defaults to
<emphasis>en</emphasis>.
</para>
</listitem>
</varlistentry>
<varlistentry id="config.global.default_page">
<term>default_page</term>
<listitem>
<para>
Default page user gets when no page is specified. Defaults to
<emphasis>index</emphasis>.
</para>
</listitem>
</varlistentry>
<varlistentry id="config.global.errorspan_begin_tag">
<term>errorspan_begin_tag</term>
<listitem>
<para>
Specifies the start tag for <PKIT_ERRORSPAN ... > and <PKIT_ERRORFONT ... >.
Defaults to <emphasis><font color="<PKIT_ERRORCOLOR>"></emphasis>.
<informalexample>
<programlisting>
errorspan_begin_tag = "&lt;span class=error&gt;"
errorspan_end_tag = "&lt;/span&gt;"
</programlisting>
</informalexample>
</para>
<para>
See also <literal><link linkend="config.global.errorspan_end_tag">errorspan_end_tag</link></literal>.
</para>
</listitem>
</varlistentry>
<varlistentry id="config.global.errorspan_end_tag">
<term>errorspan_end_tag</term>
<listitem>
<para>
Specifies the end tag for <PKIT_ERRORSPAN ... > and <PKIT_ERRORFONT ... >.
Defaults to <emphasis></font></emphasis>.
</para>
<para>
See also <literal><link linkend="config.global.errorspan_begin_tag">errorspan_begin_tag</link></literal>.
</para>
</listitem>
</varlistentry>
<varlistentry id="config.global.fop_command">
<term>fop_command</term>
<listitem>
<para>
Command line that should be used to run Apache XML FOP to generate
PDF output. PageKit will append FO file and PDF file arguments at end.
</para>
<informalexample>
<programlisting>
# some example fop command lines
fop_command = "/usr/java/jdk1.3.0_02/bin/java -cp /usr/local/javaclass/fop org.apache.fop.apps.CommandLine"
fop_command = "/usr/java/jdk1.3.0_02/bin/java -cp /usr/local/javaclass/fop org.apache.fop.apps.CommandLine"
fop_command = "/usr/java/jdk1.3.0_02/bin/java -cp /usr/local/javaclass/fop org.apache.fop.apps.Fop"
fop_command = "/usr/lib/java/bin/java -classpath /opt/fop-0.20.3/lib/xerces-1.2.3.jar:/opt/fop-0.20.3/lib/xalanj1compat.jar:/opt/fop-0.20.3/lib/xalan-2.0.0.jar:/opt/fop-0.20.3/lib/xalan-1.2.2.jar:/opt/fop-0.20.3/lib/stylebook.jar:/opt/fop-0.20.3/lib...
# disable fop_command from Apache::PageKit 1.14 on
fop_command = ""
# or remove the fop_command line option from Config.xml at all.
</programlisting>
</informalexample>
<para>
Can be overriden by specifying the server <link linkend="config.server.fop_command">fop_command</link> configuration option.
</para>
<para>
As of version 1.13 of Apache::PageKit a error is issued, if no global <link linkend="config.global.fop_command">fop_command</link> or server <link linkend="config.server.fop_command">fop_command</link> is found in the Config.xml and a 'applica...
Form Apache::PageKit 1.14 on, no error message is issued and no special action is taken.
</para>
</listitem>
</varlistentry>
<varlistentry id="config.global.gzip_output">
<term>gzip_output</term>
<listitem>
<para>
If set to <emphasis>all</emphasis>, output is gzipped dynamic and static content for browsers that send a
<literal>Accept-Encoding</literal> header containing <literal>gzip</literal>. If set to <emphasis>static</emphasis>, output is gzipped for
static pages only.
Defaults to
<emphasis>none</emphasis>.
</para>
</listitem>
</varlistentry>
<varlistentry id="config.global.login_page">
<term>login_page</term>
<listitem>
<para>
Page that gets displayed when user attempts to log in. Defaults to
<emphasis>login</emphasis>.
</para>
</listitem>
</varlistentry>
<varlistentry id="config.global.logout_kills_session">
<term>logout_kills_session</term>
docsrc/reference.xml view on Meta::CPAN
See also <link linkend="model.api.pkit_redirect">pkit_redirect</link> and
<link linkend="model.api.pkit_internal_redirect">pkit_internal_redirect</link>
</para>
</refsect1>
</refentry>
<refentry id="model.api.pkit_internal_redirect">
<refnamediv>
<refname>pkit_internal_redirect</refname>
<refpurpose>
Internal redirection to another page inside the PageKit application
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<synopsis>
$model->pkit_internal_redirect('myaccount');
return;
</synopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
Resets the page_id. This is usually used "redirect" to different template.
</para>
<para>
Note that you should perform a <link linkend="model.api.pkit_redirect">pkit_redirect</link>
for <emphasis role="bold">POST</emphasis> requests.
From PageKit v1.12 on pkit_internal_redirect handle full url's and strip them.
Parameters at the end of request are removed.
This is usefull if you get the url from a pkit_done like parameter.
</para>
</refsect1>
</refentry>
<refentry id="model.api.pkit_redirect">
<refnamediv>
<refname>pkit_redirect</refname>
<refpurpose>
Redirect to another URL.
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<synopsis>
$model->pkit_redirect("http://www.pagekit.org/");
</synopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
It is strongly recommend that you use this method on pages where a
query that changes the state of the application is executed. Typically
these are POST queries that update the database.
</para>
<para>
Note that this passes along the messages set my <link linkend="model.api.pkit_message">pkit_message</link> if applicable.
</para>
</refsect1>
</refentry>
<refentry id="model.api.pkit_set_errorfont">
<refnamediv>
<refname>pkit_set_errorfont</refname>
<refpurpose>
Sets PKIT_ERRORSPAN tags
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<synopsis>
$model->pkit_set_errorfont('state');
# possible since version 1.08
$model->pkit_set_errorfont( 'state', '#00ff00' );
</synopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
Superfluous since PageKit 1.08 please use <link linkend="model.api.pkit_set_errorspan">pkit_set_errorspan</link>.
</para>
<para>
Sets the corresponding <link linkend="pkit.errorspan">PKIT_ERRORSPAN</link> tag in the template. Useful
for implementing your own custom constraints. Since version 1.08 it is possible to select the errorstr. This
is done with the second parameter. The color must be a string thar starts with a # followed by exactly six hexdigits.
If you do not specify the errorstr, the string is taken from the
<literal><link linkend="config.global.default_errorstr">default_errorstr</link></literal>.
See also <link linkend="pkit.errorstr">PKIT_ERRORSTR</link>.
</para>
</refsect1>
</refentry>
<refentry id="model.api.pkit_set_errorspan">
<refnamediv>
<refname>pkit_set_errorspan</refname>
<refpurpose>
Sets PKIT_ERRORSPAN tags
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<synopsis>
$model->pkit_set_errorspan('state');
# possible since version 1.08
$model->pkit_set_errorspan( 'state', '#00ff00' );
</synopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
Sets the corresponding <link linkend="pkit.errorspan">PKIT_ERRORSPAN</link> tag in the template. Useful
for implementing your own custom constraints. Since version 1.08 it is possible to select the errorstr. This
is done with the second parameter. The color must be a string thar starts with a # followed by exactly six hexdigits.
If you do not specify the errorstr, the string is taken from the
<literal><link linkend="config.global.default_errorstr">default_errorstr</link></literal>.
See also <link linkend="pkit.errorstr">PKIT_ERRORSTR</link>.
</para>
</refsect1>
</refentry>
<refentry id="model.api.pkit_validate_input">
<refnamediv>
<refname>pkit_validate_input</refname>
<refpurpose>
Validates input from an HTML form.
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<synopsis><![CDATA[
# very simple validation, just check to see if name field was filled out
my $input_profile = {required => [ qw ( name ) ]};
# validate user input
unless($model->pkit_validate_input($input_profile)){
# user must have not filled out name field,
docsrc/reference.xml view on Meta::CPAN
<title>Description</title>
<para>
The <PKIT_COMMENT> tag is used to comment the block between
<PKIT_COMMENT> and </PKIT_COMMENT>.
This is done in a ballanced manner, so it is possible to have nested blocks of comments.
</para>
<para>
If you have more opening tags than closing ones, the spare opening tags are seen as text in the comment, as long as they are surrounded by any close tag.
</para>
<para>
Close tags are closed as soon as possible, so if your source contains more close tags than open tags, spare close tags are in your delivered source. </PKIT_COMMENT> is available as of Apache::PageKit 1.13.
</para>
</refsect1>
</refentry>
<refentry id="pkit.component">
<refnamediv>
<refname>PKIT_COMPONENT</refname>
<refpurpose>
Include templates and associate model code.
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<synopsis>
<PKIT_COMPONENT NAME="html_header">
<PKIT_COMPONENT NAME="top_10" loop=top_10_cd headline="CD charts" >
<PKIT_COMPONENT NAME="top_10" loop=top_10_maxi headline="Maxi charts" >
<PKIT_COMPONENT NAME="newsbox" news='<MODEL_VAR NAME="joke">' >
</synopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
This has two functions. The first works like Server Side Includes, including
another PageKit Template that is in the View directory or is generated from
the corresponding XML file using XSLT.
</para>
<para>
The second is to associate a method from the Model the page. This is used to
fill in any MODEL_VAR and MODEL_LOOP tags in the included PageKit Template.
</para>
<para>
The 2. 3. and 4. example define also some macros. These macros are also available for
XSLT with the <xsl:param name="..."> tag.
See <literal><link linkend="pkit.macro">PKIT_MACRO</link></literal>
</para>
</refsect1>
</refentry>
<refentry id="pkit.errorstr">
<refnamediv>
<refname>PKIT_ERRORSTR</refname>
<refpurpose>
Named field for your errorstr.
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<synopsis>
<![CDATA[<PKIT_ERRORSTR>
<font color="<PKIT_ERRORSTR>">bla</font>
]]>
</synopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
This tag is replaced by the string that you define with <literal><link linkend="config.global.default_errorstr">default_errorstr</link></literal>.
If it is not defined the default is <emphasis>#ff0000</emphasis>.
</para>
<para>
See also <literal><link linkend="pkit.messages">PKIT_MESSAGES</link></literal> for a example.
</para>
</refsect1>
</refentry>
<refentry id="pkit.macro">
<refnamediv>
<refname>PKIT_MACRO</refname>
<refpurpose>
Placeholder for components.
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<synopsis>
<MODEL_VAR NAME="<PKIT_MACRO NAME=headline>">
<MODEL_LOOP NAME="<PKIT_MACRO NAME=loop>">
<MODEL_VAR NAME="title"/>
</MODEL_LOOP>
</synopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
A <literal>PKIT_MACRO</literal> is replaced with the value of the key
in <literal><link linkend="pkit.component">PKIT_COMPONENT</link></literal>
that match the name of the macro.
</para>
<para>
This tag is only valid inside a template that is loaded with <literal><link linkend="pkit.component">PKIT_COMPONENT</link></literal>
</para>
</refsect1>
</refentry>
<refentry id="pkit.errorfont">
<refnamediv>
<refname>PKIT_ERRORFONT</refname>
<refpurpose>
Highlights Invalid Fields
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<synopsis>
<![CDATA[<PKIT_ERRORFONT NAME="lastname"> Last Name </PKIT_ERRORFONT> <input name="lastname"> ]]>
<![CDATA[<PKIT_ERRORFONT> new for PageKit 1.10 </PKIT_ERRORFONT> ]]>
</synopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
PKIT_ERRORFONT is the outdated alias for <link linkend="pkit.errorspan">PKIT_ERRORSPAN</link>
</para>
<para>
This tag highlights fields in red that Model reported as being filled in incorrectly.
Or, since version 1.10 of pkit it is possible to suppress the NAME attribute.
Then the field is always colored or whatever you want.
</para>
</refsect1>
</refentry>
<refentry id="pkit.errorspan">
<refnamediv>
<refname>PKIT_ERRORSPAN</refname>
<refpurpose>
Highlights Invalid Fields
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<synopsis>
<![CDATA[<PKIT_ERRORSPAN NAME="lastname"> Last Name </PKIT_ERRORSPAN> <input name="lastname"> ]]>
<![CDATA[<PKIT_ERRORSPAN> new for PageKit 1.10 </PKIT_ERRORSPAN> ]]>
</synopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
This tag highlights fields in red that Model reported as being filled in incorrectly.
Or, since version 1.10 of pkit it is possible to suppress the NAME attribute.
Then the field is always colored or whatever you want.
</para>
</refsect1>
</refentry>
<refentry id="pkit.have_messages">
<refnamediv>
<refname>PKIT_HAVE_MESSAGES</refname>
<refpurpose>
Include the block between <PKIT_HAVE_MESSAGES> and </PKIT_HAVE_MESSAGES> only,
if one or more messages are avail.
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<synopsis>
<![CDATA[<PKIT_HAVE_MESSAGES>
Here are some messages for you: <p>
<PKIT_MESSAGES>
<PKIT_IS_ERROR><font color="<PKIT_ERRORSTR>"></PKIT_IS_ERROR>
<PKIT_MESSAGE>
<PKIT_IS_ERROR></font></PKIT_IS_ERROR>
<p>
</PKIT_MESSAGES>
</PKIT_HAVE_MESSAGES>]]>
</synopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
Include the block between <PKIT_HAVE_MESSAGES> and </PKIT_HAVE_MESSAGES> only,
if one or more messages are avail.
</para>
</refsect1>
</refentry>
<refentry id="pkit.have_not_messages">
<refnamediv>
<refname>PKIT_HAVE_NOT_MESSAGES</refname>
<refpurpose>
Include the block between <PKIT_HAVE_NOT_MESSAGES> and </PKIT_HAVE_NOT_MESSAGES> only,
if no messages are avail.
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<synopsis>
<![CDATA[<PKIT_HAVE_NOT_MESSAGES>
No messages for you! <p>
</PKIT_HAVE_NOT_MESSAGES>]]>
</synopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
Include the block between <PKIT_HAVE_NOT_MESSAGES> and </PKIT_HAVE_NOT_MESSAGES> only,
if no messages are avail.
</para>
</refsect1>
</refentry>
<refentry id="pkit.hostname">
<refnamediv>
<refname>PKIT_HOSTNAME</refname>
<refpurpose>
Fills in the hostname in the URL.
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<synopsis>
<PKIT_HOSTNAME>
</synopsis>
</refsynopsisdiv>
<refsect1>
<title>DESCRIPTION</title>
<para>
Returns the hostname in the URL of the page being served. Particulary useful when you have production and development
servers and you need to link to a secure page.
</para>
<para>
Note that if you are running a proxy server in front of the PageKit server, you probably want to use mod_proxy_add_uri.c.
PageKit will extract the hostname from the frontend server using the X-Original-URI header that mod_proxy_add_uri sets.
</para>
</refsect1>
</refentry>
<refentry id="pkit.messages">
<refnamediv>
<refname>PKIT_MESSAGES</refname>
<refpurpose>
Display messages passed to pkit_message method.
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<synopsis>
<![CDATA[<PKIT_MESSAGES>
<PKIT_IS_ERROR><font color="<PKIT_ERRORSTR>"></PKIT_IS_ERROR>
<PKIT_MESSAGE>
<PKIT_IS_ERROR></font></PKIT_IS_ERROR>
<p>
</PKIT_MESSAGES>]]>
</synopsis>
<synopsis>
<![CDATA[<PKIT_MESSAGES>
<PKIT_IS_ERROR><font color="<PKIT_ERRORSTR>"><PKIT_MESSAGE></font></PKIT_IS_ERROR>
</PKIT_MESSAGES>
<PKIT_MESSAGES>
<PKIT_NOT_ERROR><font color="<PKIT_ERRORSTR>"><PKIT_MESSAGE></font></PKIT_NOT_ERROR>
</PKIT_MESSAGES>]]>
</synopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
Displays messages passed to pkit_message method in the Model code.
</para>
</refsect1>
</refentry>
<refentry id="pkit.selfurl">
<refnamediv>
<refname>PKIT_SELFURL</refname>
<refpurpose>
URL of current page.
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<synopsis>
<PKIT_SELFURL exclude="foo bar">
</synopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
The URL of the current page, including CGI parameters, but excluding those listed in the exclude attribute. Appends a '&' or '?' at the end to allow additionial parameters.
</para>
<para>
Note that if you are running a proxy server in front of the PageKit server, you probably want to use <ulink url="http://tjmather.com/mod_proxy_add_uri.c">mod_proxy_add_uri.c</ulink>.
PageKit will take the URL from the frontend server using the
X-Original-URI header that mod_proxy_add_uri sets.
</para>
</refsect1>
</refentry>
<refentry id="pkit.view">
<refnamediv>
<refname>PKIT_VIEW</refname>
<refpurpose>
Wraps a section of text to be displayed for a view.
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<synopsis>
<PKIT_VIEW NAME="print">This is text display for the printable view</PKIT_VIEW>
</synopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
Displays the enclosed text if the <link linkend="request.pkit_view">pkit_view</link>
request parameter is set to NAME attribute.
</para>
</refsect1>
</refentry>
<refentry id="pkit.else">
<refnamediv>
<refname>PKIT_ELSE</refname>
<refpurpose>
Can be used to add a else part to PKIT_... tags.
( run in 0.743 second using v1.01-cache-2.11-cpan-5735350b133 )