parameters

    use Jifty::Param::Schema;
    use Jifty::Action schema {

    param 'title';
    param 'category';
    param 'body';

    };

However, we've only scratched the surface of the power the "param" API offers. Parameters can have types, labels, validators, canonicalizers, and even more. To start with, let's add some types and labels:

    use Jifty::Param::Schema;
    use Jifty::Action schema {

    param title =>
        label is 'Title',
        max_length is 50,
        is mandatory;

    param category => 
        label is 'Category',
        max_length is 30;

    param body =>
        label is 'Entry',
        render as 'Textarea';

    };

Now, we can ask the action to render form fields, and it will know how to display them. But, we can do even better. Let's improve the look of that "category" field, by making it a combobox (a combination dropdown/text field), with some default values available:

    # ...
    param category => 
        label is 'Category',
        render as 'Combobox',
        available are qw( Personal Work Block );
    # ...

But a static list is lame. What we really want is a "Category" model, and to keep track of all the categories users have entered:

    # ...
    param categories => 
        label is 'Category',
        render as 'Select',
        available are defer {
            my $categories = MyBlog::Model::CategoryCollection->new;
            $categories->unlimit;
            [{
                display_from => 'name',
                value_from   => 'name',
                collection   => $categories,
            }];
        }
    ...

Now, Jifty will populate the combobox with the result of calling "name" on each element in $categories. Alternatively, if you set "value_from => 'id'", Jifty would automatically return the "id" of the category, for easy database reference. We don't do this with the combobox, however, since a combobox displays the selected value in its text field.

See Jifty::Action and Jifty::Web::Form::Field for more fields you can set in the "param" declaration, and see Jifty::Param::Schema for more about the syntax.

validation

    use Regexp::Common 'profanity_us';

    sub validate_body {
       my $self = shift;
       my $body = shift;

       if ( $body =~ /$RE{profanity}/i) {
           return $self->validation_error(
               body => 'Would you speak like that in front of your mother? *cough*'
           );
       }
       return $self->validation_ok('body');
    }

Your "validate_<parameter>" method will be called with the value of "<parameter>" followed by two hash references. The first is a hash reference of the full set of arguments passed along with "<parameter>" to permit more advanced validation. For example you could forbid profanity only if the content is "rated" for all ages. The final parameter is another hash reference of extra metadata. The "for" key will be set to "create" or "update" to give you still more control.

You can also do validation in the model -- see Jifty::Action::Record.

canonicalization

    use Regexp::Common 'profanity_us';

    sub canonicalize_body {
       my $self = shift;
       my $body = shift;
       $body =~ s/$RE{profanity}/**expletives**/gi;
       return $body;
    }

Note that the parameters (value, all parameters, metadata) are the same as in "validation".

A canonicalizer can also change other parts of the action. This lets you update the display dynamically in an AJAX-enabled browser based on what the user has entered. For example, we can let a user use magic syntax to provide tags for their blog post by surrounding the tags with square brackets. You can also let the user know you're doing something magical by using "canonicalization_note" which will display a message to the user.

    use Jifty::Param::Schema;
    use Jifty::Action schema {
        param title =>
            label is 'Title',
            hints is "You can provide tags like this [tag1 tag2]",
            ajax canonicalizes;

        param tags =>
            label is 'Tags';
    };

    sub canonicalize_title {
        my $self = shift;
        my $value = shift;

        if ($value =~ s/\[(.*?)\]//) {
            # this clobbers, may want to merge
            $self->argument_value( tags => $1 );
            $self->canonicalization_note(
                title => 'Removed tags from your title'
            );
        }

        return $value;
    }

If you set "ajax validates" or "ajax canonicalizes" for an argument, then Jifty will automatically validate or canonicalize it in an AJAX-enabled browser when the user stops typing and puts the focus out of the corresponding form field.

take_action

Inside "sub take_action", subclasses can access their arguments via "$self->argument_value('foo')". If you need to check whether you've been passed an argument or not (as opposed to being passed a true argument or not), use "$self->has_argument('foo')".

Once an action has done its task, it needs to inform the caller whether or not it has succeeded, possibly with some status message. To this end, every "Jifty::Action" has a "Jifty::Result" associated with. "Jifty::Result" carries both a failure/sucess code, and a textual message describing the result of running the action.

Thus, if your action failed for some reason, you would, in "take_action", write code like:

    $self->result->error('Could not write blog post');
    return;

If, however, the action completed successfully, you might write:

    $self->result->message('Posted to your blog');

Actions will default to successful with an empty message if you don't do anything with the result object. Additionally, if you need to return more semantic information than a simple message, you can set arbitrary content on the result, using $self->result->content, e.g:

    $self->result->content( id => $new_post->id);

This information can be then used elsewhere to, for example, automatically redirect you to a view page for that new blog post. The view page template may have the following piece of code in it:

    <%args>
    $id => undef
    </%args>
    <%init>
    my $result = Jifty->web->response->result('post_blog');
    $id = $result->content('id') if $result and !defined $id;
    # load the record by $id and other stuff go here...
   </%init>

where 'post_blog' is the moniker for your post page action object. In fact, that's exactly how actions "return" values to other components in your application.

Multiple action "return values" are possible and arbitrary data structures can be passed too:

    $self->result->content( keys   => $keys );
    $self->result->content( result => $collection);

It should also be mentioned that the response object is "per request". That is, it usually can't live up to another user request. Therefore, when paging mechanism is applied to your view page, for example, you have to either pass some data to the link constructor or explicitly tell Jifty to preserve states for you.

See "monikers", the Jifty Pony site's source, and Jifty::Request::Mapper for some more information.

monikers

If a moniker is unspecified, it will be autogenerated.

(XXX TODO Note about action registration here)

Argument Folding

(XXX TODO Note about "constructor" parameters)