NAME
OpenInteract2::Action::CommonUpdate - Task to update an object
SYNOPSIS
# Just subclass and the tasks 'display_form' and 'update' are
# implemented
package OpenInteract2::Action::MyAction;
use base qw( OpenInteract2::Action::CommonUpdate );
# Relevant configuration entries in your action.ini
[myaction]
...
c_object_type = myobject
c_display_form_template = mypkg::myform
c_display_form_fail_task = cannot_display_form
c_update_fail_task = display_form
c_update_security_fail_task = display_form
c_update_task = display
c_update_return_url = /index.html
c_update_fields = field_one
c_update_fields = field_two
c_update_fields = field_three
c_update_fields_toggled = field_yes_no
c_update_fields_date = field_date
c_update_fields_date_format = %Y-%m-%d
c_update_fields_datetime = field_date
c_update_fields_datetime_format = %Y-%m-%d %H:%MSUPPORTED TASKS
This common action support two tasks:
display_form
Displays the filled-in form to edit an object.
update
Read in field values for an object, apply them to an already existing object and save the object with the new values.
DESCRIPTION FOR 'display_form'
This takes the object type and an ID passed in, fetches the appropriate object and passes the object to a template which presumably displays its data in a form.
TEMPLATES USED FOR 'display_form'
c_display_form_template
Template used for editing the object. It will receive the object in the keys 'object' and '$object_type'.
It's fairly common to use the same template as when creating a new object.
METHODS FOR 'display_form'
_display_form_customize( \%template_params )
Add any necessary parameters to \%template_params before the content generation step where they get passed to the template specified in c_display_form_template.
CONFIGURATION FOR 'display_form'
Basic
c_object_type ($) (REQUIRED)
SPOPS key for object you'll be displaying.
c_display_form_fail_task ($)
If we cannot fetch the necessary object this task is run.
Default: 'common_error'
System-created parameters
c_object_class
See "_common_check_object_class" in OpenInteract2::Common
c_id_field
See "_common_check_id_field" in OpenInteract2::Common
c_id ($)
The ID of the object we've fetched for update.
c_object ($)
The object we've fetched for update.
DESCRIPTION FOR 'update'
Takes request data, including the object ID, fetches the object and if the fetch is successful sets the request data as the object properties and tries to save it.
TEMPLATES USED FOR 'update'
None
METHODS FOR 'update'
_update_customize( $object, \%old_data, \%save_options )
You can validate the data in $object and ensure that invalid data don't get saved. You can also make any necessary customizations (such as setting defaults) to $object before it's updated. You even have access to its previous values in the \%old_data mapping.
If you've encountered an error condition (including invalid data), throw a die with the necessary content. The update will not happen and the user will see whatever you've generated.
You can also specify keys and values in \%save_options which get passed along to the save() call.
Here's an example of validating your data using the 'view messages' found in the OpenInteract2::Action object. Here we'll assume that we have a database of books and someone is updating a particular book record:
sub _update_customize {
my ( $self, $book, $old_book, $save_options ) = @_;
my $validation_errors = 0;
unless ( $book->{title} ) {
$self->add_view_message( title => 'Book must have a title' );
$validation_errors++;
}
unless ( $book->{author_last} ) {
$self->add_view_message( author_last => 'Book author must have a last name' );
$validation_errors++;
}
if ( $validation_errors ) {
die $self->execute({ task => 'display_form' });
}
}_update_post_action
This method is called after the object has been successfully updated -- you'll find the object in the c_object action parameter. You can perform any action you like after this. If you throw a die with content it will be displayed to the user rather than moving to the configured c_update_task.
CONFIGURATION FOR 'update'
Basic
c_update_fail_task ($)
Task to execute on failure.
Default: 'display_form'
c_update_security_fail_task ($)
Task to update on the specific failure of insufficient security. If this is not defined we'll just use c_update_fail_task.
c_update_task ($)
Task to execute when the update succeeds. You can get at the object just updated in the c_object paramter:
[book]
class = OpenInteract2::Action::Book
...
c_update_task = display_modify_status
package OpenInteract2::Action::Book;
...
sub display_modify_status {
my ( $self ) = @_;
my $book = $self->param( 'c_object' );
my $output = 'Updated [% title %] properly';
return $self->generate_content(
{ title => $book->title },
{ text => $output } );
}Default: 'display_form'
c_update_return_url
What I should set the 'return URL' to. This is used for links like 'Login/Logout' where you perform an action and the system brings you back to a particular location. You don't want to come back to the '.../update/' URL.
Note that this will be normalized to the deployment context at runtime. So if you specify '/foo/bar/' and your application is deployed under '/Deploy', the final URL will be '/Deploy/foo/bar/'.
Default: the URL formed by the default task for the current action.
Object fields to assign
c_update_fields ($ or \@)
List the fields you just want assigned directly from the name. So if a form variable is named 'first_name' and you list 'first_name' here we'll assign that value to the object property 'first_name'.
c_update_fields_toggled ($ or \@)
List the fields you want assigned in a toggled fashion -- if any value is specified, we set it to 'yes'; otherwise we set it to 'no'. (See "param_toggled" in OpenInteract2::Request.)
c_update_fields_date ($ or \@)
List the date fields you want assigned. You can have the date read from a single field, in which case you should also specify a strptime format in c_update_fields_date_format, or multiple fields as created by the date_select OI2 control. (See "param_date" in OpenInteract2::Request.)
c_update_fields_datetime ($ or \@)
List the datetime fields you want assigned. These are just like date fields except they also have a time component. You can have the date and time read from a single field, in which case you should also specify a strptime format in c_update_fields_date_format, or multiple fields. (See "param_datetime" in OpenInteract2::Request.)
c_update_fields_date_format ($)
If you list one or more fields in c_update_fields_date and they're pulled from a single field, you need to let OI2 know how to parse the date. Just specify a strptime format as specified in DateTime::Format::Strptime.
c_update_fields_datetime_format ($)
If you list one or more fields in c_update_fields_datetime and they're pulled from a single field, you need to let OI2 know how to parse the date and time. Just specify a strptime format as specified in DateTime::Format::Strptime.
System-created parameters
c_object_class
See "_common_check_object_class" in OpenInteract2::Common
c_id_field
See "_common_check_id_field" in OpenInteract2::Common
c_id ($)
The ID of the object we're trying to update.
c_object ($)
If we're able to fetch an object to update this will be set. Whether the update succeeds or fails the object should represent the state of the object in the database.
c_object_old_data (\%)
If the update is successful we set this to the hashref of the previous record's data.
COPYRIGHT
Copyright (c) 2003-2004 Chris Winters. All rights reserved.
AUTHORS
Chris Winters <chris@cwinters.com>