NAME
Apache::PageKit - MVCC web framework using mod_perl, XML and HTML::Template
SYNOPSIS
In httpd.conf
SetHandler perl-script
PerlSetVar PKIT_ROOT /path/to/pagekit/files
PerlHandler +Apache::PageKit
<Perl>
Apache::PageKit->startup("/path/to/pagekit/files");
</Perl>
In MyPageKit/Common.pm
package MyPageKit::Common;
use base 'Apache::PageKit::Model';
sub pkit_dbi_connect {
return DBI->connect("DBI:mysql:db","user","passwd");
}
sub pkit_session_setup {
my $model = shift;
my $dbh = $model->dbh;
return {
session_lock_class => 'MySQL',
session_store_class => 'MySQL',
session_args => {
Handle => $dbh,
LockHandle => $dbh,
},
};
}
sub pkit_auth_credential {
my ($model) = @_;
# in this example, login and passwd are the names of the credential fields
my $login = $model->input('login');
my $passwd = $model->input('passwd');
# create a session key
# your code here.........
return $ses_key;
}
sub pkit_auth_session_key {
my ($model, $ses_key) = @_;
# check whether $ses_key is valid, if so return user id in $user_id
# your code here.........
return $ok ? $user_id : undef;
}
DESCRIPTION
PageKit is an mod_perl based application framework that uses HTML::Template and XML to separate code, design, and content. Includes session management, authentication, form validation, co-branding, and a content management system.
Its goal is to solve all the common problems of web programming, and to make the creation and maintenance of dynamic web sites fast, easy and enjoyable.
You have to write a module named MyPageKit::Common that inherits from Apache::PageKit::Model and provides methods common across the site. For example, if you wish to support authentication, it must include the two methods pkit_auth_credential
and pkit_auth_session_key
.
For more information, visit http://www.pagekit.org/ or http://sourceforge.net/projects/pagekit/
OBJECTS
Each $pk
object contains the following objects:
- $pk->{apr}
-
An Apache::Request object. This gets the request parameters and can also be used to set the default values in HTML form when
fill_in_form
is set. - $pk->{config}
-
An Apache::PageKit::Config object, which loads and accesses global, server and page attributes.
- $pk->{model}
-
An MyPageKit::Common class object, derived from Apache::PageKit::Model.
- $pk->{session}
-
Returns a reference to a hash tied to Apache::PageKit::Session.
- $pk->{view}
-
An Apache::PageKit::View object, which interfaces with the HTML::Template templates.
Features
- Model/View/Content/Controller approach to design
-
The Model is the user provided classes, which encapsulate the business logic behind the web site.
The View is a set of HTML::Template templates. Apache::PageKit::View acts as a bridge between the templates and the controller.
The Content is stored in XML files in the Content/xml directory. You may also store the content in the HTML::Template templates, if you don't need to seperate the View from the Content.
The Controller is a subclass of Apache::PageKit, which reads the client request, accesses the back end, and uses Apache::PageKit::View to fill in the data needed by the templates.
- Seperation of Perl from HTML
-
By using HTML::Template, this application enforces an important divide - design and programming. Designers can edit HTML without having to deal with any Perl, while programmers can edit the Perl code with having to deal with any HTML.
- Seperation of Content from Design with XML
-
Content can be stored in XML files and the Design can be stored in HTML template files or in XSL style sheets.
Content can be associated with HTML template files by using the XML::XPathTemplate module.
If you need a more powerful solution for managing large amounts of data, PageKit also has support for XSLT transformations using the XML::LibXSLT module.
- Page based attributes
-
The attributes of each Page are stored in the Config/Config.xml file. This makes it easy to change attributes of pages across the site. Apache::PageKit::Config provides a wrapper around this XML file.
For example, to require a login for a page, all you have to do is change the
require_login
attribute of the XML<PAGE>
tag to yes, instead of modifying the Perl code or moving the script to a protected directory. - Automatic Dispatching of URIs
-
Apache::PageKit translates
$r->uri
into a class and method in the user provided classes. In the example in the synopsis, the URI/account/update
will map toMyPageKit::PageCode::account->page_update
. - Easy error handling.
-
Both warnings and fatal errors can be displayed on the screen for easy debugging in a development environment, or e-mailed to the site adminstrator in a production environment, as specified in the Apache
ServerAdmin
configuration directive.You have to require Apache::PageKit::Error to turn on error handling.
- Session Management
-
Provides easy access to a hash tied to Apache::PageKit::Session.
- Authentication
-
Restricts access to pages based on the
require_login
attribute. Ifrequire_login
is set to recent, then PageKit requires that session is currently active in the lastrecent_login_timeout
seconds. - Form Validation
-
Uses HTML::FormValidator to provide easy form validation. Highlights fields in red that user filled incorrectly by using the
<PKIT_ERRORFONT NAME="FIELD_NAME"> </PKIT_ERRORFONT>
tag. To use, pass an input profile to the validate method of Apache::PageKit::Model from your perl code option. - Sticky HTML Forms
-
Uses HTML::FillInForm to implement Sticky CGI Forms.
One useful application is after a user submits an HTML form without filling out a required field. PageKit will display the HTML form with all the form elements containing the submitted info.
- Multiple Views/Co-branding
-
Any page can have multiple views, by using the
pkit_view
request parameter. One example is Printable pages. Another is having the same web site branded differently for different companies. - Components
-
PageKit can easily share HTML templates across multiple pages using components. In addition, you may specify Perl code that gets called every time a component is used by adding a component_id method to the Model.
- Language Localization
-
You may specify language properties by the
xml:lang
attribute for tags in the XML content files.The language displayed is based on the user's preference, defaulting to the browser settings.
METHODS
The following method is available to the user as Apache::PageKit API.
This function should be called at server startup from your httpd.conf file:
<Perl>
Apache::PageKit->startup("/path/to/pagekit/files","staging");
</Perl>
Where the first argument is the root directory of the PageKit application. The second (optional) argument is the server id. It loads /path/to/pagekit/files/Model into the perl search path so that PageKit can make calls into MyPageKit::Common and other Model classes. It also loads the Config and Content XML files and pre-parses the View template files.
FREQUENTLY ASKED QUESTIONS
Please look in here before you send me an email.
1) I get a segmentation fault when I start the PageKit enabled Apache server.
PageKit requires XML::Parser, which is incompatible with the expat library included in Apache. You'll have to configure Apache with --disable-rule=expat
.
For more information see http://axkit.org/faq.xml under "I install AxKit and Apache segfaults when it starts".
The mod_perl guide (http://perl.apache.org/guide) has an excellect section on compiling mod_perl and Apache from source.
SEE ALSO
Apache::Request, HTML::FillInForm, HTML::Template, HTML::FormValidator
VERSION
This document describes Apache::PageKit module version 1.01
NOTES
Requires mod_perl, XML::Parser, HTML::Clean, HTML::FillInForm, HTML::FormValidator, and HTML::Template.
I wrote these modules because I needed an application framework that was based on mod_perl and seperated HTML from Perl. HTML::Embperl, Apache::ASP and HTML::Mason are frameworks that work with mod_perl, but embed Perl code in HTML. The development was inspired in part by Webmacro, which is an open-source Java servlet framework that seperates Code from HTML.
The goal is of these modules is to develop a framework that provides most of the functionality that is common across dynamic web sites, including session management, authorization, form validation, component design, error handling, and content management.
If you have used (or are considering using) these modules to build a web site, please drop me a line with the URL of your web site. My e-mail is tj@anidea.com. Thanks!
BUGS
This framework is in alpha stage. The interface may change in later releases.
Please submit any bug reports, comments, or suggestions to tjmather@anidea.com, or join the Apache::PageKit mailing list at http://lists.sourceforge.net/mailman/listinfo/pagekit-users
TODO
Support Template-Toolkit templates as well as HTML::Template templates.
Support for exposing Model objects using XML-RPC and/or SOAP.
Gzipped output.
Support for multiple transformations with stylesheets, and for filters.
Associate sessions with authenticated user ID.
Add more tests to the test suite.
AUTHOR
T.J. Mather (tjmather@anidea.com)
CREDITS
Fixes, Bug Reports, Docs have been generously provided by:
Boris Zentner
Stu Pae
Yann Kerhervé
Ben Ausden
Chris Burbridge
Leonardo de Carvalho
Thanks!
COPYRIGHT
Copyright (c) 2000, 2001 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
1 POD Error
The following errors were encountered while parsing the POD:
- Around line 1142:
Non-ASCII character seen before =encoding in 'Kerhervé'. Assuming CP1252