From: Dan Dascalescu
Date: Mon, 30 Jun 2008 10:16:03 +0000 (+0000)
Subject: Minor: typo and format fixes
X-Git-Tag: v5.8005~275
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Manual.git;a=commitdiff_plain;h=905a3a26761669e7c4fd80daa50034eaa3375b50
Minor: typo and format fixes
---
diff --git a/lib/Catalyst/Manual/Tutorial/Authentication.pod b/lib/Catalyst/Manual/Tutorial/Authentication.pod
index e312ea8..e66fee8 100644
--- a/lib/Catalyst/Manual/Tutorial/Authentication.pod
+++ b/lib/Catalyst/Manual/Tutorial/Authentication.pod
@@ -56,8 +56,8 @@ L
=head1 DESCRIPTION
-Now that we finally have a simple yet functional application, we can
-focus on providing authentication (with authorization coming next in
+Now that we finally have a simple yet functional application, we can
+focus on providing authentication (with authorization coming next in
Part 6).
This part of the tutorial is divided into two main sections: 1) basic,
@@ -129,17 +129,17 @@ option on the DBIC model helper to do most of the work for us:
$ ls lib/MyApp/Schema
Authors.pm BookAuthors.pm Books.pm Roles.pm UserRoles.pm Users.pm
-Notice how the helper has added three new table-specific result source
-files to the C directory. And, more
-importantly, even if there were changes to the existing result source
-files, those changes would have only been written above the C<# DO NOT
-MODIFY THIS OR ANYTHING ABOVE!> comment and your hand-editted
+Notice how the helper has added three new table-specific result source
+files to the C directory. And, more
+importantly, even if there were changes to the existing result source
+files, those changes would have only been written above the C<# DO NOT
+MODIFY THIS OR ANYTHING ABOVE!> comment and your hand-editted
enhancements would have been preserved.
-Speaking of "hand-editted enhancements," we should now add
-relationship information to the three new result source files. Edit
-each of these files and add the following information between the C<#
+Speaking of "hand-editted enhancements," we should now add
+relationship information to the three new result source files. Edit
+each of these files and add the following information between the C<#
DO NOT MODIFY THIS OR ANYTHING ABOVE!> comment and the closing C<1;>:
C:
@@ -147,19 +147,19 @@ C:
#
# Set relationships:
#
-
+
# has_many():
# args:
# 1) Name of relationship, DBIC will create accessor with this name
# 2) Name of the model class referenced by this relationship
# 3) Column name in *foreign* table
__PACKAGE__->has_many(map_user_role => 'MyApp::Schema::UserRoles', 'user_id');
-
+
# many_to_many():
# args:
# 1) Name of relationship, DBIC will create accessor with this name
- # 2) Name of has_many() relationship this many_to_many() is shortcut for
- # 3) Name of belongs_to() relationship in model class of has_many() above
+ # 2) Name of has_many() relationship this many_to_many() is shortcut for
+ # 3) Name of belongs_to() relationship in model class of has_many() above
# You must already have the has_many() defined to use a many_to_many().
__PACKAGE__->many_to_many(roles => 'map_user_role', 'role');
@@ -169,7 +169,7 @@ C:
#
# Set relationships:
#
-
+
# has_many():
# args:
# 1) Name of relationship, DBIC will create accessor with this name
@@ -183,14 +183,14 @@ C:
#
# Set relationships:
#
-
+
# belongs_to():
# args:
# 1) Name of relationship, DBIC will create accessor with this name
# 2) Name of the model class referenced by this relationship
# 3) Column name in *this* table
__PACKAGE__->belongs_to(user => 'MyApp::Schema::Users', 'user_id');
-
+
# belongs_to():
# args:
# 1) Name of relationship, DBIC will create accessor with this name
@@ -199,22 +199,22 @@ C:
__PACKAGE__->belongs_to(role => 'MyApp::Schema::Roles', 'role_id');
-The code for these three sets of updates is obviously very similar to
-the edits we made to the C, C, and C
+The code for these three sets of updates is obviously very similar to
+the edits we made to the C, C, and C
classes created in Part 3.
-Note that we do not need to make any change to the
-C schema file. It simple tells DBIC to
-load all of the result source files it finds in below the
-C directory, so it will automatically pick
+Note that we do not need to make any change to the
+C schema file. It simply tells DBIC to
+load all of the result source files it finds in below the
+C directory, so it will automatically pick
up our new table information.
=head2 Sanity-Check Reload of Development Server
-We aren't ready to try out the authentication just yet; we only want
-to do a quick check to be sure our model loads correctly. Press
-C to kill the previous server instance (if it's still running)
+We aren't ready to try out the authentication just yet; we only want
+to do a quick check to be sure our model loads correctly. Press
+C to kill the previous server instance (if it's still running)
and restart it:
$ script/myapp_server.pl
@@ -238,69 +238,69 @@ Look for the three new model objects in the startup debug output:
'-------------------------------------------------------------------+----------'
...
-Again, notice that your "result source" classes have been "re-loaded"
+Again, notice that your "result source" classes have been "re-loaded"
by Catalyst under C.
=head2 Include Authentication and Session Plugins
-Edit C and update it as follows (everything below
+Edit C and update it as follows (everything below
C is new):
use Catalyst qw/
-Debug
ConfigLoader
Static::Simple
-
+
StackTrace
-
+
Authentication
-
+
Session
Session::Store::FastMmap
Session::State::Cookie
/;
-The C plugin supports Authentication while the
-C plugins are required to maintain state across multiple HTTP
-requests.
+The C plugin supports Authentication while the
+C plugins are required to maintain state across multiple HTTP
+requests.
-Note that the only required Authentication class is the main one. This
-is a change that occurred in version 0.09999_01 of the
-C plugin. You B to specify a particular
-Authentication::Store or Authentication::Credential plugin. Instead,
-indicate the Store and Credential you want to use in your application
+Note that the only required Authentication class is the main one. This
+is a change that occurred in version 0.09999_01 of the
+C plugin. You B to specify a particular
+Authentication::Store or Authentication::Credential plugin. Instead,
+indicate the Store and Credential you want to use in your application
configuration (see below).
-Note that there are several options for
-L
-(L
-is generally a good choice if you are on Unix; try
-L if you
-are on Win32) -- consult
-L and its subclasses
+Note that there are several options for
+L
+(L
+is generally a good choice if you are on Unix; try
+L if you
+are on Win32) -- consult
+L and its subclasses
for additional information and options (for example to use a database-
backed session store).
=head2 Configure Authentication
-Although C<__PACKAGE__-Econfig(name =E 'value');> is still
-supported, newer Catalyst applications tend to place all configuration
-information in C and automatically load this information
-into Cconfig> using the
-L plugin.
+Although C<__PACKAGE__-Econfig(name =E 'value');> is still
+supported, newer Catalyst applications tend to place all configuration
+information in C and automatically load this information
+into Cconfig> using the
+L plugin.
-First, as noted in Part 3 of the tutorial, Catalyst has recently
-switched from a default config file format of YAML to
+First, as noted in Part 3 of the tutorial, Catalyst has recently
+switched from a default config file format of YAML to
C (an apache-like format). In case you are using
a version of Catalyst earlier than v5.7014, delete the C
file and simply follow the directions below to create a new
C file.
-Here, we need to load several parameters that tell
-L
-where to locate information in your database. To do this, edit the
+Here, we need to load several parameters that tell
+L
+where to locate information in your database. To do this, edit the
C file and update it to match:
name MyApp
@@ -309,29 +309,29 @@ C file and update it to match:
- # Note this first definition would be the same as setting
+ # Note: this first definition would be the same as setting
# __PACKAGE__->config->{authentication}->{realms}->{dbic}
- # ->{credential} = 'Password' in lib/MyApp.pm
+ # ->{credential} = 'Password' in lib/MyApp.pm
#
# Specify that we are going to do password-based auth
class Password
# This is the name of the field in the users table with the
# password stored in it
password_field password
- # We are using an unencrypted password now
+ # We are using an unencrypted password for now
password_type clear
# Use DBIC to retrieve username, password & role information
class DBIx::Class
- # This is the model object created by Catalyst::Model::DBIC
+ # This is the model object created by Catalyst::Model::DBIC
# from your schema (you created 'MyApp::Schema::User' but as
- # the Catalyst startup debug messages show, it was loaded as
+ # the Catalyst startup debug messages show, it was loaded as
# 'MyApp::Model::DB::Users').
- # NOTE: Omit 'MyApp::Model' here just as you would when using
+ # NOTE: Omit 'MyApp::Model' here just as you would when using
# '$c->model("DB::Users)'
user_class DB::Users
- # This is the name of the field in your 'users' table that
+ # This is the name of the field in your 'users' table that
# contains the user's name
id_field username
@@ -357,10 +357,10 @@ you could have a C controller with both C and C
actions. Remember, Catalyst is designed to be very flexible, and leaves
such matters up to you, the designer and programmer.
-Then open C, locate the C method (or C if you are using an
-older version of Catalyst) that was automatically inserted by the
-helpers when we created the Login controller above, and delete this
+Then open C, locate the C method (or C if you are using an
+older version of Catalyst) that was automatically inserted by the
+helpers when we created the Login controller above, and delete this
line:
$c->response->body('Matched MyApp::Controller::Login in Login.');
@@ -368,22 +368,22 @@ line:
Then update it to match:
=head2 index
-
+
Login logic
-
+
=cut
-
+
sub index :Path :Args(0) {
my ($self, $c) = @_;
-
+
# Get the username and password from form
my $username = $c->request->params->{username} || "";
my $password = $c->request->params->{password} || "";
-
+
# If the username and password values were found in form
if ($username && $password) {
# Attempt to log the user in
- if ($c->authenticate({ username => $username,
+ if ($c->authenticate({ username => $username,
password => $password} )) {
# If successful, then let them use the application
$c->response->redirect($c->uri_for('/books/list'));
@@ -393,16 +393,16 @@ Then update it to match:
$c->stash->{error_msg} = "Bad username or password.";
}
}
-
+
# If either of above don't work out, send to the login page
$c->stash->{template} = 'login.tt2';
}
This controller fetches the C and C values from the
-login form and attempts to authenticate the user. If successful, it
-redirects the user to the book list page. If the login fails, the user
-will stay at the login page but receive an error message. If the
-C and C values are not present in the form, the
+login form and attempts to authenticate the user. If successful, it
+redirects the user to the book list page. If the login fails, the user
+will stay at the login page and receive an error message. If the
+C and C values are not present in the form, the
user will be taken to the empty login form.
Note that we could have used something like C,
@@ -411,37 +411,37 @@ is generally recommended only to use C in
C, and then mainly to generate the 404 not
found page for the application.
-Instead, we are using C here to
-specifically match the URL C. C actions (aka, "literal
-actions") create URI matches relative to the namespace of the
-controller where they are defined. Although C supports
-arguments that allow relative and absolute paths to be defined, here
-we use an empty C definition to match on just the name of the
-controller itself. The method name, C, is arbitrary. We make
+Instead, we are using C here to
+specifically match the URL C. C actions (aka, "literal
+actions") create URI matches relative to the namespace of the
+controller where they are defined. Although C supports
+arguments that allow relative and absolute paths to be defined, here
+we use an empty C definition to match on just the name of the
+controller itself. The method name, C, is arbitrary. We make
the match even more specific with the C<:Args(0)> action modifier --
-this forces the match on I C, not
+this forces the match on I C, not
C.
-Next, update the corresponding method in
+Next, update the corresponding method in
C to match:
=head2 index
-
+
Logout logic
-
+
=cut
-
+
sub index :Path :Args(0) {
my ($self, $c) = @_;
-
+
# Clear the user's state
$c->logout;
-
+
# Send the user to the starting point
$c->response->redirect($c->uri_for('/'));
}
-As with the login controller, be sure to delete the
+As with the login controller, be sure to delete the
C<$c-Eresponse-Ebody('Matched MyApp::Controller::Logout in Logout.');>
line of the C.
@@ -451,9 +451,9 @@ line of the C.
Create a login form by opening C and inserting:
[% META title = 'Login' %]
-
+
-
-Reload your browser and you should now see a "Login" and "Create" links
-at the bottom of the page (as mentioned earlier, you can update template
-files without reloading the development server). Click the first link
-to return to the login page. This time you I see the "You are
+Reload your browser and you should now see a "Login" and "Create" links
+at the bottom of the page (as mentioned earlier, you can update template
+files without reloading the development server). Click the first link
+to return to the login page. This time you I see the "You are
already logged in" message.
Finally, click the C link on the C page.
@@ -681,10 +681,10 @@ dirty" way to do this:
e727d1464ae12436e899a726da5b2f11d8381b26
$
-B If you are following along in Ubuntu, you will need to install
+B If you are following along in Ubuntu, you will need to install
C with the following command to run the example code above:
- sudo apt-get install libdigest-sha-perl
+ sudo aptitude install libdigest-sha-perl
B You should probably modify this code for production use to
not read the password from the command line. By having the script
@@ -729,7 +729,7 @@ C are new, everything else is the same):
# Note this first definition would be the same as setting
# __PACKAGE__->config->{authentication}->{realms}->{dbic}
- # ->{credential} = 'Password' in lib/MyApp.pm
+ # ->{credential} = 'Password' in lib/MyApp.pm
#
# Specify that we are going to do password-based auth
class Password
@@ -744,14 +744,14 @@ C are new, everything else is the same):
# Use DBIC to retrieve username, password & role information
class DBIx::Class
- # This is the model object created by Catalyst::Model::DBIC
+ # This is the model object created by Catalyst::Model::DBIC
# from your schema (you created 'MyApp::Schema::User' but as
- # the Catalyst startup debug messages show, it was loaded as
+ # the Catalyst startup debug messages show, it was loaded as
# 'MyApp::Model::DB::Users').
- # NOTE: Omit 'MyApp::Model' here just as you would when using
+ # NOTE: Omit 'MyApp::Model' here just as you would when using
# '$c->model("DB::Users)'
user_class DB::Users
- # This is the name of the field in your 'users' table that
+ # This is the name of the field in your 'users' table that
# contains the user's name
id_field username
@@ -774,59 +774,59 @@ login as before. When done, click the "Logout" link on the login page
=head1 USING THE SESSION FOR FLASH
As discussed in Part 3 of the tutorial, C allows you to set
-variables in a way that is very similar to C, but it will
+variables in a way that is very similar to C, but it will
remain set across multiple requests. Once the value is read, it
is cleared (unless reset). Although C has nothing to do with
authentication, it does leverage the same session plugins. Now that
those plugins are enabled, let's go back and improve the "delete
and redirect with query parameters" code seen at the end of the
-L part of the
+L part of the
tutorial.
First, open C and modify C
to match the following (everything after the model search line of code
has changed):
- =head2 delete
-
+ =head2 delete
+
Delete a book
-
+
=cut
-
+
sub delete : Local {
# $id = primary key of book to delete
my ($self, $c, $id) = @_;
-
+
# Search for the book and then delete it
$c->model('DB::Books')->search({id => $id})->delete_all;
-
+
# Use 'flash' to save information across requests until it's read
$c->flash->{status_msg} = "Book deleted";
-
+
# Redirect the user back to the list page
$c->response->redirect($c->uri_for('/books/list'));
}
-Next, open C and update the TT code to pull from
+Next, open C and update the TT code to pull from
flash vs. the C query parameter:
-
+
[% status_msg || Catalyst.flash.status_msg %]
[% error_msg %]
[% content %]
-
+
=head2 Try Out Flash
-Restart the development server and point your browser to
-L to create an extra
-several books. Click the "Return to list" link and delete one of the
-"Test" books you just added. The C mechanism should retain our
+Restart the development server and point your browser to
+L to create an extra
+several books. Click the "Return to list" link and delete one of the
+"Test" books you just added. The C mechanism should retain our
"Book deleted" status message across the redirect.
B While C will save information across multiple requests,
@@ -839,14 +839,14 @@ information.
=head2 Switch To Flash-To-Stash
-Although the a use of flash above is certainly an improvement over the
-C we employed in Part 4 of the tutorial, the C statement is a little ugly. A nice
-alternative is to use the C feature that automatically
-copies the content of flash to stash. This makes your code controller
-and template code work regardless of where it was directly access, a
-forward, or a redirect. To enable C, you can either
-set the value in C by changing the default
+Although the a use of flash above is certainly an improvement over the
+C we employed in Part 4 of the tutorial, the C statement is a little ugly. A nice
+alternative is to use the C feature that automatically
+copies the content of flash to stash. This makes your code controller
+and template code work regardless of where it was directly access, a
+forward, or a redirect. To enable C, you can either
+set the value in C by changing the default
C<__PACKAGE__-Econfig> setting to something like:
__PACKAGE__->config(
@@ -860,8 +860,8 @@ B add the following to C:
flash_to_stash 1
-The C<__PACKAGE__-Econfig> option is probably preferable here
-since it's not something you will want to change at runtime without it
+The C<__PACKAGE__-Econfig> option is probably preferable here
+since it's not something you will want to change at runtime without it
possibly breaking some of your code.
Then edit C and change the C line
@@ -870,7 +870,7 @@ to look like the following:
[% status_msg %]
Restart the development server and go to
-L in your browser. Delete another
+L in your browser. Delete another
of the "Test" books you added in the previous step. Flash should still
maintain the status message across the redirect even though you are no
longer explicitly accessing C.
diff --git a/lib/Catalyst/Manual/Tutorial/Authorization.pod b/lib/Catalyst/Manual/Tutorial/Authorization.pod
index 61c5e29..f889bde 100644
--- a/lib/Catalyst/Manual/Tutorial/Authorization.pod
+++ b/lib/Catalyst/Manual/Tutorial/Authorization.pod
@@ -78,12 +78,12 @@ Edit C and add C to the list:
-Debug
ConfigLoader
Static::Simple
-
+
StackTrace
-
+
Authentication
Authorization::Roles
-
+
Session
Session::Store::FastMmap
Session::State::Cookie
@@ -92,7 +92,7 @@ Edit C and add C to the list:
=head2 Add Config Information for Authorization
-Edit C and update it to match the following (the
+Edit C and update it to match the following (the
C and C definitions are new):
name MyApp
@@ -103,7 +103,7 @@ C and C definitions are new):
# Note this first definition would be the same as setting
# __PACKAGE__->config->{authentication}->{realms}->{dbic}
- # ->{credential} = 'Password' in lib/MyApp.pm
+ # ->{credential} = 'Password' in lib/MyApp.pm
#
# Specify that we are going to do password-based auth
class Password
@@ -118,14 +118,14 @@ C and C definitions are new):
# Use DBIC to retrieve username, password & role information
class DBIx::Class
- # This is the model object created by Catalyst::Model::DBIC
+ # This is the model object created by Catalyst::Model::DBIC
# from your schema (you created 'MyApp::Schema::User' but as
- # the Catalyst startup debug messages show, it was loaded as
+ # the Catalyst startup debug messages show, it was loaded as
# 'MyApp::Model::DB::Users').
- # NOTE: Omit 'MyApp::Model' here just as you would when using
+ # NOTE: Omit 'MyApp::Model' here just as you would when using
# '$c->model("DB::Users)'
user_class DB::Users
- # This is the name of the field in your 'users' table that
+ # This is the name of the field in your 'users' table that
# contains the user's name
id_field username
# This is the name of a many_to_many relation in the users
@@ -146,12 +146,12 @@ Open C in your editor and add the following
lines to the bottom of the file:
Hello [% Catalyst.user.username %], you have the following roles:
-
+
[% # Dump list of roles -%]
[% FOR role = Catalyst.user.roles %]- [% role %]
[% END %]
-
+
[% # Add some simple role-specific logic to template %]
[% # Use $c->check_user_roles() to check authz -%]
@@ -159,7 +159,7 @@ lines to the bottom of the file:
[% # Give normal users a link for 'logout' %]
Logout
[% END %]
-
+
[% # Can also use $c->user->check_roles() to check authz -%]
[% IF Catalyst.check_user_roles('admin') %]
[% # Give admin users a link for 'create' %]
@@ -186,41 +186,41 @@ updating C to match the following code:
Create a book with the supplied title and rating,
with manual authorization
-
+
=cut
-
+
sub url_create : Local {
# In addition to self & context, get the title, rating & author_id args
# from the URL. Note that Catalyst automatically puts extra information
# after the "//check_user_roles('admin')) {
- # Call create() on the book model object. Pass the table
+ # Call create() on the book model object. Pass the table
# columns/field values we want to set as hash values
my $book = $c->model('DB::Books')->create({
title => $title,
rating => $rating
});
-
- # Add a record to the join table for this book, mapping to
+
+ # Add a record to the join table for this book, mapping to
# appropriate author
$book->add_to_book_authors({author_id => $author_id});
# Note: Above is a shortcut for this:
# $book->create_related('book_authors', {author_id => $author_id});
-
+
# Assign the Book object to the stash for display in the view
$c->stash->{book} = $book;
-
+
# This is a hack to disable XSUB processing in Data::Dumper
# (it's used in the view). This is a work-around for a bug in
# the interaction of some versions or Perl, Data::Dumper & DBIC.
# You won't need this if you aren't using Data::Dumper (or if
- # you are running DBIC 0.06001 or greater), but adding it doesn't
+ # you are running DBIC 0.06001 or greater), but adding it doesn't
# hurt anything either.
$Data::Dumper::Useperl = 1;
-
+
# Set the TT template to use
$c->stash->{template} = 'books/create_done.tt2';
} else {
@@ -254,9 +254,9 @@ running) and restart it:
Now trying going to L and you should
be taken to the login page (you might have to C your
-browser and/or click the "Logout" link on the book list page). Try
-logging in with both C and C (both use a password
-of C) and notice how the roles information updates at the
+browser and/or click the "Logout" link on the book list page). Try
+logging in with both C and C (both use a password
+of C) and notice how the roles information updates at the
bottom of the "Book List" page. Also try the C link on the
book list page.
@@ -267,7 +267,7 @@ C. Try:
http://localhost:3000/books/url_create/test/1/6
while logged in as each user. Use one of the 'Logout' links (or go to
-L in you browser directly) when you are
+L in your browser directly) when you are
done.
@@ -275,7 +275,7 @@ done.
This section takes a brief look at how the
L
-plugin can automate much of the work required to perform role-based
+plugin can automate much of the work required to perform role-based
authorization in a Catalyst application.
=head2 Add the C Plugin
@@ -320,14 +320,14 @@ ways. The following provides a basic overview of the capabilities:
=over 4
-=item *
+=item *
The ACL plugin only operates on the Catalyst "private namespace". You
are using the private namespace when you use C actions. C,
C, and C allow you to specify actions where the path and
the namespace differ -- the ACL plugin will not work in these cases.
-=item *
+=item *
Each rule is expressed in a separate
C<__PACKAGE__-Edeny_access_unless()> or
@@ -337,11 +337,11 @@ portion of the
L
documentation for more details).
-=item *
+=item *
Each rule can contain multiple roles but only a single path.
-=item *
+=item *
The rules are tried in order (with the "most specific" rules tested
first), and processing stops at the first "match" where an allow or deny
@@ -350,13 +350,13 @@ is specified. Rules "fall through" if there is not a "match" (where a
then processing stops there and the appropriate allow/deny action is
taken.
-=item *
+=item *
If none of the rules match, then access is allowed.
-=item *
+=item *
-The rules currently need to be specific in the application class
+The rules currently need to be specified in the application class
C B the C<__PACKAGE__-Esetup;> line.
=back
@@ -375,22 +375,22 @@ Open C in your editor and add the
following method:
=head2 access_denied
-
+
Handle Catalyst::Plugin::Authorization::ACL access denied exceptions
-
+
=cut
-
+
sub access_denied : Private {
my ($self, $c) = @_;
-
+
# Set the error message
$c->stash->{error_msg} = 'Unauthorized!';
-
+
# Display the list
$c->forward('list');
}
-Then run the Catalyst development server script:
+Then run the Catalyst development server script:
$ script/myapp_server.pl