/ 
Apache-PageKit-0.89
River stage zero No dependents
/ Apache::PageKit

NAME

Apache::PageKit - Application framework using mod_perl and HTML::Template

SYNOPSIS

Perl Module that inherits from Apache::PageKit:

  package MyPageKit;

  use Apache::PageKit;

  use vars qw(@ISA);
  @ISA = qw(Apache::PageKit);

  use Apache::Constants qw(OK REDIRECT DECLINED);

  # hash reference to input profile for HTML::FormValidator
  # this is a simple example where there is only one e-mail field.
  my $input_profile = {
		       page_that_processes_html_form => {
			    required => [ qw( email ) ],
			    constraints => {
					    email => "email",
					   },
			    messages => {
					 email => "The E-mail address, <b>%%VALUE%%</b>, is invalid.",
					},
		       },
		      }

  sub handler {
    $dbh = DBI->connect("DBI:mysql:db","user","passwd");
    my $pk = __PACKAGE__->new(
			      page_dispatch_prefix => 'MyPageKit::PageCode',
			      include_dispatch_prefix => 'MyPageKit::IncludeCode',
			      dbh => $dbh,
			      form_validator_input_profile => $input_profile,
			      session_lock_class => 'MySQL',
			      session_store_class => 'MySQL',
			      session_args => {
					       Handle => $dbh,
					       LockHandle => $dbh,
					      },
			     );

    my $status_code = $pk->prepare_page;
    return $status_code unless $status_code eq OK;

    $pk->prepare_view;

    $pk->print_view;

    return $status_code;
  }

  sub auth_credential {
    my ($pk, @credentials) = @_;

    # create a session key from @credentials
    # your code here.........

    return $ses_key;
  }

  sub auth_session_key {
    my ($pk, $ses_key) = @_;

    # check whether $ses_key is valid, if so return user id in $user_id
    # your code here.........

    return $ok ? $user_id : undef;
  }

In httpd.conf

SetHandler perl-script
PerlSetVar PKIT_ROOT /path/to/pagekit/files

# this comes before PerlHandler so that PKIT_ROOT/Module gets added to @INC
PerlModule Apache::PageKit 
PerlHandler +MyPageKit

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 that inherits from Apache::PageKit and provides a handler for the PerlHandler request phase. If you wish to support authentication, it must include the two methods auth_credential and 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->{content}

An Apache::PageKit::Content object, which accesses the content stored in the XML files.

$pk->{session}

A reference to a hash tied to Apache::PageKit::Session.

$pk->{validator}

An Apache::PageKit::FormValidator object, a wrapper to HTML::FormValidator, used for validating HTML forms.

$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

By using the <TMPL_VAR> and <TMPL_LOOP> elements, you can autofill the corresponding HTML::Template <TMPL_VAR> and <TMPL_LOOP> tags.

This is an easy way of using XML with HTML::Template that doesn't require the use of stylesheets.

Page based attributes

The attributes of each Page are stored in the Controller/Config.xml file. This makes it easy to change 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.

To change a page to a popup, all you have to do is set is_popup to yes, and all the links to that page across the site will automagically become javascript popup links.

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 to MyPageKit::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.

Session Management

Provides easy access to a hash tied to Apache::PageKit::Session.

Authentication

Restricts access to pages based on the require_login attribute. If require_login is set to recent, then PageKit requires that session is currently active in the last recent_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 a hash reference to the constructor using the form_validator_input_profile 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 a pkit_view request parameter. One example is Printable pages. Another is having the same web site branded differently for different companies.

Includes

PageKit can easily share HTML templates across multiple pages using includes. In addition, you may specify Perl code that gets called every time a include is used by adding a include_include_id method to the Perl module specified by include_dispatch_prefix.

Language Localization

You may specify language properties by the xml:lang attribute for <TMPL_VAR> and <TMPL_LOOP> tags in the XML content files.

The language displayed is based on the user's preference, defaulting to the browser settings.

Content Management System (Forthcoming)

An authorized user can edit the HTML Templates for pages and includes online by simply clicking on a "edit this (page|include)" link.

METHODS

The following methods are available to the user as Apache::PageKit API.

new

Constructor object.

  $pk = __PACKAGE__->new(
			 page_dispatch_prefix => 'MyPageKit::PageCode',
			 include_dispatch_prefix => 'MyPageKit::IncludeCode',
			 dbh => $dbh,
			 session_lock_manager => 'MySQL',
			 session_object_store => 'MySQL',
			 session_args => {
					  Handle => $dbh,
					  LockHandle => $dbh,
					 },
			);

Each option is accessible from the object's hash. For example $dbh is acessible from $pk->{dbh}.

prepare_page

This executes all of the back-end business logic need for preparing the page, including executing the page and include code.

prepare_view

This fills in the view template with all of the data from the back-end

Called as a last step to output filled in view template.

message

Displays a special message to the user. The message can displayed using the <TMPL_LOOP NAME="PKIT_MESSAGE"> </TMPL_LOOP> code.

To add a message,

$pk->message("Your listing has been deleted.");

To add an error message (highlighted in red), use

$pk->message("You did not fill out the required fields.",
             is_error => 1);
redirect

Redirects to the specified URL. Should be called from the back-end code specified by page_dispatch_prefix.

package MyPageKit::PageCode;

sub page_id {
  my $pk = shift;

  $pk->redirect("http://yourdomain.com/new_page");
}
continue

Continues onto another PageKit page. Should be called from the back-end code specified by page_dispatch_prefix.

package MyPageKit::PageCode;

sub old_page_id {
  my $pk = shift;

  ...

  if( $go_to_new_page ){
    $pk->continue($new_page_id);
    return;
  }
  ...

}
auth_credential

You must define the method yourself in your subclass of Apache::PageKit.

Verify the user-supplied credentials and return a session key. The session key can be any string - often you'll use the user ID and a MD5 hash of a a secret key, user ID, password.

auth_session_key

You must define the method yourself in your subclass of Apache::PageKit.

Verify the session key (previously generated by auth_credential) and return the user ID. This user ID will be fed to $r->connection->user().

MARKUP TAGS

See the HTML::Template manpage for description of the <TMPL_VAR>, <TMPL_LOOP>, <TMPL_IF>, and <TMPL_INCLUDE> tags.

<PKIT_ERRORFONT NAME="FIELD_NAME"> </PKIT_ERRORFONT>

This tag highlights fields in red that Apache::PageKit::FormValidator reported as being filled in incorrectly. An input profile must be passed to form_validator_input_profile option for this to work.

<PKIT_INCLUDE NAME="include_id">

Calls the include code and includes the include template for the include include_id.

<PKIT_JAVASCRIPT>

This tag includes Javascript code (if necessary) for popup windows.

These tags gets converted to <A HREF="LINK_FOR_PAGE_143"> </A> tags. Given a page ID, it determines what the link should be. If PKIT_PAGE_DOMAIN is turned on, the link may include the domain name for that page. If is_popup is yes, then the link will be a javascript popup. If is_secure is yes, then the link will use the https:// protocal.

<TMPL_VAR NAME="PKIT_ADMIN">

True if user is authenticated and has administration capability.

<TMPL_LOOP NAME="PKIT_EDIT"> </TMPL_LOOP>

Links to Content Management System. This is displayed if authenticated user has administration capability.

Template should contain code that looks like

<TMPL_LOOP NAME="PKIT_EDIT">
  <PKIT_LINK PAGE="edit_page?template=<TMPL_VAR NAME="TEMPLATE">&pkit_done=<TMPL_VAR NAME="pkit_done">">(edit template <TMPL_VAR NAME="TEMPLATE">)</PKIT_LINK><<br>
</TMPL_LOOP>
<TMPL_IF NAME="PKIT_INTERNET_EXPLORER"> </TMPL_IF>

Set to 1 if User-Agent is a Microsoft Internet Explorer browser.

<TMPL_IF NAME="PKIT_LANG_iso_639_iden"> </TMPL_IF>

Set to 1 if HTTP Accept-Language Header includes to iso_639_iden as the prefered language, or if the user has set their prefered language by using the pkit_lang request parameter.

<TMPL_VAR NAME="PKIT_LOGINOUT_LINK">

If user is logged in, provides link to log out. If user is not logged in, provides link to log in.

<TMPL_LOOP NAME="PKIT_MESSAGE"> </TMPL_LOOP>

Displays messages passed to $pk->message method.

Template should contain something that looks like

<TMPL_LOOP NAME="PKIT_MESSAGE">
   <TMPL_IF NAME="IS_ERROR"><font color="#ff0000"></TMPL_IF>
   <TMPL_VAR NAME="MESSAGE">
   <TMPL_IF NAME="IS_ERROR"></font></TMPL_IF>
   <p>
</TMPL_LOOP>

This code will display error message seperated by the HTML <p> tag, highlighting error messages in red.

<PKIT_INCLUDE NAME="include_id">

Calls the include code and includes the include template for the include include_id.

<TMPL_LOOP NAME="PKIT_NAV"> </TMPL_LOOP>

Displays navigation for pages that have use_nav set to yes.

Template should contain code that looks like

<TMPL_LOOP NAME="PKIT_NAV">
  <TMPL_UNLESS NAME="__LAST__"><PKIT_LINK PAGE="<tmpl_var name="page">"></TMPL_UNLESS><TMPL_VAR NAME="NAME"><TMPL_UNLESS NAME="__LAST__"></PKIT_LINK></TMPL_UNLESS>
  <TMPL_UNLESS NAME="__LAST__"> &gt; </TMPL_UNLESS>
</TMPL_LOOP>
<TMPL_IF NAME="PKIT_NETSCAPE"> </TMPL_IF>

Set to 1 if User-Agent is a Netscape browser.

<TMPL_VAR NAME="PKIT_SELFURL">

The URL of the current page, including CGI parameters. Appends a '&' or '?' at the end to allow additionial parameters.

<TMPL_VAR NAME="PKIT_USER">

user_id of authenticated user, equal to $r->connection->user, unless overridden.

<TMPL_IF NAME="PKIT_VIEW:view"> </TMPL_IF>

Set to true if pkit_view request parameter equals view.

OPTIONS

Constructor Arguments

These arguments are global in the sense that they apply over all pages and servers.

form_validator_input_profile

Specifies a hash reference to the HTML::FormValidator input profile to be used.

session_args

Reference to an hash containing options for the session_lock_class and session_store_class.

session_lock_class

The lock manager class that should be used for Apache::PageKit::Session session handling.

session_store_class

The object store class that should be used for Apache::PageKit::Session session handling.

Other configuration variables

Global, server and page configuration variables are described in the Apache::PageKit::Config perldoc page.

REQUEST PARAMETERS

These are parameters that are specified in GET requests and POST requests where Content-type is one of application/x-www-form-urlencoded or multipart/form-data.

pkit_credential_#

Login data, typically userid/login/email (pkit_credential_0) and password (pkit_credential_1).

pkit_done

The page to return to after the user has finished logging in or creating a new account.

pkit_lang

Sets a users preferred language, using the ISO 639 identifier.

pkit_login_page

This parameter is used to specify the page that user attempted to login from. If the login fails, this page is redisplayed.

pkit_remember

If set to true upon login, will save user's cookie so that they are still logged in next time they restart their browser.

pkit_view

Used to implement multiple views/co-branding. For example, if set to print, will search for templates ending with .print.tmpl before using templates ending with .tmpl, and sets the pkit_view:print parameter in the view to true.

SEE ALSO

Apache::PageKit::Config, Apache::PageKit::Content, Apache::PageKit::Error, Apache::PageKit::FormValidator, Apache::PageKit::View, Apache::Request, HTML::FillInForm, HTML::Template, HTML::FormValidator

VERSION

This document describes Apache::PageKit module version 0.89

NOTES

Requires mod_perl, 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

Associate sessions with authenticated user ID.

Use path_info for the url to pass along session IDs when cookies are disabled.

Make Content Management System work.

Complete test suite using Apache::test.

AUTHOR

T.J. Mather (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