Extension Key: trade
Copyright 2000-2020, Steve Ryan, <stever@syntithenai.com>, Roger Bunyan
This document is published under the Open Content License
available from http://www.opencontent.org/opl.shtml
The content of this document is related to TYPO3
- a GNU/GPL CMS/Framework available from www.typo3.com
Trade Manual
Introduction
The trade extension provides a basic shopping cart that integrates with the typo3 framework.
This extension is inspired heavily from the tt_products extension. It is intended that this implementation of a shopping system is more flexible and easier to configure. Users familiar with tt_products will find configuration of the plugin very familiar.
The extension is designed to be highly configurable, allowing users with experience in HTML to control the flow of the checkout process and users with typoscript experience to add stages to the checkout process, configure shipping, payment and price calculations and more.
The extension is designed to work out of the box for inexperienced users. Anyone with access to create content on a website has the ability to insert the shopping cart as a plugin content element and use flex forms to select available payment methods and shop owner details.
The trade extension does not provide functionality for product or order administration. It is intended that these functions are managed through the record editing features available in the back end of typo3 or through the front end using one of the many available record editing libraries. We suggest the admin_interface extension to make things (relatively) easy.
This extension relies on creating records in the fe_users table.
Development of this extension was funded by Roger Bunyan of Redgum Soaps and implemented by Steve Ryan.
Users Manual
To use the trade extension you need to:
Install the extension using the extension manager
Insert a content element of type plugin/trade into the page where you wish to create a shopping cart
Use the flexform configuration to customise the shopping cart. Be sure to set shop owner details and restrict the payment options suitably for your circumstances.
Using Paypal
To use paypal as a payment option you must signup for a free paypal account. Go to http://paypal.com/. If you enable paypal as a payment option, you must also supply the email address that you used to sign up with paypal in flexform configuration. Advanced Notes If you wish to return to your website after payment or recieve notifications from paypal you will need to modify settings for your paypal account. Specifically in your profile under Website Payment Preferences. Enable return URL and set a return url to your website including post parameters id (shopping thanks page with trade plugin installed) and tx_trade_pi1[cmd]=checkout and tx_trade_pi1[external_payment_complete]=1. This will return to the order finalisation stage of the checkout process , create user and order records in the database and displays a thanks page. This approach could not be considered truly secure. Orders should be reconciled against your paypal account. It would also be possible to return to any page within your website if internal order tracking is not required. It would then be advisable to enable Payment Data Transfer to recieve emails from paypal after each transaction.
Using Eway
Eway is an Australian payment gateway service providing a standard interface to a variety of banks as a paid service. You can find out more at https://www.eway.com.au/ If you use eway as a payment option you will also need to purchase an SSL certificate and install and configure one of the typo3 extensions (suggest extension lz_https) that allows you to force the page to https. You must also provide your eway merchant number. It is possible to test your shopping cart against the eway test gateway by ticking the Eway test mode check box.
Create products and optionally product categories in the same page as the shopping cart (It is possible to set a different record storage page as described below)
Advanced users may also like to customise the look and feel by adjusting the HTML template or tweak a range of other options using typoscript.
Voila !
Screen Shots
Backend Configuration:
Front End Shop:
Design Notes
HTML template file
components vs template
TS checkout process control
The stages in the checkout process are configurable by typoscript.
To create maximum flexibility in the extension, the piVar cmd is used almost unchanged to define which template section to render. Make a request to index.php?tx_trade_pi1[cmd]=singleview will attempt to lookup a suitable record based on other parameters and render the singleview template section. Only cmds/templates listed in the TS config validCmds is allowed.
To allow for various list configurations, any cmd starting with list is rewritten as list and an extra internal variable list type is saved.
To provide the notion of state (where is the checkout process up to), where cmd is "checkout" a variety conditions are tested to rewrite the cmd so as to act/render appropriate actions and templates.
FAQ
Q How do I add fields to the user information or the product information?
Use the extension manager to create a new extension that adds fields to the relevant tables.
Customise the HTML template to include markers for your additional fields.
Note that only text area type fields are supported at this stage.
Q. How do I implement an alternate payment gateway?
Look at the files lib/paypal.php and lib/eway_payment.php
Q. How can I customise the types of product listings.
Add a subsection to the lists section in your TS temlate configuration.
eg:
list{
mylist { title=My Selection
label= My Selection
extraWhere= special=1
templateSubpart=ITEM_LIST
search=0
orderBy=title
}
}
Add the title of the subsection (prepended by list_) to the cmdList in your TS configuration so that the list type appears in the automatic lists menu.
e.g.
cmdList=productstorage,categorystorage,/..../,list_mylist
Q. What values do I need to place in my form templates to control the checkout process
For the most part tx_trade_pi1[cmd] and id control the template and the page to post to respectively.
The marker PID_<CMD> provides the ID of the configured page for this template.
SUBMIT_TO_<CMD> provides javascript to embed in a submit button that sets the cmd and id to the target command and submits the form.
LINK_TO_<CMD> provides a relative url to the target command
By default there are hidden form fields in the outermost wrapper template that need to be set with javascript on the buttons.
Additionally
The cmd parameter also drives certain activities. Specifically when:
cmd=copy_address_to_shipping, the user details are copied to the shipping details
cmd=order_history_list or order_history_single (with id=) to use the order tracking
To move on from the basket page, you must set extrainfo=approvebasket using the next button.
To request final payment processing, tx_trade_pi1[finalise_checkout]=1 must be passed as a hidden field from the confirmation or whatever other page.
To validate user or shipping or payment details, the hidden value tx_trade_pi1[submit_shipping||user||payment_details]=1 must be present in the form
Q. What markers are available in the templates.
See EXT:trade/res/ for examples. Also look in the main pi class for the methods get*Markers
Reference
plugin.tx_trade_pi1
Property: | Data type: | Description: | Default: |
|---|---|---|---|
template | file | HTML template selection. Default: template=EXT:trade/res/misc_template.html,EXT:trade/res/item_list_template.html,EXT:trade/res/basket_template.html,EXT:trade/res/confirm_template.html,EXT:trade/res/email_checkout_template.html,EXT:trade/res/saved_order_items_template.html,EXT:trade/res/thanks_template.html,EXT:trade/res/order_history_template.html,EXT:trade/res/misc_component.html,EXT:trade/res/userdetails_component.html,EXT:trade/res/paymentdetails_component.html,EXT:trade/res/shippingdetails_component.html | |
imageBasket | file | EXT:trade/res/cart.jpg | |
noImageAvailable | file | EXT:trade/res/no_picture.gif | |
adminEmail | string | Email address of the shop administrator. | |
maxListRows | interger | max number of products listed | 20 |
currencyCode | string | Currency Code | AUD |
currencySymbol | string | Currency Symbol | $ |
invoiceDescription | string | ||
confirmEmailTitle | string | Subject matter for emailed order confirmation. | Regarding your order |
plainTextEmails | boolean | Send emails in plain text. You will have to modify the email template to send in html | 1 |
shopOwnerDetails | string | Shop owner details to be included in invoices and confirmation emails. | |
userRequiredFields | string | Comma seperated list of fe_user fields | username,password,email,name |
shippingRequiredFields | string | Comma seperated list | tx_trade_shipping_name |
cmdList | string | Comma seperated list of valid comands. Default: cmdList=userstorage,list,list_search,list_recent,singleview,basket,basket_overview,checkout,user_details,user_shipping_details,user_shipping_payment_details,usersave,login,lost_password,confirm,thanks,order_history_list,order_history_single,copy_address_to_shipping,wishlist_list | |
Checkout - Basket
plugin.tx_trade_pi1.checkout.basket
condition | string | Default: if (sizeof($this->basket)>0 && $this->shipping['method']>0 && $this->payment['method']>0 && (($this->piVars['submit_payment_method']==1 && $this->piVars['submit_shipping_method']==1)||$this->user['basket_approved']==1) ) $testResult=true; | |
|---|---|---|---|
next | string | user_shipping_details | |
templateSubpart | string | Subpart of the template to use | BASKET |
Checkout – User Shipping Details
plugin.tx_trade_pi1.checkout.user_shipping_details
condition | string | Default: if ($this->user['valid']==1 && $this->user['valid_shipping_details']==1) $testResult=true; | |
|---|---|---|---|
next | string | confirm | |
templateSubpart | string | USER_SHIPPING_DETAILS | |
Checkout - Confirmation
plugin.tx_trade_pi1.checkout.confirm
condition | string | Default: if ($this->order['status']==1) $testResult=true; | |
|---|---|---|---|
next | string | thanks | |
templateSubpart | string | CONFIRM | |
Checkout - Thanks
plugin.tx_trade_pi1.checkout.thanks
condition | string | Default: $testResult=false; | |
|---|---|---|---|
next | string | NOT USED | |
templateSubpart | string | THANKS |
# WARNING. DO NOT RENUMBER THE FOLLOWING SETTINGS OR YOU WILL BREAK THE FLEX FORM
plugin.tx_trade_pi1.payment {radio = 1
10.title = Credit Card (Eway)
10.description=Secure payment gateway, real time transaction.
10.image.file = media/logos/mastercard.gif
10.priceTax =
#10.calculationScript = EXT:tt_products/pi1/products_comp_calcScript.inc
10.percentOfGoodsTotal = 5
10.detailsOK=if ($this->validateCreditCard($this->piVars['card_number'],$this->payment['card_exp_month'],$this->payment['card_exp_year'],$this->payment['card_name'])) $detailsOK=true; else $detailsOK=false;
10.detailsError=Invalid credit card information. Please check and try again.
10.handleScript=EXT:trade/lib/eway_payment.php
10.merchantCode=
10.useTestGateway=
20.title = Credit Card (Paypal)
20.description=Secure payment gateway, real time transaction.
20.image.file = media/logos/mastercard.gif
20.priceTax =
#10.calculationScript = EXT:tt_products/pi1/products_comp_calcScript.inc
20.percentOfGoodsTotal = 1.4
20.handleScript=EXT:trade/lib/paypal.php
20.paypalEmail=
40.title = Direct Deposit/Cheque/Money Order
40.description=Your order will be shipped when your cheque or money order is received.
40.image.file = media/logos/money.gif
40.priceTax = 2
#40.percentOfGoodsTotal = 0
shipping {
10.title = Ground
10.image.file = media/logos/pakketrans.gif
10.priceTax = 5
10.hideDetails=0
20.title = Airmail
20.image.file = media/logos/postdanmark.gif
20.priceTax =
20.percentOfGoodsTotal=10
20.hideDetails=0
40.title = Pick up in store
40.excludePayment=10
40.hideDetails=1
}
plugin.tx_trade_pi1{
lists {
default {
title=
#extraWhere= category_uid=3
extraWhere=
templateSubpart=ITEM_LIST
search=0
orderBy=sorting
}
search {
title=Search
extraWhere=
templateSubpart=ITEM_LIST
search=1
orderBy=title
}
recent {
title=Recently Added Products
# last 7 days
extraWhere= DATE_SUB(CURDATE(),INTERVAL 7 DAY) <= crdate
templateSubpart=ITEM_LIST
search=0
orderBy=crdate desc
}
specialoffers {
title=Special Offers
extraWhere= special=1
templateSubpart=ITEM_LIST
search=0
orderBy=title
}
}
}
TO DO List
Not necessarily in any order:
next product in list from single view
consumer wishlist
manual order approvals
agreement to terms and conditions
product comments
"also purchased products"
related products
credit poings
drag and drop to cart
vouchers
item variants
gift certificates
discount codes
downloadable products
product/order administration
import/export xml,csv,rss,qif
accounting reports
rss feed of latest products
order tracking
Known Problems
There are fields in the database tables that are not yet in use.
Changelog
Administration
The plugin can be configured over multiple pages.
Page ID for specific stages in the process can be configured by setting plugin.tx_trade_pi1.PIDS.<cmd> in your TS config
Records can be stored on a different page from the plugins by setting plugin.tx_trade_pi1.PID.<user|order|product|category>storage
Configuration
- Technical information; Installation, Reference of TypoScript, configuration options on system level, how to extend it, the technical details, how to debug it.
Code Structure
As per a normal kickstarter extension, various typo3 files exist including database, plugin and extension configuration files to define a single plugin and three additional tables - products, categories and orders.
Changes are also made to the system table fe_users.
The code is split into the main pi1 plugin class (main controller, validation), and multiple others in the lib directory.
The lib files include
class.tx_trade_div.php containing various static support functions, session management included.
class.tx_trade_render.php to wrap up rendering a command
class.tx_trade_pricecalc.php where all price calculations are performed
Other additional/modified files include
ext_typoscript_setup.txt
trade_template.html contains subparts for all possible commands and component templates for those command templates
flexforms
flexform_ds_pi1.xml
locallang_db.php
ext_tables.php
payment processing
credit_card.php
epayment.php
paypal.php
eway_payment.php
Function Flow
main
init
includeFFConf
processPostData
// capture piVars -> basket,user,shipping,order
validate
// validate dependant on what is present in piVars[submit_*]
processUserInput
// command processing
processAddToBasket
processProductSearch
processSaveUser
processFinaliseCheckout
render templates
send emails
save HTML order table against orders
processReset
rendering
renderer->init
// create marker arrays
renderer->renderSection
Core Classes
pi1
renderer
NON TEMPLATE FUNCTIONS
renderShippingMethod
renderPaymentMethod
MAIN FUNCTIONS
renderSection
renderSectionNoWrap // decides on template type - plain, list, categorised
renderCategorisedProductList // render list of items with category headings
renderProductListItems
renderList // render straight forward list of items
renderListItems
renderComponent // single template replace
renderFormWrap // wrap into form template
Data Structures
// library instances
var $renderer;
var $TSParser;
var $LANG;
// user session variables
var $basket; // an array of product records with array key basket_qty set
var $order;
var $user; // array corresponding to fe_users table
var $payment; // array containing payment selections and details
var $shipping; // user shipping details - array corresponding to extended fields in fe_users table
// storage for database results between controller doing query and renderer-> init creating markers
var $record; // single view
var $list; // search
// control variables
var $cmd='list'; // main action for this request
//set by post variables config or default action is list of items on this page
var $renderWith; // template section to render
var $template=''; // contains content of main template file
var $listType; // derived from cmd where cmd begins with list to select custom list configuration
var $doReset=false; // set by controller if a complete session reset is required
// feedback variables to pass error/warning feedback from controller to renderer
var $errors;
var $messages;
// form constants for javascript
var $formName='myform';
var $searchButtonName='do_search';
var $saveUserButtonName='do_save_user';
var $finaliseButtonName='finalise_order';
Data Model
The extension creates database tables for products, categories and orders and extends the fe_users table. See the sql definition file ext_tables.sql for details.
