--- /dev/null
+=head1 NAME
+
+Catalyst::Manual::Tutorial::Appendices - Catalyst Tutorial - Part 9: Appendices
+
+
+=head1 OVERVIEW
+
+This is B<Part 9 of 9> of the Catalyst tutorial.
+
+L<Tutorial Overview|Catalyst::Manual::Tutorial>
+
+=over 4
+
+=item 1
+
+L<Introduction|Catalyst::Manual::Tutorial::Intro>
+
+=item 2
+
+L<Catalyst Basics|Catalyst::Manual::Tutorial::CatalystBasics>
+
+=item 3
+
+L<Basic CRUD|Catalyst::Manual::Tutorial_BasicCRUD>
+
+=item 4
+
+L<Authentication|Catalyst::Manual::Tutorial::Authentication>
+
+=item 5
+
+L<Authorization|Catalyst::Manual::Tutorial::Authorization>
+
+=item 6
+
+L<Debugging|Catalyst::Manual::Tutorial::Debugging>
+
+=item 7
+
+L<Testing|Catalyst::Manual::Tutorial::Testing>
+
+=item 8
+
+L<AdvancedCRUD|Catalyst::Manual::Tutorial::AdvancedCRUD>
+
+=item 9
+
+B<Appendices>
+
+=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
+following vi/vim regexs can be helpful to "un-indent" the inserted text
+(do NOT type the quotes, they are only included to show spaces in the
+regex patterns). I<Note that all 3 of the regexs end in 4 spaces>:
+
+=over 4
+
+=item *
+
+":0,$s/^ "
+
+Removes four leading spaces from the entire file (from the first line,
+C<0>, to the last line, C<$>).
+
+=item *
+
+"%s/^ "
+
+A shortcut for the previous item (C<%> specifies the entire file; so
+this removes four leading spaces from every line).
+
+=item *
+
+":.,$s/^ "
+
+Removes the first four spaces from the line the cursor is on at the time
+the regex command is executed (".") to the last line of the file.
+
+=item *
+
+":.,44s/^ "
+
+Removes four leading space from the current line through line 44
+(obviously adjust the C<44> to the appropriate value in your example).
+
+=back
+
+=head2 "Un-indenting" with Emacs
+
+Although there author has not used emacs for many years (apologies to
+the emacs fans out there), here is a quick hint to get you started. To
+replace the leading spaces of every line in a file, use:
+
+ M-x replace-regexp<RET>
+ Replace regexp: ^ <RET>
+ with: <RET>
+
+All of that will occur on the single line at the bottom of your screen.
+Note that "<RET>" represents the return key/enter. Also, there are
+four spaces after the "^" on the "Replace regexp:" line and no spaces
+entered on the last line.
+
+You can limit the replacement operation by selecting text first (depending
+on your version of emacs, you can either use the mouse or experiment with
+commands such as C<C-SPC> to set the mark at the cursor location and
+C<C-E<lt>> and C<C-E<gt>> to set the mark at the beginning and end of the
+file respectively.
+
+
+=head1 APPENDIX 2: USING MYSQL AND POSTGRESQL
+
+The main database used in this tutorial is the very simple yet powerful
+SQLite. This section provides information that can be used to "convert"
+the tutorial to use MySQL and PostgreSQL. However, note that part of
+the beauty of the MVC architecture is that very little database-specific
+code is spread throughout the system (at least when MVC is "done
+right"). Consequently, converting from one database to another is
+relatively painless with most Catalyst applications. In general, you
+just need to adapt the schema definition C<.sql> file you use to
+initialize your database and adjust a few configuration parameters.
+
+Also note that the purpose of the data definition statements for this
+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
+
+Use the following steps to adapt the tutorial to MySQL. Thanks to Jim
+Howard for the help.
+
+=over 4
+
+=item *
+
+Part 2: Catalyst Basics
+
+=over 4
+
+=item *
+
+Install the required software:
+
+=over 4
+
+=item *
+
+The MySQL database server and client utility.
+
+=item *
+
+The Perl C<DBD::MySQL> module
+
+=back
+
+For CentOS users (see
+L<Catalyst::Manual::Installation::CentOS4|Catalyst::Manual::Installation::CentOS4>),
+you can use the following commands to install the software and start the MySQL
+daemon:
+
+ yum -y install mysql mysql-server
+ service mysqld start
+
+=item *
+
+Create the database and set the permissions:
+
+ $ mysql
+ Welcome to the MySQL monitor. Commands end with ; or \g.
+ Your MySQL connection id is 2 to server version: 4.1.20
+
+ Type 'help;' or '\h' for help. Type '\c' to clear the buffer.
+
+ mysql> create database myapp;
+ Query OK, 1 row affected (0.01 sec)
+
+ mysql> grant all on myapp.* to tutorial@'localhost';
+ Query OK, 0 rows affected (0.00 sec)
+
+ mysql> flush privileges;
+ Query OK, 0 rows affected (0.00 sec)
+
+ mysql> quit
+ Bye
+
+=item *
+
+Create the C<.sql> file and load the data:
+
+=over 4
+
+=item *
+
+Open the C<myapp01_mysql.sql> in your editor and enter:
+
+ --
+ -- Create a very simple database to hold book and author information
+ --
+ DROP TABLE IF EXISTS books;
+ DROP TABLE IF EXISTS book_authors;
+ DROP TABLE IF EXISTS authors;
+ CREATE TABLE books (
+ id INT(11) PRIMARY KEY AUTO_INCREMENT,
+ title TEXT ,
+ rating INT(11)
+ );
+ -- 'book_authors' is a many-to-many join table between books & authors
+ CREATE TABLE book_authors (
+ book_id INT(11),
+ author_id INT(11),
+ PRIMARY KEY (book_id, author_id)
+ );
+ CREATE TABLE authors (
+ id INT(11) PRIMARY KEY AUTO_INCREMENT,
+ first_name TEXT,
+ last_name TEXT
+ );
+ ---
+ --- Load some sample data
+ ---
+ INSERT INTO books VALUES (1, 'CCSP SNRS Exam Certification Guide', 5);
+ INSERT INTO books VALUES (2, 'TCP/IP Illustrated, Volume 1', 5);
+ INSERT INTO books VALUES (3, 'Internetworking with TCP/IP Vol.1', 4);
+ INSERT INTO books VALUES (4, 'Perl Cookbook', 5);
+ INSERT INTO books VALUES (5, 'Designing with Web Standards', 5);
+ INSERT INTO authors VALUES (1, 'Greg', 'Bastien');
+ INSERT INTO authors VALUES (2, 'Sara', 'Nasseh');
+ INSERT INTO authors VALUES (3, 'Christian', 'Degu');
+ INSERT INTO authors VALUES (4, 'Richard', 'Stevens');
+ INSERT INTO authors VALUES (5, 'Douglas', 'Comer');
+ INSERT INTO authors VALUES (6, 'Tom', 'Christiansen');
+ INSERT INTO authors VALUES (7, ' Nathan', 'Torkington');
+ INSERT INTO authors VALUES (8, 'Jeffrey', 'Zeldman');
+ INSERT INTO book_authors VALUES (1, 1);
+ INSERT INTO book_authors VALUES (1, 2);
+ INSERT INTO book_authors VALUES (1, 3);
+ INSERT INTO book_authors VALUES (2, 4);
+ INSERT INTO book_authors VALUES (3, 5);
+ INSERT INTO book_authors VALUES (4, 6);
+ INSERT INTO book_authors VALUES (4, 7);
+ INSERT INTO book_authors VALUES (5, 8);
+
+=item *
+
+Load the data:
+
+ mysql -ututorial myapp < myapp01_mysql.sql
+
+=item *
+
+Make sure the data loaded correctly:
+
+ $ mysql -ututorial myapp
+ Reading table information for completion of table and column names
+ You can turn off this feature to get a quicker startup with -A
+
+ Welcome to the MySQL monitor. Commands end with ; or \g.
+ Your MySQL connection id is 4 to server version: 4.1.20
+
+ Type 'help;' or '\h' for help. Type '\c' to clear the buffer.
+
+ mysql> show tables;
+ +-----------------+
+ | Tables_in_myapp |
+ +-----------------+
+ | authors |
+ | book_authors |
+ | books |
+ +-----------------+
+ 3 rows in set (0.00 sec)
+
+ mysql> select * from books;
+ +----+------------------------------------+--------+
+ | id | title | rating |
+ +----+------------------------------------+--------+
+ | 1 | CCSP SNRS Exam Certification Guide | 5 |
+ | 2 | TCP/IP Illustrated, Volume 1 | 5 |
+ | 3 | Internetworking with TCP/IP Vol.1 | 4 |
+ | 4 | Perl Cookbook | 5 |
+ | 5 | Designing with Web Standards | 5 |
+ +----+------------------------------------+--------+
+ 5 rows in set (0.00 sec)
+
+ mysql>
+
+=back
+
+=item *
+
+Update the model:
+
+=over 4
+
+=item *
+
+Delete the existing model:
+
+ rm lib/MyApp/Model/MyAppDB.pm
+
+=item *
+
+Regenerate the model using the Catalyst "_create.pl" script:
+
+ script/myapp_create.pl model MyAppDB DBIC::Schema MyAppDB dbi:mysql:myapp 'tutorial' '' '{ AutoCommit => 1 }'
+
+=back
+
+=back
+
+=item *
+
+Part 4: Authentication
+
+=over 4
+
+=item *
+
+Create the C<.sql> file for the user/roles data:
+
+Open C<myapp02_mysql.sql> in your editor and enter:
+
+ --
+ -- Add users and roles tables, along with a many-to-many join table
+ --
+ CREATE TABLE users (
+ id INT(11) PRIMARY KEY,
+ username TEXT,
+ password TEXT,
+ email_address TEXT,
+ first_name TEXT,
+ last_name TEXT,
+ active INT(11)
+ );
+ CREATE TABLE roles (
+ id INTEGER PRIMARY KEY,
+ role TEXT
+ );
+ CREATE TABLE user_roles (
+ user_id INT(11),
+ role_id INT(11),
+ PRIMARY KEY (user_id, role_id)
+ );
+ --
+ -- Load up some initial test data
+ --
+ INSERT INTO users VALUES (1, 'test01', 'mypass', 't01@na.com', 'Joe', 'Blow', 1);
+ INSERT INTO users VALUES (2, 'test02', 'mypass', 't02@na.com', 'Jane', 'Doe', 1);
+ INSERT INTO users VALUES (3, 'test03', 'mypass', 't03@na.com', 'No', 'Go', 0);
+ INSERT INTO roles VALUES (1, 'user');
+ INSERT INTO roles VALUES (2, 'admin');
+ INSERT INTO user_roles VALUES (1, 1);
+ INSERT INTO user_roles VALUES (1, 2);
+ INSERT INTO user_roles VALUES (2, 1);
+ INSERT INTO user_roles VALUES (3, 1);
+
+=item *
+
+Load the user/roles data:
+
+ mysql -ututorial myapp < myapp02_mysql.sql
+
+=item *
+
+Create the C<.sql> file for the hashed password data:
+
+Open C<myapp03_mysql.sql> in your editor and enter:
+
+ --
+ -- Convert passwords to SHA-1 hashes
+ --
+ UPDATE users SET password = 'e727d1464ae12436e899a726da5b2f11d8381b26' WHERE id = 1;
+ UPDATE users SET password = 'e727d1464ae12436e899a726da5b2f11d8381b26' WHERE id = 2;
+ UPDATE users SET password = 'e727d1464ae12436e899a726da5b2f11d8381b26' WHERE id = 3;
+
+=item *
+
+Load the user/roles data:
+
+ mysql -ututorial myapp < myapp03_mysql.sql
+
+=back
+
+=back
+
+=head2 PostgreSQL
+
+B<TODO> -- Please see the latest version of this document for possible updates:
+L<http://dev.catalyst.perl.org/repos/Catalyst/trunk/Catalyst-Runtime/lib/Catalyst/Manual/Tutorial/Appendices.pod>
+
+
+=head1 APPENDIX 3: IMPROVED HASHING SCRIPT
+
+Here is an improved SHA-1 hashing script from Gavin Henry that does
+not expose the passwords to "capture" on the command line.
+
+ #!/usr/bin/perl -w
+ #===============================================================================
+ #
+ # FILE: enc_pass.pl
+ #
+ # USAGE: ./enc_pass.pl
+ #
+ # DESCRIPTION: Encrypt a Password using SHA-1
+ #
+ # OPTIONS: ---
+ # REQUIREMENTS: ---
+ # BUGS: ---
+ # NOTES: ---
+ # AUTHOR: Gavin Henry (GH), <ghenry@suretecsystems.com>
+ # COMPANY: Suretec Systems Ltd.
+ # VERSION: 1.0
+ # CREATED: 26/06/2006
+ # REVISION: ---
+ # COPYRIGHT: http://search.cpan.org/dist/perl/pod/perlgpl.pod
+ #===============================================================================
+
+ use strict;
+ use warnings;
+ use Digest::SHA1;
+ use Term::ReadKey;
+
+ sub get_pass {
+ ReadMode 'noecho';
+ chomp( my $pw = ReadLine 0 );
+ ReadMode 'normal';
+ return $pw;
+ }
+
+ print "Enter the password to be encrypted: ";
+ my $pass = get_pass();
+
+ print "\nConfirm the password: ";
+ my $verify = get_pass();
+
+ if ( $pass eq $verify ) {
+ my $sha1_enc = Digest::SHA1->new;
+ $sha1_enc->add($pass);
+
+ print "\nYour encrypted password is: "
+ . $sha1_enc->hexdigest . "\n"
+ . "Paste this into your SQL INSERT/COPY Data.\n";
+ }
+ else {
+ print "\nPasswords do not match!\n";
+ }
+
+
+=head1 AUTHOR
+
+Kennedy Clark, C<hkclark@gmail.com>
+
+Please report any errors, issues or suggestions to the author. The
+most recent version of the Catalyst Tutorial can be found at
+L<http://dev.catalyst.perl.org/repos/Catalyst/trunk/Catalyst-Runtime/lib/Catalyst/Manual/Tutorial/>.
+
+Copyright 2006, Kennedy Clark, under Creative Commons License
+(L<http://creativecommons.org/licenses/by-nc-sa/2.5/>).