From: Matt S Trout
Date: Thu, 8 Jun 2006 14:38:31 +0000 (+0000)
Subject: Tut docs work
X-Git-Tag: 5.7099_04~528
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=3c098c712dbc92de8efb97acf71772b439956cd9;p=catagits%2FCatalyst-Runtime.git
Tut docs work
r9737@cain (orig r4286): jester | 2006-06-05 03:24:16 +0000
---
diff --git a/lib/Catalyst/Manual/Tutorial/AdvancedCRUD.pod b/lib/Catalyst/Manual/Tutorial/AdvancedCRUD.pod
index 22f562b..4543178 100644
--- a/lib/Catalyst/Manual/Tutorial/AdvancedCRUD.pod
+++ b/lib/Catalyst/Manual/Tutorial/AdvancedCRUD.pod
@@ -2,8 +2,6 @@
Catalyst::Manual::Tutorial::AdvancedCRUD - Catalyst Tutorial - Part 8: Advanced CRUD
-
-
=head1 OVERVIEW
This is B for the Catalyst tutorial.
@@ -46,12 +44,10 @@ B
=item 9
-L
+L
=back
-
-
=head1 DESCRIPTION
This part of the tutorial explores more advanced functionality for
@@ -64,23 +60,22 @@ forms and model objects.
In keeping with the Catalyst (and Perl) spirit of flexibility, there are
many different ways approach advanced CRUD operations in a Catalyst
environment. One alternative is to use
-L
-to instantly construct a set of Controller methods and templates for
-basic CRUD operations. Although a popular subject in Quicktime movies
-that serve as promotional material for various frameworks, more
-real-world applications require more control. Other options include
-L and
-L.
-
-Here, we will make use of the L to not only
-ease form creation, but to also provide validation of the submitted
-data. The approached used by the part of the tutorial is to slowly
-incorporate additional L functionality in a
-step-wise fashion (we start with fairly simple form creation and then
-move on to more complex and "magical" features such as validation and
+L to instantly construct a set
+of Controller methods and templates for basic CRUD operations. Although
+a popular subject in Quicktime movies that serve as promotional material
+for various frameworks, more real-world applications require more
+control. Other options include L and
+L.
+
+Here, we will make use of the L to not only ease form
+creation, but to also provide validation of the submitted data. The
+approached used by the part of the tutorial is to slowly incorporate
+additional L functionality in a step-wise fashion (we
+start with fairly simple form creation and then move on to more complex
+and "magical" features such as validation and
auto-population/auto-saving).
-B Part 8 of the tutorial is optional. Users who do not which to
+B Part 8 of the tutorial is optional. Users who do not wish to
use L may skip this section.
B: Note that all of the code for this part of the tutorial can be
@@ -90,22 +85,18 @@ following command:
svn checkout http://dev.catalyst.perl.org/repos/Catalyst/trunk/examples/Tutorial@###
IMPORTANT: Does not work yet. Will be completed for final version.
-
-
=head1 C FORM CREATION
-This section looks at how L can be used to
+This section looks at how L can be used to
add additional functionality to the manually created form from Part 3.
-
=head2 Add the C Plugin
Open C in your editor and add the following to the list of
-plugins (be sure to leave the existing plugins enabled:
+plugins (be sure to leave the existing plugins enabled):
HTML::Widget
-
=head2 Add a Form Creation Helper Method
Open C in your editor and add the
@@ -140,13 +131,11 @@ following method:
}
This method provides a central location (so it can be called by multiple
-actions, such as create and edit) that builds an HTML::Wiget-based form
-with the appropriate fields. The "Get Authors" code uses DBIC to
-retrieve a list of model objects and then uses C
-
=head2 Test The Create Form
Press C to kill the previous server instance (if it's still
@@ -290,7 +275,7 @@ bogus information. Although we have constrained the authors with the
drop-down list, there are no restrictions on items such as the length of
the title (for example, you can create a one-letter title) and value for
the rating (you can use any number you want, and even non-numeric values
-with SQLite). The next section seeks to address this concern.
+with SQLite). The next section will address this concern.
B Depending on the database you are using and how you established
the columns in your tables, the database could obviously provide various
@@ -298,7 +283,6 @@ levels of "type enforcement" on your data. The key point being made in
the previous paragraph is that the I itself is not
performing any validation.
-
=head1 C VALIDATION AND FILTERING
Although the use of L in the previous section
@@ -310,7 +294,6 @@ form contains a valid email address). Filtering can be used to remove
extraneous whitespace from fields or to escape meta-characters in user
input.
-
=head2 Add Constraints and Filters to the Widget Creation Method
Open C in your editor and update the
@@ -376,7 +359,6 @@ Two filters are run on every field to remove and escape unwanted input.
=back
-
=head2 Rebuild the Form Submission Method to Include Validation
Edit C and change C to
@@ -463,7 +445,6 @@ similar to the prior version of the C method.
=back
-
=head2 Try Out the Form
Press C to kill the previous server instance (if it's still running) and restart it:
@@ -476,7 +457,6 @@ two, and zero authors. When you click Submit, the HTML::Widget
C items will validate the logic and insert feedback as
appropriate.
-
=head1 Enable C Support
In this section we will take advantage of some of the "auto-population"
@@ -504,7 +484,6 @@ records in the database.
In other words, the two methods are a mirror image of each other: one
reads from the database while the other writes to the database.
-
=head2 Add C to DBIC Model
In order to use L, we
@@ -515,7 +494,6 @@ C and update the C line to match:
__PACKAGE__->load_components(qw/PK::Auto Core HTMLWidget/);
-
=head2 Use C in C
Edit C and update C to
@@ -576,8 +554,6 @@ have to call C<$book-Eadd_to_book_authors> once per author because
C does not currently handle the relationships
between tables.
-
-
=head1 AUTHOR
Kennedy Clark, C
@@ -586,7 +562,8 @@ Please report any errors, issues or suggestions to the author.
Copyright 2006, Kennedy Clark. All rights reserved.
-This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
+This library is free software; you can redistribute it and/or modify it
+under the same terms as Perl itself.
Version: .94
diff --git a/lib/Catalyst/Manual/Tutorial/Appendices.pod b/lib/Catalyst/Manual/Tutorial/Appendices.pod
index c408e82..a28e787 100644
--- a/lib/Catalyst/Manual/Tutorial/Appendices.pod
+++ b/lib/Catalyst/Manual/Tutorial/Appendices.pod
@@ -45,26 +45,21 @@ L
=item 9
-B
+B
=back
-
-
=head1 DESCRIPTION
This part of the tutorial provides supporting information relevant to
the Catalyst tutorial.
-
-
=head1 APPENDIX 1: CUT AND PASTE FOR POD-BASED EXAMPLES
You may notice that Pod indents example code with four spaces. This
section provides some quick advice to "un-indent" this text in common
editors.
-
=head2 "Un-indenting" with Vi/Vim
When cutting and pasting multi-line text from Pod-based documents, the
@@ -97,13 +92,10 @@ Removes four leading space from the current line through line 44
=back
-
=head2 "Un-indenting" with Emacs
B
-
-
=head1 APPENDIX 2: USING MYSQL AND POSTGRESQL
The main database used in this tutorial is the very simple yet powerful
@@ -121,7 +113,6 @@ section are not designed to take maximum advantage of the various
features in each database for issues such as referential integrity and
field types/constraints.
-
=head2 MySQL
B
diff --git a/lib/Catalyst/Manual/Tutorial/Testing.pod b/lib/Catalyst/Manual/Tutorial/Testing.pod
index c8ea930..527d42e 100644
--- a/lib/Catalyst/Manual/Tutorial/Testing.pod
+++ b/lib/Catalyst/Manual/Tutorial/Testing.pod
@@ -2,8 +2,6 @@
Catalyst::Manual::Tutorial::Testing - Catalyst Tutorial - Part 7: Testing
-
-
=head1 OVERVIEW
This is B for the Catalyst tutorial.
@@ -46,21 +44,18 @@ L
=item 9
-L
+L
=back
-
-
=head1 DESCRIPTION
-
You may have noticed that the Catalyst Helper scripts automatically
-create C<.t> test scripts under the C directory. This part of the
-tutorial briefly looks at how these tests can be used to not only ensure
-that your application is working correctly at the present time, but also
-provide automated regression testing as you upgrade various pieces of
-your application over time.
+create basic C<.t> test scripts under the C directory. This part of
+the tutorial briefly looks at how these tests can be used to not only
+ensure that your application is working correctly at the present time,
+but also provide automated regression testing as you upgrade various
+pieces of your application over time.
B: Note that all of the code for this part of the tutorial can be
pulled from the Catalyst Subversion repository in one step with the
@@ -70,7 +65,6 @@ following command:
IMPORTANT: Does not work yet. Will be completed for final version.
-
=head1 RUNNING THE "CANNED" CATALYST TESTS
There are a variety of ways to run Catalyst and Perl tests (for example,
@@ -106,7 +100,7 @@ Although you can edit the C to comment out the C<-Debug>
plugin, it's generally easier to simply set the C
environment variable. For example:
- CATALYST_DEBUG=0 prove --lib lib t
+ $ CATALYST_DEBUG=0 prove --lib lib t
During the C and C tests, you might notice the
C warning message. To
@@ -124,8 +118,6 @@ prints the name of each test case as it is being run:
$ CATALYST_DEBUG=0 TEST_POD=1 prove --lib lib -v t
-
-
=head1 RUNNING A SINGLE TEST
You can also run a single script by appending its name to the C
@@ -138,19 +130,17 @@ For example:
$ CATALYST_DEBUG=0 perl -Ilib t/01app.t
-
=head1 ADDING YOUR OWN TEST SCRIPT
Although the Catalyst helper scripts provide a basic level of checks
"for free," testing can become significantly more helpful when you write
your own script to exercise the various parts of your application. The
-L module
-is very popular for writing these sorts of test cases. This module
-extends L (and therefore
-L) to allow you to automate the action of
+L module is very popular for writing
+these sorts of test cases. This module extends L
+(and therefore L) to allow you to automate the action of
a user "clicking around" inside your application. It gives you all the
benefits of testing on a live system without the messiness of having to
-use an actual web server.
+use an actual web server, and a real person to do the clicking.
To create a sample test case, open the C file in your
editor and enter the following:
@@ -160,17 +150,19 @@ editor and enter the following:
use strict;
use warnings;
- # Load testing framework and use 'no_plan' to dynamically pick up all tests. Better
- # to replace "'no_plan'" with "tests => 30" so it knows exactly how many tests need
- # to be run (and will tell you if not), but 'no_plan' is nice for quick & dirty tests
+ # Load testing framework and use 'no_plan' to dynamically pick up
+ # all tests. Better to replace "'no_plan'" with "tests => 30" so it
+ # knows exactly how many tests need to be run (and will tell you if
+ # not), but 'no_plan' is nice for quick & dirty tests
+
use Test::More 'no_plan';
# Need to specify the name of your app as arg on next line
# Can also do:
# use Test::WWW::Mechanize::Catalyst "MyApp";
+
use ok "Test::WWW::Mechanize::Catalyst" => "MyApp";
-
-
+
# Create two 'user agents' to simulate two different users ('test01' & 'test02')
my $ua1 = Test::WWW::Mechanize::Catalyst->new;
my $ua2 = Test::WWW::Mechanize::Catalyst->new;
@@ -249,14 +241,12 @@ editor and enter the following:
The C test cases uses copious comments to explain each step
of the process. In addition to the techniques shown here, there are a
-variety of other methods available in
-L (for
-example, regex-based matching). Consult the documentation for more
+variety of other methods available in L
+(for example, regex-based matching). Consult the documentation for more
detail.
B: For I vs. the "full application tests" approach used
-by L, see
-L.
+by L, see L.
B The test script does not test the C and
C actions. That is left as an exercise for the reader
@@ -274,25 +264,23 @@ or
Experiment with the C, C
and C<-v> settings. If you find that there are errors, use the
techniques discussed in the "Catalyst Debugging" section (Part 6) to
-isolate and fix the problem.
+isolate and fix any problems.
If you want to run the test case under the Perl interactive debugger,
try a command such as:
$ DBIX_CLASS_STORAGE_DBI_DEBUG=0 CATALYST_DEBUG=0 perl -d -Ilib t/live_app01.t
-Note that although the tutorial uses a single custom test case for
+Note that although this tutorial uses a single custom test case for
simplicity, you may wish to break your tests into different files for
better organization.
-
-
=head1 SUPPORTING BOTH PRODUCTION AND TEST DATABASES
You may wish to leverage the techniques discussed in this tutorial to
maintain both a "production database" for your live application and a
"testing database" for your test cases. One advantage to
-L is that
+L is that
it runs your full application; however, this can complicate things when
you want to support multiple databases. One solution is to allow the
database specification to be overridden with an environment variable.
@@ -321,8 +309,6 @@ launch your normal application without the C environment
variable defined, it will default to the same C as
before.
-
-
=head1 AUTHOR
Kennedy Clark, C