EXT: My Extension¶

Table of Contents¶

EXT:trade 1

1 Introduction 1

2 Users Manual 2

4 Screen Shots 3

4.1 Configuration 3

4.2 Front End Shop 4

5 Design Notes 5

6 FAQ 5

Q How do I add fields to the user information or the product information? 5

17. How do I implement an alternate payment gateway? 5

17. How can I customise the types of product listings. 5

Q. What values do I need to place in my form templates to control the checkout process 5

17. What markers are available in the templates. 6

7 Reference 6

8 TODO List 8

9 Known Problems 9

10 Changelog 9

11 Administration 9

12 Configuration 9

Code Structure 9

Function Flow 10

Core Classes 10

Data Structures 10

Data Model 11

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

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

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

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;

if ($this->user['valid']==1 && $this->user['valid_shipping_details']==1) $testResult=true;

if ($this->order['status']==1) $testResult=true;

$testResult=false;

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.