OpenInteract2::Action::CommonUpdate - Task to update an object
# 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:%M
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.
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.
c_display_form_template
Template used for editing the object. It will receive the object in the keys 'object' and '$object_type'.
It is fairly common to use the same template as when creating a new object.
_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.
\%template_params
c_object_type ($) (REQUIRED)
SPOPS key for object you will be displaying.
c_display_form_fail_task ($)
If we cannot fetch the necessary object this task is run.
Default: 'common_error'
c_task
Name of the task originally invoked: 'display_form.
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.
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.
None
_update_customize( $object, \%old_data, \%save_options )
You can validate the data in $object and ensure that invalid data do not get saved. You can also make any necessary customizations (such as setting defaults) to $object before it is updated. You even have access to its previous values in the \%old_data mapping.
$object
\%old_data
If you have 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 have generated.
die
You can also specify keys and values in \%save_options which get passed along to the save() call.
\%save_options
save()
Here is an example of validating your data using the 'view messages' found in the OpenInteract2::Action object. Here we will 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 will 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.
c_object
c_update_task
The update() method fires two observations:
update()
pre update ( $action, 'pre update', $object, \%old_data, \%save_options )
( $action, 'pre update', $object, \%old_data, \%save_options )
This is fired just before the object is update, which means that the _update_customize() method described above has already run.
_update_customize()
This gets passed the object to be updated, a hashref of the data in the old object, and the options being sent to the save() method:
package My::Observer; sub update { my ( $class, $action, $type, $object, $old_data, $save_opts ) = @_ return unless ( $type eq 'pre update' ); ... }
post update ( $action, 'post update', $object, \%old_data )
( $action, 'post update', $object, \%old_data )
This is fired after the object is updated as well as after the _update_post_action() described above.
_update_post_action()
This gets passed the object to be updated and a hashref with the data from the old object:
package My::Observer; sub update { my ( $class, $action, $type, $object, $old_data ) = @_; return unless ( $type eq 'post update' ); ... }
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 will just use c_update_fail_task.
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 } ); }
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 do not 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.
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 will 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.)
strptime
c_update_fields_date_format
date_select
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 are 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_date
c_update_fields_datetime_format ($)
If you list one or more fields in c_update_fields_datetime and they are 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.
c_update_fields_datetime
Name of the task originally invoked: 'update'.
The ID of the object we are trying to update.
If we are 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 data from the previous record.
Copyright (c) 2003-2004 Chris Winters. All rights reserved.
Chris Winters <chris@cwinters.com>
To install OpenInteract2::URL, copy and paste the appropriate command in to your terminal.
cpanm
cpanm OpenInteract2::URL
CPAN shell
perl -MCPAN -e shell install OpenInteract2::URL
For more information on module installation, please visit the detailed CPAN module installation guide.