NAME

Template::Plugin::Handel::Order - Template Toolkit plugin for orders

SYNOPSIS

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

DESCRIPTION

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

Since new and load are used by TT2 to load plugins, Handel::Orders 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.Constants %]
    [% cart = hc.create(...) %]
    [% cart.type(hc.ORDER_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:

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

is turned into:

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

Unfortunately, it looks like TT2 reverses the @ARGS order during translation. This causes problems with Handel::Order::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::Order when calling create and items:

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

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

For example:

    [% orders = Handel.Order.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:

    [% orders = Handel.Order.fetch(undef, Handel.Order.RETURNAS_ITERATOR) %]

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

    [% WHILE (order = orders.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:

    [% order = Handel.Order.fetch({id => '12345678-7654-3212-345678987654'}) %]
    [% order.id %]
    [% order.number %]
    ...

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::Order or Handel::Order::Item object:

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

CONSTRUCTOR

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

new

This returns a new Handel.Order 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.Order %]
    [% IF (order = Handel.Order.create({
        shopper => '12345678-9876-5432-1234-567890987654',
        number  => 'O123456789'})) %]

        [% cart.number %]
        ...

    [% END %]

fetch(\%filter [, $wantiterator])

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

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

uuid

Returns a new uuid for use in add/create:

    [% USE Handel.Order %]
    [% IF (order = Handel.Order.create({
        id      => Handel.Cart.uuid,
        shopper => '12345678-9876-5432-1234-567890987654',
        number  => ')123456789'})) %]

        [% order.number %]
        ...

    [% END %]

guid

Same as uuid above.

AUTHOR

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

CPAN RT