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('bar');

    # do some processing

    ...

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

METHODS

API to be used in derived classes

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

input

Gets requested parameter from the request object $apr.

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

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

  my @keys = $model->input;

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;

fillinform

Used with HTML::FillInForm to fill in HTML forms. Useful for example when you want to fill an edit form with data from the database.

  $model->fillinform(email => $email);

pnotes

Wrapper to mod_perl's pnotes function, used to pass values from one handler to another.

For example you can set the userID when the user gets authenticated.

  $model->pnotes(user_id => $user_id);

output

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

  $model->output(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(firstname => $firstname,
               lastname => $lastname);

Alternatively you can pass a hash reference:

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

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

  $model->output(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);

Note that the message is passed along in the URI if you perform a redirect using pkit_redirect.

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.

It is strongly recommend that you use this method on pages where a query that changes the state of the application is executed. Typically these are POST queries that update the database.

Note that this passes along the messages set my pkit_message if applicable.

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 <font color="red">

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('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_page_id

Gets page_id.

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

pkit_user

Gets the user_id from $apr-connection->user>, as set by the return value of pkit_auth_session_key.

Methods to be defined in your base Model class.

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. The returned user ID will be fed to $apr-connection->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.

pkit_cleanup_code

One use for this is to cleanup any database handlers:

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

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

pkit_fixup_uri

Pre-processes the URI so that it will match the page_id's used by PageKit to dispatch the model code and find the template and content files.

  sub pkit_fixup_uri {
    my ($model, $uri) = @_;

    $uri =~ s!^/pagekit!!;
    return $uri;
  }

In this example, the request for http://yourwebsite/pagekit/myclass/mypage would get dispatched to the mypage method of the myclass class, and the View/Default/myclass/mypage.tmpl template and/or the Content/myclass/mypage.xml XML file.

See also uri_prefix in Apache::PageKit::Config.

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.

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;
    }
  }

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