[Catalyst-commits] r8024 - in Catalyst-Controller-DBIC-API/1.000/trunk/lib/Catalyst/Controller/DBIC: . API

lukes at dev.catalyst.perl.org lukes at dev.catalyst.perl.org
Sat Jun 28 13:37:14 BST 2008


Author: lukes
Date: 2008-06-28 13:37:13 +0100 (Sat, 28 Jun 2008)
New Revision: 8024

Modified:
   Catalyst-Controller-DBIC-API/1.000/trunk/lib/Catalyst/Controller/DBIC/API.pm
   Catalyst-Controller-DBIC-API/1.000/trunk/lib/Catalyst/Controller/DBIC/API/Base.pm
   Catalyst-Controller-DBIC-API/1.000/trunk/lib/Catalyst/Controller/DBIC/API/REST.pm
   Catalyst-Controller-DBIC-API/1.000/trunk/lib/Catalyst/Controller/DBIC/API/RPC.pm
Log:
base docs complete

Modified: Catalyst-Controller-DBIC-API/1.000/trunk/lib/Catalyst/Controller/DBIC/API/Base.pm
===================================================================
--- Catalyst-Controller-DBIC-API/1.000/trunk/lib/Catalyst/Controller/DBIC/API/Base.pm	2008-06-28 11:15:53 UTC (rev 8023)
+++ Catalyst-Controller-DBIC-API/1.000/trunk/lib/Catalyst/Controller/DBIC/API/Base.pm	2008-06-28 12:37:13 UTC (rev 8024)
@@ -275,8 +275,15 @@
 	}
 	
 	$c->res->status( $default_status || 200 );
+	$c->forward('serialize');
 }
 
+# from Catalyst::Action::Serialize
+sub serialize :ActionClass('Serialize') {
+	my ($self, $c) = @_;
+
+}
+
 sub push_error {
 	my ( $self, $c, $params ) = @_;
 

Modified: Catalyst-Controller-DBIC-API/1.000/trunk/lib/Catalyst/Controller/DBIC/API/REST.pm
===================================================================
--- Catalyst-Controller-DBIC-API/1.000/trunk/lib/Catalyst/Controller/DBIC/API/REST.pm	2008-06-28 11:15:53 UTC (rev 8023)
+++ Catalyst-Controller-DBIC-API/1.000/trunk/lib/Catalyst/Controller/DBIC/API/REST.pm	2008-06-28 12:37:13 UTC (rev 8024)
@@ -35,19 +35,6 @@
 
 =cut 
 
-sub end :Private {
-	my ($self, $c) = @_;
-
-	$self->NEXT::end($c);	
-	$c->forward('serialize');
-}
-
-# from Catalyst::Action::Serialize
-sub serialize :ActionClass('Serialize') {
-	my ($self, $c) = @_;
-
-}
-
 sub begin :Private {
 	my ($self, $c) = @_;
 

Modified: Catalyst-Controller-DBIC-API/1.000/trunk/lib/Catalyst/Controller/DBIC/API/RPC.pm
===================================================================
--- Catalyst-Controller-DBIC-API/1.000/trunk/lib/Catalyst/Controller/DBIC/API/RPC.pm	2008-06-28 11:15:53 UTC (rev 8023)
+++ Catalyst-Controller-DBIC-API/1.000/trunk/lib/Catalyst/Controller/DBIC/API/RPC.pm	2008-06-28 12:37:13 UTC (rev 8024)
@@ -37,19 +37,6 @@
 
 =cut 
 
-sub end :Private {
-	my ($self, $c) = @_;
-
-	$self->NEXT::end($c);	
-	$c->forward('serialize');
-}
-
-# from Catalyst::Action::Serialize
-sub serialize :ActionClass('Serialize') {
-	my ($self, $c) = @_;
-
-}
-
 =head2 object
 
 Sets the object that is used by update, delete etc which chain from this.

Modified: Catalyst-Controller-DBIC-API/1.000/trunk/lib/Catalyst/Controller/DBIC/API.pm
===================================================================
--- Catalyst-Controller-DBIC-API/1.000/trunk/lib/Catalyst/Controller/DBIC/API.pm	2008-06-28 11:15:53 UTC (rev 8023)
+++ Catalyst-Controller-DBIC-API/1.000/trunk/lib/Catalyst/Controller/DBIC/API.pm	2008-06-28 12:37:13 UTC (rev 8024)
@@ -58,7 +58,7 @@
 
 =head2 create_allows
 
-Arrayref listing columns additional to those specified in create_requires that are not required to create but which create does allow. Columns passed to create that are not listed here will be ignored.
+Arrayref listing columns additional to those specified in create_requires that are not required to create but which create does allow. Columns passed to create that are not listed in create_allows or create_requires will be ignored.
 
 =head2 update_allows
 
@@ -66,7 +66,7 @@
 
 =head2 list_returns
 
-Arrayref listing columns that list will return. Leave blank to return all columns.
+Arrayref listing columns that L</list> will return. Leave blank to return all columns.
 
 =head2 object_stash_key
 
@@ -76,11 +76,91 @@
 
 List level methods such as list and create stash the class resultset in the stash. Specify the stash key you would like to use here. Defaults to 'class_rs'.
 
+=head1 METHODS
 
+Note: see the individual interface classes - L<Catalyst::Controller::API::RPC> and L<Catalyst::Controller::API::REST> - for details of the endpoints to these abstract methods.
+
+=head2 setup
+
+This action is the chain root of the controller. It must either be overridden or configured to provide a base pathpart to the action and also a parent action. For example, for class MyAppDB::Track you might have
+
+  package MyApp::Controller::API::RPC::Track;
+  use base qw/Catalyst::Controller::DBIC::API::RPC/;
+
+  __PACKAGE__->config
+    ( action => { setup => { PathPart => 'track', Chained => '/api/rpc/rpc_base' } }, 
+	...
+  );
+
+  # or
+
+  sub setup :Chained('/api/rpc_base') :CaptureArgs(0) :PathPart('track') {
+	$self->NEXT::setup($c);
+  }
+
+This action will populate $c->stash->{$self->rs_stash_key} with $c->model($self->class) for other actions in the chain to use.
+
+=head2 object
+
+This action is the chain root for all object level actions (such as delete and update)
+
+=head2 create
+
+List level action chained from L</setup>. Checks $c->req->params for each column specified in the L</create_requires> and L</create_allows> parameters of the controller config. If all of the required columns are present then the object is created.
+
+Does not populate the response with any additional information.
+
+=head2 list
+
+List level action chained from L</setup>. By default populates $c->stash->{response}->{list} with a list of hashrefs representing each object in the class resultset. If the </list_returns> config param is defined then the hashes will contain only those columns, otherwise all columns in the object will be returned.
+
+If not all objects in the resultset are required then it's possible to pass conditions to the method as request parameters. L</CGI::Expand> is used to expand the request parameters into a structure and then $c->req->params->{search} is used as the search condition.
+
+For example, these request parameters:
+
+ ?search.name=fred&search.cd.artist=luke
+
+Would result in this search (where 'name' is a column of the schema class, 'cd' is a relation of the schema class and 'artist' is a column of the related class):
+
+ $rs->search({ name => 'fred', 'cd.artist' => 'luke' }, { join => ['cd'] })
 =head1 AUTHOR
 
+The L</format_list> method is used to format the results, so override that as required.
+
+=head2 format_list
+
+Used by L</list> to populate response based on class resultset. By default populates $c->stash->{response}->{list} with a list of hashrefs representing each object in the resultset. Can be overidden to format the list as required.
+
+=head2 update
+
+Object level action chained from L</object>. Checks $c->req->params for each column specified in the L</update_allows> parameter of the controller config. If any of these columns are found in $c->req->params then the object set by L</object> is updated with those columns.
+
+Does not populate the response with any additional information.
+
+=head2 delete
+
+Object level action chained from L</object>. Will simply delete the object set by L</object>.
+
+Does not populate the response with any additional information.
+
+=head2 end
+
+If the request was successful then $c->stash->{response}->{success} is set to 1, if not then it is set to 0 and $c->stash->{response}->{messages} set to an arrayref containing all error messages.
+
+Then the contents of $c->stash->{response} are serialized using L<Catalyst::Action::Serialize>.
+
+=head1 EXTENDING
+
+By default the create, delete and update actions will not return anything apart from the success parameter set in L</end>, often this is not ideal but the required behaviour varies from application to application. So normally it's sensible to write an intermediate class which your main controller classes subclass from.
+
+=head1 AUTHOR
+
   Luke Saunders <luke.saunders at gmail.com>
 
+=head1 CONTRIBUTORS
+  
+  Zbigniew Lukasiak <zzbbyy at gmail.com>
+
 =cut
 
 1;




More information about the Catalyst-commits mailing list