[Jifty-commit] r5806 - in JiftyX-ModelHelpers/branches/JiftyX-ModelHelpers-trunk: lib/JiftyX

[Jifty commits]

Author: gugod
Date: Mon Sep  8 09:33:22 2008
New Revision: 5806

Modified:
   JiftyX-ModelHelpers/branches/JiftyX-ModelHelpers-trunk/   (props changed)
   JiftyX-ModelHelpers/branches/JiftyX-ModelHelpers-trunk/Changes
   JiftyX-ModelHelpers/branches/JiftyX-ModelHelpers-trunk/README
   JiftyX-ModelHelpers/branches/JiftyX-ModelHelpers-trunk/lib/JiftyX/ModelHelpers.pm

Log:
 r23754 at yra:  gugod | 2008-09-08 21:21:08 +0800
 More docs


Modified: JiftyX-ModelHelpers/branches/JiftyX-ModelHelpers-trunk/Changes
==============================================================================
--- JiftyX-ModelHelpers/branches/JiftyX-ModelHelpers-trunk/Changes	(original)
+++ JiftyX-ModelHelpers/branches/JiftyX-ModelHelpers-trunk/Changes	Mon Sep  8 09:33:22 2008
@@ -0,0 +1,3 @@
+
+2008-09-08T21:13:46+0800
+0.01 - Initial release

Modified: JiftyX-ModelHelpers/branches/JiftyX-ModelHelpers-trunk/README
==============================================================================
--- JiftyX-ModelHelpers/branches/JiftyX-ModelHelpers-trunk/README	(original)
+++ JiftyX-ModelHelpers/branches/JiftyX-ModelHelpers-trunk/README	Mon Sep  8 09:33:22 2008
@@ -0,0 +1,13 @@
+JiftyX-ModelHelprs
+
+This is my work to make C<Jifty::DBI> objects a little bit easier to
+start with. It let you write something this obvious:
+
+  $book = Book(42);
+  $books = BookCollection( author => "Neal Stephenson" );
+
+This module is released as an extension under JiftyX namespace as
+requested by jifty team. Use it at your own risk.
+
+Cheers,
+Kang-min Liu <gugod at gugod.org>

Modified: JiftyX-ModelHelpers/branches/JiftyX-ModelHelpers-trunk/lib/JiftyX/ModelHelpers.pm
==============================================================================
--- JiftyX-ModelHelpers/branches/JiftyX-ModelHelpers-trunk/lib/JiftyX/ModelHelpers.pm	(original)
+++ JiftyX-ModelHelpers/branches/JiftyX-ModelHelpers-trunk/lib/JiftyX/ModelHelpers.pm	Mon Sep  8 09:33:22 2008
@@ -65,12 +65,113 @@
     $book = Book($id);
 
     # Load by other criteria
-    $book = Book(isbn => "xxx-xxxx-xxxxxxx");
+    $book = Book(isbn => " 978-0099410676");
 
     # Load a colllection of books
     $books = BookCollection(author => "Jesse");
 
-=head1 FUNCTIONS
+=head1 Description
+
+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.
+
+This module, when required, 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::Book
+    JiftyX::ModelHelpers::BookCollection
+
+They are automatically imported to your currenct package scope as:
+
+    Book
+    BookCollection
+
+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");
+
+This is exactly the same as:
+
+    my $book = Jifty->app_class(Model => 'Book');
+    $book->load_by_cols(isbn => "978-0099410676");
+
+Please also read the description of C<load_by_cols> in
+L<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.
+
+The returned C<$book> is a L<Jifty::Record> object, so please read
+its POD for how to use it.
+
+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 C<limit>
+method on the collection several times:
+
+    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 C<$books> is still a L<Jifty::Collection> object, so
+please read its POD for how to use it.
+
+For people who works daily in Jifty world, this should make your code
+more readible for most of the time.
+
+=head1 Namespace clobbering
+
+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 method is an L<Exporter>,
+so you can pass those functions your want explicitly:
+
+    # Don't want BookCollection function
+    use JiftyX::ModelHelpers qw(Book);
+
+=head1 Development
+
+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 C<jifty-devel-subscribe at lists.jifty.org>
 
 =head1 AUTHORS