The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
OpenInteract-1.99_05
River stage zero No dependents
1 ++
/ OpenInteract2::Action::Common

NAME

OpenInteract2::Action::Common - Base class for common functionality

SYNOPSIS

 package OpenInteract2::Action::CommonSearch;
 
 use base qw( OpenInteract2::Action::Common );

DESCRIPTION

This class is a subclass of OpenInteract2::Action and for now mostly provides placeholder methods to signal that an action does not implement certain common methods. It also has a few common functions as well. All common actions should subclass this class so that any inadvertent calls to other common methods get caught and a decent (if terse) message is returned. For instance, say I did this:

 package OpenInteract2::Action::MyAction;
 
 use strict;
 use base qw( OpenInteract2::Action::CommonSearch );

and in my search results template I had:

 <p>Your search results:</p>
 
 <ul>
 [% FOREACH record = records;
        display_url = OI.action.create_url( TASK = 'display',
                                            my_id = record.id ); %]
     <li><a href="[% display_url %]">[% record.title %]</li>
 [% END %]
 </ul>

Since I have not inherited a 'display' task or defined one myself, when I click on the created link I can expect an ugly error message from the dispatcher telling me that the task does not exist. Instead, I will get something like:

 Display capability is not built into action 'foo'.

It also leaves us an option for locating future common functionality.

METHODS

Fetching Objects

_common_fetch_object( [ $id ] )

Fetches an object of the type defined in the c_object_type parameter. If an ID value is not passed in it looks for the ID using the same algorithm found in _common_check_id -- so you should run that methods in your task initialization before calling this.

Returns: This method returns an object or throws an exception. If we encounter an error while fetching the object we add to the action parameter 'error_msg' stating the error and wrap the error in the appropriate OpenInteract2::Exception object and rethrow it. Appropriate: if we cannot fetch an object due to security we throw an OpenInteract2::Exception::Security exception.

If an object is not retrieved due to an ID value not being found or a matching object not being found, a new (empty) object is returned.

Setting object properties

_common_assign_properties( $object, \%field_info )

Assign values from HTTP request into $object as declared by \%field_info. The data in \%field_info tells us the names and types of data we will be setting in the object. You can learn more about the different types of parameters we are reading in the various param_* methods in OpenInteract2::Request.

The following example will set in $object the normal fields 'first_name' and 'last_name', the date field 'birth_date' (formatted in the standard 'yyyy-mm-dd' format) and the toggled field 'opt_in':

 $self->_common_assign_properties(
     $object, { standard    => [ 'first_name', 'last_name' ],
                toggled     => 'opt_in',
                date        => 'birth_date',
                date_format => '%Y-%m-%d' }
 );

Checking Parameters

This class has a number of methods that subclasses can call to check parameters. Each method returns the number of errors found (0 is good). It also deposits a message in the error_msg action parameter so you and the user can find out what happened.

_common_check_object_class()

Ensures the parameter c_object_type is present and refers to a valid object class as returned by the context. We check the latter condition like this:

 my $object_class = eval { CTX->lookup_object( $object_type ) };

If nothing is returned or the lookup_object() method throws an exception the condition fails.

If both conditions are true we set the parameter c_object_class so you do not need to do the lookup yourself.

_common_check_id_field()

Ensures the object class (set in c_object_class) has an ID field specified. (Since we depend on c_object_class you should run the _common_check_object_class() check first.) We check the ID field from the class with:

 my $object_class = $self->param( 'c_object_class' );
 my $id_field = eval { $object_class->id_field };

If no ID field is returned or the method throws an exception the condition fails.

If the condition succeeds we set the parameter c_id_field so you do not need to do the lookup yourself.

_common_check_id()

Tries to find the ID for an object using a number of methods. We depend on the c_id_field parameter being set, so you should run _common_check_id_field before this check.

Here is how we find the ID, in order.

  1. Is there an action parameter with the name c_id?

  2. Is there an action parameter with the same name as the ID field?

  3. Is there a request parameter with the same name as the ID field?

  4. Is there a request parameter with the name 'id'?

The first check that finds an ID is used. If no ID is found and there is a corresponding entry in an SPOPS object 'field_map' configuration we rerun checks 2 and 3 above with the new ID field. If no ID value is still found the check fails. If an ID is found its value is set in the action parameter c_id so you do not need to do the lookup.

_common_check_template_specified( @template_parameters )

Check to see that each of @template_parameters -- an error message is generated for each one that is not.

No side effects.

_common_check_param( @params )

Just check that each one of @params is defined -- an error message is generated for each one that is not. If you want to check that a template is defined you should use _common_check_template_specified() since it provides a better error message.

No side effects.

Setting Defaults

_common_set_defaults( \%defaults )

Treats each key/value pair in \%defaults as default action parameters to set.

Handling Errors

common_error

Displays any error messages set in your action using the template returned from _common_error_template.

Example:

 if ( $flubbed_up ) {
     $self->param_add( error_msg => 'Something is flubbed up' );
     $self->task( 'common_error' );
     return $self->execute;
 }

You could also use a shortcut:

 if ( $flubbed_up ) {
     $self->param_add( error_msg => 'Something is flubbed up' );
     return $self->execute({ task => 'common_error' });
 }

_common_error_template

Returns a fully-qualified template name for when your action encounters an error. By default this is defined as common_action_error, but you can also override this method and define it yourself. If you do should take the same parameters as the global error_message template.

SEE ALSO

OpenInteract2::Action::CommonAdd

OpenInteract2::Action::CommonDisplay

OpenInteract2::Action::CommonRemove

OpenInteract2::Action::CommonSearch

OpenInteract2::Action::CommonUpdate

COPYRIGHT

Copyright (c) 2003-2004 Chris Winters. All rights reserved.

AUTHORS

Chris Winters <chris@cwinters.com>