/ 
SweetPea-Application-0.024
/ SweetPea::Application::Orm

NAME

SweetPea::Application::Orm - Object Relational Mapping for SweetPea-Application.

SYNOPSIS ... from inside SweetPea::Application or a Controller; this example uses table (users) in the demonstration.

# SweetPea::Application::Orm is NOT a full-featured object relational
mapper but is an ORM none the less which creates and provides database
object accessors for use in your application code. SweetPea::Application::Orm
uses SQL::Abstract querying syntax.

# assign dbo (database object) users (users table) to local variable
my $user = $s->dbo->users;

# grab the first record, not neccessary if operating on only one record
$user->read->next;

$user->read;

# SQL::Abstract where clause passed to the "read" method
$user->read({
    'column' => 'query'
});

$user->first;
$user->last;

# how many records in collection
$user->count

for (0..$user->count) {
    print $user->column;
    $user->column('new stuff');
    $user->update($user->current, $user->id);
}

# the database objects main accessors are CRUD (create, read, update, and delete)

$user->create;
  $user->read;
    $user->update;
      $user->delete;

# also, need direct access to the resultset?
$user->collection; # returns an array of hashrefs
$user->current; # return a hash of the row in the current position of the collection

METHODS

new

The new method instantiates a new SweetPea::Application::Orm object
which uses the YAML datasource configuration files to create database
objects for manipulating the datasource.

$s->plug( 'profile', sub { return SweetPea::Application::Orm->new($s); });

next

The next method instructs the database object to continue to the next
row if it exists.

$s->dbo->table->next;

first

The first method instructs the database object to continue to return the first
row in the resultset.

$s->dbo->table->first;

last

The last method instructs the database object to continue to return the last
row in the resultset.

$s->dbo->table->last;

collection

The collection method return the raw resultset object.

$s->dbo->table->collection;

current

The current method return the raw row resultset object of the position in
the resultset collection.

$s->dbo->table->current;

clear

The clear method empties all resultset containers.

$s->dbo->table->clear;

key

The key method finds the database objects primary key if its defined.

$s->dbo->table->key;

return

The return method queries the database for the last created or updated
object(s) based on whether the the last statement was a create or update command.

$s->dbo->table->create({})->return;
$s->dbo->table->update({})->return;

count

The count method returns the number of items in the resultset of the
object it's called on.

my $count = $s->dbo->table->read->count;
my $count = $s->dbo->table->count;

create

Caveat 1: The create method will remove the primary key if the column
is marked as auto-incremented ...

# see declaration in the table's yaml data profile
table: 
  columns: 
    [column]: 
      auto: 1 

... this will need to be changed manually if your database doesn't
support the auto-increment declaration, i.e. SQLite

The create method creates a new entry in the datastore.
Takes 1 arg.

arg 1: hashref (SQL::Abstract fields parameter)

$s->dbo->table->create({
    'column_a' => 'value_a',
});

# example of a quick copy an existing record
my $user = $s->dbo->users->read;
$user->first;
$user->full_name('Copy of ' . $user->full_name);
$user->user_name('new');
$user->create($user->current);

# new account id
$user->return->id;
# or
$user->return;
print $user->id;
print $user->full_name;

read

The read method fetches records from the datastore.
Takes 2 arg.

arg 1: hashref (SQL::Abstract where parameter) or scalar
arg 2: arrayref (SQL::Abstract order parameter) - optional

$s->dbo->table->read({
    'column_a' => 'value_a',
});

or

$s->dbo->table->read(1);

update

The update method alters an existing record in the datastore.
Takes 2 arg.

arg 1: hashref (SQL::Abstract fields parameter)
arg 2: arrayref (SQL::Abstract where parameter) or scalar - optional

$s->dbo->table->update({
    'column_a' => 'value_a',
},{
    'column_a' => '...'
});

or

$s->dbo->table->update({
    'column_a' => 'value_a',
}, 1);

delete

Takes 1 arg.

arg 1: hashref (SQL::Abstract where parameter) or scalar

$s->dbo->table->delete({
    'column_a' => 'value_a',
});

or

$s->dbo->table->delete(1);

AUTHOR

Al Newkirk, <al.newkirk at awnstudio.com>