Creating the application skeleton
Catalyst comes with a script called catalyst.pl to make this task as simple as possible. catalyst.pl takes a single argument, the application’s name, and creates an application with that specified name. The name can be any valid Perl module name such as MyApp or MyCompany::HR::Timesheets.
Let’s get started by creating MyApp, which is the example application for this article:
$ catalyst.pl MyApp
created "MyApp"
created "MyApp/script"
created "MyApp/lib"
created "MyApp/root"
created "MyApp/root/static"
created "MyApp/root/static/images"
created "MyApp/t"
created "MyApp/lib/MyApp"
created "MyApp/lib/MyApp/Model"
created "MyApp/lib/MyApp/View"
18 ]
created "MyApp/lib/MyApp/Controller"
created "MyApp/myapp.conf"
created "MyApp/lib/MyApp.pm"
created "MyApp/lib/MyApp/Controller/Root.pm"
created "MyApp/README"
created "MyApp/Changes"
created "MyApp/t/01app.t"
created "MyApp/t/02pod.t"
created "MyApp/t/03podcoverage.t"
created "MyApp/root/static/images/catalyst_logo.png"
created "MyApp/root/static/images/btn_120x50_built.png"
created "MyApp/root/static/images/btn_120x50_built_shadow.png"
created "MyApp/root/static/images/btn_120x50_powered.png"
created "MyApp/root/static/images/btn_120x50_powered_shadow.png"
created "MyApp/root/static/images/btn_88x31_built.png"
created "MyApp/root/static/images/btn_88x31_built_shadow.png"
created "MyApp/root/static/images/btn_88x31_powered.png"
created "MyApp/root/static/images/btn_88x31_powered_shadow.png"
created "MyApp/root/favicon.ico"
created "MyApp/Makefile.PL"
created "MyApp/script/myapp_cgi.pl"
created "MyApp/script/myapp_fastcgi.pl"
created "MyApp/script/myapp_server.pl"
created "MyApp/script/myapp_test.pl"
created "MyApp/script/myapp_create.pl"
Change to application directory, and run "perl Makefile.PL" to make sure
your installation is complete.
At this point it is a good idea to check if the installation is complete by switching to the newly-created directory (cd MyApp) and running perl Makefile.PL. You should see something like the following:
$ perl Makefile.PL
include /Volumes/Home/Users/solar/Projects/CatalystBook/MyApp/inc/Module/
Install.pm
include inc/Module/Install/Metadata.pm
include inc/Module/Install/Base.pm
Cannot determine perl version info from lib/MyApp.pm
include inc/Module/Install/Catalyst.pm
*** Module::Install::Catalyst
include inc/Module/Install/Makefile.pm
Please run "make catalyst_par" to create the PAR package!
*** Module::Install::Catalyst finished.
include inc/Module/Install/Scripts.pm
include inc/Module/Install/AutoInstall.pm
include inc/Module/Install/Include.pm
include inc/Module/AutoInstall.pm
*** Module::AutoInstall version 1.03
*** Checking for Perl dependencies...
[Core Features]
- Test::More ...loaded. (0.94 >= 0.88)
- Catalyst::Runtime ...loaded. (5.80021 >= 5.80021)
- Catalyst::Plugin::ConfigLoader ...loaded. (0.23)
- Catalyst::Plugin::Static::Simple ...loaded. (0.29)
- Catalyst::Action::RenderView ...loaded. (0.14)
- Moose ...loaded. (0.99)
- namespace::autoclean ...loaded. (0.09)
- Config::General ...loaded. (2.42)
*** Module::AutoInstall configuration finished.
include inc/Module/Install/WriteAll.pm
include inc/Module/Install/Win32.pm
include inc/Module/Install/Can.pm
include inc/Module/Install/Fetch.pm
Writing Makefile for MyApp
Writing META.yml
Note that it mentions that all the required modules are available. If any modules are missing, you may have to install those modules using cpan.You can also alternatively install the missing modules by running make followed by make install.
We will discuss what each of these files do but for now, let’s just change to the newly-created MyApp directory (cd MyApp) and run the following command:
$ perl script/myapp_server.pl
This will start up the development web server. You should see some debugging information appear on the console, which is shown as follows:
[debug] Debug messages enabled
[debug] Loaded plugins:
.--------------------------------------------.
| Catalyst::Plugin::ConfigLoader 0.23
| Catalyst::Plugin::Static::Simple 0.21 |
'--------------------------------------------'
[debug] Loaded dispatcher "Catalyst::Dispatcher" [debug] Loaded engine
"Catalyst::Engine::HTTP"
[debug] Found home "/home/jon/projects/book/chapter2/MyApp"
[debug] Loaded Config "/home/jon/projects/book/chapter2/MyApp/myapp.conf"
[debug] Loaded components:
.-----------------------------+----------.
| Class | Type +-
------------------------------+----------+
| MyApp::Controller::Root | instance |
'----------------------------------+----------'
[debug] Loaded Private actions:
.----------------------+-------- --------+----.
| Private | Class | Method |
+-----------+------------+--------------+
| /default | MyApp::Controller::Root | default |
| /end | MyApp::Controller::Root | end
|/index | MyApp::Controller::Root | index
'--------------+--------------+-------'
[debug] Loaded Path actions:
.----------------+----------
----.
| Path | Private
|
+-------------------+---------------------
----+
| / | /default
|
| / | /index
|
'----------------+----------------------------
----'
[info] MyApp powered by Catalyst 5.80004
You can connect to your server at http://localhost:3000
This debugging information contains a summary of plugins, Models, Views, and Controllers that your application uses, in addition to showing a map of URLs to actions. As we haven’t added anything to the application yet, this isn’t particularly helpful, but it will become helpful as we add features.
To see what your application looks like in a browser, simply browse to http://localhost:3000. You should see the standard Catalyst welcome page as follows:
Let’s put the application aside for a moment, and see the usage of all the files that were created. The list of files is as shown in the following screenshot:
Before we modify MyApp, let’s take a look at how a Catalyst application is structured on a disk. In the root directory of your application, there are some support files. If you’re familiar with CPAN modules, you’ll be at home with Catalyst. A Catalyst application is structured in exactly the same way (and can be uploaded to the CPAN unmodified, if desired).
This article will refer to MyApp as your application’s name, so if you use something else, be sure to substitute properly.
Latest helper scripts
Catalyst 5.8 is ported to Moose and the helper scripts for Catalyst were upgraded much later. Therefore, it is necessary for you to check if you have the latest helper scripts. We will discuss helper scripts later. For now, catalyst.pl is a helper script and if you’re using an updated helper script, then the lib/MyApp.pm file (or lib/whateverappname.pm) will have the following line:
use Moose;
If you don’t see this line in your application package in the lib directory, then you will have to update the helper scripts. You can do that by executing the following command:
cpan Catalyst::Helper
Files in the MyApp directory
The MyApp directory contains the following files:
- Makefile.PL: This script generates a Makefile to build, test, and in stall your application. It can also contain a list of your application’s CPAN dependencies and automatically install them.
To run Makefile.PL and generate a Makefile, simply type perl Makefile.PL. After that, you can run make to build the application, make test to test the application (you can try this right now, as some sample tests have already been created), make install to install the application, and so on. For more details, see the Module::Install documentation. It’s important that you don’t delete this file. Catalyst looks for it to determine where the root of your application is. - Changes: This is simply a free-form text file where you can document changes to your application. It’s not required, but it can be helpful to end users or other developers working on your application, especially if you’re writing an open source application.
- README: This is just a text file with information on your application. If you’re not going to distribute your application, you don’t need to keep it around.
- myapp.conf: This is your application’s main confi guration file, which is loaded when you start your application. You can specify configuration directly inside your application, but this file makes it easier to tweak settings without worrying about breaking your code. myapp.conf is in Apache-style syntax, but if you rename the file to myapp.pl, you can write it in Perl (or myapp.yml for YML format; see the Config::Any manual for a complete list).
The name of this file is based on your application’s name. Everything is converted to lowercase, double colons are replaced with underscores, and the .conf extension is appended.
Files in the lib directory
The heart of your application lives in the lib directory.
- This directory contains a file called MyApp.pm. This file defines the namespace and inheritance that are necessary to make this a Catalyst application. It also contains the list of plugins to load application-specific configurations. These configurations can also be defined in the myapp.conf file mentioned previously. However, if the same configuration is mentioned in both the files, then the configuration mentioned here takes precedence.
- Inside the lib directory, there are three key directories, namely MyApp/Controller, MyApp/Model, and MyApp/View. Catalyst loads the Controllers, Models, and Views from these directories respectively.