Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
CatalystX::AppBuilder(User Contributed Perl DocumentatCatalystX::AppBuilder(3)

NAME
       CatalystX::AppBuilder - Build Your Application Instance Programatically

SYNOPSIS
	   # In	MyApp.pm
	   my $builder = CatalystX::AppBuilder->new(
	       appname => 'MyApp',
	       plugins => [ ...	],
	   )
	   $builder->bootstrap();

DESCRIPTION
       WARNING:	YMMV regarding this module.

       This module gives you a programatic interface to	configuring Catalyst
       applications.

       The main	motivation to write this module	is: to write reusable Catalyst
       appllications. For instance, if you build your MyApp::Base and you
       wanted to create	a new application afterwards that is mostly like
       MyApp::Base, but	slightly tweaked. Perhaps you want to add or remove a
       plugin or two.  Perhaps you want	to tweak just a	single parameter.

       Traditionally, your option then was to use catalyst.pl and create
       another scaffold, and copy/paste	the necessary bits, and	tweak what you
       need.

       After testing several approaches, it proved that	the current Catalyst
       architecture (which is Moose based, but does not	allow us to use	Moose-
       ish initialization, since the Catalyst app instance does	not
       materialize until dispatch time)	did not	allow the type of inheritance
       behavior	we wanted, so we decided to create a builder module around
       Catalyst	to overcome this.  Therefore, if/when these obstacles (to us)
       are gone, this module may simply	dissappear from	CPAN. You've been
       warned.

HOW TO USE
   DEFINING A CATALYST APP
       This module is NOT a "just-execute-this-command-and-you-get-catalyst-
       running"	module.	For the	simple applications, please just follow	what
       the Catalyst manual gives you.

       However,	if you really wanted to, you can define	a simple Catalyst app
       like so:

	   # in	MyApp.pm
	   use strict;
	   use CatalystX::AppBuilder;

	   my $builder = CatalystX::AppBuilder->new(
	       debug  => 1, # if you want
	       appname => "MyApp",
	       plugins => [ qw(
		   Authentication
		   Session
		   # and others...
	       ) ],
	       config  => { ...	}
	   );

	   $builder->bootstrap();

   DEFINING YOUR CatalystX::AppBuilder SUBCLASS
       The originally intended approach	to using this module is	to create a
       subclass	of CatalystX::AppBuilder and configure it to your own needs,
       and then	keep reusing it.

       To build	your own MyApp::Builder, you just need to subclass it:

	   package MyApp::Builder;
	   use Moose;

	   extends 'CatalystX::AppBuilder';

       Then you	will be	able to	give it	defaults to the	various	configuration
       parameters:

	   override _build_config => sub {
	       my $config = super(); # Get what	CatalystX::AppBuilder gives you
	       $config->{ SomeComponent	} = { ... };
	       return $config;
	   };

	   override _build_plugins => sub {
	       my $plugins = super(); #	Get what CatalystX::AppBuilder gives you

	       push @$plugins, qw(
		   Unicode
		   Authentication
		   Session
		   Session::Store::File
		   Session::State::Cookie
	       );

	       return $plugins;
	   };

       Then you	can simply do this instead of giving parameters	to
       CatalystX::AppBuilder every time:

	   # in	MyApp.pm
	   use MyApp::Builder;
	   MyApp::Builder->new()->bootstrap();

   EXTENDING A CATALYST	APP USING CatalystX::AppBuilder
       Once you	created	your own MyApp::Builder, you can keep inheriting it to
       create custom Builders which in turn create more	custom Catalyst
       applications:

	   package MyAnotherApp::Builder;
	   use Moose;

	   extends 'MyApp::Builder';

	   override _build_superclasses	=> sub {
	       return [	'MyApp'	]
	   }

	   ... do your tweaking	...

	   # in	MyAnotherApp.pm
	   use MyAnotherApp::Builder;

	   MyAnotherApp::Builder->new()->bootstrap();

       Voila, you just reused every inch of Catalyst app that you created via
       inheritance!

   INCLUDING EVERY PATH	FROM YOUR INHERITANCE HIERARCHY
       Components like Catalyst::View::TT, which in turn uses Template Toolkit
       inside, allows you to include multiple directories to look for the
       template	files.

       This can	be used	to recycle the templates that you used in a base
       application.

       CatalystX::AppBuilder gives you a couple	of tools to easily include
       paths that are associated with all of the Catalyst applications that
       are inherited. For example, if you have MyApp::Base and
       MyApp::Extended,	and MyApp::Extended is built using
       MyApp::Extended::Builder, you can do something like this:

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

	   extends 'CatalystX::AppBuilder';

	   override _build_superclasses	=> sub {
	       return [	'MyApp::Base' ]
	   };

	   override _build_config => sub {
	       my $self	= shift;
	       my $config = super();

	       $config->{'View::TT'}->{INCLUDE_PATH} =
		   [ $self->inherited_path_to('root') ];
	       # Above is equivalent to
	       #    [ MyApp::Extended->path_to('root'),	MyApp::Base->path_to('root') ]
	   };

       So now you can refer to some template, and it will first	look under the
       first app, then the base	app, thus allowing you to reuse	the templates.

ATTRIBUTES
   appname
       The module name of the Catalyst application. Required.

   appmeta
       The metaclass object of the Catalyst application. Users cannot set
       this.

   debug
       Boolean flag to enable debug output in the application

   version
       The version string to use (probably meaningless...)

   superclasses
       The list	of superclasses	of the Catalyst	application.

   config
       The config hash to give to the Catalyst application.

   plugins
       The list	of plugins to give to the Catalyst application.

METHODS
   bootstrap($runsetup)
       Bootstraps the Catalyst app.

   inherited_path_to(@pathspec)
       Calls path_to() on all Catalyst applications in the inheritance tree.

   app_path_to(@pathspec);
       Calls path_to() on the curent Catalyst application.

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

perl v5.24.1			  2016-02-26	      CatalystX::AppBuilder(3)

NAME | SYNOPSIS | DESCRIPTION | HOW TO USE | ATTRIBUTES | METHODS | TODO | AUTHOR | LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=CatalystX::AppBuilder&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help