ShoppingCart 31 ShoppingCart ==Xataface Shopping Cart Module== [[toc]] Status: Under development Current Version: 0.2 ===Synopsis=== Add a shopping cart to your xataface application. You can treat any record as a product that can be sold. Includes Paypal connectivity, shipping calculation, and more. ===Requirements=== * Xataface 1.0 or higher * PHP 5 or higher * MySQL 4.1 or higher ===Installation Instructions=== # Download the ShoppingCart module, extract it, and place the ShoppingCart directory in your Xataface modules directory. (i.e. /path/to/xataface/modules/ShoppingCart). # Add the following line to the [_modules] section of your [[conf.ini file]]:<code> modules_ShoppingCart=modules/ShoppingCart/ShoppingCart.php </code> # Add the following to the beginning of your [[index.php file]]:<code> function __autoload($class){ if ( $class == 'ShoppingCart' ) require_once 'modules/ShoppingCart/lib/ShoppingCart/ShoppingCart.class.php'; } </code> # In the [[fields.ini file]] for any table whose records you wish to represent items for sale, add the following:<code> [__implements__] InventoryItem=1 </code> # Specify which fields should be used for the item description, price, width, height, length, and weight in the [[fields.ini file]] for each table whose records you wish to represent items for sale by adding the following directives to the appropriate fields:<code> ShoppingCart.description=1 ShoppingCart.unitPrice=1 ShoppingCart.weight=1 ShoppingCart.width=1 ShoppingCart.height=1 ShoppingCart.length=1 </code> E.g. if your table has a field named ""price"" that you want to represent the unit price, you would have something like:<code> [price] ShoppingCart.unitPrice=1 </code> The shopping cart module will make its best guess on which fields to use for these values if they are not explicitly specified. # Specify the paypal account where money should be deposited by adding the following to your application's [[actions.ini file]]:<code> [view_cart] paypal.account="youremail@example.com" </code> ===Usage Instructions=== Once the Shopping Cart module is installed you can: # Add items to your shopping cart # View your cart contents # Checkout and pay with paypal ====Adding Items to the Cart==== In the View tab of any salable record, you'll notice a little block on the left side of the page with the heading "Add Item to Cart". This includes a field to specify the quantity and a button to add the item to the shopping cart. ====Viewing Cart Contents==== The Shopping Cart module automatically introduces an action to view the cart contents. This action is named "view_cart". Hence you can always view the cart contents by entering the URL: index.php?-action=view_cart . ====Checking Out==== # View the cart contents. # Click "Check out" # This will take you to a paypal page to pay for your items. ==Actions== This module adds the following actions to your application. {| class="listing listing2" |- ! Name ! Content-type ! Description ! Version |- | checkout | text/html | Sends user to paypal to pay for the contents of their cart. | 0.1 |- | calculate_shipping | text/html | Calculates the shipping charges for the cart. | 0.1 |- | add_to_cart | text/html | Adds an item to the cart. | 0.1 |- | clear_cart | text/html | Empties the shopping cart. | 0.1 |- | get_shipping_provinces | text/json | Returns JSON array of provinces for a given country. | 0.1 |- | invoices | text/html | Displays the current user's invoices. | 0.1 |- | payment_complete | text/html | Page that is displayed after a successful payment on paypal. | 0.1 |- | paypal_ipn | none | Handles paypal events such as successful payments. | 0.1 |- | refresh_shipping_methods | text/html | Refreshes the shipping methods available to the system. | 0.1 |- | set_shipping_method | text/html | Sets the selected shipping method to a particular method. | 0.1 |- | view_cart | text/html | View the cart contents. | 0.1 |} ==Blocks and Slots== This module adds the following blocks and slots to your applications. {| class="listing listing2" |- ! Name ! Description ! Version |- | shipping_method | A block with a form to select the shipping method. | 0.1 |- | add_to_cart | A block with a form to add a record/item to the shopping cart. | 0.1 |} ==Application Delegate Class Hooks== You can modify the shopping cart behavior by defining the following methods to the application delegate class. {| class="listing listing2" |- ! Name ! Description ! Version |- | isShippingMandatory | Returns a boolean value indicating whether the user must select a shipping method. | 0.1 |- | getDefaultShippingMethod | Returns a string with the name of the default shipping method to be used. | 0.1 |} ==Table Delegate Class Hooks== You can modify the behavior of the shopping cart by defining the following methods to the delegate class of any table that implements the InventoryItem ontology (i.e. any table that is to be used to store products that can be added to the cart). {| class="listing listing2" |- ! Name ! Description ! Version |- | field__taxes | A calculated field that returns an associative array of all applicable taxes for a product. | 0.1 |} ==Internal Storage== This module creates the following tables to store its data: ===dataface__invoices=== The dataface__invoices table stores the actual invoices for purchases made. An invoice is automatically created as soon as the user "checks out". {| class="listing listing2" |- ! Column Name ! Data Type ! Description ! Version |- | InvoiceID | int(11) | Auto incrementing primary key for the invoice. | 0.1 |- | dateCreated | datetime | The date that the invoice was created. | 0.1 |- | dateModified | datetime | The date that the invoice was last modified | 0.1 |- | status | enum | The status of the invoice (either PENDING, PAID, or APPROVED). | 0.1 |- | amount | decimal(10,2) | The total amount on the invoice. | 0.1 |- | paymentMethod | varchar(32) | The name of the payment method used. | 0.1 |- | referenceID | varchar(64) | ?? | 0.1 |- | username | varchar(32) | The username of the user who owns this invoice. | 0.1 |- | firstName | varchar(32) | The first name of the payer. | 0.1 |- | lastName | varchar(32) | The last name of the payer. | 0.1 |- | address_name | varchar(100) | The name on the shipping address. | 0.1 |- | address1 | varchar(100) | The shipping address line 1. | 0.1 |- | address2 | varchar(100) | The shipping address line 2. | 0.1 |- | city | varchar(40) | The shipping address city. | 0.1 |- | province | varchar(2) | The shipping province or state. | 0.1 |- | country | varchar(2) | The shipping country. | 0.1 |- | postalCode | varchar(32) | The shipping postal code. | 0.1 |- | shipping_method | varchar(50) | The name of the shipping method to use. | 0.1 |- | phone | varchar(32) | The phone number of the payer. | 0.1 |- | email | varchar(127) | The email address of the buyer. | 0.1 |- | data | text | Serialize shopping cart data. | 0.1 |} ===dataface__shipping_methods=== Stores the available shipping methods. {| class="listing listing2" |- ! Column Name ! Data Type ! Description ! Version |- | shipping_method_id | int(11) | Auto increment ID for a shipping method. | 0.1 |- | shipping_method_name | varchar(50) | The name of the shipping method. | 0.1 |- | shipping_method_label | varchar(100) | The label for the shipping method (displayed to the user). | 0.1 |- | shipping_method_enabled | tinyint(1) | Whether or not this shipping method is currently enabled. | 0.1 |- | shipping_method_module | varchar(32) | The name of the handler that this shipping method belongs to. | 0.1 |} ==Payment Handlers== Information about payment handlers to be added here. ==Shipping Handlers== The Shopping Cart module is itself modular, allowing you to develop custom shipping handlers for different types of shipping. A shipping handler is responsible for calculating shipping costs to a destination address. Currently only a UPS shipping handler has been created, but it is not difficult to create other handlers. ===Shipping Handler Public Interface=== {| class="listing listing2" |- ! Method ! Description ! Version |- | calculateShipping | Calculates the shipping cost for the current shopping cart, and adds the shipping cost to the cart as a line item. | 0.1 |- | getInfo | Returns an array of shipping methods that can be handled by this handler. | 0.1 |} en 0