Chapter 2. Reference

$Id: reference.xml,v 1.65 2003/10/07 13:29:54 borisz Exp $

Table of Contents

Configuration Options
Global Attributes
Section Attributes
Server Attributes
User Attributes
View Attributes
Page Attributes
Model API
PageKit Extensions
PageKit API
PageKit Template Tags
XML content tags
Model tags
PageKit tags
Request parameters

Configuration Options

Global Attributes

These settings are global in the sense that they apply over all servers, views, and pages. They are attributes of the <GLOBAL> tag in Config/Config.xml.

cache_dir

Specifies the directory where the PageKit Template cache files are stored. Defaults to View/pkit_cache.

cookies_not_set_page

This is the page that gets displayed if the user attempts to log in, but their cookies are not enabled. Defaults to login_page.

default_errorstr

Default errorstr, that PageKit use for PKIT_ERRORSTR, pkit_set_errorspan and the obsolete pkit_set_errorfont.

Defaults to #ff0000.

default_input_charset

Default charset that PageKit Templates and Model output are encoded in. Defaults to ISO-8859-1. PageKit uses this to convert the PageKit templates and output from output_convert to UTF-8.

default_output_charset

Default charset that PageKit templates compiled to. Defaults to ISO-8859-1. This should be the charset that supports your default_input_charset and has good support among the client's browsers.

default_lang

Default language outputed when no language is specified or request language is not available. Defaults to en.

default_page

Default page user gets when no page is specified. Defaults to index.

errorspan_begin_tag

Specifies the start tag for <PKIT_ERRORSPAN ... > and <PKIT_ERRORFONT ... >. Defaults to <font color="<PKIT_ERRORCOLOR>">.

	errorspan_begin_tag = "&lt;span class=error&gt;"
        errorspan_end_tag = "&lt;/span&gt;"
       

See also errorspan_end_tag.

errorspan_end_tag

Specifies the end tag for <PKIT_ERRORSPAN ... > and <PKIT_ERRORFONT ... >. Defaults to </font>.

See also errorspan_begin_tag.

fop_command

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.

        # 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/logkit-1.0b4.jar:/opt/fop-0.20.3/lib/buildtools.jar:/opt/fop-0.20.3/lib/bsf.jar:/opt/fop-0.20.3/lib/batik.jar:/opt/fop-0.20.3/lib/avalon-framework-4.0.jar:/opt/fop-0.20.3/lib/ant.jar:/opt/fop-0.20.3/lib/ant-1.3-optional.jar:/opt/fop-0.20.3/build/fop.jar: org.apache.fop.apps.Fop"

       

Can be overriden by specifying the server fop_command configuration option.

gzip_output

If set to all, output is gzipped dynamic and static content for browsers that send a Accept-Encoding header containing gzip. If set to static, output is gzipped for static pages only. Defaults to none.

login_page

Page that gets displayed when user attempts to log in. Defaults to login.

logout_kills_session

When pkit_logout is called it normally resets just the pkit_id cookie. With logout_kills_session enabled (set to yes), pkit_logout will also reset pkit_session_id and forcing a new pkit_session_id cookie to be set with a new session_id. Defaults to yes.

model_base_class

Specifies the base Model class that typically contains code that used across entire the web application, including methods for authentication and connecting to the database.

If you have multiple PageKit applications running on the same mod_perl server, then you'll need to specify a unique model_base_class for each application.

Defaults to MyPageKit::Common.

model_dispatch_prefix

This prefixeds the Derived Model Classes. Defaults to MyPageKit::MyModel.

Methods in this class take an derived Apache::PageKit::Model object as their only argument.

not_found_page

Error page when page cannot be found. Defaults to default_page.

page_session

Sets the default for all non static pages. If set to yes, every non static page gets a unique session. Defaults to no. This value is overridden with page_session.

page_session_class

Name for the Module, that is used to create the page_session objects. Defaults to Apache::SessionX.

post_max

Maximum size of file uploads, in bytes. Defaults to 100,000,000 (100 MB).

upload_tmp_dir

Temporary directory for file uploads. Defaults to whatever libapreq finds usefull. This options is only usefull if you use libapreq >= 1.0. The temporary directory usually needs to reside on the same filesystem as the location supplied to the upload object's

link

method. See the Apache::Request documentation for further information.

protect_static

If set to yes static files can also be protected with the require_login attribute in the SECTION or PAGE tags. Set this option to no to be compatible to PageKit < 1.09. Defaults to yes.

recent_login_timeout

Seconds that user's session has to be inactive before a user is asked to verify a password on pages with the require_login attribute set to recent. Defaults to 3600 (1 hour).

relaxed_parser

If set to yes, this option allows template tags to be placed inside HTML comments. It also permits spaces and newlines within the tag itself. This option may be useful to HTML authors who would like to validate their templates' HTML syntax prior to processing, or who use DTD-aware editing tools. Defaults to no.

        relaxed_parser = "yes"

        # these tags are all allowed if relaxed_parser is enabled:
        <MODEL_VAR NAME="x">
        < MODEL_VAR NAME = 'x' >
        < MODEL_LOOP NAME = x >
        < PKIT_COMPONENT NAME = x />
        <!-- MODEL_VAR NAME="x" -->
        <!--   CONTENT_VAR   NAME   =    "x"   /-->
       

request_param_in_tmpl

If set to yes, then <MODEL_VAR> tags in template automatically get filled in with corresponding request parameters across all pages. Can be overriden by the corresponding page attribute. Defaults to no.

session_class

Name for the Module, that is used to create the session objects. Defaults to Apache::SessionX.

session_expires

Sets the expire time for the cookie that stores the session id on the user's computer. If it is not set, then the expire time on the cookie will not be set, and the cookie will expire when the user closes their browser.

         session_expires = "+3h"
        

template_class

Name for the Module, that is used to create the template objects. Defaults to HTML::Template.

uri_prefix

Prefix of URI that should be trimmed before dispatching to the Model code.

See also pkit_fixup_uri in the Model API.

use_locale

If set to yes pkit translates the original message to the language of the client if possible. If reload is set to yes, the translationtables are reloaded on every usage else only on first usage.

Defaults to no. See also pkit_gettext and pkit_gettext_message in the Model API.

verify_page

Verify password form. Defaults to login_page.

Section Attributes

These options are global across each server and all Views. They are in the <SECTIONS> tag of Config/Config.xml.

All Page attributes are valid. <SECTION> Tags with the longest matching part of the id attribute provide the defaults for pages without the attribute in question. <PAGE> attributes written in the <PAGE> tag have the highest priority. If nothing is found the <SECTION> Tags are scanned for a default. The closest match wins and the search is over. See the line with /xyz in the example bellow, if we request /xyz/abc, the search ends at the line with id='/xyz' and the page does not require a login!

        <SECTIONS>
        <SECTION id='/' require_login='yes'/>
        <SECTION id='/xyz' request_param_in_tmpl='yes'/>
        <SECTION id='/free' require_login='no'/>
        </SECTIONS>
       
id

This is part of the uri path to the page where the defaults take place. '/' Means the whole site. This attribute is needed in every <SECTION> tag.

Server Attributes

These options are global over all pages, but are local to each server configuration (e.g. production, staging, development). They are located in the <SERVERS> tag of Config/Config.xml.

can_edit

If set to yes, enables on-line editing tools.

cookie_domain

Domain for that cookies are issued. Note that you must have at least two periods in the cookie domain.

If not set then cookie issued for the current domain name.

cookie_postfix

The content of cookie_postfix is appended to pkit_id and pkit_session_id. With this option it is possible to force different names for your cookies. Usefull if for some reason your cookies overwrite eachother.

fop_command

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.

        # 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/logkit-1.0b4.jar:/opt/fop-0.20.3/lib/buildtools.jar:/opt/fop-0.20.3/lib/bsf.jar:/opt/fop-0.20.3/lib/batik.jar:/opt/fop-0.20.3/lib/avalon-framework-4.0.jar:/opt/fop-0.20.3/lib/ant.jar:/opt/fop-0.20.3/lib/ant-1.3-optional.jar:/opt/fop-0.20.3/build/fop.jar: org.apache.fop.apps.Fop"
       
html_clean_level

Sets optimization level for HTML::Clean. If set to 0, disables use of HTML::Clean. Levels range from 1 to 9. Level 1 includes only simple fast optimizations. Level 9 includes all optimizations. Defaults to 0. A good choice for production is 3. Higher Levels might end up in wrong pages.

reload

If set to yes, check for new view, content and config xml files on each request. Should be set to no on production servers. Default is no.

If you change this from no to yes it is certainly that the server must be restarted to notice the change.

User Attributes

These options are like the <GLOBAL> tag. With the difference, that you can store any information here that you like. The are located in the <USER> tag of Config/Config.xml.

You can retrieve this information with the pkit_get_config_attr function.

View Attributes

These options are local to each view, but are global across servers and pages. Currently only the output media can be set, but there are plans to have a parent_view, so that there can be multiple levels of derived views.

content_type

Sets the content type of the output sent to the client. Content types are strings like "text/plain", "text/html" or "application/xml". This corresponds to the "Content-Type" header in the HTTP protocol. The following content types have default views and/or special handing associated with them:

content_type

Description

Default Views

Special Handing

text/html HTML output. This is for traditional screen browsers such as Netscape and Internet Explorer. This is the default content_type for all views except for those listed belowPageKit translates sets the charset in the Content-Type headers and translates the output according to the Accept-Charset header.
application/pdf PDF Output, for display in Acrobat Reader. Uses Apache XML FOP pdfPageKit uses Apache XML FOP to generate the PDF, if fop_command is set.
text/vnd.wap.wml WML output. This is for WAP handhelds such as Palmpilots and cellphones. wmlNone
application/xml XML output, for Internet Explorer 5.0 and above. xmlNone

Page Attributes

These options are local to each page on the site, but are global across each server and all views. The are located in the <PAGES> tag of Config/Config.xml.

browser_cache

If set to no, sends an Expires = -1 header to disable client-side caching on the browser.

content_type

Sets the content type for output. Overrides the View content_type configuration option.

fill_in_form

When set to yes, automatically fills in HTML forms using HTML::FillInForm with values from the request parameters when it detects a <form> tag. Default is yes.

id

Page ID for this page.

page_session

If set to yes, this page gets a unique session. Defaults to no. This value overriddes whatever you have requested in page_session.

request_param_in_tmpl

If set to yes, then <MODEL_VAR> tags in template automatically get filled in with corresponding request parameters. Defaults to the value set by the global request_param_in_tmpl attribute, or if that is not set, then it defaults to no.

require_login

If set to yes, page requires a login. If set to recent, page requires a login and that the user has been active in the last recent_login_timeout seconds. Default is no.

uri_match

Value should be a regular expression. Servers requests whose URL (after the host name) match the regular expression. For example, ^member\/\d*$ matches http://yourdomain.tld/member/4444.

use_template

If set to yes, uses HTML::Template files. If set to no page code is responsible for sending output. Default is yes.