+++ /dev/null
-=head1 NAME
-
-Catalyst::Manual::Tutorial::CatalystBasics - Catalyst Tutorial - Chapter 2: Catalyst Application Development Basics
-
-
-=head1 OVERVIEW
-
-This is B<Chapter 2 of 10> for the Catalyst tutorial.
-
-L<Tutorial Overview|Catalyst::Manual::Tutorial>
-
-=over 4
-
-=item 1
-
-L<Introduction|Catalyst::Manual::Tutorial::Intro>
-
-=item 2
-
-B<Catalyst Basics>
-
-=item 3
-
-L<More Catalyst Basics|Catalyst::Manual::Tutorial::MoreCatalystBasics>
-
-=item 4
-
-L<Basic CRUD|Catalyst::Manual::Tutorial::BasicCRUD>
-
-=item 5
-
-L<Authentication|Catalyst::Manual::Tutorial::Authentication>
-
-=item 6
-
-L<Authorization|Catalyst::Manual::Tutorial::Authorization>
-
-=item 7
-
-L<Debugging|Catalyst::Manual::Tutorial::Debugging>
-
-=item 8
-
-L<Testing|Catalyst::Manual::Tutorial::Testing>
-
-=item 9
-
-L<Advanced CRUD|Catalyst::Manual::Tutorial::AdvancedCRUD>
-
-=item 10
-
-L<Appendices|Catalyst::Manual::Tutorial::Appendices>
-
-=back
-
-
-=head1 DESCRIPTION
-
-In this chapter of the tutorial, we will create a very basic Catalyst
-web application, demonstrating a number of powerful capabilities, such
-as:
-
-=over 4
-
-=item * Helper Scripts
-
-Catalyst helper scripts that can be used to rapidly bootstrap the
-skeletal structure of an application.
-
-=item * 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
-L<Catalyst::Manual::About|Catalyst::Manual::About>). In short:
-
-=over 4
-
-=item * 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.
-
-=item * 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.
-
-=item * Controller
-
-As suggested by its name, the controller takes user requests and routes
-them to the necessary model and view.
-
-=back
-
-=item * 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.
-
-=back
-
-You can checkout the source code for this example from the catalyst
-subversion repository as per the instructions in
-L<Catalyst::Manual::Tutorial::Intro|Catalyst::Manual::Tutorial::Intro>.
-
-
-=head1 CREATE A CATALYST PROJECT
-
-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 C<catalyst.pl> helper (see
-L<Catalyst::Helper|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 L<Catalyst::Runtime|Catalyst::Runtime>
-and L<Catalyst::Devel|Catalyst::Devel>.
-
-In this first chapter of the tutorial, use the Catalyst C<catalyst.pl>
-script to initialize the framework for an application called C<Hello>:
-
- $ catalyst.pl Hello
- created "Hello"
- created "Hello/script"
- created "Hello/lib"
- created "Hello/root"
- ...
- created "Hello/script/hello_create.pl"
- $ cd Hello
-
-The C<catalyst.pl> 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
- Hello.pm # 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
- favicon.ico
- static # Directory for static files
- images # Directory for image files used in welcome screen
- script # Directory for Perl scripts
- hello_cgi.pl # To run your app as a cgi (not recommended)
- hello_create.pl # To create models, views, controllers
- hello_fastcgi.pl # To run app as a fastcgi program
- hello_server.pl # The normal development server
- hello_test.pl # Test your app from the command line
- t # Directory for tests
- 01app.t # Test scaffold
- 02pod.t
- 03podcoverage.t
-
-
-Catalyst will "auto-discover" modules in the Controller, Model, and
-View directories. When you use the hello_create.pl 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 "maitai_create.pl".
-
-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
-directory.
-
-Run the following command to start up the built-in development web
-server (make sure you didn't forget the "C<cd Hello>" from the
-previous step):
-
- $ script/hello_server.pl
- [debug] Debug messages enabled
- [debug] Statistics enabled
- [debug] Loaded plugins:
- .----------------------------------------------------------------------------.
- | Catalyst::Plugin::ConfigLoader 0.20 |
- | Catalyst::Plugin::Static::Simple 0.20 |
- '----------------------------------------------------------------------------'
-
- [debug] Loaded dispatcher "Catalyst::Dispatcher"
- [debug] Loaded engine "Catalyst::Engine::HTTP"
- [debug] Found home "/home/me/Hello"
- [debug] Loaded Config "/home/me/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 |
- +-------------------------------------+--------------------------------------+
- | / | /default |
- | / | /index |
- '-------------------------------------+--------------------------------------'
-
- [info] Hello powered by Catalyst 5.80003
- You can connect to your server at http://debian:3000
-
-Point your web browser to L<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] *** Request 1 (0.005/s) [20712] [Sun Mar 8 15:49:09 2009] ***
- [debug] "GET" request for "/" from "1.1.1.98"
- [info] Request took 0.007342s (136.203/s)
- .----------------------------------------------------------------+-----------.
- | Action | Time |
- +----------------------------------------------------------------+-----------+
- | /index | 0.000491s |
- | /end | 0.000595s |
- '----------------------------------------------------------------+-----------'
-
-Press Ctrl-C to break out of the development server.
-
-
-=head1 HELLO WORLD
-
-=head2 The Simplest Way
-
-The Root.pm controller is a place to put global actions that usually
-execute on the root URL. Open the C<lib/Hello/Controller/Root.pm> 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. 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.
-
- sub index :Path :Args(0) {
- my ( $self, $c ) = @_;
-
- # Hello World
- $c->response->body( $c->welcome_message );
- }
-
-The "C<$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 L<Catalyst|Catalyst>,
-L<Catalyst::Response|Catalyst::Response>, and
-L<Catalyst::Request|Catalyst::Request>)
-
-C<$c-E<gt>response-E<gt>body> sets the HTTP response (see
-L<Catalyst::Response|Catalyst::Response>), while C<$c-E<gt>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. (Depending on your version of
-Catalyst, it used to say "Private" but using that with 'default' or 'index'
-is currently deprecated.)
-
-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 single 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 C<http://hello.com/admin/articles/create> maps
-to the package C<Hello::Controller::Admin::Articles>, and the C<create>
-method.
-
-Add the following subroutine to your C<lib/Hello/Controller/Root.pm>
-file:
-
- sub hello : Global {
- my ( $self, $c ) = @_;
-
- $c->response->body("Hello, World!");
- }
-
-B<TIP>: See Appendix 1 for tips on removing the leading spaces when
-cutting and pasting example code from POD-based documents.
-
-Here you're sending your own string to the webpage.
-
-Save the file, start the server (stop and restart it if it's still
-up), and go to L<http://localhost:3000/hello> to
-see "Hello, World!"
-
-
-=head2 Hello, World! Using a View and a Template
-
-In the Catalyst world a "View" is not a page of XHTML or a template
-designed to present a page to a browser. It is the module that
-determines the I<type> of view -- HTML, pdf, XML, etc. For the
-thing that generates the I<content> of that view, (such as the
-default Toolkit Template) the actual templates go under the
-"root" directory.
-
-To create a TT view, run:
-
- $ script/hello_create.pl view TT TT
-
-This creates the C<lib/Hello/View/TT.pm> module, which is a subclass of
-C<Catalyst::View::TT>.
-
-=over 4
-
-=item *
-
-The "view" keyword tells the create script that you are creating a view.
-
-=item *
-
-The first "TT" tells the script to name the View module "TT.pm", which is a
-commonly used name for TT views. (You can name it anything you want, such as
-"HTML.pm".)
-
-=item *
-
-The final "TT" tells it that you are creating a Template Toolkit view.
-
-=back
-
-If you look at C<lib/Hello/View/TT.pm> you will find that it only contains a
-config statement to set the TT extension to ".tt".
-
-Now that the TT.pm "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 C<Catalyst::View::TT class>.
-
-Template Toolkit is a very full featured template facility, with
-excellent documentation at L<http://template-toolkit.org/>,
-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 tutorial).
-
-Create a C<root/hello.tt> template file (put it in the C<root> under
-the C<Hello> directory that is the base of your application). Here is
-a simple sample:
-
- <p>
- This is a TT view template, called '[% template.name %]'.
- </p>
-
-[% 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 (C<hello.tt>). The rest of the template is normal HTML.
-
-Change the hello method in C<lib/Hello/Controller/Root.pm> to the
-following:
-
- sub hello : Global {
- my ( $self, $c ) = @_;
-
- $c->stash->{template} = 'hello.tt';
- }
-
-This time, instead of doing C<$c-E<gt>response-E<gt>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 method. 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<$c-E<gt>response-E<gt>body()> statement). So your
-template will be magically displayed at the end of your method.
-
-After saving the file, restart the development server, and look at
-L<http://localhost:3000/hello> again. You should
-see the template that you just made.
-
-
-=head1 CREATE A SIMPLE CONTROLLER AND AN ACTION
-
-Create a controller named "Site" by executing the create script:
-
- $ script/hello_create.pl controller Site
-
-This will create a C<lib/Hello/Controller/Site.pm> file (and a test
-file). Bring Site.pm up in your editor, and you can see that there's
-not much there. Most people probably don't bother to use the create
-script to make controllers after they're used to using Catalyst.
-
-In C<lib/Hello/Controller/Site.pm>, add the following method:
-
- sub test : Local {
- my ( $self, $c ) = @_;
-
- $c->stash->{username} = "John";
- $c->stash->{template} = 'site/test.tt';
- }
-
-Notice the "Local" attribute on the C<test> method. This will cause
-the C<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
-L<Catalyst::Manual::Intro/Actions>.
-
-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/method.tt", 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
-template.
-
-Make a subdirectory "site" in the "root" directory. Copy the hello.tt
-file into the directory as C<root/site/test.tt>, or create a new
-template file at that location. Include a line like:
-
- <p>Hello, [% username %]!</p>
-
-Bring up or restart the server. Notice in the server output that
-C</site/test> is listed in the Loaded Path actions. Go to
-L<http://localhost:3000/site/test> in your browser.
-
-You should see your test.tt file displayed, including the name "John"
-that you set in the controller.
-
-
-=head1 AUTHORS
-
-Gerda Shank, C<gerda.shank@gmail.com>
-Kennedy Clark, C<hkclark@gmail.com>
-
-Please report any errors, issues or suggestions to the author. The
-most recent version of the Catalyst Tutorial can be found at
-L<http://dev.catalyst.perl.org/repos/Catalyst/Catalyst-Manual/5.70/trunk/lib/Catalyst/Manual/Tutorial/>.
-
-Copyright 2006-2008, Kennedy Clark & Gerda Shank, under Creative Commons License
-(L<http://creativecommons.org/licenses/by-sa/3.0/us/>).
projects / catagits/Catalyst-Manual.git / blobdiff