OpenInteract2 Documentation: OpenInteract2::Action::CommonAdd

NAME

OpenInteract2::Action::CommonAdd - Tasks to display empty form and create an object

SYNOPSIS

 # Just subclass and the tasks 'display_add' and 'add' are implemented
 
 package OpenInteract2::Action::MyAction;
 
 use base qw( OpenInteract2::Action::CommonAdd );
 
 # Relevant configuration entries in your conf/action.ini
 
 [myaction]
 ...
 c_object_type                = myobject
 c_display_add_template       = mypkg::new_form
 c_add_task                   = display
 c_add_fail_task              = display_add
 c_add_return_url             = /index.html
 c_add_fields                 = title
 c_add_fields                 = author
 c_add_fields                 = publisher
 c_add_fields_toggled         = has_nyt_review
 c_add_fields_boolean         = flagged_by_accounting
 c_add_fields_date            = publish_date
 c_add_fields_date_format     = %Y-%m-%d
 c_add_fields_datetime        = last_edit_time
 c_add_fields_datetime_format = %Y-%m-%d %H:%M

SUPPORTED TASKS

This common action supports the following tasks:

display_add - Display a form to create a new object.

add - Add the new object.

DESCRIPTION FOR 'display_add'

Displays a possibly empty form to create a new object. The 'possibly' derives from your ability to pre-populate the object with default data so the user can do less typing. Because your job is all about the users...

TEMPLATES USED FOR 'display_add'

c_display_add_template: Template with a form for the user to fill in with values to create a new object.

The template gets an unsaved (likely empty) object in the keys 'object' and '$object_type'.

METHODS FOR 'display_add'

_display_add_customize( \%template_params )

Called just before the content is generated, giving you the ability to modify the likely empty object to display or to add more parameters.

CONFIGURATION FOR 'display_add'

These are in addition to the template parameters defined above.

Basic

c_object_type ($) (REQUIRED)

SPOPS key for object you will be displaying.

System-created parameters

c_task

Name of the task originally invoked: 'display_add'.

c_object ($)

System will create a new instance of the object type if not previously set.

c_object_class ($)

Set to the class corresponding to c_object_type. This has already been validated.

DESCRIPTION FOR 'add'

Takes data from a form and creates a new object from it.

TEMPLATES USED FOR 'add'

None

METHODS FOR 'add'

_add_customize( $object, \%save_options )

Called just before the save() operation which creates the object in your datastore. (Note that it is also before the 'pre add' observation is posted, see below.) You have three opportunities to affect the operation:

Modify the object being saved by modifying or adding values to $object.
Modify the options passed to save() by modifying or adding values to \%save_options.
Throw a die with content from the method. This content will be sent on to the user. This gives you an opportunity to do any necessary validation, quota ceiling inspections, time of day checking, etc.

Here is an example of a validation check:

 sub _add_customize {
     my ( $self, $object, $save_options ) = @_;
     if ( $self->widget_type eq 'Frobozz' and $self->size ne 'Large' ) {
 
         # First set an error message to tell the user what is wrong...
 
         $self->add_view_message(
             size => "Only large widgets of type Frobozz are allowed" );
 
         # Next, provide the object with its values to the form so we
         # can prepopulate it...
 
         $self->param( c_object => $object );
 
         # ...and display the editing form again
 
         die $self->execute({ task => 'display_add' });
     }
 }

_add_post_action( $object )

This method is called after the $object has been successfully created. You can perform any action you like in this method. Similar to _add_customize(), if you throw a die with content it will be displayed to the user rather than moving to the configured c_add_task.

OBSERVATIONS FIRED

The add() method fires two observations:

pre add ( $action, 'pre add', $object, \%save_options )

This is fired just before the object is added, which means that the _add_customize() method described above has already run.

This gets passed the object to be saved and the options being sent to the save() method:

 package My::Observer;
 
 sub update {
     my ( $class, $action, $type, $object, $save_opts ) = @_
     return unless ( $type eq 'pre add' );
     ...
 }

post add ( $action, 'post add', $object )

This is fired after the object is added as well as after the _add_post_action() described above.

This gets passed the object to be saved:

 package My::Observer;
 
 sub update {
     my ( $class, $action, $type, $object ) = @_;
     return unless ( $type eq 'post add' );
     ...
 }

CONFIGURATION FOR 'add'

Basic

c_object_type ($) (REQUIRED)

SPOPS key for object you'll be displaying.

c_add_task ($) (REQUIRED)

Task executed when the add is successful.

c_add_fail_task ($)

Task to run if we fail to fetch the object.

Default: 'display_add'

c_add_return_url ($)

Path we use for returning. (For example, if someone logs in on the resulting page.)

Default: the default task for this action

Object fields to assign

These configuration keys control what data will be read from the HTTP request into your object, and in some cases how it will be read.

c_add_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_add_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 OpenInteract2::Request/param_toggled.)

c_add_fields_boolean ($ or \@)

List the fields you want assigned in a boolean fashion -- if any value is specified, we set it to '1'; otherwise we set it to '0'. (See OpenInteract2::Request/param_boolean.) Use this instead of c_add_fields_toggled when your field maps to a SQL BIT or BOOLEAN datatype.

c_add_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_add_fields_date_format, or multiple fields as created by the date_select OI2 control. (See OpenInteract2::Request/param_date.)

c_add_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_add_fields_date_format, or multiple fields. (See OpenInteract2::Request/param_datetime.)

c_add_fields_date_format ($)

If you list one or more fields in c_add_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_add_fields_datetime_format ($)

If you list one or more fields in c_add_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_task

Name of the task originally invoked: 'add'.

c_object ($)

If the add is successful this will be set to the newly-created object.

c_object_class ($)

Set to the class corresponding to c_object_type. This has already been validated.

COPYRIGHT

AUTHORS

Chris Winters <chris@cwinters.com>

Generated from the OpenInteract 1.99_06 source.