[Jifty-commit] r2816 - in jifty/branches/virtual-models: . lib/Jifty lib/Jifty/Action lib/Jifty/Script

jifty-commit at lists.jifty.org jifty-commit at lists.jifty.org
Thu Feb 22 11:57:07 EST 2007


Author: audreyt
Date: Thu Feb 22 11:57:07 2007
New Revision: 2816

Modified:
   jifty/branches/virtual-models/   (props changed)
   jifty/branches/virtual-models/Makefile.PL
   jifty/branches/virtual-models/lib/Jifty.pm
   jifty/branches/virtual-models/lib/Jifty/API.pm
   jifty/branches/virtual-models/lib/Jifty/Action.pm
   jifty/branches/virtual-models/lib/Jifty/Action/Autocomplete.pm
   jifty/branches/virtual-models/lib/Jifty/Action/Record.pm
   jifty/branches/virtual-models/lib/Jifty/ClassLoader.pm
   jifty/branches/virtual-models/lib/Jifty/Script/Schema.pm
   jifty/branches/virtual-models/lib/Jifty/Test.pm
   jifty/branches/virtual-models/lib/Jifty/Web.pm

Log:
* Merge from trunk to V-M branch; no test results affected.

Modified: jifty/branches/virtual-models/Makefile.PL
==============================================================================

Modified: jifty/branches/virtual-models/lib/Jifty.pm
==============================================================================
--- jifty/branches/virtual-models/lib/Jifty.pm	(original)
+++ jifty/branches/virtual-models/lib/Jifty.pm	Thu Feb 22 11:57:07 2007
@@ -429,11 +429,6 @@
 }
 
 
-=head1 LICENSE
-
-Jifty is Copyright 2005-2006 Best Practical Solutions, LLC.
-Jifty is distributed under the same terms as Perl itself.
-
 =head1 SEE ALSO
 
 L<http://jifty.org>, L<Jifty::Manual::Tutorial>, L<Jifty::Everything>, L<Jifty::Config>, L<Jifty::Handle>, L<Jifty::Logger>, L<Jifty::Handler>, L<Jifty::Web>, L<Jifty::API>, L<Jifty::Subs>, L<IPC::PubSub>, L<Jifty::Plugin>, L<Jifty::ClassLoader>
@@ -442,6 +437,12 @@
 
 Jesse Vincent, Alex Vandiver and David Glasser.
 
+=head1 LICENSE
+
+Jifty is Copyright 2005-2006 Best Practical Solutions, LLC.
+Jifty is distributed under the same terms as Perl itself.
+
+
 
 =cut
 

Modified: jifty/branches/virtual-models/lib/Jifty/API.pm
==============================================================================
--- jifty/branches/virtual-models/lib/Jifty/API.pm	(original)
+++ jifty/branches/virtual-models/lib/Jifty/API.pm	Thu Feb 22 11:57:07 2007
@@ -10,17 +10,8 @@
 
 =head1 SYNOPSIS
 
- # A nice way to run actions in your application
+ # Find the full name of an action
  my $class = Jifty->api->qualify('SomeAction');
- $class->require;
- $action = $class->new(
-     moniker  => 'my_action',
-     argument => {
-         foo => 1,
-         bar => 'baz',
-     },
- );
- $action->run;
 
  # Logged users with an ID greater than 10 have restrictions
  if (Jifty->web->current_user->id > 10) {

Modified: jifty/branches/virtual-models/lib/Jifty/Action.pm
==============================================================================
--- jifty/branches/virtual-models/lib/Jifty/Action.pm	(original)
+++ jifty/branches/virtual-models/lib/Jifty/Action.pm	Thu Feb 22 11:57:07 2007
@@ -51,18 +51,20 @@
 
 =head1 COMMON METHODS
 
-These common methods are designed to 
+These common methods provide the basic guts for the action.
 
 =head2 new 
 
-Construct a new action.  Subclasses who need do custom initialization
-should start with:
+B<Do not call this directly>; always go through C<< Jifty->web->new_action >>! 
 
-    my $class = shift; my $self = $class->SUPER::new(@_)
+This method constructs a new action. Subclasses who need do custom initialization should start with:
 
-B<Do not call this yourself>; always go through C<<
-Jifty->web->new_action >>!  The arguments that this will be
-called with include:
+    my $class = shift;
+    my $self = $class->SUPER::new(@_)
+
+The arguments that this will be called with include:
+
+=head3 Arguments
 
 =over
 
@@ -1045,7 +1047,7 @@
 Used to report a warning during validation.  Inside a validator you
 should write:
 
-  return $self->validation_warning( $field => "warning");
+  return $self->validation_warning( $field => _("warning"));
 
 ..where C<$field> is the name of the argument which is at fault.
 
@@ -1085,7 +1087,7 @@
 Used to send an informational message to the user from the canonicalizer.  
 Inside a canonicalizer you can write:
 
-  $self->canonicalization_note( $field => "I changed $field for you");
+  $self->canonicalization_note( $field => _("I changed $field for you"));
 
 ..where C<$field> is the name of the argument which the canonicalizer is 
 processing
@@ -1108,8 +1110,108 @@
 Autogenerated Actions will always return true when this method is called. 
 "Regular" actions will return false.
 
+=head1 CUSTOMIZATION
+
+=head2 Canonicalization
+
+If you wish to have the data in a field normalized into a particular format (such as changing a date into YYYY-MM-DD format, adding commas to numbers, capitalizing words, or whatever you need) you can do so using a canonicalizer. 
+
+This is just a method titled C<canonicalize_FIELD> where C<FIELD> is the name of the field be normalized. Here is an example:
+
+  sub canonicalize_foo {
+      my ($self, $value) = @_;
+
+      # do something to canonicalize the value
+      my $normal_form = lc($value);
+      
+      return $normal_form;
+  }
+
+In this case, all values in the "foo" field will be changed into lower case.
+
+While doing this you might also want to call the L</canonicalization_note> to inform the client of the modification:
+
+  my $normal_form = lc($value);
+  $self->canonicalization_note( 
+      foo => _('Foo values are always in lowercase.'));
+
+If the "foo" field has "ajax canoncalizes" set in the action schema, then this process will be performed automatically as the form is being filled without reloading the page.
+
+=head2 Validation
+
+If a value must follow a certain format, you can provide a validation method for fields to make sure that no value enters the database until it is in a valid form.
+
+A validation method is one named C<validate_FIELD> where C<FIELD> is the name of the field being checked. Here is an example:
+
+  sub validate_foo {
+      my ($self, $value) = @_;
+
+      # Check for uppercase letters
+      if ($value =~ /\p{Lu}/) {
+          return $self->validation_warning(
+              foo => _("Foo cannot contain uppercase letters."));
+      }
+
+      # Check for -, *, +, and ?
+      elsif ($value =~ /[\-\*\+\?]/) {
+          return $self->validation_error(
+              foo => _("Foo cannot contain -, *, +, or ?."));
+      }
+
+      return 1;
+  }
+
+Here the "foo" field should not contain uppercase letters and must not contain the characters '-', '*', '+', or '?'. You can use L</validation_error> and L</validation_warning> to return the results of your validation to the user or simply return 1 to indicate a valid value.
+
+If you just have a list of valid values, you may want to use the C<valid_values> schema parameter to perform this task instead.
+
+=head2 Autocompletion
+
+Autocompletion provides a way of suggesting choices to the client based upon partial data entry. This doesn't necessarily force the client to use one of the choices given but gives hints in an application specific way.
+
+To create an autocompletion field, you implement a method named C<autocomplete_FIELD> where C<FIELD> is the field to autocomplete. This is generally done with fields rendered as 'Text'. Here is an example:
+
+  sub autocomplete_foo {
+      my ($self, $value) = @_;
+
+      # Be careful to validate your input! You don't want a malicious user
+      # hacking your system.
+      my ($match_value) = $value =~ /^(\w+)$/;
+
+      my $foos = MyApp::Model::FooCollection->new;
+      $foos->limit(
+          column   => 'name',
+          operator => 'LIKE',
+          value    => '%$value%',
+      );
+
+      return map { $_->name } @{ $foos->item_array_ref };
+  }
+
+In this example, the "foo" field is autocompleted from names matched from the C<MyApp::Model::Foo> table. The match, in this case, matches any substring found in the database. I could have matched any item that starts with the string, ends with the string, matches other fields than the one returned, etc. It's up to you to decide.
+
+Note also that I have untainted the value coming in to make sure a malicious user doesn't get anyway. You should always perform a check like this when data is coming in from an outside source.
+
+If you need a more complicated solution, you can return the autocompletion values as a list of hash references containing the keys C<value> and (optionally) C<label>:
+
+  return map { { value => $_->name, label => $_->label } }
+            @{ $foos->item_array_ref };
+
+In this case, the labels will be shown to the client, but the selected value would be returned to your application.
+
 =cut
 
 sub autogenerated {0}
 
+=head1 SEE ALSO
+
+L<Jifty>, L<Jifty::API>, L<Jifty::Action::Record>, L<Jifty::Result>, L<Jifty::Param::Schema>, L<Jifty::Manual::Actions>
+
+=head1 LICENSE
+
+Jifty is Copyright 2005-2006 Best Practical Solutions, LLC.
+Jifty is distributed under the same terms as Perl itself.
+
+=cut
+
 1;

Modified: jifty/branches/virtual-models/lib/Jifty/Action/Autocomplete.pm
==============================================================================
--- jifty/branches/virtual-models/lib/Jifty/Action/Autocomplete.pm	(original)
+++ jifty/branches/virtual-models/lib/Jifty/Action/Autocomplete.pm	Thu Feb 22 11:57:07 2007
@@ -3,7 +3,7 @@
 
 =head1 NAME
 
-Jifty::Action::Autocomplete
+Jifty::Action::Autocomplete - An action for making autocompletion suggestions
 
 =head1 DESCRIPTION
 
@@ -71,5 +71,16 @@
     return 1;
 }
 
+=head1 SEE ALSO
+
+L<Jifty::Action>
+
+=head1 LICENSE
+
+Jifty is Copyright 2005-2006 Best Practical Solutions, LLC.
+Jifty is distributed under the same terms as Perl itself.
+
+=cut
+
 1;
 

Modified: jifty/branches/virtual-models/lib/Jifty/Action/Record.pm
==============================================================================
--- jifty/branches/virtual-models/lib/Jifty/Action/Record.pm	(original)
+++ jifty/branches/virtual-models/lib/Jifty/Action/Record.pm	Thu Feb 22 11:57:07 2007
@@ -11,8 +11,9 @@
 
 Represents a web-based action that is a create, update, or delete of a
 L<Jifty::Record> object.  This automatically populates the arguments
-method of L<Jifty::Action> so that you don't need to bother.  To
-actually use this class, you probably want to inherit from one of
+method of L<Jifty::Action> so that you don't need to bother.  
+
+To actually use this class, you probably want to inherit from one of
 L<Jifty::Action::Record::Create>, L<Jifty::Action::Record::Update>, or
 L<Jifty::Action::Record::Delete> and override the C<record_class>
 method.
@@ -392,7 +393,13 @@
 =head1 SEE ALSO
 
 L<Jifty::Action>, L<Jifty::Record>, L<Jifty::DBI::Record>,
-L<Jifty::Action::Record::Create>, L<Jifty::Action::Record::Update>
+L<Jifty::Action::Record::Create>, L<Jifty::Action::Record::Update>,
+L<Jifty::Action::Reocrd::Delete>
+
+=head1 LICENSE
+
+Jifty is Copyright 2005-2006 Best Practical Solutions, LLC.
+Jifty is distributed under the same terms as Perl itself.
 
 =cut
 

Modified: jifty/branches/virtual-models/lib/Jifty/ClassLoader.pm
==============================================================================

Modified: jifty/branches/virtual-models/lib/Jifty/Script/Schema.pm
==============================================================================

Modified: jifty/branches/virtual-models/lib/Jifty/Test.pm
==============================================================================
--- jifty/branches/virtual-models/lib/Jifty/Test.pm	(original)
+++ jifty/branches/virtual-models/lib/Jifty/Test.pm	Thu Feb 22 11:57:07 2007
@@ -403,7 +403,7 @@
         # Disconnect the PubSub bus, if need be; otherwise we may not
         # be able to drop the testing database
         Jifty->bus->disconnect
-          if Jifty->bus;
+          if Jifty->config and Jifty->bus;
 
         # Remove testing db
         if (Jifty->handle) {

Modified: jifty/branches/virtual-models/lib/Jifty/Web.pm
==============================================================================
--- jifty/branches/virtual-models/lib/Jifty/Web.pm	(original)
+++ jifty/branches/virtual-models/lib/Jifty/Web.pm	Thu Feb 22 11:57:07 2007
@@ -401,25 +401,39 @@
 
 =head3 new_action class => CLASS, moniker => MONIKER, order => ORDER, arguments => PARAMHASH
 
-Creates a new action (an instance of a subclass of L<Jifty::Action>)
+Creates a new action (an instance of a subclass of L<Jifty::Action>). The named arguments passed to this method are passed on to the C<new> method of the action named in C<CLASS>.
+
+=head3 Arguments
+
+=over
+
+=item class 
 
 C<CLASS> is L<qualified|Jifty::API/qualify>, and an instance of that
 class is created, passing the C<Jifty::Web> object, the C<MONIKER>,
 and any other arguments that C<new_action> was supplied.
 
+=item moniker
+
 C<MONIKER> is a unique designator of an action on a page.  The moniker
 is content-free and non-fattening, and may be auto-generated.  It is
 used to tie together arguments that relate to the same action.
 
+=item order
+
 C<ORDER> defines the order in which the action is run, with lower
 numerical values running first.
 
+=item arguments
+
 C<ARGUMENTS> are passed to the L<Jifty::Action/new> method.  In
 addition, if the current request (C<< $self->request >>) contains an
 action with a matching moniker, any arguments that are in that
 requested action but not in the C<PARAMHASH> list are set.  This
 implements "sticky fields".
 
+=back
+
 As a contrast to L<Jifty::Web::Form/add_action>, this does not add the
 action to the current form -- instead, the first form field to be
 rendered will automatically register the action in the current form


More information about the Jifty-commit mailing list