[Handel] Customising Handel

I have a few questions about customising Handel, specifically the checkout
process. I'm not sure how to do this.

Specifically I want to use the Paypal Standard process (where Paypal handles
the credit cards etc).

I have set up the Handel-cart "out of the box" with help from Claco and that
seems to be working.

However, what I want to happen, when the customer clicks on the checkout
button, is that the process creates an order summary page, that also
generates a form with a "pay with Paypal" button with lots of hidden fields.
All of this is documented on paypal.com, but essentially it articulates the
customer's order. I don't anticipate any problem generating this form as it
should just be a job for the template toolkit.

However, I'm not sure what changes I need to make to my Handel installation
so that it skips the enter-billing-address and enter-credit-card-details
pages. I presume I do something with Handel::Checkout and methods such as
add_handler, add_phase and phases. However, I cannot find enough
documentation to explain what I need to do there.

Paypal will call back (refer the customer browser) to one of several pages
depending on whether the customer coughs up or has second thoughts, so I
want to either mark the order as paid-for or go back to the shopping cart
(and presumably abandon that order); does Handel do these or should I use
some mechanism outside Handel?

This is an OpenPGP/MIME signed message (RFC 2440 and 3156)
--==============50933632=Content-Type: multipart/signed; micalg=pgp-sha1;
protocol="application/pgp-signature";
boundary="------------enig2558DD62482BF1C09E15AC62"

This is an OpenPGP/MIME signed message (RFC 2440 and 3156)
--------------enig2558DD62482BF1C09E15AC62
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: quoted-printable

Martin Ellison wrote:
> I have a few questions about customising Handel, specifically the checkout
> process. I'm not sure how to do this.
>
> Specifically I want to use the Paypal Standard process (where Paypal handles
> the credit cards etc).
>
> I have set up the Handel-cart "out of the box" with help from Claco and that
> seems to be working.
>
> However, what I want to happen, when the customer clicks on the checkout
> button, is that the process creates an order summary page, that also
> generates a form with a "pay with Paypal" button with lots of hidden fields.
> All of this is documented on paypal.com, but essentially it articulates the
> customer's order. I don't anticipate any problem generating this form as it
> should just be a job for the template toolkit.
>
> However, I'm not sure what changes I need to make to my Handel installation
> so that it skips the enter-billing-address and enter-credit-card-details
> pages. I presume I do something with Handel::Checkout and methods such as
> add_handler, add_phase and phases. However, I cannot find enough
> documentation to explain what I need to do there.
>
> Paypal will call back (refer the customer browser) to one of several pages
> depending on whether the customer coughs up or has second thoughts, so I
> want to either mark the order as paid-for or go back to the shopping cart
> (and presumably abandon that order); does Handel do these or should I use
> some mechanism outside Handel?

Sometimes I wish I never added Cat helper code to this dist. It implies
that things will always be done for you, or that things must be done by
cramming code into the generated code. My advice will always be: look at
what it does, then write your own.

The first thing to keep in mind about Handel::Checkout is that
Handel::Checkout does nothing for you. That's right. Handel::Checkout
does nothing. Handel::Checkout is simply a pipeline runner. You tell it
what plugins to apply to an order/orders, group the plugins by name
(phases) and tell the checkout process to run them [all, or just plugsin
in a specific phase], passing the order to each plugin.

So, my advice would be:

1. Determine what phases your checkout will have.

Let's say for the sake of verbosity that your workflow is:
    - init order (when "checkout" is pressed
    - preview page  - gets shipping estimates
    - payment - authorize funds against paypal
    - confirmation page - send order confirmation email

This means you could have the following phases:
    - INITIALIZE
    - PREVIEW
    - AUTHORIZE
    - DELIVER

Add any non standard phases to your checkout module:

    Handel::Checkout->add_phase('CHECKOUT_PHASE_PREVIEW', 42, 1);


2. Write plugins to do small bits of work, and assign them to the
appropriate phases:

> package MyApp::Checkout::Plugin::GetShippingOptions;
> use strict;
> use warnings;
>
> BEGIN {
>     use base qw/Handel::Checkout::Plugin/;
>     use Handel::Constants qw/:checkout/;
>     use Net::UPS;
> };
>
> sub register {
>     my ($self, $ctx) = @_;
>
> $ctx->add_handler(CHECKOUT_PHASE_PREVIEW, \&handler);
>
>     return;
> };
>
> sub handler {
>     my ($self, $ctx) = @_;
> my $ups = Net::UPS->new($userid, $password, $accesskey);
> my $services = $ups->shop_for_rates(15228, 15241, $package);
>  
> $ctx->order->shipping_methods($services);
>
>     return CHECKOUT_HANDLER_OK;
> };
>
> 1;

3. Run the appropriate phases on the appropriate pages/controllers

> sub preview : Local {
>     my ($self, $c) = @_;
> $c->stash->{'template'} = '[% action %]/preview';
>
>     if (my $order = $c->forward('load')) {
>         $c->stash->{'order'} = $order;
>
>  my $checkout = Handel::Checkout->new({
>      order  => $order,
>      phases => 'CHECKOUT_PHASE_PREVIEW'
>  });
>
> if ($checkout->process != CHECKOUT_STATUS_OK) {
> $c->stash->{'errors'} = $checkout->messages;
>  };
>     };
>
>     return;
> };
> [% methods = order.shipping_methods %]
>

> ## in preview.tt
> <select name="shipping_method">
> [% FOREACH method = methods %]
> <option value="[% method.code %]">[% method.label %] - [% method.total_charges %]</option>
> [% END %]
> </select>

This is a very rough overview, but I hope you get the idea of things.
Because everyone checkout is different, I made handel checkout do
nothing specific. The helper generated code is more of an example of how
things are put together...not how things have to be done.

-=Chris


--------------enig2558DD62482BF1C09E15AC62
Content-Type: application/pgp-signature; name="signature.asc"
Content-Description: OpenPGP digital signature
Content-Disposition: attachment; filename="signature.asc"

Chris,

OK, thanks for answering. I'll try writing something tomorrow morning and
see how it goes. I suppose at the moment I am trying to get my head around
the architecture. For example, are checkout phases 1:1 with user pages? Or
do we sometimes have several checkout phases for one user page? Does Handel
connect the template to the phase, or is that something I do in the
controller? What will George I of Hanover do when he comes to London?
(Sorry, wrong Handel).

This is an OpenPGP/MIME signed message (RFC 2440 and 3156)
--==============91352085=Content-Type: multipart/signed; micalg=pgp-sha1;
protocol="application/pgp-signature";
boundary="------------enig06E4AAA86BDD86FA02B084DF"

This is an OpenPGP/MIME signed message (RFC 2440 and 3156)
--------------enig06E4AAA86BDD86FA02B084DF
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: quoted-printable

Martin Ellison wrote:
> Chris,
>
> OK, thanks for answering. I'll try writing something tomorrow morning and
> see how it goes. I suppose at the moment I am trying to get my head around
> the architecture. For example, are checkout phases 1:1 with user pages? Or
> do we sometimes have several checkout phases for one user page? Does Hande

Yes. Any/Or/Either. Nothing is required. You could have one page that
runs all phases, or some phases, or no phases. You could have a page
that runs checkout twice, using two different phases.


l
> connect the template to the phase, or is that something I do in the
> controller? What will George I of Hanover do when he comes to London?
> (Sorry, wrong Handel).


Checkout plugins/phases aren't away of anyhting page related at all. YOu
could run them in a comman line app if you wanted too.

-=Chris


--------------enig06E4AAA86BDD86FA02B084DF
Content-Type: application/pgp-signature; name="signature.asc"
Content-Description: OpenPGP digital signature
Content-Disposition: attachment; filename="signature.asc"

OK, I've looked at the code generated by the helper and also at the Handel
source code. So I think my task list is:

   - clone Handel::Checkout::Plugin::AssignOrderNumber (one copy for each
   checkout step) and modify.
   - if required, modify database tables order and order_items and adjust
   MyApp::Storage::* and MyApp::Model::* accordingly as per
http://search.cpan.org/dist/Handel/lib/Handel/Manual/Cookbook/AddingColumns.pod
   - modify MyApp/Controller/Checkout.pm extensively to use new workflow
   - create any new templates
   - update MyApp/root/{checkout|order}/{messages|profiles}.yml to
   validate any forms


I think that's all I need to do...

What I have found is that what we get from Handel out of the box is

   - creating order numbers and setting orders as 'saved' (the supplied
   plugins)
   - the pages (enter shipping/billing details, enter credit card info,
   etc) and validation for these pages
   - the table schemas and supporting modules
   - the framework

and I need to do the rest.

Is this correct?