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.
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:
# 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
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>,
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
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.
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
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
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
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
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 *
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"
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