NAME
Catalyst::ActionRole::RequestModel - Inflate a Request Model
SYNOPSIS
package Example::Controller::Account;
use Moose;
use MooseX::MethodAttributes;
extends 'Catalyst::Controller';
sub root :Chained(/root) PathPart('account') CaptureArgs(0) { }
sub update :POST Chained('root') PathPart('') Args(0) Does(RequestModel) BodyModel(AccountRequest) {
my ($self, $c, $request_model) = @_;
## Do something with the $request_model
}
sub list :GET Chained('root') PathPart('') Args(0) Does(RequestModel) QueryModel(PagingModel) {
my ($self, $c, $paging_model) = @_;
}
__PACKAGE__->meta->make_immutable;DESCRIPTION
Moves creating the request model into the action class execute phase. The following two actions are essentially the same in effect:
sub update :POST Chained('root') PathPart('') Args(0) Does(RequestModel) BodyModel(AccountRequest) {
my ($self, $c, $request_model) = @_;
## Do something with the $request_model
}
sub update :POST Chained('root') PathPart('') Args(0) {
my ($self, $c) = @_;
my $request_model = $c->model('AccountRequest');
## Do something with the $request_model
}The main reason for moving this into the action attributes line is the thought that it allows us to declare the request model as meta data on the action and in the future we will be able to introspect that meta data at application setup time to do things like generate an Open API specification. Also, if you have several request models for the endpoint you can declare all of them on the attributes line and we will match the incoming request to the best request model, or throw an exception if none match. So if you have more than one this saves you writing that boilerplate code to chose and to handled the no match conditions.
You might also just find the code neater and more clean reading. Downside is for people unfamiliar with this system it might increase learning curve time.
ATTRITBUTE VALUE DEFAULTS
Although you may prefer to be explicit in defining the request model name, we infer default values for both BodyModeL and QueryModel based on the action name and the controller namespace. For example,
package Example::Controller::Account;
use Moose;
use MooseX::MethodAttributes;
extends 'Catalyst::Controller';
sub root :Chained(/root) PathPart('account') CaptureArgs(0) { }
sub update :POST Chained('root') PathPart('') Args(0) Does(RequestModel) BodyModel() {
my ($self, $c, $request_model) = @_;
## Do something with the $request_model
}
sub list :GET Chained('root') PathPart('') Args(0) Does(RequestModel) QueryModel() {
my ($self, $c, $paging_model) = @_;
}For the body model associated with the update action, we will look for a model named Example::Model::Account:UpdateBody and for the query model associated with the list action we will look for a model named Example::Model::Account:ListQuery. You can change the default 'postfix' for both types of models by defining the following methods in your controller class:
sub default_body_postfix { return 'Body' }
sub default_query_postfix { return 'Query' }Or via the controller configuration:
__PACKAGE__->config(
default_body_postfix => 'Body',
default_query_postfix => 'Query',
);You can also prepend a namespace affix to either the body or query model name by defining the following methods in your controller class:
sub default_body_prefix_namespace { return 'MyApp::Model' }
sub default_query_prefix_namespace { return 'MyApp::Model' }Or via the controller configuration:
__PACKAGE__->config(
default_body_prefix_namespace => 'MyApp::Model',
default_query_prefix_namespace => 'MyApp::Model',
);By default both namespace prefixes are empty, while the postfixes are 'Body' and 'Query' respectively. This I think sets a reasonable pattern that you can reuse to help make your code more consistent while allowing overrides for special cases.
Alternatively you can use the action namespace of the current controller as a namespace prefix for the model name. For example, if you have the following controller:
package Example::Controller::Account;
use Moose;
use MooseX::MethodAttributes;
extends 'Catalyst::Controller';
sub root :Chained(/root) PathPart('account') CaptureArgs(0) { }
## You can use either ~ or ~:: to indicate 'under the current namespace'.
sub update :POST Chained('root') PathPart('') Args(0) Does(RequestModel) BodyModel(~::RequestBody) {
my ($self, $c, $request_model) = @_;
## Do something with the $request_model
}
sub list :GET Chained('root') PathPart('') Args(0) Does(RequestModel) QueryModel(~RequestQuery) {
my ($self, $c, $paging_model) = @_;
}
__PACKAGE__->meta->make_immutable;Then we will look for a model named Example::Model::Account::RequestBody and Example::Model::Account:RequestQuery in your application namespace. This approach also can set a query and body namespace prefix but not the postfix.
METHOD ATTRIBUTES
This action role defines the following method attributes
RequestModel
Deprecated; for now this is an alias for BodyModel. Use BodyModel instead and please convert your code to use.
BodyModel
Should be the name of a Catalyst::Model subclass that does <CatalystX::RequestModel::DoesRequestModel>. You may supply more than one value to handle different request content types (the code will match the incoming content type to an available request model and throw an CatalystX::RequestModel::Utils::InvalidContentType exception if none of the available models match.
Example of an action with more than one request model, which will be matched based on request content type.
sub update :POST Chained('root') PathPart('') Args(0) Does(RequestModel) BodyModel(AccountRequestForm) RequestModel(AccountRequestJSON) {
my ($self, $c, $request_model) = @_;
## Do something with the $request_model
}Also, if more than one model matches, you'll get an instance of each matching model.
You can also leave the BodyModel value empty; if you do so it use a default model based on the action private name. For example if the private name is /posts/user_comments we will look for a model package name MyApp::Model::Posts::UserCommentsBody. Please see "ATTRITBUTE VALUE DEFAULTS" for more on configurating and controlling how this works.
QueryModel
Should be the name of a Catalyst::Model subclass that does CatalystX::QueryModel::DoesQueryModel. You may supply more than one value to handle different request content types (the code will match the incoming content type to an available query model and throw an CatalystX::RequestModel::Utils::InvalidContentType exception if none of the available models match.
sub root :Chained(/root) PathPart('users') CaptureArgs(0) { }
sub list :GET Chained('root') PathPart('') Args(0) Does(RequestModel) QueryModel(PagingModel) {
my ($self, $c, $paging_model) = @_;
}NOTE: In the situation where you have QueryModel and BodyModel for the same action, the request models will be added first to the action argument list, followed by the query models, no matter what order they appear in the action method declaration. This is due to a limitation in how Catalyst collects the subroutine attributes (we can't know the order of dissimilar attributes since this information is stored in a hash, not an array, and Catalyst allows a controller to inherit attributes from a base class, or from a role or even from configutation). However the order of QueryModels and RequestModels independently are preserved.
You can also leave the QueryModel value empty; if you do so it use a default model based on the action private name. For example if the private name is /posts/user_comments we will look for a model package name MyApp::Model::Posts::UserCommentsQuery. Please see "ATTRITBUTE VALUE DEFAULTS" for more on configurating and controlling how this works.
BodyModelFor
QueryModelFor
Use the default models for a different action in the same controller. Useful for example if you have a lot of basic CRUD style controllers where the create and update actions need the same parameters.