[Jifty-commit] r502 - Jifty-DBI/trunk/lib/Jifty/DBI
jifty-commit at lists.jifty.org
jifty-commit at lists.jifty.org
Sat Jan 14 12:19:22 EST 2006
Author: jesse
Date: Sat Jan 14 12:19:19 2006
New Revision: 502
Modified:
/ (props changed)
Jifty-DBI/trunk/Changes
Jifty-DBI/trunk/lib/Jifty/DBI/Record.pm
Log:
r22389 at truegrounds: jesse | 2006-01-14 12:17:14 -0500
* Updated docs to document hooks. I guess we're stuck with them now.
Modified: Jifty-DBI/trunk/Changes
==============================================================================
--- Jifty-DBI/trunk/Changes (original)
+++ Jifty-DBI/trunk/Changes Sat Jan 14 12:19:19 2006
@@ -1,5 +1,7 @@
Revision history for Perl extension Jifty::DBI.
+* Updated record docs to show hooks
+
0.09 Thu Dec 29 07:56:30 EST 2005
* Fixed dependency on Class::Data::Inheritable
Modified: Jifty-DBI/trunk/lib/Jifty/DBI/Record.pm
==============================================================================
--- Jifty-DBI/trunk/lib/Jifty/DBI/Record.pm (original)
+++ Jifty-DBI/trunk/lib/Jifty/DBI/Record.pm Sat Jan 14 12:19:19 2006
@@ -372,6 +372,87 @@
return sort map { $_->name } grep { $_->writable } $self->columns;
}
+
+=head2 record values
+
+As you've probably already noticed, C<Jifty::DBI::Record> autocreates methods for your
+standard get/set accessors. It also provides you with some hooks to massage the values
+being loaded or stored.
+
+When you fetch a record value by calling C<$my_record->some_field>, C<Jifty::DBI::Record>
+provides the following hook
+
+=over
+
+
+
+=item after_I<column_name>
+
+This hook is called with a reference to the value returned by Jifty::DBI. Its return value is discarded.
+
+=back
+
+When you set a value, C<Jifty::DBI> provides the following hooks
+
+=over
+
+=item before_set_I<column_name> PARAMHASH
+
+C<Jifty::DBI::Record> passes this function a reference to a paramhash composed of:
+
+=over
+
+=item column
+
+The name of the column we're updating.
+
+=item value
+
+The new value for I<column>.
+
+=item is_sql_function
+
+A boolean that, if true, indicates that I<value> is an SQL function, not just a value.
+
+=back
+
+If before_set_I<column_name> returns false, the new value isn't set.
+
+=item validate_I<column_name> VALUE
+
+This hook is called just before updating the database. It expects the
+actual new value you're trying to set I<column_name> to. It returns
+two values. The first is a boolean with truth indicating success. The
+second is an optional message. Note that validate_I<column_name> may be
+called outside the context of a I<set> operation to validate a potential
+value. (The Jifty application framework uses this as part of its AJAX
+validation system.)
+
+
+=back
+
+
+=cut
+
+=head2 _value
+
+_value takes a single column name and returns that column's value for
+this row. Subclasses can override _value to insert custom access
+control.
+
+=cut
+
+sub _value {
+ my $self = shift;
+ my $column = shift;
+
+ my $value = $self->__value( $column => @_ );
+ my $method = "after_$column";
+ $self->$method( \$value ) if ( $self->can($method) );
+ return $value;
+}
+
+
=head2 __value
Takes a column name and returns that column's value. Subclasses should
@@ -423,24 +504,6 @@
return $self->{'values'}{ $column->name };
}
-=head2 _value
-
-_value takes a single column name and returns that column's value for
-this row. Subclasses can override _value to insert custom access
-control.
-
-=cut
-
-sub _value {
- my $self = shift;
- my $column = shift;
-
- my $value = $self->__value( $column => @_ );
- my $method = "after_$column";
- $self->$method( \$value ) if ( $self->can($method) );
- return $value;
-}
-
=head2 _set
_set takes a single column name and a single unquoted value.
@@ -459,8 +522,11 @@
);
my $method = "before_set_" . $args{column};
- $self->$method( \%args ) if ( $self->can($method) );
-
+ if ( $self->can($method) ) {
+ my $before_set_ret = $self->$method( \%args );
+ return $before_set_ret
+ unless ($before_set_ret);
+ }
return $self->__set(%args);
}
@@ -574,7 +640,7 @@
return ( $ret->return_value );
}
-=head2 _Validate column VALUE
+=head2 _validate column VALUE
Validate that value will be an acceptable value for column.
@@ -745,14 +811,31 @@
foreach my $f ( keys %{ $self->{'values'} } ) {
$self->{'fetched'}{ lc $f } = 1;
}
- return ( 1, "Found Object" );
+ return ( 1, "Found object" );
}
-=head2 create
+=head2 create PARAMHASH
+
+This method creates a new record with the values specified in the PARAMHASH.
+
+Keys that aren't known as columns for this record type are dropped.
+
+This method calls two hooks in your subclass:
+
+=over
+
+=item before_create
+
+This method is called before trying to create our row in the database. It's handed a reference to your paramhash. (That means it can modify your parameters on the fly). C<before_create> returns a true or false value. If it returns false, the create is aborted.
+
+=item after_create
+
+This method is called after attempting to insert the record into the database. It gets handed a reference to the return value of the insert. That'll either be a true value or a L<Class::ReturnValue>
+
+
+=back
-Takes an array of key-value pairs and drops any keys that aren't known
-as columns for this recordtype
=cut
@@ -760,7 +843,10 @@
my $self = shift;
my %attribs = @_;
- $self->before_create( \%attribs ) if $self->can('before_create');
+ if ($self->can('before_create')) {
+ my $before_ret = $self->before_create( \%attribs ) ;
+ return ($before_ret) unless ($before_ret);
+ }
foreach my $column_name ( keys %attribs ) {
my $column = $self->column($column_name);
@@ -796,7 +882,7 @@
}
}
my $ret = $self->_handle->insert( $self->table, %attribs );
- $self->after_create($ret) if $self->can('after_create');
+ $self->after_create(\$ret) if $self->can('after_create');
return ($ret);
}
@@ -805,11 +891,29 @@
Delete this record from the database. On failure return a
Class::ReturnValue with the error. On success, return 1;
+This method has two hooks
+
+=over
+
+=item before_delete
+
+This method is called before the record deletion, if it exists. It returns a boolean value. If the return value is false, it aborts the create and returns the return value from the hook.
+
+=item after_delete
+
+This method is called after deletion, with a reference to the return value
+from the delete operation.
+
+=back
+
=cut
sub delete {
my $self = shift;
- $self->before_delete() if $self->can('before_delete');
+ if ($self->can('before_delete')) {
+ my $before_ret = $self->before_delete();
+ return $before_ret unless ($before_ret);
+ }
my $ret = $self->__delete;
$self->after_delete( \$ret ) if $self->can('after_delete');
return ($ret);
@@ -975,11 +1079,13 @@
=head1 AUTHOR
-Jesse Vincent, <jesse at fsck.com>
+Jesse Vincent <jesse at bestpractical.com>, Alex Vandiver <alexmv at bestpractical.com>, David Glasser <glasser at bestpractical.com>, Ruslan Zakirov <ruslan.zakirov at gmail.com>
-Enhancements by Ivan Kohler, <ivan-rt at 420.am>
+Based on DBIx::SearchBuilder::Record, whose credits read:
-Docs by Matt Knopp <mhat at netlag.com>
+ Jesse Vincent, <jesse at fsck.com>
+ Enhancements by Ivan Kohler, <ivan-rt at 420.am>
+ Docs by Matt Knopp <mhat at netlag.com>
=head1 SEE ALSO
More information about the Jifty-commit
mailing list