NAME

CatalystX::VirtualComponents - Setup Virtual Catalyst Components Based On A Parent Application Class

SYNOPSIS

    # in your base app...
    package MyApp;
    use Catalyst;

    # in another app...
    package MyApp::Extended;
    use Moose;
    use Catalyst qw(+CatalystX::VirtualComponents);
    
    extends 'MyApp';

DESCRIPTION

WARNING: YMMV with this module.

This module provides a way to reuse controllers, models, and views from another Catalyst application.

HOW IT WORKS

Suppose you have a Catalyst application with the following components:

    # Application MyApp::Base
    MyApp::Base::Controller::Root
    MyApp::Base::Model::DBIC
    MyApp::Base::View::TT

And then in MyApp::Extended, you wanted to reuse these components -- except you want to customize the Root controller, and you want to add another model (say, Model::XML::Feed).

In your new app, you can skip creating MyApp::Extended::Model::DBIC and MyApp::Extended::View::TT -- CatalystX::VirtualComponents will take care of these.

Just provide the customized Root controller and the new model:

    package MyApp::Extended::Controller::Root;
    use Moose;

    BEGIN { extends 'MyApp::Base::Controller::Root' }

    sub new_action :Path('new_action') {
        ....
    }

(We will skip XML::Feed, as it's just a regular model)

Then, in MyApp::Extended

    packge MyApp::Extended;
    use Moose;
    use Catalyst;

    extends 'MyApp::Base';

Note that MyApp::Extended inherits from MyApp::Base. Naturally, if you are inheriting from an application, you'd probably want to inherit all of its controllers and such. To do this, specify CatalystX::VirtualComponents in the Catalyst plugin list for MyApp::Extended:

    __PACKAGE__->setup( qw(
        ... # your regular Catalyst plugins
        +CatalystX::VirtualComponent
    ) );

When setup() is run, CatalystX::VirtualComponent will intercept the component setup code and will automatically create virtual subclasses for components that exist in MyApp::Base, but not in MyApp::Extended. In the above case, MyApp::Extended::View::TT and MyApp::Extended::Model::DBIC will be created.

MyApp::Extended::Controller::Root takes precedence over the base class, so only the local component will be loaded. MyApp::Extended::Model::XML::Feed only exists in the MyApp::Extended namespace, so it just works like a normal Catalyst model.

GENERATING VIRTUAL CLASSES WITHOUT INHERITANCE

If you don't want to subclass, or use a more fine-grained control on which namespaces to look for base components, specify the namespaces in a config element:

    __PACKAGE__->config(
        VirtualComponents => {
            inherit => [
                'NamespaceA',
                'NamespaceB'
            ]
        }
    );

USING IN CONJUNCTION WITH CatalystX::AppBuilder

Simply add CatalystX::VirtualComponents in the plugin list:

    package MyApp::Extended::Builder;
    use Moose;

    extends 'CatalystX::AppBuilder';

    override _build_plugins {
        my $plugins = super();
        push @$plugins, '+CatalystX::VirtualComponents';
        return $plugins;
    };

    1;

METHODS

search_components($class)

Finds the list of components for Catalyst app $class.

setup_components()

Overrides Catalyst's setup_components() method.

TODO

Documentation. Samples. Tests.

AUTHOR

Daisuke Maki <daisuke@endeworks.jp>

LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://www.perl.com/perl/misc/Artistic.html

cpanm CatalystX::VirtualComponents

perl -MCPAN -e shell
install CatalystX::VirtualComponents