/ 
Apache-PageKit-0.96
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');
content_param

Similar to output_param but sets content variables associated with the <CONTENT_VAR> and <CONTENT_LOOP> tags.

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.

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
  $model->pkit_internal_redirect('orig_form');
  return;
}

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 session setup arguments.

pkit_auth_credential

Verifies 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.

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').

SEE ALSO

Apache::PageKit, HTML::FormValidator

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