/ 
Apache-PageKit-0.97
River stage zero No dependents
/ Apache::PageKit::Model

NAME

Apache::PageKit::Model - Base Model Class

DESCRIPTION

This class provides a base class for the Modules implementing the backend business logic for your web site.

This module also contains a wrapper to HTML::FormValidator. It validates the form data from the Apache::Request object contained in the Apache::PageKit object.

When deriving classes from Apache::PageKit::Model, keep in mind that all methods and hash keys that begin with pkit_ are reserved for future use.

SYNOPSIS

Method in derived class.

sub my_method {
  my $model = shift;

  # get database handle, session
  my $dbh = $model->dbh;
  my $session = $model->session;

  # get inputs (from request parameters)
  my $foo = $model->input_param('bar');

  # do some processing

  ...

  # set outputs in template
  $model->output_param(result => $result);
}

METHODS

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

input_param

Gets requested parameter from the request object $apr.

my $value = $model->input_param($key);

If called without any parameters, gets all available input parameters:

my @keys = $model->input_param;

Can also be used to set parameter that Model gets as input. For example you can set the userID when the user gets authenticated:

$model->input_param(pkit_user => $userID);
pkit_input_hashref

This method fetches all of the parameters from the request object $apr, returning a reference to a hash containing the parameters as keys, and the parameters' values as values. Note a multivalued parameters is returned as a reference to an array.

$params = $model->pkit_input_hashref;
output_param

This is similar to the HTML::Template method. It is used to set <MODEL_*> template variables.

$model->output_param(USERNAME => "John Doe");

Sets the parameter USERNAME to "John Doe". That is <MODEL_VAR NAME="USERNAME"> will be replaced with "John Doe".

It can also be used to set multiple parameters at once by passing a hash:

$model->output_param(firstname => $firstname,
             lastname => $lastname);

Alternatively you can pass a hash reference:

$model->output_param({firstname => $firstname,
             lastname => $lastname});

Note, to set the bread crumb for the <PKIT_LOOP NAME="BREAD_CRUMB"> tag, use the following code:

  $model->output_param(pkit_bread_crumb =>
		       [
			{ pkit_page => 'toplink', pkit_name='Top'},
			{ pkit_page => 'sublink', pkit_name='Sub Class'},
			{ pkit_name => 'current page' },
		       ]
		      );
pkit_query

Basically a wrapper to the "query()" in HTML::Template method of HTML::Template:

my $type = $model->pkit_query(name => 'foo');
apr

Returns the Apache::Request object.

my $apr = $model->apr;
dbh

Returns a database handle, as specified by the MyPageKit::Model::dbi_connect method.

my $dbh = $model->dbh;
session

Returns a hash tied to <Apache::PageKit::Session>

my $session = $model->session;
pkit_message

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

You can add a message from the Model code:

$model->pkit_message("Your listing has been deleted.");

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

$model->pkit_message("You did not fill out the required fields.",
             is_error => 1);
pkit_internal_redirect

Resets the page_id. This is usually used "redirect" to different template.

$model->pkit_internal_redirect($page_id);
pkit_redirect

Redirect to another URL.

$model->pkit_redirect("http://www.pagekit.org/");

Redirects user to the PageKit home page.

Note that this method automically adds the host name, if the url does not include http://.

pkit_set_errorfont

Sets the corresponding &lt;PKIT_ERRORFONT&gt; tag in the template. Useful for implementing your own custom constraints.

$model->pkit_set_errorfont('state');

Sets &lt;PKIT_ERRORFONT NAME="state"&gt; to &lt;font color="red"&gt;

pkit_validate_input

Takes an hash reference containing a HTML::FormValidator input profile and returns true if the request parameters are valid.

# very simple validation, just check to see if name field was filled out
my $input_profile = {required => [ qw ( name ) ]};
# validate user input
unless($model->pkit_validate_input($input_profile)){
  # user must have not filled out name field, 
  # i.e. $apr->param('name') = $model->input_param('name') is
  # not set, so go back to original form
  # if you used a <PKIT_ERRORFONT NAME="name"> tag, then it will be set to
  # red
  $model->pkit_internal_redirect('orig_form');
  return;
}
pkit_get_orig_uri

Gets the original URI requested.

pkit_get_server_id

Gets the server_id for the server, as specified by the PKIT_SERVER directive in the httpd.conf file.

pkit_get_session_id

Gets the session id if you have set up session management using pkit_session_setup. Note the following code is equivalent:

my $session_id = $model->pkit_get_session_id;
my $session_id = $model->session->{_session_id};
pkit_root

Gets the PageKit root directory, as defined by PKIT_ROOT in your httpd.conf file.

my $pkit_root = $model->pkit_root

The following methods should be defined in your base module as defined by model_base_class in Config.xml:

pkit_dbi_connect

Returns database handler, $dbh, which can be accessed by rest of Model through $model->dbh.

pkit_session_setup

Returns hash reference to Apache::PageKit::Session session setup arguments.

pkit_auth_credential

Verifies the user-supplied credentials and return a session key. The session key is a string that is stored on the user's computer using cookies. Often you'll use the user ID and a MD5 hash of a a secret key, user ID, password.

Note that the string returned should not contain any commas, spaces, or semi-colons.

pkit_auth_session_key

Verifies the session key (previously generated by auth_credential) and return the user ID. This user ID will be fed to $model->input_param('pkit_user').

pkit_common_code

Code that gets called before the page and component code for every page on the site.

pkit_post_common_code

Code that gets called after the page and component code is executed. Note that this is experimental and may change in future releases.

One use for this is to cleanup any database handlers:

sub pkit_post_common_code { my $model = shift; my $dbh = $model->dbh; $dbh->disconnect; }

Although a better solution is to use Apache::DBI.

pkit_output_filter

Filters the output from the PageKit handler. Should only use when necessary, a better option is to modify the templates directly.

Here we filter the image links to that they point to the secure site if we are on a secure page (the only good use of pkit_output_filter that I know of)

sub pkit_output_filter {
  my ($model, $output_ref) = @_;
  if($model->apr->parsed_uri->scheme eq 'https'){
    $$output_ref =~ s(http://images.yourdomain.com/)(https://images.yourdomain.com/)g;
  }
}
pkit_get_default_page

If no page is specified, then this subroutine will return the page_id of the page that should be displayed. You only have to provide this routine if you wish to override the default method, which simply returns the default_page attribute as listed in the Config.xml file.

SEE ALSO

Apache::PageKit, HTML::FormValidator

AUTHOR

T.J. Mather (tjmather@anidea.com)

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