Apache::PageKit

Apache::PageKit
===============

Status
------
Version: 1.17

Description
-----------
PageKit is a web applications framework that is based on mod_perl.
This framework is distinguished from others such as Embperl and Mason
by providing a clear separation of programming, content and
presentation.

It does this by implementing a Model/View/Content/Controller (MVCC)
design paradigm:
- Model is user supplied Perl Classes
- View is set of PageKit Templates and/or XSLT files
- Content is set of XML Files
- Controller is PageKit

This allows your programmers, designers and content editors to work
independently with clean well-defined interfaces.

PageKit provides the following features:
- Component-based architecture
- Language Localization and charset translation
- Session Management
- Input Validation
- Sticky HTML Forms
- Authentication
- Co-branding and XML,WML, and PDF output
- Automatic Dispatching of URIs
- Easy Error Handling
- Online Editing Tools
- Page based sessions
- Localized error/messages

Requirements
------------
- perl 5.006001 or greater
- mod_perl 1.9916
- Apache 2
- libapreq2

- Apache::SessionX
- Compress::Zlib
- Data::FormValidator
- Digest::MD5
- HTML::FillInForm 0.12
- HTML::Template 2.2
- HTML::Template::XPath
- HTML::Clean
- Text::Iconv
- libxml2 library - download from http://www.xmlsoft.org
- XML::LibXML 1.31

Required for example web site located in eg/ directory
----------------------
- DBD::SQLite
- HTTP::Headers
- Apache::Reload

Recommended
-----------
- Mail::Mailer (needed if you use Apache::ErrorReport)
- Apache::DBI (*strongly* recommended if you use DBI)
- MIME::Types (needed if you want to serve static files from
View/Default directory)
- XML::LibXSLT 1.31 (needed if you want to use XSLT tranformations)
- Apache XML FOP - need for generating PDF
- Locale::gettext 1.01 (needed if you want to localize pkit messages)

Installation
------------

You must have a mod_perl enabled apache server. That's all.

After installing the requirements, you can use the standard

perl Makefile.PL
make
make test
make install

Setting up Included Example PageKit Site
----------------------------------------

An example web site is included in the eg/ directory. This is an
good starting point for building your own website. See eg/README
for more details.

Make sure httpd is found in your PATH.
To setup and configure, run

./t/TEST -start-httpd

This will be used to configure and start a PageKit enabled
web server on port 8529.

and killed by

./t/TEST -stop-httpd

To view the site, point your browser to http://localhost:8529/
(Replace localhost with the name of the server, if necessary)

If this page fails to load, you may find the error in t/logs/error_log.

Note that to test the PDF generation, you will have to download the
Apache XML FOP Processor from http://xml.apache.org/fop/ and
configure the path to the processor using fop_command configuration
directive in Config.xml.

Please note that the above is only for a quick test.
If you like to start on a new application take a look into
./t/conf/httpd.conf.

To start a new application read Setup and Configuration in this
README

Upgrading
---------
To upgrade from an earlier version of PageKit see migration/README.
You may have to change your Model, View, Content, or Config files.

Setup
-----
You should use the directories and files contained in the eg/
directory of the distribution as a starting point for your own
application.

Note that the example application uses DBD::SQLite to store the
login data. This is choosen because it will work on any platform
and support a resonable part of SQL.
However, when building your own application you can change to
whartever database you like.

Just provide a database with the tables 'pkit_user' and 'session'

CREATE
TABLE pkit_user (
user_id CHAR(8), login CHAR(255), email CHAR(255), passwd CHAR(255)
);

CREATE
TABLE sessions (
id char(32) not null primary key, a_session text
);

You can adjust or remove database fields from these tables as you like,
just supply the fields you use. My pkit_user table is typical larger and I
like to use VARCHAR on some fields.

Note for Win32 user:
On Win32 you should use a session_lock_class => 'Null'
in the eg site if you encount any problems. At least for me
session_lock_class => 'File' is not working.

For the example application to work on a real database you must
create the above table on it as well.

For sessions to work, you will have
to manually create a database 'sessions', and include a table (this
example is for MySQL/PostgreSQL/SQLite, adjust as needed for your
target database)

CREATE TABLE sessions (
id char(32) not null primary key,
a_session text
);

A MySQL configuration inside Common.pm might look like:
sub pkit_session_setup {
my $model = shift;
my $dbh = $model->dbh;

my %session_setup = (
session_store_class => 'MySQL',
session_lock_class => 'MySQL',
session_args => {
Handle => $dbh,
LockHandle => $dbh,
}
);
return \%session_setup;
}

A PostgreSQL configuration inside Common.pm might look like:
sub pkit_session_setup {
my $model = shift;
my $dbh = $model->dbh;

my %session_setup = (
session_store_class => 'Postgres',
session_lock_class => 'Null',
session_serialize_class => 'Base64',
session_args => {
Handle => $dbh,
IDLength => 32,
Commit => 0,
}
);
return \%session_setup;
}

Postgres user MUST use the Commit parameter in the session_args no
matter if it is on or off.
Look in Apache::Session::Postgres and Apache::Session.

A SQLite configuration inside Common.pm might look like:
sub pkit_session_setup {
my $model = shift;
my $dbh = $model->dbh;

my %session_setup = (
session_store_class => 'MySQL',
session_lock_class => 'Null',
session_serialize_class => 'Base64',
session_args => {
Handle => $dbh,
},
);
return \%session_setup;
}
For more information look in Apache::Session::SQLite,
Apache::Session::Flex and Apache::Session.

Configuration
-------------

PageKit >= 1.09 with mod_perl >= 1.26
If you use PageKit >= 1.09 and mod_perl < 1.26, the follow the instructions
for PageKit < 1.09.

Configuring PageKit is as easy as adding the following
to your httpd.conf

SetHandler perl-script
PerlSetVar PKIT_ROOT /path/to/pagekit/files
PerlSetVar PKIT_SERVER staging
PerlHandler +Apache::PageKit
<Perl>
Apache::PageKit->startup;
</Perl>

# Optional
PerlRequire /path/to/startup.pl
PerlModule Apache::ErrorReport
PerlSetVar ErrorReportHandler display

and changing the settings in

/path/to/pagekit/files/Config/Config.xml

PageKit < 1.09

Configuring PageKit is as easy as adding the following
to your httpd.conf

SetHandler perl-script
PerlSetVar PKIT_ROOT /path/to/pagekit/files
PerlSetVar PKIT_SERVER staging
PerlHandler +Apache::PageKit
<Perl>
Apache::PageKit->startup("/path/to/pagekit/files","staging");
</Perl>

# Optional
PerlRequire /path/to/startup.pl
PerlModule Apache::ErrorReport
PerlSetVar ErrorReportHandler display

and changing the settings in

/path/to/pagekit/files/Config/Config.xml

Bugs
----

There is a bug in Perl 5.6.1 that causes weirdness with the templates
are encoded in UTF-8.

Please submit any bug reports, comments, or suggestions to the Apache::PageKit
mailing list at http://lists.sourceforge.net/mailman/listinfo/pagekit-users

Copyright
---------

Copyright (c) 2000, 2001, 2002, 2003, 2004, 2005 AnIdea Corporation. All rights Reserved.
PageKit is a trademark of AnIdea Corporation.

License
-------

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
Ricoh Source Code Public License for more details.

You can redistribute this module and/or modify it only under the
terms of the Ricoh Source Code Public License.

You should have received a copy of the Ricoh Source Code Public
License along with this program; if not, obtain one at
http://www.pagekit.org/license.html