plainblack.com
Username Password
search
Bookmark and Share

Writing Tax Drivers

Like payment and shipping drivers, tax drivers allow you to calculate the amount of tax to add to an order. WebGUI already comes with two tax drivers that will handle almost any need in the US and Europe, but since taxes can be even more confusing than payment and shipping, WebGUI allows you to write your own tax driver.

 

API Highlights

WebGUI comes with two tax drivers. The Generic driver takes the cart's shipping address and applies tax based on a configured tax table. The EU driver handles Europe's VAT system and connects to an external system to validate VAT numbers. These are both excellent examples of fully-featured tax handling systems.

 

The Master Classes

Before you begin to write your own tax driver, you'll want to take a look at WebGUI::Shop::Tax and WebGUI::Shop::TaxDriver. As before, WebGUI::Shop::Tax is the management interface to tax drivers, and WebGUI::Shop::TaxDriver is the class your driver must inherit from.

 

Also as before, tax drivers are allowed to have their own www_ methods that can be accessed through a URL like this:

 

/home?shop=tax;method=do;do=someMethod

 

The someMethod refers to the www_someMethod in your tax driver.

 

The Basics

There is only one important method in a tax driver: getTaxRate. Given a WebGUI::Asset::Sku and a WebGUI::Shop::Address, it returns a tax rate in percents (19 is 19% tax).

 

Since it is called on each SKU individually, you can customize the tax rate for every SKU (like some places where food is not taxed unless it is prepared for you).

 

There are three types of configuration for taxes. First, the driver has its own configuration in getConfigurationScreen. Second, the driver can expose a form for every SKU to have some tax configuration options of its own with skuFormDefinition. Last, the driver can expose configuration options tied to a user account with getUserScreen.

 

A Simple Tax Driver Example

This example demonstrates how to write a tax driver that lets you choose one tax rate for everything, and allows individual SKUs to be marked as tax-exempt.

 

To start, make the driver a subclass of the base TaxDriver.

 

package WebGUI::Shop::TaxDriver::Simple;



use strict;

use base 'WebGUI::Shop::TaxDriver';



# Return the class name so WebGUI knows what to look for

sub className { return __PACKAGE__; }

 

Next, set up a configuration screen for the shop admin to enter the tax rate.

 

sub getConfigurationScreen {

my ( $self ) = @_;

my $session = $self->session;

my $hf = WebGUI::HTMLForm->new( $session );

 

You also need to handle the saving of the form, so make the form target the www_saveConfiguration method of your driver. This will make a URL like ...?shop=tax;method=do;do=saveConfiguration.

 

$hf->hidden( name => 'shop', value => 'tax' );

$hf->hidden( name => 'method', value => 'do' );

$hf->hidden( name => 'do', value => 'saveConfiguration' );

 

Finally, add the field to input the tax rate you want. Like other places in WebGUI, you can use the get() method to get a configuration value.

 

$hf->text(

name => 'taxRate',

label => 'Tax Rate',

value => $self->get('taxRate'),

);

$hf->submit();

return $hf->print;

}

 

Of course, we need to make a www_saveConfiguration method to save our configuration.

 

sub www_saveConfiguration {

my ( $self ) = @_;

my $session = $self->session;

my ( $form ) = $session->quick(qw{ form });

$self->update({ taxRate => $form->get('taxRate') });

return ''; # Send us back to the config screen

}

 

You may need to be able to mark individual SKUs as tax-exempt. To do this, override the skuFormDefinition method to give a hash reference of field configuration.

 

sub skuFormDefinition {

my ( $self ) = @_;

return {

isTaxExempt => {

fieldType => 'yesNo',

label => “Is Tax Exempt?”

},

};

}

 

Finally, write the method that will return the tax rate for the item.

 

sub getTaxRate {

my ( $self, $sku, $address ) = @_;

if ( $sku->getTaxConfiguration( $self->className )->{ isTaxExempt } ) {

return 0;

}

else {

return $self->get('taxRate');

}

}

 

Now, you just need to add your class to the “taxDrivers” configuration in the site configuration file and restart the server. Once a driver is chosen, the configuration forms will appear and you will be able to enter tax information.

 

The full module should look like this:

 

package WebGUI::Shop::TaxDriver::Simple;



use strict;

use base 'WebGUI::Shop::TaxDriver';



# Return the class name so WebGUI knows what to look for

sub className { return __PACKAGE__; }



sub getConfigurationScreen {

my ( $self ) = @_;

my $session = $self->session;

my $hf = WebGUI::HTMLForm->new( $session );

$hf->hidden( name => 'shop', value => 'tax' );

$hf->hidden( name => 'method', value => 'do' );

$hf->hidden( name => 'do', value => 'saveConfiguration' );

$hf->text(

name => 'taxRate',

label => 'Tax Rate',

value => $self->get('taxRate'),

);

$hf->submit();

return $hf->print;

}



sub www_saveConfiguration {

my ( $self ) = @_;

my $session = $self->session;

my ( $form ) = $session->quick(qw{ form });

$self->update({ taxRate => $form->get('taxRate') });

return '';

}



sub getTaxRate {

my ( $self, $sku, $address ) = @_;

if ( $sku->getTaxConfiguration( $self->className )->{ isTaxExempt } ) {

return 0;

}

else {

return $self->get('taxRate');

}

}



sub skuFormDefinition {

my ( $self ) = @_;

return {

isTaxExempt => {

fieldType => 'yesNo',

label => "Is Tax Exempt",

},

};

}



1;

Keywords: API tax taxes

Search | Most Popular | Recent Changes | Wiki Home
© 2018 Plain Black Corporation | All Rights Reserved