NAME

Jifty::Action - The ability to Do Things in the framework

DESCRIPTION

Jifty::Action is the meat of the Jifty framework; it controls how form elements interact with the underlying model. See also Jifty::Action::Record for data-oriented actions, Jifty::Result for how to return values from actions.

COMMON METHODS

new

Construct a new action. Subclasses who need do custom initialization should start with:

    my $class = shift; my $self = $class->SUPER::new(@_)

Do not call this yourself; always go through Jifty->web->new_action! The arguments that this will be called with include:

moniker

The moniker of the action. Defaults to an autogenerated moniker.

order

An integer that determines the ordering of the action's execution. Lower numbers occur before higher numbers. Defaults to 0.

arguments

A hash reference of default values for the arguments of the action. Defaults to none.

sticky_on_failure

A boolean value that determines if the form fields are sticky when the action fails. Defaults to true.

sticky_on_success

A boolean value that determines if the form fields are sticky when the action succeeds. Defaults to false.

arguments

Note: this API is in serious need of rototilling. Expect it to change in the near future, into something probably more declarative, like Jifty::DBI::Schema's. This will also increase the speed; these methods are the most-often called in Jifty, so caching them will improve things significantly.

This method, along with "take_action", is the most commonly overridden method. It should return a hash which describes the arguments this action takes:

  {
    argument_name    => {label => "properties go in this hash"},
    another_argument => {mandatory => 1}
  }

Each argument listed in the hash will be turned into a Jifty::Web::Form::Field object. For each argument, the hash that describes it is used to set up the Jifty::Web::Form::Field object by calling the keys as methods with the values as arguments. That is, in the above example, Jifty will run code similar to the following:

  # For 'argument_name'
  $f = Jifty::Web::Form::Field->new;
  $f->name( "argument_name" );
  $f->label( "Properties go in this hash" );

If an action has parameters that must be passed to it to execute, these should have the constructor property set. This is separate from the mandatory property, which deal with requiring that the user enter a value for that field.

See Jifty::Web::Form::Field for the list of possible keys that each argument can have.

run

This routine, unsurprisingly, actually runs the action.

If the result of the action is currently a success (validation did not fail), run calls "take_action", and finally "cleanup".

validate

Checks authorization with "check_authorization", calls /setup, canonicalizes and validates each argument that was submitted, but doesn't actually call "take_action".

The outcome of all of this is stored on the "result" of the action.

check_authorization

Returns true if whoever invoked this action is authorized to perform this action.

By default, always returns true.

setup

Whatever the action needs to do to set itself up, it can do it by overriding setup. setup is expected to return a true value, or "run" will skip all other actions.

By default, does nothing.

take_action

Do whatever the action is supposed to do. This and "arguments" are the most commonly overridden methods.

By default, does nothing.

The return value from this method is NOT returned. (Instead, you should be using the "result" object to store a result).

cleanup

Perform any action-specific cleanup. By default, does nothing.

Runs after "take_action" -- whether or not "take_action" returns success.

moniker

Returns the moniker for this action.

argument_value ARGUMENT [VALUE]

Returns the value from the argument with the given name, for this action. If VALUE is provided, sets the value.

form_field ARGUMENT

Returns a Jifty::Web::Form::Field object for this argument. If there is no entry in the "arguments" hash that matches the given ARGUMENT, returns undef.

form_value ARGUMENT

Returns a Jifty::Web::Form::Field object that renders a display value instead of an editable widget for this argument. If there is no entry in the "arguments" hash that matches the given ARGUMENT, returns undef.

order [INTEGER]

Gets or sets the order that the action will be run in. This should be an integer, with lower numbers being run first. Defaults to zero.

result [RESULT]

Returns the Jifty::Result method associated with this action. If an action with the same moniker existed in the last request, then this contains the results of that action.

register

Registers this action as being present, by outputting a snippet of HTML. This expects that an HTML form has already been opened. Note that this is not a guarantee that the action will be run, even if the form is submitted. See Jifty::Request for the definition of "active" actions.

Normally, "new_action" in Jifty::Web takes care of calling this when it is needed.

render_errors

Render any the "error" in Jifty::Result of this action, if any, as HTML. Returns nothing.

button arguments => { KEY => VALUE }, PARAMHASH

Create and render a button. It functions nearly identically like "link" in Jifty::Web, except it takes arguments in addition to parameters, and defaults to submitting this Jifty::Action. Returns nothing.

NAMING METHODS

These methods return the names of HTML form elements related to this action.

register_name

Returns the name of the "registration" query argument for this action in a web form.

form_field_name ARGUMENT

Turn one of this action's arguments into a fully qualified name; takes the name of the field as an argument.

fallback_form_field_name ARGUMENT

Turn one of this action's arguments into a fully qualified "fallback" name; takes the name of the field as an argument.

This is specifically to support checkboxes, which only show up in the query string if they are checked. Jifty creates a checkbox with the value of form_field_name as its name and a value of 1, and a hidden input with the value of fallback_form_field_name as its name and a value of 0; using this information, Jifty::Request can both determine if the checkbox was present at all in the form, as well as its true value.

double_fallback_form_field_name ARGUMENT

Turn one of this action's arguments into a fully qualified "double fallback" name; takes the name of the field as an argument.

This is specifically to support "constructor" hidden inputs, which need to be have even lower precedence than checkbox fallbacks. Probably we need a more flexible system, though.

error_div_id ARGUMENT

Turn one of this action's arguments into the id for the div in which its errors live; takes name of the field as an argument.

VALIDATION METHODS

argument_names

Returns the list of argument names. This information is extracted from "arguments".

_canonicalize_arguments

Canonicalizes each of the arguments that this action knows about.

This is done by calling "_canonicalize_argument" for each field described by "arguments".

_canonicalize_argument ARGUMENT

Canonicalizes the value of an argument. If the argument has an attribute named canonicalizer, call the subroutine reference that attribute points points to.

If it doesn't have a canonicalizer attribute, but the action has a canonicalize_ARGUMENT function, also invoke that function.

_validate_arguments

Validates the form fields. This is done by calling "_validate_argument" for each field described by "arguments"

_validate_argument ARGUMENT

Validate your form fields. If the field ARGUMENT is mandatory, checks for a value. If the field has an attribute named validator, call the subroutine reference validator points to.

If the action doesn't have an explicit validator attribute, but does have a validate_ARGUMENT function, invoke that function.

_autocomplete_argument ARGUMENT

Get back a list of possible completions for ARGUMENT.

If the field has an attribute named autocompleter, call the subroutine reference autocompleter points to.

If the action doesn't have an explicit autocomplete attribute, but does have a autocomplete_ARGUMENT function, invoke that function.

valid_values ARGUMENT

Given an argument name, returns the list of valid values for it, based on its valid_values parameter in the "arguments" list.

If the parameter is not an array ref, just returns it (not sure if this is ever OK except for undef). If it is an array ref, returns a new array ref with each element converted into a hash with keys display and value, which should be (if in a SELECT, say) the string to display for the value, and the value to actually send to the server. Things that are allowed in the array include hashes with display and value (which are just sent through); hashes with collection (a Jifty::Collection), and display_from and value_from (the names of methods to call on each record in the collection to get display and value); or strings, which are treated as both display and value.

(Avoid using this -- this is not the appropriate place for this logic to be!)

available_values ARGUMENT

Just like valid_values, but if our action has a set of available recommended values, returns that instead. (We use this to differentiate between a list of acceptable values and a list of suggested values)

validation_error ARGUMENT => ERROR TEXT

Used to report an error during validation. Inside a validator you should write:

  return $self->validation_error( $field => "error");

..where $field is the name of the argument which is at fault.

validation_ok ARGUMENT

Used to report that a field does validate. Inside a validator you should write:

  return $self->validation_ok($field);

cpanm Jifty

perl -MCPAN -e shell
install Jifty