NAME
Jifty::DBI::Record - Superclass for records loaded by Jifty::DBI::Collection
SYNOPSIS
package MyRecord;
use base qw/Jifty::DBI::Record/;
DESCRIPTION
Jifty::DBI::Record encapuslates records and tables as part of the Jifty::DBI object-relational mapper.
METHODS
new
Instantiate a new, empty record object.
id
Returns this row's primary key.
primary_keys
Return a hash of the values of our primary keys for this function.
_parse_autoload_method $AUTOLOAD
Parses autoload methods and attempts to determine if they're set, get or validate calls.
Returns a tuple of (COLUMN_NAME, ACTION);
_accessible COLUMN ATTRIBUTE
Private method.
DEPRECATED
Returns undef unless COLUMN has a true value for ATTRIBUTE.
Otherwise returns COLUMN's value for that attribute.
_primary_keys
Return our primary keys. (Subclasses should override this, but our default is that we have one primary key, named 'id'.)
_init_columns
Sets up the primary key columns.
_to_record COLUMN VALUE
This PRIVATE method takes a column name and a value for that column.
It returns undef unless COLUMN is a valid column for this record that refers to another record class.
If it is valid, this method returns a new record object with an id of VALUE.
add_column
column
readable_attributes
Returns a list this table's readable columns
writable_attributes
Returns a list of this table's writable columns
record values
As you've probably already noticed, 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 $my_record-some_field>, Jifty::DBI::Record provides the following hook
- after_column_name
-
This hook is called with a reference to the value returned by Jifty::DBI. Its return value is discarded.
When you set a value, Jifty::DBI provides the following hooks
- before_set_column_name PARAMHASH
-
Jifty::DBI::Recordpasses this function a reference to a paramhash composed of:- column
-
The name of the column we're updating.
- value
-
The new value for column.
- is_sql_function
-
A boolean that, if true, indicates that value is an SQL function, not just a value.
If before_set_column_name returns false, the new value isn't set.
- validate_column_name VALUE
-
This hook is called just before updating the database. It expects the actual new value you're trying to set 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_column_name may be called outside the context of a set operation to validate a potential value. (The Jifty application framework uses this as part of its AJAX validation system.)
_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.
__value
Takes a column name and returns that column's value. Subclasses should never override __value.
_set
_set takes a single column name and a single unquoted value. It updates both the in-memory value of this column and the in-database copy. Subclasses can override _set to insert custom access control.
_validate column VALUE
Validate that value will be an acceptable value for column.
Currently, this routine does nothing whatsoever.
If it succeeds (which is always the case right now), returns true. Otherwise returns false.
load
Takes a single argument, $id. Calls load_by_cols to retrieve the row whose primary key is $id
load_by_cols
Takes a hash of columns and values. Loads the first record that matches all keys.
The hash's keys are the columns to look at.
The hash's values are either: scalar values to look for OR has references which contain 'operator' and 'value'
load_by_primary_keys
load_from_hash
Takes a hashref, such as created by Jifty::DBI and populates this record's loaded values hash.
_load_from_sql QUERYSTRING @BIND_VALUES
Load a record as the result of an SQL statement
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:
- 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).
before_createreturns a true or false value. If it returns false, the create is aborted. - 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 Class::ReturnValue
delete
Delete this record from the database. On failure return a Class::ReturnValue with the error. On success, return 1;
This method has two hooks
- 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.
- after_delete
-
This method is called after deletion, with a reference to the return value from the delete operation.
table
This method returns this class's default table name. It uses Lingua::EN::Inflect to pluralize the class's name as we believe that class names for records should be in the singular and table names should be plural.
If your class name is My::App::Rhino, your table name will default to rhinos. If your class name is My::App::RhinoOctopus, your default table name will be rhino_octopuses. Not perfect, but arguably correct.
_guess_table_name
Guesses a table name based on the class's last part.
_handle
Returns or sets the current Jifty::DBI::Handle object
used for the declarative syntax
AUTHOR
Jesse Vincent <jesse@bestpractical.com>, Alex Vandiver <alexmv@bestpractical.com>, David Glasser <glasser@bestpractical.com>, Ruslan Zakirov <ruslan.zakirov@gmail.com>
Based on DBIx::SearchBuilder::Record, whose credits read:
Jesse Vincent, <jesse@fsck.com>
Enhancements by Ivan Kohler, <ivan-rt@420.am>
Docs by Matt Knopp <mhat@netlag.com>