| Form::Factory::Action - Role implemented by actions |
Form::Factory::Action - Role implemented by actions
version 0.014
package MyApp::Action::Foo; use Form::Factory::Processor;
has_control bar => ( type => 'text', );
sub run { my $self = shift;
# Do something...
}
This is the role implemented by all form actions.
All form actions have the following attributes.
This is the the Form::Factory::Interface manpage that constructed this action. If you need to get at the implementation directly for some reason, here it is. This is mostly used by the action itself when calling the render and consume methods.
This is a hash of extra parameters to keep with the form. Normally, these are saved with a call to stash and recovered with a call to unstash.
This is a the Form::Factory::Result::Gathered manpage object that tracks the general success, failure, messages, and output from the execution of this action.
Actions delegate a number of methods to this object. See RESULTS.
This is a the Form::Factory::Result::Single manpage used to record general outcome.
Actions delegate a number of methods to this object. See RESULTS.
This is a list of the Form::Factory::Feature manpage objects used to modify the object. This will always contain the features that are attached to the class itself. Additional features may be added here.
This is a hash of controls attached to this action. For every has_control line in the action class, there should be a matching control in this hash.
$action->stash($moniker);
Given a $moniker (a key under which to store the information related to this form), this will stash the form's stashable information under that name using the the Form::Factory::Stasher manpage associated with the form_interface.
The globals, stashable parts of controls, and the results are stashed. This allows those values to be recovered across requests or between process calls or whatever the implementation requires.
$action->unstash($moniker);
Given a $moniker previously named in a call to stash, it restores the previously stashed state. This is a no-op if nothing is stashed under this moniker.
This method clears the stashable state of the action.
$action->render(%options);
Renders the form using the associated form_interface. You may specify the following options:
This is a list of control names to render. If not given, all controls will be rendered.
Any other options will be passed on to the render_control in the Form::Factory::Interface manpage method.
my $control = $action->render_control($name, \%options);
Creates and renders a one time control. This is mostly useful for attaching buttons to a form. The control is not added to the list of controls on the action and will not be processed later.
This method returns the control object that was just rendered.
$action->consume(%options);
This consumes any input from user and places it into the controls of the form. You may pass the following options:
This is a list of names of controls to consume. Any not listed here will not be consumed. If this option is missing, all control values are consumed.
Any additional options will be passed to the consume_control in the Form::Factory::Interface manpage method call.
my $control = $action->consume_control($name, \%options, %params);
Consumes the value of a one time control. This is useful for testing to see if a form submitted using a one-time control has been submitted or not.
This method returns the control object that was consumed.
$action->clean(%options);
Takes the values consumed from the user and cleans them up. For example, if you allow users to type in a phone number, this can be used to clear out any unwanted or incorrect punctuation and format the phone number properly.
This method runs through all the requested the Form::Factory::Feature manpage objects in features and runs the clean in the Form::Factory::Feature manpage method for each.
The following options are used:
This is the list of controls to clean. If not given, all features will be run. If given, only the control-features (those implementing the Form::Factory::Feature::Role::Control manpage attached to the named controls) will be run. Any form-features or unlisted control-features will not be run.
$action->check(%options);
The check method is responsible for verifying the correctness of the input. It assumes that clean has already run.
It runs the check in the Form::Factory::Feature manpage method of all the selected features attached to the action. It also sets the is_valid flag to true if no errors have been recored yet or to false if they have.
The following options are used:
This is the list of controls to check. If not given, all features will be run. If given, only the control-features (those implementing the Form::Factory::Feature::Role::Control manpage attached to the named controls) will be run. Any form-features or unlisted control-features will not be run.
$action->process;
This does nothing if the action did not validate.
In the case the action is valid, this will use set_attributes_from_controls to copy the control values to the action attributes, run the pre_process in the Form::Factory::Feature manpage methods for all form-features and control-features, call the run method, run the post_process in the Form::Factory::Feature manpage methods for all form-features and control-features, and set the is_success flag to true if no errors are recorded or false if there are.
This is a shortcut for taking all the usual workflow actions in a single call:
$action->consume(@_); $action->clean; $action->check $action->process;
This method must be implemented by any action implementation.
This is the method that actually does the work. It takes no arguments and is expected to return nothing. You should draw your input from the action attributes (not the controls) and report your results to result.
These methods are primarily intended for internal use.
Given the name of a control, this will copy the current value in the control to the attribute.
This method is used by process to copy the values out of the controls into the form action attributes. This assumes that such a copy will work because the clean and check phases should have already run and passed without error.
Gathers results for all the associated controls and result into results. This is called just before deciding if the action has validated correctly or if the action has succeeded.
Actions are tied closely to the Form::Factory::Result manpages. As such, a number of methods are delegated to result classes.
The following methods are delegated to results in the Form::Factory::Result::Gathered manpage.
These methods are delegated to the result manpage in the Form::Factory::Result::Single manpage.
=item info
=item field_info
The action workflow typically goes like this. There are two phases.
Phase 1 is responsible for showing the form to the user. This phase might be skipped altogether in situations where automatic processing is taking place where the robot doing the work already knows what inputs are expected for the action. However, typically, you do something like this:
my $action = $interface->new_action('Foo'); $action->unstash('foo'); $action->render; $action->render_control(button => { name => 'submit', label => 'Do It', }); $action->stash('foo');
This tells the interface that you want to prepare a form object for class "Foo."
The call to unstash then pulls in any state saved from the user's prior entry. This will cause any errors that occurred on a previous validation or process execution to show up (assuming that your interface does that work for you). This also means that any previously stashed values entered should reappear in the form so that a failure to save or something won't cause the field information to be lost forever.
The call to render causes all of the controls of the form to be rendered for input.
The call to render_control causes a button to appear in the form.
The call to stash returns the form's stashable information back to the stash, since unstash typically removes it.
Once the user has submitted the form, you will want to process the input and perform the action. This typically looks like this:
my $action = $interface->new_action('Foo'); $action->unstash('foo'); $action->consume_and_clean_and_check_and_process( request => $q->Vars );
if ($action->is_valid and $action->is_success) { # Go on to the next thing } else { $action->stash('foo'); # Go render the form again and show the errors }
We request an instance of the form again and then call unstash to recover any stashed setup. We then call the consume_and_clean_and_check_and_process method, which will consume all the input. Here we use something that looks like a CGI request for the source of input, but it should be whatever is appropriate to your environment and the the Form::Factory::Interface manpage implementation used.
At the end, we check to see if the action checked out and then that the run method ran without problems. If so, we can show the success page or the record view or whatever is appropriate after filling this form.
If there are errors, we should perform the rendering action for PHASE 1: SHOW THE FORM again after doing a stash to make sure the information is ready to be recovered.
Ajax or GUIs will generally want to give their feedback as early as possible. As such, whenever the user finishes entering a value or the application thinks that validation is needed, the app might perform:
$action->check( controls => [ qw( some_control ) ] ); $action->clean( controls => [ qw( some_control ) ] );
unless ($action->is_valid) { # Report $action->results->error_messages }
You will still run the steps above, but can do a check and clean on a subset of controls when you need to do so to give the user early feedback.
Andrew Sterling Hanenkamp <hanenkamp@cpan.org>
Copyright 2009 Qubling Software LLC.
This library is free software. You can redistribute it and/or modify it under the same terms as Perl itself.
| Form::Factory::Action - Role implemented by actions |