Edikon Release 0.1 of the phpShop InterShipper module.

These are release and functional notes for the phpShop InterShipper module.
We hope to clearly identify the state of the distribution and inform you of any 
installation, configuration and programming changes to the module.


******
NOTICE
******
This document contains IMPORTANT information regarding InterShipper module
functionality, features, and limitations.  Please read completely before
deciding to integrate this module into your phpShop installation.

If you enjoy this module and would like to help, please start by reporting any
bugs to us.  This would help us tremendously.  You can report bugs at

     http://sourceforge.net/bugs/?group_id=747.


This version of the phpShop InterShipper module is distributed under the
pSPL License.  


********
FEATURES
********

The features available in this version of the InterShipper module are:

1.  Live up to the minute shipping calculations for 6 major US carriers with
    over 24 shipping methods
2.  Ability to calculate handling charges at a flat or percentage rate by
    shipping method
3.  Ability to add lead time to the shipment delivery date per shipping method
4.  Ability to offer customers a choice of shipping methods based on cost
    and delivery date.


***********
LIMITATIONS
***********

The phpShop InterShipper module currently has the following limitations:

1.  Only supprts international shipping from WITHIN the US.  Does not support
    originating addresses outside the US.
2.  Shipping quotes are based on the cumulative weight of all products in the
    cart. This quote may differ considerably from the actual cost of shipping
    if items are shipped sepatately.
3.  Shipping quotes do not currently consider package shape, size, material,
    or contents. This quote may differ considerable from the actual cost of
    shipping for shipments of irregular shape or material, and hazardous
    materials
4.  The InterShipper module is dependent on the availability of the
    InterShipper server. If the InterShipper server is down, no shipping
    calculations are made, unless an alternative shipping calculation
    method is supplied. (See ps_intershipper_module.html doc)

Some of these limitations may be addressed in later releases of this module,
but some are permanent.


**************************
BUGS FIXED IN THIS RELEASE
**************************

This is the first release.  So, no bug fixes.

To see detailed bug reports, please look at 
http://sourceforge.net/bugs/?group_id=747.


*************
REQUIREMENTS:
*************

The phpShop InterShipper module requires that you already have a working
installation of phpShop. 


********
OVERVIEW
********

** The Code **

All module functionality is contained in two main include files, ps_intershipper.inc
and Intershipper.inc:

classes/Intershipper.php
This file contains the PHP InterShipper class developed by Desert Raven
(http://www.desertraven.com) for interfacing with the InterShipper API. It is
responsible for generating and interpreting the XML messages that are exchanged
with the InterShipper server, as well as communicating with the InterShipper
server. Thanks to Desert Raven, most of our work has already been done for us.
Much appreciation to Desert Raven for making our task so much simpler. For more
information on the PHP InterShipper class, and the InterShipper API read the
phpintershipperdoc.html file included in this distribution.

classes/ps_intershipper.php
This file contains the class and methods accessible from within phpShop.  It is
responsible for validating and processing the data required for generating
InterShipper requests, and processing the quotes received from the InterShipper
server. It performs all the handling charge and lead time claculations. Other
methods include an InterShipper server ping, and an ISshipping database refresh
function. For more information on the ps_ISship.inc class and methods read
the ps_intershipper_module.html document included in this distribution.

** The Database **

In this release, only one table is required. The mos_pshop_isshipping table contains
all information about the shipping methods. No information regarding quotes,
prices, or shipping zones is maintained in the database. All quotes and
prices are calculated on the fly at the time of checkout. All shipping method
records contain a reference to the vendor_id.  So, it is possible for multiple
vendors to manage different shipping methods.  For more information regarding
the ISshipping table see the ps_intershipper_module.html file.

** The Module **

The phpShop InterShipper module allows the store administrator to select from
among a large variety of shipping methods to use.  Each of the shipping methods
can be configured individually for handling charges and lead time. The shipping
methods that are configured and activated in the admin will be displayed to the
users when they are asked to choose a shipping method, and will be quoted when
the InterShipper server is queried.

A ship from address, ship to address, shipping method, and product weight are
required before a shipping quote can be retreived from the InterShipper server.
For this reason, shipping calculations cannot occur until the checkout process,
and all products in the cart must have a weight assignment.

An InterShipper query is attempted whenever the fetch_quote() function is
called. Querying the InterShipper server for a quote can take some time
(usually about 10-15 seconds). So, to limit the number of times that the server
is queried, the InterShipper module registers the quote with the session. That
way, even if the fetch_quote() function is called multiple times, the
InterShipper server is only queried once per order, unless the cart or ship to
method changes. Then the InterShipper server is queried again with the changes.

** Here's a tip - When retreiving quotes, the InterShipper server is queried by
   carrier, NOT shipping method. So, activating all ship methods for a single
   carrier will return a quote faster than activating a single ship method for
   multiple carriers.

Once the quote has been retreived, and the order processed, the quote and ship
method id is stored in the orders table and in the session variable IS_quote.
The checkout and thankyou pages that came with phpshop need to be modified in
order to recognize the new shipping functionality. Example pages have been
included in this distribution to help you in designing your own checkout and
thankyou pages. Read the INSTALL doc for instructions on how to install the
example pages.

** Configuration & Use **

The following is a brief explaination of how to configure shipping for your
store, and how to incorporate shipping functionality into your checkout
procedures. For more detailed instructions on using the module, read the
ps_intershipper_module.html file.

1.  After you have installed the phpShop Intershipper module, the first time
    you access the "Configure Shipping Methods" page from within the
    administration pages the module will attempt to retreive all shipping
    methods from the InterShipper server.  This can take a while, as the module
    actually queries the server several times.
2.  There are several configuration options available for each shipping method.
    a) ACTIVATE specifies whether the shipping method will be used by your
       store or not. All "active" shipping methods will be queried when a quote
       request is made, and will be displayed by the form element functions.
    b) HANDLING CHARGE specifies the amount and type of handling charge to use
       for that ship method.
    c) LEAD TIME specifies the amount of lead time that should be added to the
       delivery date for the particular ship method.
3.  Once your shipping methods have been activated and configured all that is
    left to do is incorporate the form elements into your checkout pages, and
    shipping calculations into the thankyou page. Depending on how your
    checkout pages are written, this can be very simple or very difficult.
    This distribution comes with example checkout and thankyou pages
    incorporating the shipping functionality. Use these as templates for
    designing your own checkout and thankyou pages. It will almost always be
    necessary to have a two step checkout process.  This is because the
    ship to address needs to be resolved before shipping calculations can be
    made.


*************
INSTALLATION
*************

Please refer to INSTALL for installation instructions.


******************
IN CASE OF TROUBLE
******************

Please let us know of any trouble you run into.  You can view existing bugs
or report new ones by going to http://sourceforge.net/bugs/?group_id=747. 
Please make sure that you check the bug list for any bugs you may think need 
reporting to make sure nobody else has already reported them.

If you need support you should check the online forums at the phpShop homepage.
Go to http://www.phpshop.org.
