1Catalyst::Model::AdaptoUrs(e3r)Contributed Perl DocumentCaattiaolnyst::Model::Adaptor(3)
2
6 Catalyst::Model::Adaptor - use a plain class as a Catalyst model
7
9 Given a good old perl class like:
10 package NotMyApp::SomeClass;
12 use Moose; # to provide "new"
13 sub method { 'yay' }
14 Wrap it with a Catalyst model:
16 package MyApp::Model::SomeClass;
18 use base 'Catalyst::Model::Adaptor';
19 __PACKAGE__->config( class => 'NotMyApp::SomeClass' );
20 Then you can use "NotMyApp::SomeClass" from your Catalyst app:
22 sub action :Whatever {
24 my ($self, $c) = @_;
25 my $someclass = $c->model('SomeClass');
26 $someclass->method; # yay
27 }
28 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
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 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 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 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 Catalyst is glue, not a way of life!
58
60 Subclasses of this model accept the following configuration keys, which
61 can be hard-coded like:
62 package MyApp::Model::SomeClass;
64 use base 'Catalyst::Model::Adaptor';
65 __PACKAGE__->config( class => 'NotMyApp::SomeClass' );
66 Or be specified as application config:
68 package MyApp;
70 MyApp->config->{'Model::SomeClass'} = { class => 'NotMyApp::SomeClass' };
71 Or in your ConfigLoader-loaded config file:
73 ---
75 Model::SomeClass:
76 class: NotMyApp::SomeClass
77 args:
78 foo: ...
79 bar: ...
80 This is exactly like every other Catalyst component, so you should
82 already know this.
83 Anyway, here are the options:
85 class
87 This is the name of the class you're adapting to Catalyst. It MUST be
88 specified.
89 Your application will die horribly if it can't require this package.
91 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 Your application will die horribly if it can't call this method.
97 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
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 These methods are called by Catalyst:
109 COMPONENT
111 Setup this component.
112
114 By default, the instance of your adapted class is instantiated like
115 this:
116 my $args = $self->prepare_arguments($app); # $app sometimes called $c
118 $adapted_class->$constructor($self->mangle_arguments($args));
119 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 NOTE: If you need to pass some args at instance time, you can do
124 something like:
125 my $model = $c->model('MyFoo', { foo => 'myfoo' });
127 or
129 my $model = $c->model('MyFoo', foo => 'myfoo');
131 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 By default, this method returns the "args" configuration key.
139 Example:
141 sub prepare_arguments {
143 my ($self, $app) = @_; # $app sometimes written as $c
144 return { foobar => $app->config->{foobar}, baz => $self->{baz} };
145 }
146 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 Example:
154 sub mangle_arguments {
156 my ($self, $args) = @_;
157 return %$args; # now the args are a plain list
158 }
159 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
166 If you need a new instance returned each time "$c->model" is called,
167 use Catalyst::Model::Factory instead.
168 If you need to have exactly one instance created per request, use
170 Catalyst::Model::Factory::PerRequest instead.
171
173 Jonathan Rockway "<jrockway@cpan.org>"
174
176 Wallace Reis "<wreis@cpan.org>"
177
179 This module is Copyright (c) 2007 Jonathan Rockway. You may use,
180 modify, and redistribute it under the same terms as Perl itself.
181perl v5.28.0 2011-02-23 Catalyst::Model::Adaptor(3)