JiftyX::ModelHelpers - Make it simpler to fetch records in Jifty.
version 0.23
Suppose you have a "Book" model in your app:
use JiftyX::ModelHelper; # Load the record of book with id = $id $book = M(Book => $id); # Another way. $book = M(Book => id => $id); # Load by other criteria $book = M(Book => isbn => " 978-0099410676"); # Load a colllection of books $books = M("BookCollection", author => "Jesse");
Or, even better:
use JiftyX::ModelHelper; # Load the record of book with id = $id $book = Book($id); $book = Book(isbn => " 978-0099410676"); $books = BookCollection(author => "Jesse");
Jifty programmers may find them self very tired of typing in their View or Dispatcher when it comes to retrieve records or collection of records. That is why this module was borned.
When used, this module export a function named M by default. This function takes one model name and returns its record object:
M
$book = M("Book");
Effectively, this is the same as doing:
$book = Jifty->app_class(Model => "Book")->new;
It also works for collections:
$book = M("BookCollection");
The M function is a short-hand to create both record and collection objects. The first argument is reqruied and has to be one of the model name existed in your application. For example, this creates an blank record object of Book model:
It's said to be blank because it is not associated with a record stored in the database, and does not have any meaningful properties. However, it is useful to create records with this representation:
M("Book")->create({ name => "RT Essentials", author => "Jesse Vincent" });
Thanks to the design of Jifty::DBI::Record, which allows record creations with both object method and class method.
Jifty::DBI::Record
The M function optionally takes a list of key-value pairs after model names. The keys will be treated as column names, as values are, of course, column values. These key-value pairs will be the requirement used to load records. For example, this statement loads a record of Book with certain isbn:
$book = M("Book", isbn => "978-0099410676");
Effectively, this is the same as:
$book => Jifty->app_class(Model => "Book")->new; $book->load_by_cols(isbn => "978-0099410676");
If you pass only one numeric value instead of a key-value pair, that is specially treated as if it's an record id. So instead of saying:
$book = M("Book", id => 42);
It can be shorten to:
$book = M(Book => 42);
If the given model name is a collection, instead of meaning a blank collection object, it means the collection of all records.
$books = M("BookCollection");
Effectly the same as:
$books = Jifty->app_class(Model => "BookCollection")->new; $books->unlimit;
Practially this is the mostly used scenario, that's why I this decision to lett it represent a collection of "all" instead of "none".
If you need to set "current_user" to different ones when you construct a new model object, you can do it like this:
my $u = Jifty->app_class('CurrentUser')->superuser; $book = M("Book", isbn => "978-0099410676", { current_user => $u });
If the last argument to the M() method is a hashref, it is then passed to the new method of the model class.
new
Optionally, JiftyX::ModelHelpers generates two functions for each models your Jifty application. One for accessing records, the other for accessing collections. For example, if you have a model named "Book", the generated functions are:
JiftyX::ModelHelpers
JiftyX::ModelHelpers::Book JiftyX::ModelHelpers::BookCollection
They are imported to your currenct package scope as:
Book BookCollection
The are generated and imported when you say:
use JiftyX::ModelHelpers;
The record function takes either exact one argument or a hash. When it is given only one argument, that argument is treated as the value of "id" field and the record with that id is retured. Such as:
my $book = Book(42);
This is exactly the same as:
my $book = Jifty->app_class(Model => 'Book')->new; $book->load(42);
In other cases, it'd expect a hash:
my $book = Book(isbn => "978-0099410676");
my $book = Jifty->app_class(Model => 'Book'); $book->load_by_cols(isbn => "978-0099410676");
Please also read the description of load_by_cols in Jifty::DBI::Record to know how to use it. Basically the generate helper functions just delegate all its argument to that method and returns whatever returned from there.
load_by_cols
The returned $book is a Jifty::Record object, so please read its POD for how to use it.
$book
As for the function of collections, here's the example to get a collection of all records of books:
my $books = BookCollection;
And that's identical to:
my $books = Jifty->app_class(Model => "BookCollection")->new; $books->unlimit;
The function for collection can take a hash too, and calls limit method on the collection several times:
limit
my $books = BookCollection( author => "Neal Stephenson", binding => "paperback" );
This is the same as:
my $books = Jifty->app_class(Model => "BookCollection")->new; $books->limit(column => "author", value => "Neal Stephenson"); $books->limit(column => "binding", value => "paperback");
The returned $books is still a Jifty::Collection object, so please read its POD for how to use it.
$books
For people who works daily in Jifty world, this should make your code more readible for most of the time.
One major issue for using this module is that it automaically defines many functions in its caller, and that might cause naming collision.
To work around this, keep in mind that this module is an Exporter, and you can pass those functions your want explicitly:
# Don't want BookCollection function use JiftyX::ModelHelpers qw(Book);
Or you can only import the M() function, which is likely much less problematic:
use JiftyX::ModelHelpers qw(M);
The code repository for this project is hosted on
http://svn.jifty.org/svn/jifty.org/JiftyX-ModelHelpers
If you want to report a bug or an issue, please use this form:
https://rt.cpan.org/Ticket/Create.html?Queue=JiftyX-ModelHelpers
If you want to disscuss about this module, please join jifty-devel mailing list.
To join the list, send mail to jifty-devel-subscribe@lists.jifty.org
jifty-devel-subscribe@lists.jifty.org
Kang-min Liu <gugod@gugod.org>
This software is Copyright (c) 2008, 2009 by Kang-min Liu.
This is free software, licensed under:
The MIT (X11) License
To install JiftyX::ModelHelpers, copy and paste the appropriate command in to your terminal.
cpanm
cpanm JiftyX::ModelHelpers
CPAN shell
perl -MCPAN -e shell install JiftyX::ModelHelpers
For more information on module installation, please visit the detailed CPAN module installation guide.