[Jifty-commit] r1634 - in jifty/trunk: . lib/Jifty lib/Jifty/Manual lib/Jifty/Param t/Continuations/lib/Continuations/Action t/TestApp/lib/TestApp/Action

jifty-commit at lists.jifty.org jifty-commit at lists.jifty.org
Fri Jul 21 01:52:39 EDT 2006


Author: audreyt
Date: Fri Jul 21 01:52:37 2006
New Revision: 1634

Added:
   jifty/trunk/lib/Jifty/Param/
   jifty/trunk/lib/Jifty/Param/Schema.pm
Modified:
   jifty/trunk/META.yml
   jifty/trunk/Makefile.PL
   jifty/trunk/lib/Jifty/Action.pm
   jifty/trunk/lib/Jifty/Manual/Glossary.pod
   jifty/trunk/t/Continuations/lib/Continuations/Action/CrossBridge.pm
   jifty/trunk/t/Mapper/lib/Mapper/Action/CrossBridge.pm
   jifty/trunk/t/TestApp/lib/TestApp/Action/DoSomething.pm

Log:
* Declarative Jifty Parameters.
* See Jifty::Param and Jifty::Param::Schema for the new syntax.
* Also added dependencies for Jifty::Script::Deps and declarative parameters.
* Also updated test applications to use declarative parameters. 

Modified: jifty/trunk/META.yml
==============================================================================
--- jifty/trunk/META.yml	(original)
+++ jifty/trunk/META.yml	Fri Jul 21 01:52:37 2006
@@ -31,6 +31,7 @@
   Email::Send: 1.99_01
   Email::Simple: 0
   Email::Simple::Creator: 0
+  Exporter::Lite: 0
   File::Find::Rule: 0
   File::MMagic: 0
   File::ShareDir: 0
@@ -43,7 +44,7 @@
   HTTP::Server::Simple::Recorder: 0
   Hash::Merge: 0
   Hook::LexWrap: 0
-  JSON::Syck: 0.13
+  JSON::Syck: 0.14
   Jifty::DBI: 0.21
   LWP::UserAgent: 0
   Locale::Maketext::Extract: 0.20
@@ -54,8 +55,12 @@
   Module::Install::Admin: 0.50
   Module::Pluggable: 2.95
   Module::Refresh: 0.09
+  Module::ScanDeps: 0
+  Object::Declare: 0.12
+  PAR::Dist::FromCPAN: 0
   Params::Validate: 0
   Pod::Simple: 0
+  Scalar::Defer: 0.06
   String::Koremutake: 0
   Test::Base: 0.44
   Test::HTML::Lint: 0

Modified: jifty/trunk/Makefile.PL
==============================================================================
--- jifty/trunk/Makefile.PL	(original)
+++ jifty/trunk/Makefile.PL	Fri Jul 21 01:52:37 2006
@@ -21,6 +21,7 @@
 requires('Email::Send' => '1.99_01'); # Email::Send::Jifty::Test
 requires('Email::Simple');
 requires('Email::Simple::Creator');
+requires('Exporter::Lite');
 requires('File::Find::Rule');
 requires('File::MMagic');
 requires('File::ShareDir');
@@ -43,8 +44,12 @@
 requires('Module::Install::Admin' => '0.50');
 requires('Module::Pluggable' => '2.95');
 requires('Module::Refresh' => '0.09');
+requires('Module::ScanDeps');
+requires('Object::Declare' => '0.12');
+requires('PAR::Dist::FromCPAN');
 requires('Params::Validate');
 requires('Pod::Simple'); #Pod::Simple::Text
+requires('Scalar::Defer' => '0.06');
 requires('String::Koremutake');
 requires('Test::Base' => 0.44);            # Test::Base::Filter
 requires('Test::HTTP::Server::Simple' => '0.02');

Modified: jifty/trunk/lib/Jifty/Action.pm
==============================================================================
--- jifty/trunk/lib/Jifty/Action.pm	(original)
+++ jifty/trunk/lib/Jifty/Action.pm	Fri Jul 21 01:52:37 2006
@@ -17,9 +17,10 @@
 =cut
 
 
-use base qw/Jifty::Object Class::Accessor::Fast/;
+use base qw/Jifty::Object Class::Accessor::Fast Class::Data::Inheritable/;
 
 __PACKAGE__->mk_accessors(qw(moniker argument_values order result sticky_on_success sticky_on_failure));
+__PACKAGE__->mk_classdata(qw/PARAMS/);
 
 =head1 COMMON METHODS
 
@@ -104,11 +105,8 @@
 
 =head2 arguments
 
-B<Note>: this API is in serious need of rototilling.  Expect it to
-change in the near future, into something probably more declarative,
-like L<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.
+B<Note>: this API is now deprecated in favour of the declarative syntax
+offered by L<Jifty::Action::Schema>.
 
 This method, along with L</take_action>, is the most commonly
 overridden method.  It should return a hash which describes the
@@ -136,36 +134,12 @@
 L<mandatory|Jifty::Manual::Glossary/mandatory> property, which deal with
 requiring that the user enter a value for that field.
 
-See L<Jifty::Web::Form::Field> for the list of possible keys that each
-argument can have.
-
-In addition to the list there, you may use these additional keys:
-
-=over
-
-=item constructor
-
-A boolean which, if set, indicates that the argument B<must> be
-present in the C<arguments> passed to create the action, rather than
-being expected to be set later.
-
-Defaults to false.
-
-=item ajax_canonicalizes
-
-This key takes a boolean value that determines if the value displayed in
-the form field is updated via AJAX with the result returned by this argument's
-L<canonicalize|Jifty::Manual::Glossary/canonicalize> function.
-
-Defaults to false.
-
-=back
 
 =cut
 
 sub arguments {
     my  $self= shift;
-    return {}
+    return($self->PARAMS || {});
 }
 
 =head2 run
@@ -367,16 +341,19 @@
         $sticky = 1 if $self->sticky_on_failure and (!Jifty->web->response->result($self->moniker) or $self->result->failure);
         $sticky = 1 if $self->sticky_on_success and (Jifty->web->response->result($self->moniker) and $self->result->success);
 
+        # $sticky can be overrided per-parameter
+        $sticky = $field_info->{sticky} if defined $field_info->{sticky};
+
         if ($field_info) {
             # form_fields overrides stickiness of what the user last entered.
             $self->{_private_form_fields_hash}{$arg_name}
                 = Jifty::Web::Form::Field->new(
+                %$field_info,
                 action       => $self,
                 name         => $args{'argument'},
                 sticky       => $sticky,
                 sticky_value => $self->argument_value($args{'argument'}),
                 render_mode  => $args{'render_mode'},
-                %$field_info,
                 %args
                 );
 
@@ -783,7 +760,7 @@
         {
 
             return $self->validation_error(
-                $field => q{That doesn't look like a correct value} );
+                $field => _("That doesn't look like a correct value") );
         }
 
    # ... but still check through a validator function even if it's in the list
@@ -851,21 +828,12 @@
 
 =head2 valid_values ARGUMENT
 
-Given an L<argument|Jifty::Manual::Glossary/argument> name, returns the list
-of valid values for it, based on its C<valid_values> parameter in the
-L</arguments> list.
-
-If the parameter is not an array ref, just returns it (not sure if
-this is ever OK except for C<undef>).  If it is an array ref, returns
-a new array ref with each element converted into a hash with keys
-C<display> and C<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
-C<display> and C<value> (which are just sent through); hashes with
-C<collection> (a L<Jifty::Collection>), and C<display_from> and
-C<value_from> (the names of methods to call on each record in the
-collection to get C<display> and C<value>); or strings, which are
-treated as both C<display> and C<value>.
+Given an L<parameter|Jifty::Manual::Glossary/parameter> name, returns the
+list of valid values for it, based on its C<valid_values> field.
+
+This method returns a hash referenece with a C<display> field for the string
+to display for the value, and a C<value> field for the value to actually send
+to the server.
 
 (Avoid using this -- this is not the appropriate place for this logic
 to be!)

Modified: jifty/trunk/lib/Jifty/Manual/Glossary.pod
==============================================================================
--- jifty/trunk/lib/Jifty/Manual/Glossary.pod	(original)
+++ jifty/trunk/lib/Jifty/Manual/Glossary.pod	Fri Jul 21 01:52:37 2006
@@ -11,9 +11,10 @@
 =item action
 
 An B<action> is a specifically designed RPC call that can do something to the
-system.  An action takes any number of L</argument>s, which it
-L</canonicalize>s, L</validate>s, and then uses to do something useful.  Each
-action has a L</result>.  See L<Jifty::Action> and L<Jifty::Manual::Actions>.
+system, with any number of declared L</parameter>s.  At runtime, an action
+can take L</argument>s, which it L</canonicalize>s, L</validate>s, and then
+uses to do something useful.  Each action has a L</result>.  See
+L<Jifty::Action> and L<Jifty::Manual::Actions>.
 
 =item active
 
@@ -32,8 +33,8 @@
 
 =item argument
 
-An B<argument> is a named parameter to an L</action>.  Jifty generally renders
-these on the screen as L</form field>s.  See L<Jifty::Action>.
+An B<argument> is a user-supplied input to fill in a L</parameter> in an
+L</action>.  See L<Jifty::Action>.
 
 =item canonicalize
 
@@ -43,8 +44,8 @@
 
 =item constructor
 
-A property of an L</argument>; the action B<must> have a value submitted for
-this argument in order to be constructed.  This is different from
+A property of a L</parameter>; the action B<must> have an argument value for
+this paramater in order to be constructed.  This is different from
 L</mandatory>, in that the user can leave mandatory fields empty.  For
 instance, the C<id> of a L<Jifty::Action::Record::Update> is a constructor.
 See L<Jifty::Action>.
@@ -62,7 +63,7 @@
 =item form field
 
 A widget which the browser renders.  These are generally useful to ask the user
-for a value for a L</argument> to an L</action>.  See
+for a value for an L</argument> to an L</action>.  See
 L<Jifty::Web::Form::Field>.
 
 =item fragment
@@ -84,7 +85,7 @@
 
 =item mandatory
 
-A property of an L</argument>; the user must enter a value for the action to
+A property of a L</parameter>; the user must enter a value for the action to
 validate.  This is the simplest level of L<validation|/validate>.
 
 =item moniker
@@ -96,6 +97,12 @@
 be globally unique, but they must be unique within a single request.
 Monikers have no semantic meaning. See L<Jifty::Action/monikers>
 
+=item parameter
+
+A B<parameter> is a named parameter to an L</action>.  Jifty generally renders
+these on the screen as L</form field>s.  See L<Jifty::Param> and
+L<Jifty::Param::Schema>.
+
 =item region
 
 An area of the page which JavaScript can replace.  The content in the region is
@@ -129,7 +136,7 @@
 
 =item validate
 
-To check that the provided value of a L</argument> is a possible value for it
+To check that the provided value of an L</argument> is a possible value for it
 to have.  See L<Jifty::Web::Form::Field>.
 
 =back

Added: jifty/trunk/lib/Jifty/Param/Schema.pm
==============================================================================
--- (empty file)
+++ jifty/trunk/lib/Jifty/Param/Schema.pm	Fri Jul 21 01:52:37 2006
@@ -0,0 +1,110 @@
+package Jifty::Param::Schema;
+
+=head1 NAME
+
+Jifty::Param::Schema - Declare parameters of a Jifty action with ease.
+
+=head1 SYNOPSIS
+
+    package Wifty::Action::Login;
+    use Jifty::Param::Schema;
+    use Jifty::Action schema {
+
+    param email =>
+        label is 'Email address',
+        is mandatory,
+        ajax validates;
+
+    param password =>
+        type is 'password',
+        label is 'Password',
+        is mandatory;
+
+    param remember =>
+        type is 'checkbox',
+        label is 'Remember me?',
+        hints is 'If you want, your browser can remember your login for you'
+        default is 0;
+
+    };
+
+=head1 DESCRIPTION
+
+This module provides a simple syntax to declare action parameters.
+
+It re-exports C<defer> and C<lazy> from L<Scalar::Defer>, for setting
+parameter fields that must be recomputed at request-time.
+
+=head2 schema
+
+The C<schema> block from a L<Jifty::Action> subclass describes an action
+for a Jifty application.
+
+Within the C<schema> block, the localization function C<_> is redefined
+with C<defer>, so that it resolves into a dynamic value that will be
+recalculated upon each request, according to the user's current language
+preference.
+
+=head2 param
+
+Each C<param> statement inside the C<schema> block sets out the name
+and attributes used to describe one named parameter, which is then used
+to build a L<Jifty::Param> object.  That class defines possible field names
+to use in the declarative syntax here.
+
+The C<param> function is not available outside the C<schema> block.
+
+=head1 SEE ALSO
+
+L<Object::Declare>, L<Scalar::Defer>
+
+=cut
+
+use strict;
+use warnings;
+use Jifty::I18N;
+use Jifty::Param;
+use Scalar::Defer;
+use Object::Declare (
+    mapping => {
+        param => 'Jifty::Param',
+    },
+    copula  => {
+        is      => '',
+        are     => '',
+        ajax    => 'ajax_',
+    }
+);
+use Exporter::Lite;
+use Class::Data::Inheritable;
+
+our @EXPORT = qw( defer lazy param schema );
+
+sub schema (&) {
+    my $code = shift;
+    my $from = caller;
+
+    no warnings 'redefine';
+    local *_ = sub { my $args = \@_; defer { _(@$args) } };
+
+    Class::Data::Inheritable::mk_classdata($from => qw/PARAMS/);
+    my @params = &declare($code);
+    my $count = 1; # Start at 1, increment by 10
+    foreach my $param (@params) {
+        next if !ref($param) or defined($param->sort_order);
+        $param->sort_order($count);
+        $count += 10;
+    }
+
+    if ($from->can('SUPER::PARAMS')) {
+        unshift @params, %{ $from->can('SUPER::PARAMS')->() || {} }
+    }
+
+    $from->PARAMS({ @params });
+
+    no strict 'refs';
+    push @{$from . '::ISA'}, 'Jifty::Action';
+    return;
+}
+
+1;

Modified: jifty/trunk/t/Continuations/lib/Continuations/Action/CrossBridge.pm
==============================================================================
--- jifty/trunk/t/Continuations/lib/Continuations/Action/CrossBridge.pm	(original)
+++ jifty/trunk/t/Continuations/lib/Continuations/Action/CrossBridge.pm	Fri Jul 21 01:52:37 2006
@@ -1,14 +1,13 @@
 package Continuations::Action::CrossBridge;
 
-use base qw/Jifty::Action/;
+use Jifty::Param::Schema;
+use Jifty::Action schema {
 
-sub arguments {
-    {
-        name   => {},
-        quest  => {},
-        colour => {valid_values => ["Blue, I mean greeeeeen!", "Green"]},
-    }
-}
+param 'name';
+param 'quest';
+param 'colour' => valid_values are ("Blue, I mean greeeeeen!", "Green");
+
+};
 
 sub validate_quest {
     my $self = shift;

Modified: jifty/trunk/t/Mapper/lib/Mapper/Action/CrossBridge.pm
==============================================================================
--- jifty/trunk/t/Mapper/lib/Mapper/Action/CrossBridge.pm	(original)
+++ jifty/trunk/t/Mapper/lib/Mapper/Action/CrossBridge.pm	Fri Jul 21 01:52:37 2006
@@ -1,14 +1,13 @@
 package Mapper::Action::CrossBridge;
 
-use base qw/Jifty::Action/;
+use Jifty::Param::Schema;
+use Jifty::Action schema {
 
-sub arguments {
-    {
-        name   => { default_value => "something" },
-        quest  => {},
-        colour => {valid_values => ["Blue, I mean greeeeeen!", "Green"]},
-    }
-}
+param name      => default_value is 'something';
+param 'quest';
+param colour    => valid_values are ("Blue, I mean greeeeeen!", "Green");
+
+};
 
 sub validate_quest {
     my $self = shift;

Modified: jifty/trunk/t/TestApp/lib/TestApp/Action/DoSomething.pm
==============================================================================
--- jifty/trunk/t/TestApp/lib/TestApp/Action/DoSomething.pm	(original)
+++ jifty/trunk/t/TestApp/lib/TestApp/Action/DoSomething.pm	Fri Jul 21 01:52:37 2006
@@ -1,16 +1,14 @@
 package TestApp::Action::DoSomething;
 
-use base qw/Jifty::Action/;
+use Jifty::Param::Schema;
+use Jifty::Action schema {
 
-sub arguments {
-    return({
-        email => {
-            label => 'Email',
-            ajax_canonicalizes => 1,
-            ajax_validates => 1,
-        }
-    });
-}
+param email =>
+    label is 'Email',
+    is ajax_canonicalizes,
+    is ajax_validates;
+
+};
 
 sub canonicalize_email {
     my $self = shift;


More information about the Jifty-commit mailing list