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

Status
------
	Version: 0.99 (Alpha)
	API is subject to change, and should stabilize as
	we approach version 1.00

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 HTML Templates
		- 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
		- Session Management
		- Input Validation
		- Sticky HTML Forms
		- Authentication
		- Co-branding
		- Automatic Dispatching of URIs
		- Easy Error Handling

Requirements
------------
	- perl 5.005 or greater
	- mod_perl 1.24_01 (lastest version requir'd for make test only)
	- Apache 1.3.x compiled _without_ expat
	- libapreq
	- Apache::Session 1.5
	- Digest::MD5
	- HTML::FillInForm
	- HTML::Template 2.2
	- HTML::Clean
	- Mail::Mailer
	- expat library
	- XML::Parser
	- XML::XPath

Required for make test
----------------------
	- DBD::CSV
	- Digest::MD5
	- HTTP::Headers
	- SQL::Statement
	- Text::CSV_XS
	- Apache::Reload

Recommended
-----------
	- Apache::DBI (*strongly* recommended if you use DBI)
	- Unicode::String (useful for converting accented characters in Content)
	- XML::LibXSLT (needed if you want to use XSLT tranformations)

Installation
------------
	First you must have a mod_perl enabled apache server _without_
	expat compiled in.  That is you should supply the option
	RULE_EXPAT=NO to ./configure when you build Apache.  Alternatively
	if you build Apache with mod_perl, it will supply this option
	automatically for you.  For more information on the expat conflict,
	read http://www.axkit.org/faq.xml under "I install AxKit and Apache
	segfaults when it starts".  For an excellent reference on installing
	a mod_perl server from source, see http://perl.apache.org/guide/

	It is recommended that you compile mod_perl with the EVERYTHING switch.
	In any case, you should make sure that you allow the httpd.conf <Perl>
	directive.

	By the way, you may download the expat library from sourceforge
		http://sourceforge.net/projects/expat/
	(Required for XML::Parser)

	For make test to work, when installing Apache::Session, you will have
	to manually create a database 'sessions', and include a table (this
	example is for MySQL, adjust as needed for your target database)

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

	After installing the requirements, you can use the standard

	perl Makefile.PL
	make
	make test
	make install

	You will be prompted for the location of your mod_perl enabled server.
	This will be used to start a running PageKit enabled web server
	for testing.

	If you have any problems with the install, and have read this
	README file throughly, please e-mail me (tjmather@anidea.com)
	and I will try to see what I can do.  I'm trying hard to make
	the install as easy as possible, and will welcome suggestions
	for documentation additions or improvements.

Troubleshooting
---------------

	In order for make test to pass, you must have mod_perl 1.25
	or greater.  Also, if 3_httpd fails, you can find the error
	in find t/error_log.

	To run a more verbose make test, try

		make test TEST_VERBOSE=1

	Also, if you type

		make start_httpd

	you can start a pagekit enabled web server on port 8228.
	You can kill this with

		make kill_httpd

	Finally, you can check t/httpd.conf for the settings.  In
	particular, you may have to change 'nobody' to the user
	that you are running under if you get permission denied
	errors.

Upgrading
---------
	To upgrade from an earlier version of PageKit, follow the
	installation instructions above.  You may have to change your
	Model, View, Content, or Config files.  For more information,
	see migration/README.

Setup
-----
	You should use the directories and files contained in the eg/
	directory of the distribution as a starting point for your own
	application.  In fact, the eg/Config/Config.dtd,
	eg/Content/Content.dtd, and the eg/View/Default/Page/pkit_edit/
	files are required for the sucessful operation of a pagekit
	server.

	Note that the example application uses DBD::CSV to store the
	login data.  This is choosen because it will work on any platform
	for 'make test'.  However, when building your own application
	you should rip this out and put in a real database.  But in case
	you still want to use DBD::CSV, you'll have to run something like

	my $dbh = DBI->connect("DBI:CSV:f_dir=/tmp/csvdb");
	$dbh->do("CREATE TABLE pkit_user (user_id CHAR(8), login CHAR(255), email CHAR(255), passwd CHAR(255))");

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

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

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

	and changing the settings in

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

Bugs
----

Send bug reports and suggestions to tjmather@anidea.com

Copyright
---------

Copyright (c) 2000, 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 
