From: Rafael Kitover Date: Wed, 23 Dec 2009 06:23:19 +0000 (+0000) Subject: pod cleanup, release X-Git-Tag: v0.32^0 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Model-DBIC-Schema.git;a=commitdiff_plain;h=cbe03ea7ec9a649973a404a41b3aa8d8f2ab4163 pod cleanup, release --- diff --git a/Changes b/Changes index 13cbafd..8f425ca 100644 --- a/Changes +++ b/Changes @@ -1,6 +1,6 @@ Revision history for Perl extension Catalyst::Model::DBIC::Schema -0.32 Mon Dec 21 21:33:53 EST 2009 +0.32 Wed Dec 23 01:22:06 EST 2009 - Move documentation on setting up authentication into its own section for clarity. - Other misc documentation enhancements to make the docs more clear diff --git a/lib/Catalyst/Model/DBIC/Schema.pm b/lib/Catalyst/Model/DBIC/Schema.pm index 81e4c4a..5ee32c9 100644 --- a/lib/Catalyst/Model/DBIC/Schema.pm +++ b/lib/Catalyst/Model/DBIC/Schema.pm @@ -24,53 +24,35 @@ Catalyst::Model::DBIC::Schema - DBIx::Class::Schema Model Class =head1 SYNOPSIS -=over 4 - -=item 1. - -First, prepare your database schema using C. - -(If you're not sure how to do this, then read L first!) - -This example assumes that you already have a schema called -C, -which defines some tables in C and -C. - -=item 2. - -Now, to expose it to Catalyst as a model, you should create a DBIC Model in -MyApp/Model/FilmDB.pm: - -=over 8 - -You can do this: +First, prepare your database schema using L, see +L for how to generate a +L from your database using the Helper script, and +L. -=item * With the helper script +A typical usage of the helper script would be: - script/create.pl model FilmDB DBIC::Schema MyApp::Schema::FilmDB ...options... + script/myapp_create.pl model FilmDB DBIC::Schema MyApp::Schema::FilmDB \ + create=static dbi:mysql:filmdb dbusername dbpass \ + quote_char='`' name_sep='.' -See L for details. +If you are unfamiliar with L, see L +first. -=item * Manually +These examples assume that you already have a schema called +C, which defines some Result classes for tables in +C and +C. Either created by the helper script (as +shown above) or manually. - package MyApp::Model::FilmDB; - use base qw/Catalyst::Model::DBIC::Schema/; +The helper also creates a Model in C, if you already +have a schema you can create just the Model using: - __PACKAGE__->config( - schema_class => 'MyApp::Schema::FilmDB', - connect_info => { - dsn => "DBI:...", - user => "username", - password => "password", - } - ); + script/myapp_create.pl model FilmDB DBIC::Schema MyApp::Schema::FilmDB + dbi:mysql:filmdb dbusername dbpass -See below for a full list of the possible config parameters. - -=back - -=back +The connect_info is optional and will be hardcoded into the Model if provided. +It's better to configure it in your L config file, which will also +override any hardcoded config, see L for examples. Now you have a working Model which accesses your separate DBIC Schema. This can be used/accessed in the normal Catalyst manner, via C<< $c->model() >>: @@ -78,7 +60,7 @@ be used/accessed in the normal Catalyst manner, via C<< $c->model() >>: my $db_model = $c->model('FilmDB'); # a Catalyst::Model my $dbic = $c->model('FilmDB')->schema; # the actual DBIC object -The Model proxies the DBIC instance so you can do +The Model proxies to the C instance so you can do: my $rs = $db_model->resultset('Actor'); # ... or ... my $rs = $dbic ->resultset('Actor'); # same! @@ -88,9 +70,17 @@ instead of a L: my $rs = $c->model('FilmDB::Actor'); -To find out more about which methods can be called on a ResultSet, or how to -add your own methods to it, please see the ResultSet documentation in the -L distribution. +See L to find out more about which methods can be +called on ResultSets. + +You can also define your own ResultSet methods to encapsulate the +database/business logic of your applications. These go into, for example, +C. The class must inherit from +L and is automatically loaded. + +Then call your methods like any other L method: + + $c->model('FilmDB::Actor')->SAG_members =head2 Some examples: @@ -130,11 +120,11 @@ This is a Catalyst Model for L-based Models. See the documentation for L for information on generating these Models via Helper scripts. -When your Catalyst app starts up, a thin Model layer is created as an -interface to your DBIC Schema. It should be clearly noted that the model -object returned by C<< $c->model('FilmDB') >> is NOT itself a DBIC schema or -resultset object, but merely a wrapper proving L to access -the underlying schema. +When your Catalyst app starts up, a thin Model layer is created as an interface +to your DBIC Schema. It should be clearly noted that the model object returned +by C<< $c->model('FilmDB') >> is NOT itself a DBIC schema or resultset object, +but merely a wrapper proving L to access the underlying +schema (but also proxies other methods to the underlying schema.) In addition to this model class, a shortcut class is generated for each source in the schema, allowing easy and direct access to a resultset of the @@ -164,8 +154,15 @@ resultset object: In order to add methods to a DBIC resultset, you cannot simply add them to the source (row, table) definition class; you must define a separate custom -resultset class. See L -for more info. +resultset class. This is just a matter of making a +C class that inherits from +L, if you are using +L, the default for helper script generated +schemas. + +See L +for information on definining your own L classes for +use with L, the old default. =head1 CONFIG PARAMETERS @@ -465,13 +462,15 @@ sub BUILD { $self->composed_schema($schema_class->compose_namespace($class)); + my $was_mutable = $self->meta->is_mutable; + $self->meta->make_mutable; $self->meta->add_attribute('schema', is => 'rw', isa => 'DBIx::Class::Schema', handles => $self->_delegates ); - $self->meta->make_immutable; + $self->meta->make_immutable unless $was_mutable; $self->schema($self->composed_schema->clone); @@ -623,8 +622,9 @@ __PACKAGE__->meta->make_immutable; =item CMDS_NO_SOURCES -Set this variable if you will be using schemas with no sources (tables) to -disable the warning. The warning is there because this is usually a mistake. +Set this variable if you will be using schemas with no sources (Result classes) +to disable the warning. The warning is there because having no Result classes +is usually a mistake. =back @@ -674,7 +674,8 @@ L, L Traits: L, -L +L, +L =head1 AUTHOR @@ -692,7 +693,7 @@ t0m: Tomas Doran C osfameron: C -Ozum Eldogan C +ozum: Ozum Eldogan C =head1 COPYRIGHT