The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

CGI::AppToolkit::Data::Object - A data source component of CGI::AppToolkit

DESCRIPTION

CGI::AppToolkit::Data::Objects provide a common interface to multiple data sources. The data sources are provided by CGI::AppToolkit::Data::Object decendants that you create, generally on a per-project basis. Providing a data source requires creating an object in the CGI::AppToolkit::Data:: namespace that inherits from CGI::AppToolkit::Data::Object.

You do not use this module or it's descendants in your code directly, but instead call CGI::AppToolkit->data() to load it for you.

USAGE

For a Person object, you might start the module like this:

  package CGI::AppToolkit::Data::Person;
  
  use CGI::AppToolkit::Data::Object;
  use strict;
  
  @CGI::AppToolkit::Data::Person::ISA = qw/CGI::AppToolkit::Data::Object/;

After that, you simply have to override four subroutines: fetch, store, delete, and update. All of these are called with two parameters: the object, of course, and the arguments. The arguments are passed in a single parameter which is usually a hashref.

  sub store { # or fetch, update, or delete
    my $self = shift;
    my $args = shift;
    
        # args is usually a hashref, so you would use it like this
        my $id = $args->{'id'};
        
        #... do the actual storing and such here
  }

There is nothing forcing you to implement all of these subroutines. For example, if you are implementing a read-only object, then you could override only fetch.

Conventionally a relational database is used, but there's nothing forcing you to that either. The data can come from any source at all. However, if you data is coming from a DBI accessed RDBMS that uses SQL, then you should take a look at CGI::AppToolkit::Data::SQLObject and CGI::AppToolkit::Data::Automorph. CGI::AppToolkit::Data::SQLObject handles a few of the common DBI tasks for you, and it's descendant CGI::AppToolkit::Data::Automorph attempts to handle the rest of them.

METHODS

CGI::AppToolkit::Data::Object provides several convenience methods to inherit.

get_kit()

Returns the creating CGI::AppToolkit object. This can be used to retrieve required data.

  my $dbi = $self->get_kit()->get_dbi();

The CGI::AppToolkit object has an autoload mechanism that provides all variables that are passed to it's new() method as method calls, with get_ or set_ added to the beginning to retrieve or set the value, repectively.

In particular, CGI::AppToolkit->get_dbi() retrieves the DBI object stored from a call to CGI::AppToolkit->connect().

_new_error()

Returns a new, empty CGI::AppToolkit::Data::Object::Error object, as described in detail below.

AUTOLOAD

Using the built-in AUTOLOAD mechanism, you can retrieve and set object variables with named method calls. These method names are not case sensitive.

  # setting
  $self->set_wierd_variable($value);
  
  # retrieving
  my $value = $self->get_wierd_variable();

CGI::AppToolkit::Data::Object::Error

DESCRIPTION

CGI::AppToolkit::Data::Object::Error provides a simple interface to errors returned by Data-fetch()>. This class seperates errors into three classes: plain text errors (errors), missing items (missing), and wrong items (wrong). Plain text errors are for sending back to the interface. Missing items and wrong items are both lists of keys that were missing or wrong in the args provided to store.

METHODS

The following methods are for use by scripts using CGI::AppToolkit::Data and will only need to retrieve errors.

has_errors()

Return nonzero if there are errors and zero if there are not.

get()

Returns three arrayrefs: errors, missing, and wrong, in that order. The errors arrayref points to an array of hashes of the form {'text' => $error}. The other two arrayrefs point to arrays of strings.

  # as called in a script using CGI::AppToolkit
  # $of is an instance of CGI::AppToolkit
  my $ret = $CGI::AppToolkit->data('person')->store(\%person);
  if (ref $ret =~ /Error/) {
    my ($errors_a, $missing_a, $wrong_a) = $ret->get();
        # ...
  }

The following methods are for use inside CGI::AppToolkit::Data::Object descendants.

error(ERROR)

Adds an error with the text ERROR to the error object.

  $error->error('You screwed up, dude!');
missing(ITEM)
wrong(ITEM)

Adds a missing or wrong ITEM to the error object.

  $error->missing('address1'); # missing a required field
  $error->wrong('email'); # malformed email address

AUTHOR

Copyright 2002 Robert Giseburt (rob@heavyhosting.net). All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Please visit http://www.heavyhosting.net/AppToolkit/ for complete documentation.