[Jifty-commit] r1933 - in jifty/trunk: .
jifty-commit at lists.jifty.org
jifty-commit at lists.jifty.org
Mon Sep 4 15:30:35 EDT 2006
Author: wolfgang
Date: Mon Sep 4 15:30:31 2006
New Revision: 1933
Added:
jifty/trunk/lib/Jifty/Manual/Models.pod
Modified:
jifty/trunk/AUTHORS
Log:
Wolfgang Kinkeldei: added a pod on models - not yet complete
Modified: jifty/trunk/AUTHORS
==============================================================================
--- jifty/trunk/AUTHORS (original)
+++ jifty/trunk/AUTHORS Mon Sep 4 15:30:31 2006
@@ -15,3 +15,4 @@
Norman Nunley, Jr. <nnunley at cpan.org>
Mark Fowler <mark at twoshortplanks.com>
Liang-Bin Hsueh <hlb at bestpractical.com>
+Wolfgang Kinkeldei <wolfgang at kinkeldei.de>
Added: jifty/trunk/lib/Jifty/Manual/Models.pod
==============================================================================
--- (empty file)
+++ jifty/trunk/lib/Jifty/Manual/Models.pod Mon Sep 4 15:30:31 2006
@@ -0,0 +1,203 @@
+=head1 NAME
+
+Jifty::Manual::Models - Managing your datastore
+
+=head1 DESCRIPTION
+
+The idea behing a model is to give the user a database-independent way
+of defining how the data looks alike and how different parts of the
+data relate to each other. In database terms, you might think of a
+schema definition.
+
+Besides the pure definition of a model, creation, updating and lookup
+of data is also possible in a comfortable way.
+
+=head2 Creating a model
+
+Every model consists of two classes: I<AppName>::Model::I<ModelName>
+and I<AppName>::Model::I<ModelName>::Schema. Behind the scenes, a
+class named I<AppName>::Model::I<ModelName>Collection is created by
+L<Jifty::ClassLoader>.
+
+A simple model to store just one line of text might look like this:
+
+ use strict;
+ use warnings;
+
+ package MyApp::Model::TextLine::Schema;
+ use Jifty::DBI::Schema;
+
+ column 'textline';
+
+ package MyApp::Model::TextLine;
+ use base qw/MyApp::Record/;
+
+ 1;
+
+To create the database schema for a model inside an application you
+could simply run:
+
+ jifty schema --name TextLine
+
+from inside your application's directory and Jifty will create exactly
+this class structure for you (minus the I<column> line, to be
+precise).
+
+=head3 Schema definition language
+
+Creating a model has important side effects:
+
+=over 4
+
+=item * correctly type your data inside the data-store
+
+=item * let Jifty create (and update) your database schema for you
+
+=item * tell Jifty the behaviour in terms of form display
+
+=item * allow to work with multiple records (referred to as
+Collections) without effort
+
+=back
+
+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>
+followed by the column's name.
+
+A simple definition could look like this:
+
+ column name =>
+ type is 'text',
+ label is 'Name',
+ render_as 'Text',
+ sincle '0.0.1';
+
+The following BNF shows the full syntax supported (omitting
+non-terminals that are self explaining for perl-developers):
+
+ schema_definition ::= column_definition+ ';'
+
+ column_definition ::= 'column' string_columnname '=>' column_info [ ',' column_info ]+
+
+ column_info ::= 'type' 'is' string
+ | 'label' 'is' string
+ | 'render_as' string
+ | 'hints' 'is' string
+ | 'refers_to' class_name 'by' string_columnname
+ | 'default' 'is' string
+ | 'literal' 'is' string
+ | 'validator' 'is' subroutine_reference
+ | 'immutable'
+ | 'unreadable'
+ | 'length' 'is' number
+ | 'mandatory'
+ | 'not_null'
+ | 'distinct'
+ | 'virtual'
+ | 'sort_order' 'is' number
+ | 'input_filters' 'are' string_classname
+ | 'output_filters' 'are' string_classname
+ | 'filters' 'are' string_classname
+ | 'since' string_version_number
+ | 'valid_values' 'are' array_of_valid_values
+ | 'hints' 'are' string
+
+ * 'is', 'by', 'on' and 'are' are fill-words that may get omitted.
+
+For a full description of all parameter's meaning, look at
+L<Jifty::DBI::Schema>.
+
+=head3 Versioning
+
+Every time you run the jifty utility with C<schema> as an argument,
+Jifty will keep track on what it has done for you. To get that done,
+the version-number being stored in your application's config file
+C<etc/config.yml> under the key named C<framework/Database/Verson> is
+matched agains your schema definition.
+
+To force an update of your schema, simple create a new version number
+in your config file and modify your schema definition by using exactly
+this version number for every modified entry. After running
+
+ jifty schema --setup
+
+your database structure will be in sync to your schema definition.
+
+=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.
+
+=head2 The classes behind a model
+
+=over 4
+
+=item * MyApp::Model::Xxx
+
+This is the model-class you created to access 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
+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
+so by manually creating this class.
+
+=item * L<Jifty::Record>
+
+This is the super-class of 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
+directly deals with the underlying database.
+
+=item * App::Model::XxxCollection
+
+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.
+
+=item * App::Collection
+
+Every collection of your schemata will have this class as its
+base. Usually this class is autocreated by L<Jifty::ClassLoader>. If
+you intend to create new features for all of your collection this will
+be your chance to do.
+
+=item * L<Jifty::Collection>
+
+This is the base class of an C<App::Collection>, managing user
+capabilities on records it will keep track of.
+
+=item * L<Jifty::DBI::Collection>
+
+This is the low-level base class that directly manages the access to
+the underlying database.
+
+=back
+
+=head2 Working with a model's data
+
+XXX - write more
+
+=head2 Action - Model relationship
+
+XXX - write more
+
+=head1 SEE ALSO
+
+L<Jifty::Record>, L<Jifty::DBI::Record>, L<Jifty::Collection>, L<Jifty::DBI::Collection>, L<Jifty::Manual::Actions>, L<Jifty::Manual::Tutorial>
+
+
+=cut
More information about the Jifty-commit
mailing list