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>

cpanm SweetPea::Application

perl -MCPAN -e shell
install SweetPea::Application