Codex.gallery2.org

Gallery3:Modules:Basket Plus

2014-01-04

Created page with "{{ModuleInfo |author=Jeroen ten Kate |link=http://www.gallerymodules.com |description=Via Gallery Modules |version=1}} == Basket Plus Module == The Basket Plus module provides..."

New page

{{ModuleInfo

|author=Jeroen ten Kate

|link=http://www.gallerymodules.com

|description=Via Gallery Modules

|version=1}}

== Basket Plus Module ==

The Basket Plus module provides a shopping basket with order workflow, offline and PayPal payment, html e-mail support and several other additions to the configuration. The module is based on the original basket module by Glooper. 

Original Gallery forum post: @TODO 

== Installation ==

To install, extract the "basket_plus" folder from the zip file into your Gallery 3 modules folder. Afterwards log into your Gallery website as an administrator and activate the module in the Admin -> Modules menu. 

Important: error logging should be off when installing the module. 

''Note'': if you want to load the default Basket Plus settings, make sure you have set the default language to either English (en_US or en_UK) or Dutch (nl_NL) before activating the module. The default settings are defined in the file basket_plus_installer_local.php in the Helpers folder. You can modify this file to define default settings for other languages. the 

== Configuration and Order Administration ==

There are six configuration pages and two order administration pages added with the basket plus module. Also, some additional settings are made available in the User details. 

==== Configuration ====

* Configure: basic configuration settings for the web shop, PayPal and localisation. 

* Templates: template settings for the order process pages, order emails and 

* Email Templates: email templates for the confirmation email (offline and PayPal) and update emails 

* Translations: page to enable translations of texts that cannot be translated in the various basket pages 

* Product Lines: to maintain the different photo products offered to customers 

* Postage Bands: to maintain your various packing and shipping options. Define/modify before adding products. 

For more details see the section 'Configuration details' below. 

==== Order Administration ====

* Show Orders: shows an overview of all active orders: orders not delivered or cancelled. 

* Show All Orders: shows an overview of all orders. 

For more details see the section 'Order Administration details' below. 

==== Additional User settings ====

In the User details page, additional settings for pickup and order reference are available. 

More details in the section 'Configuration details' below. 

== Order workflow ==

An order goes through a predefined order workflow. 

==== Standard workflow: ====

1. Customer confirms the order: resulting order status is Waiting Payment 

2. Customer pays the order: resulting order status is Payment Confirmed 

3. Web shop ships the order: resulting order status is Order Delivered 

In above steps, alternative steps are possible: 

==== Alternative workflow: shipment before payment ====

2a. Web shop ships the order without payment: resulting order status is Order Delivered without payment 

3a. Customer pays the order: resulting order status is Order Delivered 

==== Alternative workflow: cancellation ====

2b. Customer cancels the order: resulting order status is Cancelled 

Note: cancellation is not supported after order payment has been done, as prints may have been made already. 

The status transitions can be done in the Order detail page, accessible from one of the order overviews. See the section ' 

== Configuration details ==

The six configuration pages and additional User settings are described below. 

=== Configure ===

'''Webshop''' - Name of the webshop 

'''Webshop Owner''' - Name of the webshop owner 

'''Webshop Address''' - Webshop Address 

'''Webshop Postalcode''' - Webshop Postalcode 

'''Webshop City''' - Webshop City. Add Province, State and/or Country if needed. 

'''Webshop Phone''' - Webshop Phone number 

'''Webshop Details''' - Html block of webshop details used in the confirmation and update emails. 

'''Email From''' - From address (sender address) 

'''Email Order''' - Email address used to send the internal order emails to 

'''Email Contact''' - Email address used in customer emails as default communication 

'''Currency''' - The currency used in the webshop 

'''Date Time Format''' - Format of date and time in emails. Has two choices: European day-month-year 24hr and US month/day/year 12hr. 

'''Decimal Separator''' - Decimal separator for amounts.Has two choices: comma and period. 

'''Use side bar only''' - Determines if the side bar is the single place for basket actions. 

'''Allow Pickup''' - Determines if pickup of the order is allowed. 

'''Is Pickup Default''' - Determines if pickup of the order is checked by default. Only applicable if Allow Pickup is checked. 

'''Pickup Location''' - The default pickup location. Only applicable if Allow Pickup is checked. Note that a specific pickup Location is configurable for each user. 

'''Use Paypal''' - Determines if PayPal payment is possible. 

'''Paypal Account''' - PayPal account of the webshop (owner) to be used with PayPal payments. Only applicable if Use PayPal is checked. 

'''Paypal Test mode''' - Determines if the PayPal test environment is used. Only applicable if Use PayPal is checked. 

'''Order Prefix''' - The fixed text to be put in front of the order id. 

'''Order Bank Account''' - The bank account information for offline payments used in the confirmation and update emails. 

'''Order Bank Account owner''' - Information on the bank account owner for offline payments used in the confirmation and update emails. 

'''Payment Options''' - Html block with the payment options and information on the general terms. Shown in order process step 1: checkout. 

'''Address Format''' - Html block with the address format for showing the customer address. Shown in order process step 2: confirm and used in the confirmation and update emails. 

'''Use Address Suburb''' - Determines if Suburb is used with address information 

'''Use Address Province''' - Determines if Province (or State) is used with address information 

'''Use Address Country''' - Determines if Country is used with address information 

=== Templates ===

'''Payment Details''' - Html block with the payment details used in the confirmation email 

'''Customer Details''' - Html block with the customer details used in the confirmation email 

'''Order Complete Page''' - Html block with the information shown after completing an order with offline payment. 

'''Order Paid Complete Page''' - Html block with the information shown after completing an order with PayPal payment. 

'''Order Thankyou''' - Html block with a thank you message used in the confirmation email 

'''Order Details''' - Html block with all order details used in the confirmation email 

'''Order Complete Email Subject''' - Subject of the confirmation email 

'''Order Paid Email Subject''' - Subject of the update email sent when the order has been paid 

'''Order Paid Email''' - Html body contents of the update email sent when the order has been paid 

'''Order Paid Delivered Email Subject''' - Subject of the update email sent when the order has been paid after delivery 

'''Order Paid Delivered Email''' - Html body contents of the update email sent when the order has been paid after delivery 

'''Order Late Payment Email Subject''' - Subject of the update email sent when payment of the order is overdue 

'''Order Late Payment Email''' - Html body contents of the update email sent when payment of the order is overdue 

'''Order Delivered Email Subject''' - Subject of the update email sent when the order will be or has been delivered 

'''Order Delivered Email''' - Html body contents of the update email sent when the order will be or has been delivered 

'''Order Delivered Notpaid Email Subject''' - Subject of the update email sent when the order will be or has been delivered before payment 

'''Order Delivered Notpaid Email''' - Html body contents of the update email sent when the order will be or has been delivered before payment 

'''Order Delayed Email Subject''' - Subject of the update email sent when delivery of the order is delayed 

'''Order Delayed Email''' - Html body contents of the update email sent when delivery of the order is delayed 

'''Order Cancelled Email Subject''' - Subject of the update email sent when the order has been cancelled 

'''Order Cancelled Email''' - Html body contents of the update email sent when the order has been cancelled 

'''Order Email Closing''' - Html text for the closing of the confirmation and update emails. 

'''Email Template Style''' - CSS styling applied to the confirmation and update emails. 

'''Order Email footer''' - Html text shown in the footer of the confirmation and update emails. 

'''Order Email Logo''' - URL to the Logo of the webshop. Used in the confirmation and update emails. Format: "http://yourdomain/path_to_logo/logo_file" 

=== Email Templates ===

With the email templates you can personalise the communication with your customers. 

An email template contains a text field (max. 2048) and an html field (max. 32K). The text field is meant for the text-only internal order emails, the html field for customer emails. 

By default, three email templates are defined: 

* order: template for the confirmation email that is sent when the customer chooses Offline payment 

* order_paypal: template for the confirmation email that is sent when the customer chooses PayPal payment 

* order_update: template for update emails. The content of these emails is determined by the settings in Templates. The text field is not used as there are no internal update emails sent. 

=== Translations ===

The translations page is only meant to enable translations of texts that cannot be translated in the various basket pages. 

To make or modify translations, activate the translation mode as administrator in the Languages page. Return to the Translations page to modify the translations. 

=== Product Lines ===

From the product lines page you can choose, edit and create the products that you can ship images in. As default three product lines are set up 4x6 8x10 and Original photo. You should edit these to reflect the products that you can ship in and the cost. When a client is viewing an image he will be able to click the "add to basket" button and choose from the list of available products. 

==== Overriding products and prices ====

You can override the available products and costs at either the album or photo level. To do this as an administrator go to the album or photo you wish to override the available products for and choose the edit option. From here you can select the "no products except" and then manually select the products available and the price. Note that when doing this for an album then it effects all sub albums. 

For instance you can edit your root album and disable all photos from being sold by clicking the "no products except" and not choosing any products. This would mean that the "add to basket" will be disabled on all photos, you can then allow a photo to be bought by editing that photo and again clicking the "no products except" and choosing the product lines available. 

=== Postage Bands ===

Postage bands provide ways of adding postage and packaging costs at the checkout. Each product line can be assigned a postage band (this is done on the product line page). A Postage Band consists of a name and two numbers a fixed rate and a per item cost. A fixed rate is the postage added regardless of quantity where as the per item is the postage cost added for each individual item. 

For instance here's how it would work with a couple of scenario's 

* If you only sold prints and always charged $5 for P+P regardless of quantity bought then you would set up a postage band called say "Fixed Rate For Prints". And have the fixed rate set to 5 and the per-item set to 0. This postage band could then be assigned to all products and as such the client would only ever get charged $5 for postage regardless of items bought. 

* If you sold framed prints and sent each print separately regardless of ordered quantity and wish to charge postage of $5 for each framed print then you would create a postage band called "Framed Prints Per Item". And have the Fixed rate sate to 0 and the per-item set to $5. now if a client ordered 10 framed prints, he or she would be charged $50 postage and packaging. 

* It might be that you post frames in the same package but wish to charge a little extra for each print as the weight increase, as such you can edit the previous postage band and set the fixed rate to say $5 and the per-item to $2. Now if a client ordered 10 framed prints, he she would be charged 5 + 2 * 10 = $25. 

You can of course have many different postage bands set up and applied to different products. If a client has products from different postage bands then all the postage options are added up i.e. if he/she bough 5 prints and 10 framed prints he/she could be charged 5 (for the prints) + 25 (for the framed prints) = $30 postage 

=== Additional User settings ===

In the User details page, additional settings for pickup and order reference are available: 

'''Pickup Location''' - A user-specific pickup location, meant for user groups that have a common location other that the default pickup location. For instance, a sports club, school or child day care. Only applicable if Allow Pickup is checked. 

'''Group of users''' - Determines if this user actually represents a group of users. If checked, the specific labels will be used with pickup. 

'''Extra Order Info Label''' - Label for extra order information in case of delivery via pickup. In case of a school, it may contain 'Class'. Only applicable if Group of users is checked. 

'''Extra Order Info ''' - For future use. 

'''Extra Order Info Label 2''' - Second label for extra order information in case of delivery via pickup. In case of a school, it may contain 'Student name'. Only applicable if Group of users is checked. 

'''Extra Order Info 2''' - For future use. 

== Order Administration details ==

==== Order views ====

The order views give an overview of the current status of the orders. The overviews have five columns: 

* Order number: the order number is a link to the order details. When clicked, the order details are displayed below the orders. The order number is coloured red when the order is not paid, green when paid but not delivered and blue when delivered or cancelled. 

* Name: the customer name 

* Order status: the order status is a link to the order log. When clicked, the order log entries are displayed below the orders. 

* Payment - Delivery: the payment choice and delivery choice of the order 

* Total amount: the total order amount, including packaging and posting costs 

==== Order details ====

The order details page shows the saved order record. Depending on the order status, different buttons for sending order updates are available: 

* Order status '''Waiting payment''': buttons Confirm Payment, Send Payment reminder, Send Order confirmation copy, Confirm Delivery without Payment and Cancel Order 

* Order status '''Payment confirmed''': buttons Confirm Delivery and Send Order delayed notification 

* Order status '''Delivered without payment''': buttons Confirm Payment, Send Payment reminder and Send Order confirmation copy 

* Order status '''Delivered''': no buttons 

* Order status '''Cancelled''': no buttons 

== Known issues ==

It is not possible to save certain html tags in textarea-fields, for example the <style> tag. Therefore, the variable %GT is used as replacement. In the code, the variable is replaced with the '<' character to restore the tag. 

== Change Log ==

2014-01-03: Version 1.0 Initial release 

[[Category:Gallery 3:Modules|basket_plus]]