X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Manual.git;a=blobdiff_plain;f=lib%2FCatalyst%2FManual%2FTutorial%2FTutorial%2FAppendices.pod;fp=lib%2FCatalyst%2FManual%2FTutorial%2FTutorial%2FAppendices.pod;h=102564027d468dc74a9fc1ddbf7e83c044fba122;hp=0000000000000000000000000000000000000000;hb=d442cc9fbdf45a28fe02f13552f44e3e2f7ec22e;hpb=4be096acef2b81af64442da618294f69630029a3 diff --git a/lib/Catalyst/Manual/Tutorial/Tutorial/Appendices.pod b/lib/Catalyst/Manual/Tutorial/Tutorial/Appendices.pod new file mode 100644 index 0000000..1025640 --- /dev/null +++ b/lib/Catalyst/Manual/Tutorial/Tutorial/Appendices.pod @@ -0,0 +1,473 @@ +=head1 NAME + +Catalyst::Manual::Tutorial::Appendices - Catalyst Tutorial - Part 9: Appendices + + +=head1 OVERVIEW + +This is B of the Catalyst tutorial. + +L + +=over 4 + +=item 1 + +L + +=item 2 + +L + +=item 3 + +L + +=item 4 + +L + +=item 5 + +L + +=item 6 + +L + +=item 7 + +L + +=item 8 + +L + +=item 9 + +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 +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: + +=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 + Replace regexp: ^ + with: + +All of that will occur on the single line at the bottom of your screen. +Note that "" 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 to set the mark at the cursor location and +C> and C> 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 module + +=back + +For CentOS users (see +L), +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 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 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 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 -- Please see the latest version of this document for possible updates: +L + + +=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), + # 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 + +Please report any errors, issues or suggestions to the author. The +most recent version of the Catalyst Tutorial can be found at +L. + +Copyright 2006, Kennedy Clark, under Creative Commons License +(L).