.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Catalyst::Model::Adaptor 3pm" .TH Catalyst::Model::Adaptor 3pm "2022-06-09" "perl v5.34.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Catalyst::Model::Adaptor \- use a plain class as a Catalyst model .SH "SYNOPSIS" .IX Header "SYNOPSIS" Given a good old perl class like: .PP .Vb 3 \& package NotMyApp::SomeClass; \& use Moose; # to provide "new" \& sub method { \*(Aqyay\*(Aq } .Ve .PP Wrap it with a Catalyst model: .PP .Vb 3 \& package MyApp::Model::SomeClass; \& use base \*(AqCatalyst::Model::Adaptor\*(Aq; \& _\|_PACKAGE_\|_\->config( class => \*(AqNotMyApp::SomeClass\*(Aq ); .Ve .PP Then you can use \f(CW\*(C`NotMyApp::SomeClass\*(C'\fR from your Catalyst app: .PP .Vb 5 \& sub action :Whatever { \& my ($self, $c) = @_; \& my $someclass = $c\->model(\*(AqSomeClass\*(Aq); \& $someclass\->method; # yay \& } .Ve .PP Note that \f(CW\*(C`NotMyApp::SomeClass\*(C'\fR is instantiated at application startup time. If you want the adapted class to be created for call to \f(CW\*(C`$c\->model\*(C'\fR, see Catalyst::Model::Factory instead. If you want the adapted class to be created once per request, see Catalyst::Model::Factory::PerRequest. .SH "DESCRIPTION" .IX Header "DESCRIPTION" The idea is that you don't want your Catalyst model to be anything other than a line or two of glue. Using this module ensures that your Model classes are separate from your application and therefore are well-abstracted, reusable, and easily testable. .PP Right now there are too many modules on \s-1CPAN\s0 that are Catalyst-specific. Most of the models would be better written as a class that handles most of the functionality with just a bit of glue to make it work nicely with Catalyst. This module aims to make integrating your class with Catalyst trivial, so you won't have to do any extra work to make your model generic. .PP For a good example of a Model that takes the right design approach, take a look at Catalyst::Model::DBIC::Schema. All it does is glues an existing DBIx::Class::Schema to Catalyst. It provides a bit of sugar, but no actual functionality. Everything important happens in the \f(CW\*(C`DBIx::Class::Schema\*(C'\fR object. .PP The end result of that is that you can use your app's \s-1DBIC\s0 schema without ever thinking about Catalyst. This is a Good Thing. .PP Catalyst is glue, not a way of life! .SH "CONFIGURATION" .IX Header "CONFIGURATION" Subclasses of this model accept the following configuration keys, which can be hard-coded like: .PP .Vb 3 \& package MyApp::Model::SomeClass; \& use base \*(AqCatalyst::Model::Adaptor\*(Aq; \& _\|_PACKAGE_\|_\->config( class => \*(AqNotMyApp::SomeClass\*(Aq ); .Ve .PP Or be specified as application config: .PP .Vb 2 \& package MyApp; \& MyApp\->config\->{\*(AqModel::SomeClass\*(Aq} = { class => \*(AqNotMyApp::SomeClass\*(Aq }; .Ve .PP Or in your ConfigLoader-loaded config file: .PP .Vb 6 \& \-\-\- \& Model::SomeClass: \& class: NotMyApp::SomeClass \& args: \& foo: ... \& bar: ... .Ve .PP This is exactly like every other Catalyst component, so you should already know this. .PP Anyway, here are the options: .SS "class" .IX Subsection "class" This is the name of the class you're adapting to Catalyst. It \s-1MUST\s0 be specified. .PP Your application will die horribly if it can't require this package. .SS "constructor" .IX Subsection "constructor" This is the name of the class method in \f(CW\*(C`class\*(C'\fR that will create an instance of the class. It defaults to \f(CW\*(C`new\*(C'\fR. .PP Your application will die horribly if it can't call this method. .SS "args" .IX Subsection "args" This is a hashref of arguments to pass to the constructor of \f(CW\*(C`class\*(C'\fR. It is optional, of course. If you omit it, nothing is passed to the constructor (as opposed to \f(CW\*(C`{}\*(C'\fR, an empty hashref). .SH "METHODS" .IX Header "METHODS" There are no methods that you call directly. When you call \f(CW\*(C`$c\->model\*(C'\fR on a model that subclasses this, you'll get back an instance of the class being adapted, not this model. .PP These methods are called by Catalyst: .SS "\s-1COMPONENT\s0" .IX Subsection "COMPONENT" Setup this component. .SH "CUSTOMIZING THE PROCESS" .IX Header "CUSTOMIZING THE PROCESS" By default, the instance of your adapted class is instantiated like this: .PP .Vb 2 \& my $args = $self\->prepare_arguments($app); # $app sometimes called $c \& $adapted_class\->$constructor($self\->mangle_arguments($args)); .Ve .PP Since a static hashref of arguments may not be what \f(CW$class\fR needs, you can override the following methods to change what \f(CW$args\fR is. .PP \&\s-1NOTE:\s0 If you need to pass some args at instance time, you can do something like: .PP .Vb 1 \& my $model = $c\->model(\*(AqMyFoo\*(Aq, { foo => \*(Aqmyfoo\*(Aq }); .Ve .PP or .PP .Vb 1 \& my $model = $c\->model(\*(AqMyFoo\*(Aq, foo => \*(Aqmyfoo\*(Aq); .Ve .SS "prepare_arguments" .IX Subsection "prepare_arguments" This method is passed the entire configuration for the class and the Catalyst application, and returns the hashref of arguments to be passed to the constructor. If you need to get dynamic data out of your application to pass to the consturctor, do it here. .PP By default, this method returns the \f(CW\*(C`args\*(C'\fR configuration key. .PP Example: .PP .Vb 4 \& sub prepare_arguments { \& my ($self, $app) = @_; # $app sometimes written as $c \& return { foobar => $app\->config\->{foobar}, baz => $self\->{baz} }; \& } .Ve .SS "mangle_arguments" .IX Subsection "mangle_arguments" This method is passed the hashref from \f(CW\*(C`prepare_arguments\*(C'\fR, mangles them into a form that your constructor will like, and returns the mangled form. If your constuctor wants a list instead of a hashref, this is your opportunity to do the conversion. .PP Example: .PP .Vb 4 \& sub mangle_arguments { \& my ($self, $args) = @_; \& return %$args; # now the args are a plain list \& } .Ve .PP If you need to do more than this, you might as well just write the whole class yourself. This module is designed to make the common case work with 1 line of code. For special needs, it's easier to just write the model yourself. .SH "SEE ALSO" .IX Header "SEE ALSO" If you need a new instance returned each time \f(CW\*(C`$c\->model\*(C'\fR is called, use Catalyst::Model::Factory instead. .PP If you need to have exactly one instance created per request, use Catalyst::Model::Factory::PerRequest instead. .SH "AUTHOR" .IX Header "AUTHOR" Jonathan Rockway \f(CW\*(C`\*(C'\fR .SH "CONTRIBUTORS" .IX Header "CONTRIBUTORS" Wallace Reis \f(CW\*(C`\*(C'\fR .SH "LICENSE" .IX Header "LICENSE" This module is Copyright (c) 2007 Jonathan Rockway. You may use, modify, and redistribute it under the same terms as Perl itself.