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

[Jifty commits]

Author: gugod
Date: Mon Oct 20 13:19:00 2008
New Revision: 5950

Modified:
   JiftyX-ModelHelpers/trunk/Changes
   JiftyX-ModelHelpers/trunk/lib/JiftyX/ModelHelpers.pm

Log:
POD Update.


Modified: JiftyX-ModelHelpers/trunk/Changes
==============================================================================
--- JiftyX-ModelHelpers/trunk/Changes	(original)
+++ JiftyX-ModelHelpers/trunk/Changes	Mon Oct 20 13:19:00 2008
@@ -1,3 +1,8 @@
 
+0.20
+- Breaks backwoard compatbility :)
+- Add M() function exported by default
+- All auto-created functions are now NOT exported by default.
+
 2008-09-08T21:13:46+0800
 0.01 - Initial release

Modified: JiftyX-ModelHelpers/trunk/lib/JiftyX/ModelHelpers.pm
==============================================================================
--- JiftyX-ModelHelpers/trunk/lib/JiftyX/ModelHelpers.pm	(original)
+++ JiftyX-ModelHelpers/trunk/lib/JiftyX/ModelHelpers.pm	Mon Oct 20 13:19:00 2008
@@ -82,7 +82,7 @@
 
 =head1 NAME
 
-JiftyX::ModelHelpers - Use Jifty model easily.
+JiftyX::ModelHelpers - Use Jifty model more easily.
 
 =head1 VERSION
 
@@ -95,12 +95,21 @@
     use JiftyX::ModelHelper;
 
     # Load the record of book with id = $id
-    $book = Book($id);
+    $book = M(Book => id => $id);
 
     # Load by other criteria
-    $book = Book(isbn => " 978-0099410676");
+    $book = M(Book => isbn => " 978-0099410676");
 
     # Load a colllection of books
+    $books = M("BookCollection", author => "Jesse");
+
+If you want more sugar:
+
+    use JiftyX::ModelHelper ':auto';
+
+    # Load the record of book with id = $id
+    $book  = Book($id);
+    $book  = Book(isbn => " 978-0099410676");
     $books = BookCollection(author => "Jesse");
 
 =head1 Description
@@ -109,19 +118,85 @@
 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:
+When used, this module export a function named C<M> by default.
+This function takes one model name and returns its record object:
+
+    $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");
+
+=head2 The M() function
+
+The C<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
+I<blank> record object of Book model:
+
+    $book = M("Book");
+
+It's said to be I<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 C<Jifty::DBI::Record>, which allows record
+creations with both object method and class method.
+
+The C<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 the given model name is a collection, instead of meaning a I<blank>
+collection object, it means the collection of I<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".
+
+=head2 The auto-generated model functions.
+
+Optionally, C<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::Book
     JiftyX::ModelHelpers::BookCollection
 
-They are automatically imported to your currenct package scope as:
+They are imported to your currenct package scope as:
 
     Book
     BookCollection
 
+But only when use use C<JiftyX::ModelHelpers> with an C<:auto> tag:
+
+    use JiftyX::ModelHelpers ':auto':
+
 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:
@@ -208,13 +283,13 @@
 
 =head1 AUTHORS
 
-Kang-min Liu C< <gugod at gugod.org> >
+Kang-min Liu C<gugod at gugod.org>
 
 =head1 COPYRIGHT & LICENSE
 
 The MIT License
 
-Copyright (c) 2008 Kang-min Liu
+Copyright (c) 2008 Kang-min Liu C<gugod at gugod.org>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal