/ 
Handel-1.00014
River stage one • 2 direct dependents • 2 total dependents
/ Handel::Manual::QuickStart

NAME

Handel::Manual::QuickStart - A quick start guide to getting Handel up and running.

DESCRIPTION

This guide is meant for those who want to get a shopping cart up and running as quickly as possible using Handel as a stand alone set of classes, as a complete Catalyst application, or as an addition to an existing Catalyst application.

INSTALLATION

See Handel::Manual::Requirements for the list of requirements needed for Handel to run properly. These should be installed automatically by CPAN or CPANPLUS.

CPAN

$ cpan -i Handel

CPANPLUS

$ cpanp -i Handel

NO CUSTOMIZATION

If you don't plan on customizing the default schema or classes, then you're done. Simply use the stock classes in your existing program as you would any other CPAN module.

STAND ALONE APPLICATIONS

If you plan on customizing the default schema (adding columns, changing table names, etc), it is recommended that you create your own set of subclasses, and customize those instead of altering the behaviour of the Handel classes themselves.

To create a new application with Handel classes, run handel: and give it a new application name:

$ handel MyApp

Created MyApp
Created MyApp\lib
Created MyApp\lib\MyApp.pm
Created MyApp\lib\MyApp
Created MyApp\lib\MyApp\Cart.pm
Created MyApp\lib\MyApp\Cart
Created MyApp\lib\MyApp\Cart\Item.pm
Created MyApp\lib\MyApp\Storage
Created MyApp\lib\MyApp\Storage\Cart.pm
Created MyApp\lib\MyApp\Storage\Cart
Created MyApp\lib\MyApp\Storage\Cart\Item.pm
Created MyApp\lib\MyApp\Order.pm
Created MyApp\lib\MyApp\Order
Created MyApp\lib\MyApp\Order\Item.pm
Created MyApp\lib\MyApp\Storage\Order.pm
Created MyApp\lib\MyApp\Storage\Order
Created MyApp\lib\MyApp\Storage\Order\Item.pm
Created MyApp\lib\MyApp\Checkout.pm
Created MyApp\t
Created MyApp\t\pod_syntax.t
Created MyApp\t\pod_spelling.t
Created MyApp\t\basic.t
Created MyApp\t\pod_coverage.t
Created MyApp\.cvsignore
Created MyApp\Makefile.PL
Created MyApp\MANIFEST
Created MyApp\script\myapp_handel.pl
Created starter directories and files

This creates a new CPAN style distribution with all of the recommended Handel subclasses. If you need to change any table names, or add columns, etc, simply alter the various Storage classes using the options in Handel::Storage::DBIC. For example, if you wanted to change the carts table to be named myapp_carts instead, add this to MyApp::Storage::Cart:

__PACKAGE__->table_name('myapp_carts');

Once you are done customizing the storage classes, we need to install the database schema. To do that, run the setup script created in the step above, passing it the DBI dsn /user/pass for the database you wish to install into.

Note: The database you specify must already exist and you need to use a user/password that has permissions to create tables.

$ cd MyApp
$ perl script/myapp_handel.pl schema --install --dsn dbi:mysql:handel:localhost --user myuser --pass mypass
Installed/created database schema

If you want to use a local SQLite database, you can simply pass the --default option which will create a database in MyApp/data/handel.db

$ cd MyApp
$ perl script/myapp_handel.pl schema --install --default
Installed/created database schema

Now, simply treat the newly created code as any other CPAN distribution:

$ perl Makefile.PL
$ make
$ make test
$ make install

NEW CATALYST APPLICATIONS

If you plan on using Handel within a new Catalyst application, you're in luck. Simply create a new Catalyst application using catalyst:

$ catalyst MyApp

created "MyApp"
created "MyApp\script"
created "MyApp\lib"
created "MyApp\root"
created "MyApp\root\static"
created "MyApp\root\static\images"
created "MyApp\t"
created "MyApp\lib\MyApp"
created "MyApp\lib\MyApp\Model"
created "MyApp\lib\MyApp\View"
created "MyApp\lib\MyApp\Controller"
created "MyApp\myapp.yml"
created "MyApp\lib\MyApp.pm"
created "MyApp\lib\MyApp\Controller\Root.pm"
created "MyApp/README"
created "MyApp/Changes"
created "MyApp\t/01app.t"
created "MyApp\t/02pod.t"
created "MyApp\t/03podcoverage.t"
created "MyApp\root\static\images\catalyst_logo.png"
created "MyApp\root\static\images\btn_120x50_built.png"
created "MyApp\root\static\images\btn_120x50_built_shadow.png"
created "MyApp\root\static\images\btn_120x50_powered.png"
created "MyApp\root\static\images\btn_120x50_powered_shadow.png"
created "MyApp\root\static\images\btn_88x31_built.png"
created "MyApp\root\static\images\btn_88x31_built_shadow.png"
created "MyApp\root\static\images\btn_88x31_powered.png"
created "MyApp\root\static\images\btn_88x31_powered_shadow.png"
created "MyApp\root\favicon.ico"
created "MyApp/Makefile.PL"
created "MyApp\script/myapp_cgi.pl"
created "MyApp\script/myapp_fastcgi.pl"
created "MyApp\script/myapp_server.pl"
created "MyApp\script/myapp_test.pl"
created "MyApp\script/myapp_create.pl"

Now, in that new directory, use the Handel helper to create all of the custom subclasses as well as all of the models, controllers, page templates, etc. Make sure to specify the dsn/user/pass of the database this application will be connecting to:

$ cd MyApp
$ perl script/myapp_create.pl Handel mydsn myuser mypass

created "C:\MyApp\data"
 exists "C:\MyApp\lib\MyApp"
created "C:\MyApp\lib\MyApp\Cart.pm"
created "C:\MyApp\lib\MyApp\Cart"
created "C:\MyApp\lib\MyApp\Cart\Item.pm"
created "C:\MyApp\lib\MyApp\Storage"
created "C:\MyApp\lib\MyApp\Storage\Cart.pm"
created "C:\MyApp\lib\MyApp\Storage\Cart"
created "C:\MyApp\lib\MyApp\Storage\Cart\Item.pm"
 exists "C:\MyApp\lib\MyApp"
created "C:\MyApp\lib\MyApp\Order.pm"
created "C:\MyApp\lib\MyApp\Order"
created "C:\MyApp\lib\MyApp\Order\Item.pm"
 exists "C:\MyApp\lib\MyApp\Storage"
created "C:\MyApp\lib\MyApp\Storage\Order.pm"
created "C:\MyApp\lib\MyApp\Storage\Order"
created "C:\MyApp\lib\MyApp\Storage\Order\Item.pm"
 exists "C:\MyApp\lib\MyApp"
created "C:\MyApp\lib\MyApp\Checkout.pm"
created "C:\MyApp\script\myapp_handel.pl"
 exists "C:\MyApp\lib\MyApp\View"
 exists "C:\MyApp\t"
created "C:\MyApp\lib\MyApp\View\TT.pm"
created "C:\MyApp\t\view_TT.t"
 exists "C:\MyApp\lib\MyApp\Model"
 exists "C:\MyApp\t"
created "C:\MyApp\lib\MyApp\Model\Cart.pm"
created "C:\MyApp\t\model_Cart.t"
 exists "C:\MyApp\lib\MyApp\Model"
 exists "C:\MyApp\t"
created "C:\MyApp\lib\MyApp\Model\Order.pm"
created "C:\MyApp\t\model_Order.t"
 exists "C:\MyApp\lib\MyApp\Controller"
 exists "C:\MyApp\t"
created "C:\MyApp\root\cart"
created "C:\MyApp\lib\MyApp\Controller\Cart.pm"
created "C:\MyApp\root\cart\default"
created "C:\MyApp\root\cart\list"
created "C:\MyApp\root\cart\errors"
created "C:\MyApp\root\cart\profiles.yml"
created "C:\MyApp\root\cart\messages.yml"
created "C:\MyApp\root\static\products.htm"
created "C:\MyApp\t\controller_Cart.t"
 exists "C:\MyApp\lib\MyApp\Controller"
 exists "C:\MyApp\t"
created "C:\MyApp\root\order"
created "C:\MyApp\lib\MyApp\Controller\Order.pm"
created "C:\MyApp\root\order\default"
created "C:\MyApp\root\order\view"
created "C:\MyApp\root\order\errors"
created "C:\MyApp\root\order\profiles.yml"
created "C:\MyApp\root\order\messages.yml"
created "C:\MyApp\t\controller_Order.t"
 exists "C:\MyApp\lib\MyApp\Controller"
 exists "C:\MyApp\t"
created "C:\MyApp\root\checkout"
created "C:\MyApp\lib\MyApp\Controller\Checkout.pm"
created "C:\MyApp\root\checkout\default"
created "C:\MyApp\root\checkout\billing"
 exists "C:\MyApp\root\checkout\billing"
created "C:\MyApp\root\checkout\preview"
created "C:\MyApp\root\checkout\payment"
created "C:\MyApp\root\checkout\complete"
created "C:\MyApp\root\checkout\errors"
created "C:\MyApp\root\checkout\profiles.yml"
created "C:\MyApp\root\checkout\messages.yml"
created "C:\MyApp\t\controller_Checkout.t"

If you need to change any table names, or add columns, etc, simply alter the various Storage classes using the options in Handel::Storage::DBIC. For example, if you wanted to change the carts table to be named myapp_carts instead, add this to MyApp::Storage::Cart:

__PACKAGE__->table_name('myapp_carts');

Once you are done customizing the storage classes, we need to install the database schema. To do that, run the createdb script created in the step above, passing it the DBI dsn /user/pass you used above.

Note: The database you specify must already exist and you need to use a user/password that has permissions to create tables.

$ cd MyApp
$ perl script/myapp_handel.pl schema --install --dsn mydsn --user myuser --pass mypass
Installed/created database schema

Edit MyApp.pm and load the Session plugins and a Session::Store/State plugins of your choosing.

Now, just run your shiny new Catalyst/Handel application:

$ perl script/myapp_server.pl

EXISTING CATALYST APPLICATIONS

If you already have a Catalyst application but want to add Handel bits and piece to it, several helpers are provided to assist.

See the individual helper documentation below for more information.

SEE ALSO

Catalyst::Helper::Controller::Handel::Cart, Catalyst::Helper::Controller::Handel::Order, Catalyst::Helper::Controller::Handel::Checkout, Catalyst::Helper::Handel::Scaffold, Catalyst::Helper::Model::Handel::Cart, Catalyst::Helper::Model::Handel::Order

AUTHOR

Christopher H. Laco
CPAN ID: CLACO
claco@chrislaco.com
http://today.icantfocus.com/blog/