yaml expurgation and placeholders for a couple of upcoming tutorial articles
Kieren Diment [Fri, 23 May 2008 22:56:03 +0000 (22:56 +0000)]
Changes
lib/Catalyst/Manual/Cookbook.pod
lib/Catalyst/Manual/Plugins.pod
lib/Catalyst/Manual/Tutorial/AdvancedCRUD/FormBuilder.pod
lib/Catalyst/Manual/Tutorial/AdvancedCRUD/FormFu.pod
lib/Catalyst/Manual/Tutorial/Authentication.pod
lib/Catalyst/Manual/Tutorial/Authorization.pod
lib/Catalyst/Manual/Tutorial/CatalystBasics.pod
lib/Catalyst/Manual/Tutorial/MoreCatalystBasics.pod

diff --git a/Changes b/Changes
index 085da0d..e32ad12 100644 (file)
--- a/Changes
+++ b/Changes
@@ -1,6 +1,10 @@
 Revision history for Catalyst-Manual
 
- 5.7011
+5.7012
+       - Expurgation of all yaml as configuration format
+       - Major updates to tutorial, thanks hkclark and gerda 
+
+5.7011
        - added warnings and poiinters to newer examples in HTML::Widget,
          and Authentication parts of the tutorial.
 
index d115523..192d3bd 100644 (file)
@@ -160,36 +160,27 @@ You configure your application with the C<config> method in your
 application class. This can be hard-coded, or brought in from a
 separate configuration file.
 
-=head3 Using YAML
+=head3 Using Config::General
 
-YAML is a method for creating flexible and readable configuration
-files. It's a great way to keep your Catalyst application
-configuration in one easy-to-understand location.
+L<Config::General|Config::General> is a method for creating flexible
+and readable configuration files. It's a great way to keep your
+Catalyst application configuration in one easy-to-understand location.
 
-In your application class (e.g. C<lib/MyApp.pm>):
+Now create C<myapp.conf> in your application home:
 
-  use YAML;
-  # application setup
-  __PACKAGE__->config( YAML::LoadFile(__PACKAGE__->config->{'home'} . '/myapp.yml') );
-  __PACKAGE__->setup;
-
-Now create C<myapp.yml> in your application home:
-
-  --- #YAML:1.0
-  # DO NOT USE TABS FOR INDENTATION OR label/value SEPARATION!!!
-  name:     MyApp
+  name     MyApp
 
   # session; perldoc Catalyst::Plugin::Session::FastMmap
-  session:
-    expires:        '3600'
-    rewrite:        '0'
-    storage:        '/tmp/myapp.session'
+  <Session>
+    expires 3600
+    rewrite 0
+    storage /tmp/myapp.session
+  </Session>
 
   # emails; perldoc Catalyst::Plugin::Email
   # this passes options as an array :(
-  email:
-    - SMTP
-    - localhost
+  Mail SMTP
+  Mail localhost
 
 This is equivalent to:
 
@@ -208,7 +199,7 @@ This is equivalent to:
   # configure email sending
   __PACKAGE__->config->{email} = [qw/SMTP localhost/];
 
-See also L<YAML>.
+See also L<Config::General|Config::General>.
 
 =head1 Skipping your VCS's directories
 
index 5ce9609..a15b47f 100644 (file)
@@ -157,6 +157,7 @@ enabling easy access to a shared cache.
 
 Provides a standard method for loading config files. Support
 exists for various formats. See
+L<Catalyst::Plugin::ConfigLoader::General>
 L<Catalyst::Plugin::ConfigLoader::INI>,
 L<Catalyst::Plugin::ConfigLoader::JSON>,
 L<Catalyst::Plugin::ConfigLoader::Perl>,
index 198d7c6..9485500 100644 (file)
@@ -2,6 +2,7 @@
 
 Catalyst::Manual::Tutorial::AdvancedCRUD::FormBuilder - Catalyst Tutorial - Part 9: Advanced CRUD - FormBuilder
 
+NOTE:  This part of the tutorial is in progress and will be ready soon.
 
 =head1 OVERVIEW
 
index 40eb8d0..38eab9b 100644 (file)
@@ -3,6 +3,8 @@
 Catalyst::Manual::Tutorial::AdvancedCRUD::FormFu - Catalyst Tutorial - Part 9: Advanced CRUD - FormFu
 
 
+NOTE:  This part of the tutorial is in progress and will be ready soon.
+
 =head1 OVERVIEW
 
 This is B<Part 9 of 10> for the Catalyst tutorial.
index fa577d3..cbaa099 100644 (file)
@@ -293,49 +293,49 @@ L<ConfigLoader|Catalyst::Plugin::ConfigLoader> plugin.  Here, we need
 to load several parameters that tell 
 L<Catalyst::Plugin::Authentication|Catalyst::Plugin::Authentication> 
 where to locate information in your database.  To do this, edit the 
-C<myapp.yml> YAML and update it to match:
-
-    ---
-    name: MyApp
-    authentication:
-        default_realm: dbic
-        realms:
-            dbic:
-                credential:
+C<myapp.conf> file and update it to match:
+
+    name MyApp
+    <authentication>
+        default_realm dbic
+        <realms>
+            <dbic>
+                <credential>
                     # Note this first definition would be the same as setting
                     # __PACKAGE__->config->{authentication}->{realms}->{dbic}
                     #     ->{credential} = 'Password' in lib/MyApp.pm 
-                    # (IOW, each hash key becomes a "name:" in the YAML file).
                     #
                     # Specify that we are going to do password-based auth
-                    class:          Password
+                    class Password
                     # This is the name of the field in the users table with the
                     # password stored in it
-                    password_field: password
+                    password_field password
                     # We are using an unencrypted password now
-                    password_type:  clear
-                store:
+                    password_type clear
+                </credential>
+                <store>
                     # Use DBIC to retrieve username, password & role information
-                    class:          DBIx::Class
+                    class DBIx::Class
                     # This is the model object created by Catalyst::Model::DBIC 
                     # from your schema (you created 'MyAppDB::User' but as the 
                     # Catalyst startup debug messages show, it was loaded as 
                     # 'MyApp::Model::MyAppDB::Users').
                     # NOTE: Omit 'MyApp::Model' here just as you would when using 
                     # '$c->model("MyAppDB::Users)'
-                    user_class:     MyAppDB::Users
+                    user_class MyAppDB::Users
                     # This is the name of the field in your 'users' table that 
                     # contains the user's name
-                    id_field:       username
+                    id_field username
+                </store>
+            </dbic>
+          </realms>
+        </authentication>
 
 Inline comments in the code above explain how each field is being used.
 
-B<TIP>: Although YAML uses a very simple and easy-to-ready format, it 
-does require the use of a consistent level of indenting.  Be sure you 
-line up everything on a given 'level' with the same number of indents. 
-Also, be sure B<not> to use C<tab> characters (YAML does not support 
-them because they are handled inconsistently across editors).
-
+Note that you can use many other config file formats with catalyst.
+See L<Catalyst::Plugin::ConfigLoader|Catalyst::Plugin::ConfigLoader>
+for details.
 
 =head2 Add Login and Logout Controllers
 
@@ -712,40 +712,43 @@ Edit C<myapp.yml> and update it to match (the C<password_type> and
 C<password_hash_type> are new, everything else is the same):
 
     ---
-    name: MyApp
-    authentication:
-        default_realm: dbic
-        realms:
-            dbic:
-                credential:
+    name MyApp
+    <authentication>
+        default_realm dbic
+        <realms>
+            <dbic>
+                <credential>
                     # Note this first definition would be the same as setting
                     # __PACKAGE__->config->{authentication}->{realms}->{dbic}
                     #     ->{credential} = 'Password' in lib/MyApp.pm 
-                    # (IOW, each hash key becomes a "name:" in the YAML file).
                     #
                     # Specify that we are going to do password-based auth
-                    class:          Password
+                    class Password
                     # This is the name of the field in the users table with the
                     # password stored in it
-                    password_field: password
+                    password_field password
                     # Switch to more secure hashed passwords
-                    password_type:  hashed
+                    password_type  hashed
                     # Use the SHA-1 hashing algorithm
-                    password_hash_type: SHA-1
-                store:
+                    password_hash_type SHA-1
+                 </credential>
+                <store>
                     # Use DBIC to retrieve username, password & role information
-                    class:          DBIx::Class
+                    class DBIx::Class
                     # This is the model object created by Catalyst::Model::DBIC 
                     # from your schema (you created 'MyAppDB::User' but as the 
                     # Catalyst startup debug messages show, it was loaded as 
                     # 'MyApp::Model::MyAppDB::Users').
                     # NOTE: Omit 'MyApp::Model' here just as you would when using 
                     # '$c->model("MyAppDB::Users)'
-                    user_class:     MyAppDB::Users
+                    user_class MyAppDB::Users
                     # This is the name of the field in your 'users' table that 
                     # contains the user's name
-                    id_field:       username
-
+                    id_field username
+                 </store>
+              </dbic>
+           </realms>
+         </authentication>
 
 =head2 Try Out the Hashed Passwords
 
index 5f4e4ef..b1c16ad 100644 (file)
@@ -96,43 +96,47 @@ Edit C<myapp.yml> and update it to match the following (the
 C<role_relation> and C<role_field> definitions are new):
 
     ---
-    name: MyApp
-    authentication:
-        default_realm: dbic
-        realms:
-            dbic:
-                credential:
+    name MyApp
+    <authentication>
+        default_realm dbic
+        <realms>
+            <dbic>
+                <credential>
                     # Note this first definition would be the same as setting
                     # __PACKAGE__->config->{authentication}->{realms}->{dbic}
                     #     ->{credential} = 'Password' in lib/MyApp.pm 
-                    # (IOW, each hash key becomes a "name:" in the YAML file).
                     #
                     # Specify that we are going to do password-based auth
-                    class:          Password
+                    class Password
                     # This is the name of the field in the users table with the
                     # password stored in it
-                    password_field: password
+                    password_field password
                     # We are using an unencrypted password now
-                    password_type:  clear
-                store:
+                    password_type clear
+                 </credential>
+                <store>
                     # Use DBIC to retrieve username, password & role information
-                    class:          DBIx::Class
+                    class DBIx::Class
                     # This is the model object created by Catalyst::Model::DBIC 
                     # from your schema (you created 'MyAppDB::User' but as the 
                     # Catalyst startup debug messages show, it was loaded as 
                     # 'MyApp::Model::MyAppDB::Users').
                     # NOTE: Omit 'MyApp::Model' here just as you would when using 
                     # '$c->model("MyAppDB::Users)'
-                    user_class:     MyAppDB::Users
+                    user_class MyAppDB::Users
                     # This is the name of the field in your 'users' table that 
                     # contains the user's name
-                    id_field:       username
+                    id_field username
                     # This is the name of a many_to_many relation in the users
                     # object that points to the roles for that user
-                    role_relation:  roles
+                    role_relation  roles
                     # This is the name of field in the roles table that contains
                     # the role information
-                    role_field:     role
+                    role_field role
+                  </store>
+                </dbic>
+              </realms>
+            </authentication>
 
 
 =head2 Add Role-Specific Logic to the "Book List" Template
index c1e1b91..e366b10 100644 (file)
@@ -318,8 +318,8 @@ Now that the TT.pm "View" exists, Catalyst will autodiscover it and be
 able to use it to display the view templates, using the "process" 
 method that it inherits from the C<Catalyst::View::TT class>.
 
-Template Toolkit is a rather complicated template facility, with 
-excellent docs at 
+Template Toolkit is a very full featured template facility, with 
+excellent documentation at 
 L<http://template-tookit.org/|http://template-tookit.org/>, 
 but since this is not a TT tutorial, we'll stick to only basic TT 
 usage here (and explore some of the more common TT features in later 
index c52f435..29ea997 100644 (file)
@@ -133,12 +133,12 @@ free to make use of it in your own projects.
 L<Catalyst::Plugin::ConfigLoader|Catalyst::Plugin::ConfigLoader>
 
 C<ConfigLoader> provides an automatic way to load configurable
-parameters for your application from a central YAML file (versus having
-the values hard-coded inside your Perl modules).  If you have not been
-exposed to YAML before, it is a human-readable data serialization format
-that can be used to read (and write) values to/from text files.  We will
-see how to use this feature of Catalyst during the authentication and
-authorization sections (Part 5 and Part 6).
+parameters for your application from a central
+L<Config::General|Config::General> file (versus having the values
+hard-coded inside your Perl modules).  Config::General uses syntax
+very similar to Apache configuration files.  We will see how to use
+this feature of Catalyst during the authentication and authorization
+sections (Part 5 and Part 6).
 
 =item *
 
@@ -570,13 +570,13 @@ in the past, Matt Trout's L<DBIx::Class|DBIx::Class> (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
+=head2 Create a DBIC Model
 
-Use the C<create=dynamic> model helper option to build a model that 
+Use the C<create=static> model helper option to build a model that 
 dynamically reads your database structure every time the application
 starts:
 
-    $ script/myapp_create.pl model MyAppDB DBIC::Schema MyApp::Schema::MyAppDB create=dynamic dbi:SQLite:myapp.db
+    $ script/myapp_create.pl model MyAppDB DBIC::Schema MyApp::Schema::MyAppDB create=static dbi:SQLite:myapp.db
      exists "/home/me/MyApp/script/../lib/MyApp/Model"
      exists "/home/me/MyApp/script/../t"
     created "/home/me/MyApp/script/../lib/MyApp/Schema"
@@ -597,13 +597,6 @@ the schema information from the database every time the application
 starts.  And finally, C<dbi:SQLite:myapp.db> is the standard DBI connect 
 string for use with SQLite.
 
-B<NOTE>: Although the C<create=dynamic> option to the DBIC helper 
-makes for a nifty demonstration, is not suitable for real world 
-applications. Moreover, it may not be supported in future versions of 
-DBIC.  After this demonstration, please use the C<create=static> 
-option that we switch to below.
-
-
 =head1 RUN THE APPLICATION
 
 First, let's enable an environment variable option that causes