X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Manual.git;a=blobdiff_plain;f=lib%2FCatalyst%2FManual%2FTutorial%2FMoreCatalystBasics.pod;h=fef48feb79f11d03cbef2ceda2021eba2e9dbb72;hp=7be1749f600c98a8ff5cafabf3eb2bb420a3e9e3;hb=245b41d18d896641288e60c37d687ae25c716db1;hpb=82ab4bbf7fc1c88e5c23821a9cc304c69d0aaf09 diff --git a/lib/Catalyst/Manual/Tutorial/MoreCatalystBasics.pod b/lib/Catalyst/Manual/Tutorial/MoreCatalystBasics.pod index 7be1749..fef48fe 100644 --- a/lib/Catalyst/Manual/Tutorial/MoreCatalystBasics.pod +++ b/lib/Catalyst/Manual/Tutorial/MoreCatalystBasics.pod @@ -151,7 +151,7 @@ C (or any other format supported by L and L). If you are using a versions of Catalyst::Devel prior to 1.06, you can convert to the newer format by -simply creating the C file manually and deleting +simply creating the C file manually and deleting C. The default contents of C should only consist of one line: C. @@ -174,7 +174,7 @@ as images and CSS files under the development server. =back -For out application, we want to add one new plugin into the mix. To +For our application, we want to add one new plugin into the mix. To do this, edit C (this file is generally referred to as your I) and delete the line with: @@ -190,6 +190,21 @@ Then replace it with: StackTrace /); +B Recent versions of C have used a variety of +techniques to load these plugins/flags. If you are following along in +Ubuntu 8.10, you should have C v1.07 and see the +default code shown above. If you are using v1.08, you should see the +following by default: + + use Catalyst qw/-Debug + ConfigLoader + Static::Simple/; + ... + __PACKAGE__->setup(); + +Don't let these variations confuse you -- they all accomplish the same +result. + This tells Catalyst to start using one new plugin, L, to add a stack trace to the standard Catalyst "debug screen" (the screen @@ -279,26 +294,89 @@ Context object is automatically passed to all Catalyst components. It is used to pass information between components and provide access to Catalyst and plugin functionality. -B Catalyst actions are regular Perl methods, but they make use -of Nicholas Clark's C module (that's the "C<: Local>" next -to the C in the code above) to provide additional -information to the Catalyst dispatcher logic. Many newer Catalyst -applications are switching to the use of "Literal" C<:Path> actions -and C attribute in lieu of C<: Local> and C<: Private>. For -example, C can be used instead of C (because no path was supplied to C it matches -the "empty" URL in the namespace of that module... the same thing -C would do) or C could be -used instead of the C above (the C argument to -C would make it match on the URL C under C, the -namespace of the current module). See "Action Types" in -L as well as Part 5 -of this tutorial (Authentication) for additional information. Another -popular but more advanced feature is C actions that allow a -single URL to "chain together" multiple action method calls, each with -an appropriate number of arguments (see -L for -details). +Catalyst actions are regular Perl methods, but they make use of +attributes (the "C<: Local>" next to the "C" in the code +above) to provide additional information to the Catalyst dispatcher +logic (note that the space between the colon and the attribute name is +optional... you will see attributes written both ways). Most Catalyst +Controllers use one of five action types: + +=over 4 + +=item * + +B<:Private> -- Use C<:Private> for methods that you want to make into +an action, but you do not want Catalyst to directly expose the action +to your users. Catalyst will not map C<:Private> methods to a URI. +Use them for various sorts of "special" methods (the C, +C, etc. discussed below) or for methods you want to be able to +C or C to. (If the method is a plain old "helper +method" that you don't want to be an action at all, then just define +the method without any attribute -- you can call it in your code, but +the Catalyst dispatcher will ignore it.) + +=over 4 + +There are five types of "special" build-in C<:Private> actions: +C, C, C, C, and C. + +=item * + +With C, C, C, C private actions, only the +most specific action of each type will be called. For example, if you +define a C action in your controller it will I a +C action in your application/root controller -- I the +action in your controller will be called. + +=item * + +Unlike the other actions where only a single method is called for each +request, I auto action along the chain of namespaces will be +called. Each C action will be called I. + +=back + +=item * + +B<:Path> -- C<:Path> actions let you map a method to an explicit URI +path. For example, "C<:Path('list')>" in +C would match on the URL +C but "C<:Path('/list')>" would match +on C. You can use C<:Args()> to specify +how many arguments an action should except. See +L for more information and a few +examples. + +=item * + +B<:Local> -- C<:Local> is merely a shorthand for +"C<:Path('_name_of_method_')>". For example, these are equivalent: +"C" and +"C". + +=item * + +B<:Global> -- C<:Global> is merely a shorthand for +"C<:Path('/_name_of_method_')>". For example, these are equivalent: +"C" and +"C". + +=item * + +B<:Chained> -- Newer Catalyst applications tend to use the Chained +dispatch form of action types because of its power and flexibility. +It allows a series of controller methods to automatically be dispatched +to service a single user request. See +L +and L +for more information on chained actions. + +=back + +You should refer to L for +additional information and for coverage of some lesser-used action +types not discussed here (C and C). =head1 CATALYST VIEWS @@ -333,18 +411,20 @@ L =back -Both are similar, but C merely creates the C +Both helpers are similar. C creates the C file and leaves the creation of any hierarchical template organization entirely up to you. (It also creates a C file for testing; -test cases will be discussed in Part 8.) On the other hand, the -C helper creates a modular and hierarchical view layout with +test cases will be discussed in Part 8.) C, on the other hand, +creates a modular and hierarchical view layout with separate Template Toolkit (TT) files for common header and footer information, configuration values, a CSS stylesheet, and more. -While TTSite is useful to bootstrap a project, most in the Catalyst -community recommend that it's easier to learn both Catalyst and -Tempalte Toolkit if you use the more basic TT approach. Consequently, -this tutorial will use "plain old TT." +While C was useful to bootstrap a project, its use is now +deprecated and to be considered historical. For most Catalyst +applications it adds redundant functionality and structure; many in the +Catalyst community recommend that it's easier to learn both Catalyst and +Template Toolkit if you use the more basic C approach. +Consequently, this tutorial will use "plain old TT." Enter the following command to enable the C style of view rendering for this tutorial: @@ -376,16 +456,18 @@ And update it to match: TEMPLATE_EXTENSION => '.tt2', # Set the location for TT files INCLUDE_PATH => [ - MyApp->path_to( 'root/src' ), + MyApp->path_to( 'root', 'src' ), ], ); B Make sure to add a comma after '.tt2' outside the single quote. -This changes the default extenstion for Template Toolkit from '.tt' to +This changes the default extension for Template Toolkit from '.tt' to '.tt2' and changes the base directory for your template files from -C to C. +C to C. These changes from the default are done mostly +to facilitate the application we're developing in this tutorial; as with +most things Perl, there's more than one way to do it... =head2 Create a TT Template Page @@ -550,19 +632,21 @@ required if you do a single SQL statement on the command line). Use ".q" to exit from SQLite from the SQLite interactive mode and return to your OS command prompt. +For using other databases, such as PostgreSQL or MySQL, see +L. =head1 DATABASE ACCESS WITH C -Catalyst can be used with virtually any form of persistent datastore -available via Perl. For example, -L can be used to -easily access databases through the traditional Perl C interface. -However, most Catalyst applications use some form of ORM technology to -automatically create and save model objects as they are used. Although -Tony Bowden's L has been a popular choice -in the past, Matt Trout's L (abbreviated -as "DBIC") has rapidly emerged as the Perl-based ORM technology of choice. -Most new Catalyst applications rely on DBIC, as will this tutorial. +Catalyst can be used with virtually any form of persistent datastore +available via Perl. For example, +L can be used to easily +access databases through the traditional Perl C interface. However, +most Catalyst applications use some form of ORM technology to +automatically create and save model objects as they are used. Although +L has been a popular choice in the past, Matt +Trout's L (abbreviated as "DBIC") has rapidly +emerged as the Perl-based ORM technology of choice. Most new Catalyst +applications rely on DBIC, as will this tutorial. =head2 Create a Dynamic DBIC Model @@ -587,8 +671,12 @@ to C. Because we specified C to the helper, it use L to dynamically load the schema information from the database every time -the application starts. And finally, C is the -standard DBI connect string for use with SQLite. +the application starts. DBIC uses the schema to load other classes +that represent the tables in your database (DBIC refers to these +"table objects" as "result sources," see +L). And finally, +C is the standard DBI connect string for use with +SQLite. B Although the C option to the DBIC helper makes for a nifty demonstration, is only really suitable for very @@ -598,8 +686,8 @@ use the C option that we switch to below. =head1 ENABLE THE MODEL IN THE CONTROLLER -Open C and uncomment the model code we -left disabled earlier (uncomment the line containing +Open C and un-comment the model code we +left disabled earlier (un-comment the line containing C<[$c-Emodel('DB::Books')-Eall]> and delete the next 2 lines): =head2 list @@ -624,9 +712,26 @@ C<[$c-Emodel('DB::Books')-Eall]> and delete the next 2 lines): $c->stash->{template} = 'books/list.tt2'; } -B: You may see the C<$c-Emodel('DB::Book')> uncommented above -written as C<$c-Emodel('DB')-Eresultset('Book')>. The two -are equivalent. +B: You may see the C<$c-Emodel('DB::Book')> un-commented +above written as C<$c-Emodel('DB')-Eresultset('Book')>. The +two are equivalent. Either way, C<$c-Emodel> returns a +L which handles queries +against the database and iterating over the set of results that are +returned. + +We are using the C<-Eall> to fetch all of the books. DBIC +supports a wide variety of more advanced operations to easily do +things like filtering and sorting the results. For example, the +following could be used to sort the results by descending title: + + $c->model('DB::Books')->search({}, {order_by => 'title DESC'}); + +Some other examples are provided in +L, with +additional information found at L, +L, +L +and L. =head2 Test Run The Application @@ -733,7 +838,7 @@ Next, to view the book list, change the URL in your browser to L. You should get a list of the five books loaded by the C script above without any formatting. The rating for each book should appear on each row, but the "Author(s)" -column will sitll be blank (we will fill that in later). +column will still be blank (we will fill that in later). Also notice in the output of the C