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

FreeBSD Manual Pages


home | help

       Catalyst::Manual::Tutorial::02_CatalystBasics - Catalyst	Tutorial -
       Chapter 2: Catalyst Application Development Basics

       This is Chapter 2 of 10 for the Catalyst	tutorial.

       Tutorial	Overview

       1.  Introduction

       2.  02_Catalyst Basics

       3.  More	Catalyst Basics

       4.  Basic CRUD

       5.  Authentication

       6.  Authorization

       7.  Debugging

       8.  Testing

       9.  Advanced CRUD

       10. Appendices

       In this chapter of the tutorial,	we will	create a very basic Catalyst
       web application,	demonstrating a	number of powerful capabilities, such

       o   Helper Scripts

	   Catalyst helper scripts that	can be used to rapidly bootstrap the
	   skeletal structure of an application.

       o   MVC

	   Model/View/Controller (MVC) provides	an architecture	that
	   facilitates a clean "separation of control" between the different
	   portions of your application. Given that many other documents cover
	   this	subject	in detail, MVC will not	be discussed in	depth here
	   (for	an excellent introduction to MVC and general Catalyst
	   concepts, please see	Catalyst::Manual::About). In short:

	   o   Model

	       The model usually represents a data store. In most
	       applications, the model equates to the objects that are created
	       from and	saved to your SQL database.

	   o   View

	       The view	takes model objects and	renders	them into something
	       for the end user	to look	at. Normally this involves a template-
	       generation tool that creates HTML for the user's	web browser,
	       but it could easily be code that	generates other	forms such as
	       PDF documents, e-mails, spreadsheets, or	even "behind the
	       scenes" formats such as XML and JSON.

	   o   Controller

	       As suggested by its name, the controller	takes user requests
	       and routes them to the necessary	model and view.

       o   ORM

	   The use of Object-Relational	Mapping	(ORM) technology for database
	   access. Specifically, ORM provides an automated and standardized
	   means to persist and	restore	objects	to/from	a relational database
	   and will automatically create our Catalyst model for	use with a

       You can checkout	the source code	for this example from the catalyst
       subversion repository as	per the	instructions in

       Catalyst	provides a number of helper scripts that can be	used to
       quickly flesh out the basic structure of	your application. All Catalyst
       projects	begin with the helper (see Catalyst::Helper	for
       more information	on helpers).  Also note	that as	of Catalyst 5.7000,
       you will	not have the helper scripts unless you install both
       Catalyst::Runtime and Catalyst::Devel.

       In this first chapter of	the tutorial, use the Catalyst
       script to initialize the	framework for an application called "Hello":

	   $ Hello
	   created "Hello"
	   created "Hello/script"
	   created "Hello/lib"
	   created "Hello/root"
	   created "Hello/script/"
	   Change to application directory and Run "perl Makefile.PL" to make sure your	install	is complete
	   $ cd	Hello

       Note: If	you are	using Strawberry Perl on Win32,	drop the ".pl" from
       the end of the "" command and	simply use "catalyst Hello".

       The helper script will display the names of the directories
       and files it creates:

	   Changes		 # Record of application changes
	   lib			 # Lib directory for your app's	Perl modules
	       Hello		 # Application main code directory
		   Controller	 # Directory for Controller modules
		   Model	 # Directory for Models
		   View		 # Directory for Views		 # Base	application module
	   Makefile.PL		 # Makefile to build application
	   hello.conf		 # Application configuration file
	   README		 # README file
	   root			 # Equiv of htdocs, dir	for templates, css, javascript
	       static		 # Directory for static	files
		   images	 # Directory for image files used in welcome screen
	   script		 # Directory for Perl scripts	 # To run your app as a	cgi (not recommended)	 # To create models, views, controllers	 # To run app as a fastcgi program	 # The normal development server	 # Test	your app from the command line
	   t			 # Directory for tests
	       01app.t		 # Test	scaffold

       Catalyst	will "auto-discover" modules in	the Controller,	Model, and
       View directories. When you use the script it will
       create Perl module scaffolds in those directories, plus test files in
       the "t" directory. The default location for templates is	in the "root"
       directory. The scripts in the script directory will always start	with
       the lowercased version of your application name.	If your	app is MaiTai,
       then the	create script would be "".

       Though it's too early for any significant celebration, we already have
       a functioning application. We can use the Catalyst supplied script to
       start up	a development server and view the default Catalyst page	in
       your browser. All scripts in the	script directory should	be run from
       the base	directory of your application, so change to the	Hello

       Run the following command to start up the built-in development web
       server (make sure you didn't forget the ""cd Hello"" from the previous

       Note: The "-r" argument enables reloading on code changes so you	don't
       have to stop and	start the server when you update code. See "perldoc
       script/" or "script/ --help" for
       additional options you might find helpful. Most of the rest of the
       tutorial	will assume that you are using "-r" when you start the
       development server, but feel free to manually start and stop it (use
       "Ctrl-C"	to breakout of the dev server) if you prefer.

	   $ script/ -r
	   [debug] Debug messages enabled
	   [debug] Statistics enabled
	   [debug] Loaded plugins:
	   | Catalyst::Plugin::ConfigLoader  0.30					|

	   [debug] Loaded dispatcher "Catalyst::Dispatcher"
	   [debug] Loaded engine "Catalyst::Engine"
	   [debug] Found home "/home/catalyst/Hello"
	   [debug] Loaded Config "/home/catalyst/Hello/hello.conf"
	   [debug] Loaded components:
	   | Class							     | Type	|
	   | Hello::Controller::Root					     | instance	|

	   [debug] Loaded Private actions:
	   | Private		  | Class				 | Method	|
	   | /default		  | Hello::Controller::Root		 | default	|
	   | /end		  | Hello::Controller::Root		 | end		|
	   | /index		  | Hello::Controller::Root		 | index	|

	   [debug] Loaded Path actions:
	   | Path				 | Private				|
	   | /					 | /index				|
	   | /					 | /default				|

	   [info] Hello	powered	by Catalyst 5.90002
	   HTTP::Server::PSGI: Accepting connections at	http://0:3000/

       Point your web browser to <http://localhost:3000> (substituting a
       different hostname or IP	address	as appropriate)	and you	should be
       greeted by the Catalyst welcome screen (if you get some other welcome
       screen or an "Index" screen, you	probably forgot	to specify port	3000
       in your URL).  Information similar to the following should be appended
       to the logging output of	the development	server:

	   [info] Hello	powered	by Catalyst 5.90002
	   HTTP::Server::PSGI: Accepting connections at	http://0:3000/
	   [info] *** Request 1	(0.067/s) [19026] [Tue Aug 30 17:24:32 2011] ***
	   [debug] "GET" request for "/" from ""
	   [debug] Path	is "/"
	   [debug] Response Code: 200; Content-Type: text/html;	charset=utf-8; Content-Length: 5613
	   [info] Request took 0.040895s (24.453/s)
	   | Action							| Time	    |
	   | /index							| 0.000916s |
	   | /end							| 0.000877s |

       Note: Press "Ctrl-C" to break out of the	development server if

   The Simplest	Way
       The controller is a place to put	global actions that usually
       execute on the root URL.	Open the lib/Hello/Controller/ file in
       your editor. You	will see the "index" subroutine, which is responsible
       for displaying the welcome screen that you just saw in your browser.

	   sub index :Path :Args(0) {
	       my ( $self, $c )	= @_;

	       # Hello World
	       $c->response->body( $c->welcome_message );

       Later on	you'll want to change that to something	more reasonable, such
       as a "404" message or a redirect, but for now just leave	it alone.

       The "$c"	here refers to the Catalyst context, which is used to access
       the Catalyst application. In addition to	many other things, the
       Catalyst	context	provides access	to "response" and "request" objects.
       (See Catalyst::Runtime, Catalyst::Response, and Catalyst::Request)

       "$c->response->body" sets the HTTP response (see	Catalyst::Response),
       while "$c->welcome_message" is a	special	method that returns the
       welcome message that you	saw in your browser.

       The "":Path :Args(0)"" after the	method name are	attributes which
       determine which URLs will be dispatched to this method. (You might see
       ":Private" if you are using an older version of Catalyst, but using
       that with "default" or "index" is currently deprecated.	If so, you
       should also probably upgrade before continuing the tutorial.)

       Some MVC	frameworks handle dispatching in a central place. Catalyst, by
       policy, prefers to handle URL dispatching with attributes on controller
       methods.	There is a lot of flexibility in specifying which URLs to
       match.  This particular method will match all URLs, because it doesn't
       specify the path	(nothing comes after "Path"), but will only accept a
       URL without any args because of the ":Args(0)".

       The default is to map URLs to controller	names, and because of the way
       that Perl handles namespaces through package names, it is simple	to
       create hierarchical structures in Catalyst. This	means that you can
       create controllers with deeply nested actions in	a clean	and logical
       way. For	example, the URL "" maps
       to the package "Hello::Controller::Admin::Articles", and	the "create"

       While you leave the "script/ -r" command running the
       development server in one window	(don't forget the "-r" at the end!),
       open another window and add the following subroutine to your
       lib/Hello/Controller/ file:

	   sub hello :Global {
	       my ( $self, $c )	= @_;

	       $c->response->body("Hello, World!");

       TIP: See	Appendix 1 for tips on removing	the leading spaces when
       cutting and pasting example code	from POD-based documents.

       Notice in the window running the	Development Server that	you should get
       output similar to the following:

	   Saw changes to the following	files:
	    - /home/catalyst/Hello/lib/Hello/Controller/	(modify)

	   Attempting to restart the server
	   [debug] Loaded Private actions:
	   | Private		  | Class				 | Method	|
	   | /default		  | Hello::Controller::Root		 | default	|
	   | /end		  | Hello::Controller::Root		 | end		|
	   | /index		  | Hello::Controller::Root		 | index	|
	   | /hello		  | Hello::Controller::Root		 | hello	|

       The development server noticed the change in "Hello::Controller::Root"
       and automatically restarted itself.

       Go to <http://localhost:3000/hello> to see "Hello, World!".   Also
       notice that the newly defined 'hello' action is listed under "Loaded
       Private actions"	in the development server debug	output.

   Hello, World! Using a View and a Template
       In the Catalyst world a "View" itself is	not a page of XHTML or a
       template	designed to present a page to a	browser. Rather, it is the
       module that determines the type of view -- HTML,	PDF, XML, etc. For the
       thing that generates the	content	of that	view (such as a	Template
       Toolkit template	file), the actual templates go under the "root"

       To create a TT view, run:

	   $ script/ view HTML TT

       This creates the	lib/Hello/View/ module, which is	a subclass of

       o   The "view" keyword tells the	create script that you are creating a

       o   The first argument "HTML" tells the script to name the View module
	   "", which is a commonly used name for	TT views.  You can
	   name	it anything you	want, such as "". If you have more
	   than	one view, be sure to set the default_view in (See
	   Catalyst::View::TT for more details on setting this).

       o   The final "TT" tells	Catalyst the type of the view, with "TT"
	   indicating that you want to use a Template Toolkit view.

       If you look at lib/Hello/View/ you will find that	it only
       contains	a config statement to set the TT extension to ".tt".

       Now that	the "View" exists, Catalyst will autodiscover it and
       be able to use it to display the	view templates using the "process"
       method that it inherits from the	Catalyst::View::TT class.

       Template	Toolkit	is a very full-featured	template facility, with
       excellent documentation at <>, but since
       this is not a TT	tutorial, we'll	stick to only basic TT usage here (and
       explore some of the more	common TT features in later chapters of	the

       Create a	root/ template file (put it in the "root" under	the
       "Hello" directory that is the base of your application).	Here is	a
       simple sample:

	       This is a TT view template, called '[% %]'.

       [% and %] are markers for the TT	parts of the template. Inside you can
       access Perl variables and classes, and use TT directives. In this case,
       we're using a special TT	variable that defines the name of the template
       file (	 The rest of the template is normal HTML.

       Change the hello	method in lib/Hello/Controller/ to the

	   sub hello :Global {
	       my ( $self, $c )	= @_;

	       $c->stash(template => '');

       This time, instead of doing "$c->response->body()", you are setting the
       value of	the "template" hash key	in the Catalyst	"stash", an area for
       putting information to share with other parts of	your application. The
       "template" key determines which template	will be	displayed at the end
       of the request cycle. Catalyst controllers have a default "end" action
       for all methods which causes the	first (or default) view	to be rendered
       (unless there's a "$c->response->body()"	statement). So your template
       will be magically displayed at the end of your method.

       After saving the	file, the development server should automatically
       restart (again, the tutorial is written to assume that you are using
       the "-r"	option -- manually restart it if you aren't), and look at
       <http://localhost:3000/hello> in	your web browser again.	You should see
       the template that you just created.

       TIP: If you keep	the server running with	"-r" in	a "background window,"
       don't let that window get totally hidden... if you have a syntax	error
       in your code, the debug server output will contain the error

       Note: You will probably run into	a variation of the "stash" statement
       above that looks	like:

	   $c->stash->{template} = '';

       Although	this style is still relatively common, the approach we used
       previous	is becoming more common	because	it allows you to set multiple
       stash variables in one line.  For example:

	   $c->stash(template => '', foo => 'bar',
		     another_thing => 1);

       You can also set	multiple stash values with a hashref:

	   $c->stash({template => '', foo => 'bar',
		     another_thing => 1});

       Any of these formats work, but the "$c->stash(name => value);" style is
       growing in popularity --	you may	wish to	use it all the time (even when
       you are only setting a single value).

       Create a	controller named "Site"	by executing the create	script:

	   $ script/ controller Site

       This will create	a lib/Hello/Controller/ file (and a test	file).
       If you bring up in your editor, you can see that	there's	not
       much there to see.

       In lib/Hello/Controller/,	add the	following method:

	   sub test :Local {
	       my ( $self, $c )	= @_;

	       $c->stash(username => 'John',
			 template => 'site/');

       Notice the "Local" attribute on the "test" method. This will cause the
       "test" action (now that we have assigned	an "action type" to the	method
       it appears as a "controller action" to Catalyst)	to be executed on the
       "controller/method" URL,	or, in this case, "site/test".	We will	see
       additional information on controller actions throughout the rest	of the
       tutorial, but if	you are	curious	take a look at "Actions" in

       It's not	actually necessary to set the template value as	we do here.
       By default TT will attempt to render a template that follows the	naming
       pattern "controller/", and we're following that	pattern	here.
       However,	in other situations you	will need to specify the template
       (such as	if you've "forwarded" to the method, or	if it doesn't follow
       the default naming convention).

       We've also put the variable "username" into the stash, for use in the

       Make a subdirectory "site" in the "root"	directory.

	   $ mkdir root/site

       Create a	new template file in that directory named root/site/
       and include a line like:

	   <p>Hello, [%	username %]!</p>

       Once the	server automatically restarts, notice in the server output
       that "/site/test" is listed in the Loaded Path actions.	Go to
       <http://localhost:3000/site/test> in your browser and you should	see
       your file displayed, including the name "John" that you set in
       the controller.

       You can jump to the next	chapter	of the tutorial	here: More Catalyst

       Gerda Shank, "" Kennedy Clark, ""

       Feel free to contact the	author for any errors or suggestions, but the
       best way	to report issues is via	the CPAN RT Bug	system at

       Copyright 2006-2011, Kennedy Clark, under the Creative Commons
       Attribution Share-Alike License Version 3.0

perl v5.32.1		      Catalyst::Manual::Tutorial::02_CatalystBasics(3)


Want to link to this manual page? Use this URL:

home | help