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=b6d944d5690c841b1460cbe40df5ec95db78bdfd;hp=7be1749f600c98a8ff5cafabf3eb2bb420a3e9e3;hb=0416017e10f523ec522ef48e0acef28217b57b55;hpb=82ab4bbf7fc1c88e5c23821a9cc304c69d0aaf09 diff --git a/lib/Catalyst/Manual/Tutorial/MoreCatalystBasics.pod b/lib/Catalyst/Manual/Tutorial/MoreCatalystBasics.pod index 7be1749..b6d944d 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 them written both ways). Over time, the +recommended style for most Catalyst applications has changed: + +=over 4 + +=item * From "C<:Local>" and "C<:Private>" + +=item * To "C<:Path>" and "C<:Args>" + +=item * To "C<:Chained>" + +=back + +Although all three styles work just fine, the newer forms offer more +advanced capbilities and allow you to be more expressive with the URIs +that your application uses. + +Here is a quick summary of the most commonly used action types: +C, C, C and C: + +=over 4 + +=item * + +B -- In the past, the majority of applications have +traditionally used C actions for items that respond to user +requests and C actions for those that do not directly respond +to user input. + +=over 4 + +There are five types of build-in C 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 -- C actions were the next style of action types to +become popular and essentially provide a limited subset of what can be +found done with Chained actions. You can match on different portions +of the URI (for example C in +C would match on the URL +C but C would match +on C) and it let's you be very specific with +what arguments each controller method will accept. See +L for more information and a few +examples. + +=item * + +B -- 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, 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