[Jifty-commit] r1638 - in jifty/branches/moose: . lib/Jifty/Manual
lib/Jifty/Param t/Continuations/lib/Continuations/Action
t/Mapper/lib/Mapper/Action t/TestApp/lib/TestApp/Action
jifty-commit at lists.jifty.org
jifty-commit at lists.jifty.org
Fri Jul 21 03:05:26 EDT 2006
Author: audreyt
Date: Fri Jul 21 03:04:21 2006
New Revision: 1638
Modified:
jifty/branches/moose/ (props changed)
jifty/branches/moose/META.yml
jifty/branches/moose/Makefile.PL
jifty/branches/moose/lib/Jifty/Action.pm
jifty/branches/moose/lib/Jifty/Manual/Actions.pod
jifty/branches/moose/lib/Jifty/Manual/Glossary.pod
jifty/branches/moose/lib/Jifty/Param/Schema.pm
jifty/branches/moose/t/Continuations/lib/Continuations/Action/CrossBridge.pm
jifty/branches/moose/t/Mapper/lib/Mapper/Action/CrossBridge.pm
jifty/branches/moose/t/TestApp/lib/TestApp/Action/DoSomething.pm
Log:
r16465 at T (orig r1634): audreyt | 2006-07-21 01:52:37 -0400
* 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.
r16466 at T (orig r1635): audreyt | 2006-07-21 02:50:59 -0400
* Introduce aliases. See Jifty::Param::Schema for the table.
r16468 at T (orig r1637): audreyt | 2006-07-21 03:02:56 -0400
* Jifty::Manual::Actions -- update the worldview to reflect the
parameters/arguments concept split.
Modified: jifty/branches/moose/META.yml
==============================================================================
--- jifty/branches/moose/META.yml (original)
+++ jifty/branches/moose/META.yml Fri Jul 21 03:04:21 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.13
+ 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/branches/moose/Makefile.PL
==============================================================================
--- jifty/branches/moose/Makefile.PL (original)
+++ jifty/branches/moose/Makefile.PL Fri Jul 21 03:04:21 2006
@@ -43,11 +43,12 @@
requires('Module::Install::Admin' => '0.50');
requires('Module::Pluggable' => '2.95');
requires('Module::Refresh' => '0.09');
-requires('Moose' => '0.11');
-requires('Object::Declare' => '0.05');
+requires('Module::ScanDeps');
+requires('Object::Declare' => '0.13');
+requires('PAR::Dist::FromCPAN');
requires('Params::Validate');
requires('Pod::Simple'); #Pod::Simple::Text
-requires('Scalar::Defer');
+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/branches/moose/lib/Jifty/Action.pm
==============================================================================
--- jifty/branches/moose/lib/Jifty/Action.pm (original)
+++ jifty/branches/moose/lib/Jifty/Action.pm Fri Jul 21 03:04:21 2006
@@ -28,6 +28,7 @@
no Moose;
__PACKAGE__->mk_classdata(qw/PARAMS/);
+__PACKAGE__->mk_classdata(qw/PARAMS/);
=head1 COMMON METHODS
@@ -112,11 +113,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
@@ -144,22 +142,6 @@
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.
-
-=back
=cut
@@ -367,6 +349,9 @@
$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}
@@ -851,21 +836,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/branches/moose/lib/Jifty/Manual/Actions.pod
==============================================================================
--- jifty/branches/moose/lib/Jifty/Manual/Actions.pod (original)
+++ jifty/branches/moose/lib/Jifty/Manual/Actions.pod Fri Jul 21 03:04:21 2006
@@ -4,13 +4,14 @@
=head1 DESCRIPTION
-C<Jifty::Action> abstracts around the idea of taking named inputs
-(L<"arguments"|Jifty::Manual::Glossary/argument>), doing something
-with them, and returning some result to the user. If this sounds
-incredibly general, that's because it is -- actions do nearly
-B<everything> in Jifty.
+C<Jifty::Action> abstracts around the idea of declaring named
+(L<"parameters"|Jifty::Manual::Glossary/parameter>) at compile time.
+At runtime, the action collects user input as
+(L<"arguments"|Jifty::Manual::Glossary/argument>), do something with them,
+and returning some result to the user. If this sounds incredibly
+general, that's because it is -- actions do nearly B<everything> in Jifty.
-C<Jifty::Action> will also generate HTML for you for its arguments --
+C<Jifty::Action> will also generate HTML for you from its parameters --
no more manually writing C<< <input> >> tags and extracting GET and
POST arguments by hand and dispatching them where they belong --
C<Jifty::Action>> does it all for you.
@@ -47,80 +48,76 @@
you. )
However, if you want to actually do something with your actions, you
-need to define two things: their L<arguments|/arguments>, and a
+need to define two things: their L<parameters|/parameters>, and a
L</take_action> method.
-=head2 arguments
+=head2 parameters
-Every C<Jifty::Action> subclass should define a C<sub arguments> that
-returns a hashref describing what arguments it takes. Supposing we
-were writing a an action to post a blog article, we might start out
-with arguments like thus:
+Every C<Jifty::Action> subclass should define a C<schema>, which contains
+some C<param> declarations that describes what arguments it takes.
+Supposing we were writing a an action to post a blog article, we might start
+out with parameters like thus:
+ use Jifty::Param::Schema;
+ use Jifty::Action schema {
- sub arguments {
- my $self = shift;
- return { title => {},
- category => {},
- body => {} };
- }
+ param 'title';
+ param 'category';
+ param 'body';
+
+ };
However, we've only scratched the surface of the power the
-C<arguments> API offers. Arguments (can) have types, labels,
+C<param> API offers. Parameters can have types, labels,
validators, canonicalizers, and even more. To start with, lets add
some types and labels:
- sub arguments {
- my $self = shift;
- return {
- title => {
- label => "Title",
- length => 50,
- mandatory => 1,
- },
- category => {
- label => "Category",
- length => 30,
- },
- body => {
- label => "Entry",
- render_as => 'Textarea',
- }
- };
- }
+ use Jifty::Param::Schema;
+ use Jifty::Action schema {
+
+ param title =>
+ label is 'Title',
+ length is 50,
+ is mandatory;
+
+ param category =>
+ label is 'Category',
+ 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:
- ...
- category => {
- label => "Category",
- render_as => "Combobox",
- available_values => ["Personal", "Work", "Blog"]
- },
- ...
+ # ...
+ 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:
- ...
- my $categories = MyBlog::Model::CategoryCollection->new();
- $categories->unlimit;
-
- ...
- category => {
- label => "Category",
- render_as => "Select",
- available_values => [
- {
- display_from => 'name',
- value_from => 'name',
- collection => $categories
- }
- ]
- },
+ # ...
+ 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 combox with the result of calling C<name>
@@ -131,7 +128,8 @@
text field.
See L<Jifty::Action> and L<Jifty::Web::Form::Field> for more fields
-you can set in the returned C<arguments> hash.
+you can set in the C<param> declaration, and see L<Jifty::Param::Schema>
+for more about the syntax.
=head3 validation
@@ -294,7 +292,7 @@
provides a way to do, e.g. a C<BulkEdit> action that applies some set
of changes to many records at once.
-(XXX TODO Note about C<constructor> arguments)
+(XXX TODO Note about C<constructor> parameters)
=head1 ACTIONS AS WEB SERVICES
Modified: jifty/branches/moose/lib/Jifty/Manual/Glossary.pod
==============================================================================
--- jifty/branches/moose/lib/Jifty/Manual/Glossary.pod (original)
+++ jifty/branches/moose/lib/Jifty/Manual/Glossary.pod Fri Jul 21 03:04:21 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
Modified: jifty/branches/moose/lib/Jifty/Param/Schema.pm
==============================================================================
--- jifty/branches/moose/lib/Jifty/Param/Schema.pm (original)
+++ jifty/branches/moose/lib/Jifty/Param/Schema.pm Fri Jul 21 03:04:21 2006
@@ -1,30 +1,126 @@
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 ALIASES
+
+In addition to the labels provided by L<Jifty::Web::Form::Field> and
+L<Jifty::Param>, this module offers the following aliases:
+
+ ajax validates, # ajax_validates is 1
+ ajax canonicalizes, # ajax_canonicalizes is 1
+ order is -1, # sort_order is -1
+ default is 0, # default_value is 0
+ valid are qw( 1 2 3 ), # valid_values are qw( 1 2 3 )
+ available are qw( 1 2 3 ), # available_values are qw( 1 2 3 )
+ render as 'select', # render_as is 'select'
+
+=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 ['Jifty::Param'];
+use Object::Declare (
+ mapping => {
+ param => 'Jifty::Param',
+ },
+ aliases => {
+ default => 'default_value',
+ available => 'available_values',
+ valid => 'valid_values',
+ render => 'render_as',
+ order => 'sort_order',
+ },
+ copula => {
+ is => '',
+ are => '',
+ as => '',
+ ajax => 'ajax_',
+ }
+);
use Exporter::Lite;
use Class::Data::Inheritable;
-our @EXPORT = qw( defer lazy param schema from );
+our @EXPORT = qw( defer lazy param schema );
sub schema (&) {
my $code = shift;
my $from = caller;
no warnings 'redefine';
- local *_ = sub {
- my $args = \@_;
- defer { local *_; Jifty::I18N->new; _(@$args) };
- };
+ local *_ = sub { my $args = \@_; defer { _(@$args) } };
Class::Data::Inheritable::mk_classdata($from => qw/PARAMS/);
my @params = &declare($code);
- my $count = 100; # arbitrary number
+ my $count = 1; # Start at 1, increment by 10
foreach my $param (@params) {
- $param->sort_order($count++) if ref($param) and !defined($param->sort_order);
+ 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';
Modified: jifty/branches/moose/t/Continuations/lib/Continuations/Action/CrossBridge.pm
==============================================================================
--- jifty/branches/moose/t/Continuations/lib/Continuations/Action/CrossBridge.pm (original)
+++ jifty/branches/moose/t/Continuations/lib/Continuations/Action/CrossBridge.pm Fri Jul 21 03:04:21 2006
@@ -5,7 +5,7 @@
param 'name';
param 'quest';
-param 'colour' => valid_values are ("Blue, I mean greeeeeen!", "Green");
+param 'colour' => valid are ("Blue, I mean greeeeeen!", "Green");
};
Modified: jifty/branches/moose/t/Mapper/lib/Mapper/Action/CrossBridge.pm
==============================================================================
--- jifty/branches/moose/t/Mapper/lib/Mapper/Action/CrossBridge.pm (original)
+++ jifty/branches/moose/t/Mapper/lib/Mapper/Action/CrossBridge.pm Fri Jul 21 03:04:21 2006
@@ -3,9 +3,9 @@
use Jifty::Param::Schema;
use Jifty::Action schema {
-param name => default_value is 'something';
+param name => default is 'something';
param 'quest';
-param colour => valid_values are ("Blue, I mean greeeeeen!", "Green");
+param colour => valid are ("Blue, I mean greeeeeen!", "Green");
};
Modified: jifty/branches/moose/t/TestApp/lib/TestApp/Action/DoSomething.pm
==============================================================================
--- jifty/branches/moose/t/TestApp/lib/TestApp/Action/DoSomething.pm (original)
+++ jifty/branches/moose/t/TestApp/lib/TestApp/Action/DoSomething.pm Fri Jul 21 03:04:21 2006
@@ -5,8 +5,8 @@
param email =>
label is 'Email',
- is ajax_canonicalizes,
- is ajax_validates;
+ ajax canonicalizes,
+ ajax validates;
};
More information about the Jifty-commit
mailing list