NAME

Template::Plugin::Handel::Cart - Template Toolkit plugin for shopping cart

SYNOPSIS

    [% USE Handel.Cart %]
    [% IF (cart = Handel.Cart.fetch(id => 'A2CCD312-73B5-4EE4-B77E-3D027349A055')) %]
        [% cart.name %]
        [% FOREACH item IN cart.items %]
            [% item.sku %]
        [% END %]
    [% END %]

DESCRIPTION

Template::Plugin::Handel::Cart is a TT2 (Template Toolkit 2) plugin for Handel::Cart. It's API is exactly the same as Handel::Cart with a few minor exceptions noted below.

Since new and load are used by TT2 to load plugins, Handel::Carts new and load can be accessed using create and fetch.

Starting in version 0.08, Handel::Constants are now imported into this module automatically. This removes the need to use Template::Plugin::Handel::Constants separately when working with carts.

    [% USE hc = Handel.Cart %]
    [% cart = hc.create(...) %]
    [% cart.type(hc.CART_TYPE_TEMP) %]

CAVEATS

Template Toolkit handles method params in a smart fashion that allows you to pass named parameters into methods and it will convert them into HASH references.

For example:

    [% cart.method(name1=val1, name2=val2, otherarg);

is turned into:

    cart->method(otherarg, {name1=>val1, name2=>val2});

Unfortunately, it looks like TT2 reverses the @ARGS order during translation. This causes problems with Handel::Cart::load and items as they expect ($hashref, $wantiterator) instead.

Do to this, it is recommended that you always use the same explicit form as you would use when calling Handel::Cart when calling create and items:

    [% cart.method({name1=>val1, name2=>val2}, $wantiterator) %]

Other issue is how Handel::Cart returns an iterator or an array based on its inspection of wantarray. It appears that TT2 thwarts wantarray in some manner.

For example:

    [% carts = Handel.Cart.fetch() %]

returns an array reference since it's not clear at this point what you really want. To counteract this behavior, you can use RETURNAS constants to specify the exact output desired:

    [% carts = Handel.Cart.fetch(undef, Handel.Cart.RETURNAS_ITERATOR) %]

This will force a return of a Handel::Iterator in scalar context. Then you can simply loop through the iterator:

    [% WHILE (cart = carts.next) %]
        ...
    [% END %]

On the upshot, if you are only expecting a single result, like loading a specific cart by id, then it will just do Do What You Want:

    [% cart = Handel.Cart.fetch({id => '12345678-7654-3212-345678987654'}) %]
    [% cart.id %]
    [% cart.name %]
    ...

You can even use FOREACH without specifying the return type as TT2 appears to just Do The Right Thing regardless of whether it receives an array or a single Handel::Cart or Handel::Cart::Item object:

    [% FOREACH cart IN Handel.Cart.fetch({id => '12345678-7654-3212-345678987654'}}) %]
        [% FOREACH item IN cart.items %]
            [% item.sku %]
        [% END %]
    [% END %]

CONSTRUCTOR

Unlike using Handel::Cart to create a new cart object using new and load, Template::Plugin::Handel::Cart takes a slightly different approach to cart objects. Because USEing in TT2 calls new, we first USE or create a new Template::Plugin::Handel::Cart object then create or load to return a new cart object, iterator, or array of carts.

new

This returns a new Handel.Cart object. This is used internally when loading TT2 plugins and should not be used directly.

METHODS

load

This method is called when TT2 loaded the plugin for the first time. This is used internally by TT2 and should not be used directly.

create(\%filter)

    [% USE Handel.Cart %]
    [% IF (cart = Handel.Cart.create({
        shopper => '12345678-9876-5432-1234-567890987654',
        name    => 'My New Cart',
        description =>'Favorite Items'})) %]

        [% cart.name %]
        ...

    [% END %]

fetch(\%filter [, $wantiterator])

The safest way to get a cart is to use FOREACH. This negates the need to specify $wanteriterator for Handel::Cart::load. See CAVEATS for further info on $wantiterator, Perls wantarray within TT2.

    [% USE Handel.Cart %]
    [% FOREACH cart IN Handel.Cart.fetch({shopper => '12345678-9876-5432-1234-567890987654'}) %]
        [% cart.id %]
        [% cart.name %]
        ...
    [% END %]

uuid

Returns a new uuid for use in add/create:

    [% USE Handel.Cart %]
    [% IF (cart = Handel.Cart.create({
        id      => Handel.Cart.uuid,
        shopper => '12345678-9876-5432-1234-567890987654',
        name    => 'My New Cart',
        description =>'Favorite Items'})) %]

        [% cart.name %]
        ...

    [% END %]

guid

Same as uuid above.

AUTHOR

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

CPAN RT