[Jifty-commit] r2328 - jifty/trunk/lib/Jifty/Manual
jifty-commit at lists.jifty.org
jifty-commit at lists.jifty.org
Tue Dec 5 03:17:43 EST 2006
Author: agentz
Date: Tue Dec 5 03:17:42 2006
New Revision: 2328
Modified:
jifty/trunk/lib/Jifty/Manual/Models.pod
Log:
[Jifty::Manual::Models]
- typo fixes
- mentioned the build_select_query method, paging, and
Jifty::Manual::Upgrading.
Modified: jifty/trunk/lib/Jifty/Manual/Models.pod
==============================================================================
--- jifty/trunk/lib/Jifty/Manual/Models.pod (original)
+++ jifty/trunk/lib/Jifty/Manual/Models.pod Tue Dec 5 03:17:42 2006
@@ -63,8 +63,8 @@
To get all these things done, Jifty allows to describe the schema
definition in a simply comprehendable but powerful syntax that looks
more like written text than a programming language. The schema
-definition is made inside the I<MyApp::Model::XXX::Schema> package and
-for every single column to get created, starts with the word C<column>
+definition is made inside the C<MyApp::Model::XXX::Schema> package and
+every single column to get created starts with the word C<column>
followed by the column's name.
A simple definition could look like this:
@@ -76,7 +76,7 @@
since '0.0.1';
The following BNF shows the full syntax supported (omitting
-non-terminals that are self explaining for perl-developers):
+non-terminals that are self-explanatory to perl-developers):
schema_definition ::= column_definition+
@@ -128,12 +128,13 @@
jifty schema --setup
your database structure will be in sync to your schema definition.
+See L<Jifty::Manual::Upgrading> for more information on model upgrading.
=head2 Testing a model
After having created a schema, you might use the B<ADMINISTRATION>
-Menu entry in Jifty's web view to browse through your models and add,
-edit or delete records in your database.
+Menu entry in Jifty's web view (i.e. the "pony") to browse through
+your models and add, edit or delete records in your database.
=head2 The classes behind a model
@@ -141,12 +142,12 @@
=item * MyApp::Model::Xxx
-This is the model-class you created to access records of your desired
+This is the model-class you created to access individual records of your desired
type. You will directly deal with objects of this class.
=item * MyApp::Record
-All records of MyApp::Model::Xxx will have this class as their base
+All records of C<MyApp::Model::Xxx> will have this class as their base
class. Usually, this class will be automatically created by
L<Jifty::ClassLoader> for you. But, if you want to automatically
enable all your records to do something, you will have a chance to do
@@ -154,13 +155,13 @@
=item * L<Jifty::Record>
-This is the super-class of MyApp::Record. Inside this class, loading
+This is the super-class of C<MyApp::Record>. Inside this class, loading
of records as well as the checking of user capabilities is done before
going one level down to the database layer.
=item * L<Jifty::DBI::Record>
-This is the lowest-level class that the database-stack provides. It
+This is the lowest-level class that the database stack provides. It
directly deals with the underlying database.
=item * App::Model::XxxCollection
@@ -168,8 +169,9 @@
As the name applies, a collection is a set of typically more than one
record. Every collection of this class conists of multiple
C<App::Model::Xxx> objects that can get retrieved from your data-store
-without explicit SQL statements, ordered by any criteria you like and
-iterated sequentially or accessed at random order.
+without explicit SQL statements, ordered by any criteria you give,
+paged in the fashion you like,
+and iterated sequentially or accessed at random order.
=item * App::Collection
@@ -185,14 +187,14 @@
=item * L<Jifty::DBI::Collection>
-This is the low-level base class that directly manages the access to
+This is the lowest-level base class that directly manages the access to
the underlying database.
=back
-=head2 Working with single records
+=head2 Working with a single record
-Working with single records means work with objects of classes like
+Working with a single record means working with objects of classes like
C<MyApp::Model::Xxx>. The typical creation and usage of a single
record is:
@@ -200,17 +202,17 @@
my $object = new MyApp::Model::Xxx;
# either create a representation in the DB
- $object->create(column=>'value', ...);
+ $object->create(column => 'value', ...);
# or load the data from DB somehow
$object->load($id); # by a matching ID
- $object->load_by_cols(column=>'value', other_column=>'secondvalue');
+ $object->load_by_cols(column => 'value', other_column => 'secondvalue');
# try to load and if failed, create a record
- $object->load_or_create(column=>'value');
+ $object->load_or_create(column => 'value');
# get the record's ID in the database
- # results in 'undef' if record is not valid (usually means not found)
+ # results in 'undef' if record is not valid (which usually means not found)
my $id = $object->id;
# delete the record from the database
@@ -247,10 +249,10 @@
$collection->unlimit;
# or restrict items to match some condition
- $collection->limit(column=>'colname', operator=>'=', value=>42);
+ $collection->limit(column => 'colname', operator => '=', value => 42);
# bring the items into some sorting order
- $collection->order_by(column=>'colname');
+ $collection->order_by(column => 'colname');
# if neccesarry, directly jump to some record from the set
$collection->goto_first_item;
@@ -270,7 +272,7 @@
# get back an array-ref containing all items
my $records = $collection->items_array_ref;
-=head3 some options provided by C<limit>
+=head3 Some options provided by C<limit>
In order to construct more complex restrictions the C<limit> method
may get called more than once, specifying one single condition with
@@ -292,19 +294,24 @@
# combining restrictions with "AND"
# note that "AND" is implicit here
- $collection->limit(column=>'col1', value=>'...');
- $collection->limit(column=>'col2', value=>'...');
+ $collection->limit(column => 'col1', value => '...');
+ $collection->limit(column => 'col2', value => '...');
# combining restrictions with "OR"
# note that the 'subclause' has the same value
- $collection->limit(column=>'col1', value=>'...',
- entry_aggregator=>'OR', # is already default
- subclause=>'some_id');
- $collection->limit(column=>'col2', value=>'...',
- entry_aggregator=>'OR', # is already default
- subclause=>'some_id');
+ $collection->limit(column => 'col1', value => '...',
+ entry_aggregator => 'OR', # is already default
+ subclause => 'some_id');
+ $collection->limit(column => 'col2', value => '...',
+ entry_aggregator => 'OR', # is already default
+ subclause => 'some_id');
-see L<Jifty::DBI::Collection> about more ways or ordering and limiting
+For debugging purposes, you might want to examine the SQL statement
+generated behind the scene:
+
+ warn $collection->build_select_query;
+
+See L<Jifty::DBI::Collection> about more ways or ordering and limiting
collections.
=head2 Action - Model relationship
More information about the Jifty-commit
mailing list