1Catalyst::Model::AdaptoUrs(e3r)Contributed Perl DocumentCaattiaolnyst::Model::Adaptor(3)
2
3
4

NAME

6       Catalyst::Model::Adaptor - use a plain class as a Catalyst model
7

SYNOPSIS

9       Given a good old perl class like:
10
11           package NotMyApp::SomeClass;
12           use Moose; # to provide "new"
13           sub method { 'yay' }
14
15       Wrap it with a Catalyst model:
16
17           package MyApp::Model::SomeClass;
18           use base 'Catalyst::Model::Adaptor';
19           __PACKAGE__->config( class => 'NotMyApp::SomeClass' );
20
21       Then you can use "NotMyApp::SomeClass" from your Catalyst app:
22
23           sub action :Whatever {
24               my ($self, $c) = @_;
25               my $someclass = $c->model('SomeClass');
26               $someclass->method; # yay
27           }
28
29       Note that "NotMyApp::SomeClass" is instantiated at application startup
30       time.  If you want the adapted class to be created for call to
31       "$c->model", see Catalyst::Model::Factory instead.  If you want the
32       adapted class to be created once per request, see
33       Catalyst::Model::Factory::PerRequest.
34

DESCRIPTION

36       The idea is that you don't want your Catalyst model to be anything
37       other than a line or two of glue.  Using this module ensures that your
38       Model classes are separate from your application and therefore are
39       well-abstracted, reusable, and easily testable.
40
41       Right now there are too many modules on CPAN that are Catalyst-
42       specific.  Most of the models would be better written as a class that
43       handles most of the functionality with just a bit of glue to make it
44       work nicely with Catalyst.  This module aims to make integrating your
45       class with Catalyst trivial, so you won't have to do any extra work to
46       make your model generic.
47
48       For a good example of a Model that takes the right design approach,
49       take a look at Catalyst::Model::DBIC::Schema.  All it does is glues an
50       existing DBIx::Class::Schema to Catalyst.  It provides a bit of sugar,
51       but no actual functionality.  Everything important happens in the
52       "DBIx::Class::Schema" object.
53
54       The end result of that is that you can use your app's DBIC schema
55       without ever thinking about Catalyst.  This is a Good Thing.
56
57       Catalyst is glue, not a way of life!
58

CONFIGURATION

60       Subclasses of this model accept the following configuration keys, which
61       can be hard-coded like:
62
63          package MyApp::Model::SomeClass;
64          use base 'Catalyst::Model::Adaptor';
65          __PACKAGE__->config( class => 'NotMyApp::SomeClass' );
66
67       Or be specified as application config:
68
69          package MyApp;
70          MyApp->config->{'Model::SomeClass'} = { class => 'NotMyApp::SomeClass' };
71
72       Or in your ConfigLoader-loaded config file:
73
74          ---
75          Model::SomeClass:
76            class: NotMyApp::SomeClass
77            args:
78              foo: ...
79              bar: ...
80
81       This is exactly like every other Catalyst component, so you should
82       already know this.
83
84       Anyway, here are the options:
85
86   class
87       This is the name of the class you're adapting to Catalyst.  It MUST be
88       specified.
89
90       Your application will die horribly if it can't require this package.
91
92   constructor
93       This is the name of the class method in "class" that will create an
94       instance of the class.  It defaults to "new".
95
96       Your application will die horribly if it can't call this method.
97
98   args
99       This is a hashref of arguments to pass to the constructor of "class".
100       It is optional, of course.  If you omit it, nothing is passed to the
101       constructor (as opposed to "{}", an empty hashref).
102

METHODS

104       There are no methods that you call directly.  When you call "$c->model"
105       on a model that subclasses this, you'll get back an instance of the
106       class being adapted, not this model.
107
108       These methods are called by Catalyst:
109
110   COMPONENT
111       Setup this component.
112

CUSTOMIZING THE PROCESS

114       By default, the instance of your adapted class is instantiated like
115       this:
116
117           my $args = $self->prepare_arguments($app); # $app sometimes called $c
118           $adapted_class->$constructor($self->mangle_arguments($args));
119
120       Since a static hashref of arguments may not be what $class needs, you
121       can override the following methods to change what $args is.
122
123       NOTE: If you need to pass some args at instance time, you can do
124       something like:
125
126           my $model = $c->model('MyFoo', { foo => 'myfoo' });
127
128       or
129
130           my $model = $c->model('MyFoo', foo => 'myfoo');
131
132   prepare_arguments
133       This method is passed the entire configuration for the class and the
134       Catalyst application, and returns the hashref of arguments to be passed
135       to the constructor.  If you need to get dynamic data out of your
136       application to pass to the consturctor, do it here.
137
138       By default, this method returns the "args" configuration key.
139
140       Example:
141
142           sub prepare_arguments {
143               my ($self, $app) = @_; # $app sometimes written as $c
144               return { foobar => $app->config->{foobar}, baz => $self->{baz} };
145           }
146
147   mangle_arguments
148       This method is passed the hashref from "prepare_arguments", mangles
149       them into a form that your constructor will like, and returns the
150       mangled form.  If your constuctor wants a list instead of a hashref,
151       this is your opportunity to do the conversion.
152
153       Example:
154
155           sub mangle_arguments {
156               my ($self, $args) = @_;
157               return %$args; # now the args are a plain list
158           }
159
160       If you need to do more than this, you might as well just write the
161       whole class yourself.  This module is designed to make the common case
162       work with 1 line of code.  For special needs, it's easier to just write
163       the model yourself.
164

SEE ALSO

166       If you need a new instance returned each time "$c->model" is called,
167       use Catalyst::Model::Factory instead.
168
169       If you need to have exactly one instance created per request, use
170       Catalyst::Model::Factory::PerRequest instead.
171

AUTHOR

173       Jonathan Rockway "<jrockway@cpan.org>"
174

CONTRIBUTORS

176       Wallace Reis "<wreis@cpan.org>"
177

LICENSE

179       This module is Copyright (c) 2007 Jonathan Rockway.  You may use,
180       modify, and redistribute it under the same terms as Perl itself.
181
182
183
184perl v5.32.1                      2021-01-26       Catalyst::Model::Adaptor(3)
Impressum