view release on metacpan or  search on metacpan

lib/Jifty/Manual/Actions_zhtw.pod  view on Meta::CPAN

    use strict;

    package MyApp::Action::DoNothing;
    use base qw/MyApp::Action Jifty::Action/;

    1;

(Instead of copying-and-pasting that, or typing it in, though, you
could just run:

    jifty action --name DoNothing

in your application's directory, and Jifty would create a skeleton for
you. )

However, if you want to actually do something with your actions, you
need to define two things: their L<parameters|/parameters>, and a
L</take_action> method.

=head2 parameters

Every C<Jifty::Action> subclass should define a C<schema>, which contains
some C<param> declarations that describe what arguments it takes.
Supposing we were writing an action to post a blog article, we might start
out with parameters like thus:

    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
C<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 C<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 C<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 C<name>
on each element in C<$categories>. Alternatively, if you set
C<< value_from => 'id' >>, Jifty would automatically return the C<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 L<Jifty::Action> and L<Jifty::Web::Form::Field> for more fields
you can set in the C<param> declaration, and see L<Jifty::Param::Schema>
for more about the syntax.

=head2 validation

C<Jifty::Action> can automatically validate arguments for you, as
appropriate. If an argument has C<valid_values>, then C<Jifty::Action>
will automatically verify if the given value matches one of
them. However, you can also write your own validators. Just write a
C<< sub validate_<parameter> >>, and it will be called as appropriate:

    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');
    }

You can also do validation in the model -- see
L<Jifty::Action::Record> 

=head2 canonicalization

If, instead of failing, you want to automatically modify
invalid content to be valid, you want a
L<canonicalizer|Jifty::Manual::Glossary/canonicalize>, not a
validator.

    use Regexp::Common 'profanity_us';

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

A L<canonicalizer|Jifty::Manual::Glossary/canonicalize> can also 
change other parts of the action.  This lets you update the display
dynamically in an L<AJAX|Jifty::Manual::Glossary/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 C<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]",