X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Manual.git;a=blobdiff_plain;f=lib%2FCatalyst%2FManual%2FTutorial%2FCatalystBasics.pod;h=5ad770286b26e113704104232d7146a1c8d25971;hp=e366b1075df231cdfe53feefd684690ef1ac76c5;hb=1390ef0ecd30a0dcfe59f212353ed81094fdf64a;hpb=c010ae0de590159369925f16f03dcad4732a91e6 diff --git a/lib/Catalyst/Manual/Tutorial/CatalystBasics.pod b/lib/Catalyst/Manual/Tutorial/CatalystBasics.pod index e366b10..5ad7702 100644 --- a/lib/Catalyst/Manual/Tutorial/CatalystBasics.pod +++ b/lib/Catalyst/Manual/Tutorial/CatalystBasics.pod @@ -73,7 +73,7 @@ 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. In short: +L). In short: =over 4 @@ -88,8 +88,8 @@ database. 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, or Excel -spreadsheets. +that generates other forms such as PDF documents, e-mails, spreadsheets, +or even "behind the scenes" formats such as XML and JSON. =item * Controller @@ -108,7 +108,7 @@ to persist and restore objects to/from a relational database. You can checkout the source code for this example from the catalyst subversion repository as per the instructions in -L +L. =head1 CREATE A CATALYST PROJECT @@ -138,14 +138,14 @@ The C helper script will display the names of the directories and files it creates: Changes # Record of application changes - lib # Lib directory for Perl modules - Hello # Application code directory + 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.yml # Application configuration file + hello.conf # Application configuration file README # README file root # Equiv of htdocs, dir for templates, css, javascript favicon.ico @@ -183,16 +183,17 @@ server: $ script/hello_server.pl [debug] Debug messages enabled + [debug] Statistics enabled [debug] Loaded plugins: .----------------------------------------------------------------------------. - | Catalyst::Plugin::ConfigLoader 0.17 | + | 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.yml" + [debug] Loaded Config "/home/me/Hello/hello.conf" [debug] Loaded components: .-----------------------------------------------------------------+----------. | Class | Type | @@ -208,7 +209,15 @@ server: | /end | Hello::Controller::Root | end | '----------------------+--------------------------------------+--------------' - [info] Hello powered by Catalyst 5.7011 + [debug] Loaded Path actions: + .-------------------------------------+--------------------------------------. + | Path | Private | + +-------------------------------------+--------------------------------------+ + | / | /default | + | / | /index | + '-------------------------------------+--------------------------------------' + + [info] Hello powered by Catalyst 5.7014 You can connect to your server at http://localhost:3000 Point your web browser to @@ -218,7 +227,7 @@ greeted by the Catalyst welcome screen. Information similar to the following should be appended to the logging output of the development server: - [info] *** Request 1 (1.000/s) [10301] [Sun May 18 10:11:36 2008] *** + [info] *** Request 1 (1.000/s) [10301] [Sun Nov 23 10:11:36 2008] *** [debug] "GET" request for "/" from "127.0.0.1" [info] Request took 0.017964s (55.667/s) .----------------------------------------------------------------+-----------. @@ -237,37 +246,42 @@ Press Ctrl-C to break out of the development server. The Root.pm controller is a place to put global actions that usually execute on the root URL. Open the C file in -your editor. You will see the "default" subroutine, which is +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 but for now just leave it alone. +reasonable, such as a "404" message or a redirect, but for now just +leave it alone. - sub default : Path : Args { + 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, L, and L) +objects. (See L, +L, and +L) -C<$c->response->body> sets the HTTP response (see -L), while C<$c->welcome_message> is a special method -that returns the welcome message that you saw in your browser. +C<$c-Eresponse-Ebody> sets the HTTP response (see +L), while C<$c-Ewelcome_message> +is a special method that returns the welcome message that you saw in +your browser. -The ": Path : Args" after the method name are attributes which determine +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 is -currently deprecated.) +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"), and will accept -any number of args (nothing after args). +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, @@ -279,27 +293,30 @@ For example, the URL C maps to the package C, and the C method. - -Add the following subroutine to your Root.pm file: +Add the following subroutine to your C +file: sub hello : Global { my ( $self, $c ) = @_; + $c->response->body("Hello, World!"); } 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 to +up), and go to L 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 type of view--HTML, pdf, XML. For the case of a -template view (such as the default Toolkit Template) the actual -templates go under the "root" directory. +determines the I of view -- HTML, pdf, XML, etc. For the +thing that generates the I of that view, (such as the +default Toolkit Template) the actual templates go under the +"root" directory. To create a TT view, run: @@ -307,8 +324,8 @@ To create a TT view, run: This creates the C module, which is a subclass of C. The "view" keyword tells the create script that -you are creating a view, the first "TT" tells it that you are creating -a Template Toolkit view, and the second "TT" tells the script to name +you are creating a view, the second "TT" tells it that you are creating +a Template Toolkit view, and 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".) If you look at TT.pm, you will find that it only contains a config statement to set @@ -319,8 +336,7 @@ able to use it to display the view templates, using the "process" method that it inherits from the C. Template Toolkit is a very full featured template facility, with -excellent documentation at -L, +excellent documentation at L, 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 parts of the tutorial). @@ -331,30 +347,31 @@ a simple sample: [% META title = 'Hello, World!' %]

- This is a TT view template, located in the root directory. + This is a TT view template, located in the 'root/' directory.

[% and %] are markers for the TT parts of the template. Inside you can access Perl variables and classes, and use TT directives. The rest of -the template is normal HTML. Change the hello method in Root.pm to the -following: +the template is normal HTML. Change the hello method in +C to the following: sub hello : Global { my ( $self, $c ) = @_; + $c->stash->{template} = 'hello.tt'; } -This time, instead of doing C<$c->response->body()>, you are setting +This time, instead of doing C<$c-Eresponse->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->response->body()> statement). So your +rendered (unless there's a C<$c-Eresponse->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 again. You should +L again. You should see the template that you just made. @@ -369,10 +386,11 @@ 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 Site.pm, add the following method: +In C, add the following method: sub test : Local { my ( $self, $c ) = @_; + $c->stash->{username} = "John"; $c->stash->{template} = 'site/test.tt'; } @@ -389,14 +407,14 @@ naming convention). We've also put the variable "name" 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 root/site/test.tt, or create a new template -file at that location. Include a line like: +file into the directory as C, or create a new +template file at that location. Include a line like: -

Hello, [% username %]!

+

Hello, [% username %]!

Bring up or restart the server. Notice in the server output that C is listed in the Loaded Path actions. Go to -L +L in your browser. You should see your test.tt file displayed, including the name "John" that you set in the controller. @@ -411,5 +429,5 @@ Please report any errors, issues or suggestions to the author. The most recent version of the Catalyst Tutorial can be found at L. -Copyright 2006, Kennedy Clark & Gerda Shank, under Creative Commons License -(L). +Copyright 2006-2008, Kennedy Clark & Gerda Shank, under Creative Commons License +(L).