.. You may want to use the usual include line. Uncomment and adjust the path. .. include:: ../Includes.txt ================= EXT: My Extension ================= :Author: Kasper Skårhøj :Created: 2002-11-01T00:32:00 :Changed by: Roger Bunyan :Changed: 2006-03-23T11:18:40 :Email: your@email.com .. _EXT-trade: EXT:trade ========= 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 .. _Table-of-Contents: 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 Q. How do I implement an alternate payment gateway? 5 Q. 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 Q. 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: 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: 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: Screen Shots ------------ **Backend Configuration:** |img-1| **Front End Shop:** |img-2| .. _Design-Notes: 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: 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\_ provides the ID of the configured page for this template. - SUBMIT\_TO\_ provides javascript to embed in a submit button that sets the cmd and id to the target command and submits the form. - LINK\_TO\_ 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: Reference --------- plugin.tx\_trade\_pi1 .. ### BEGIN~OF~TABLE ### .. _template: template ^^^^^^^^ .. container:: table-row Property template Data type file Description 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 Default .. _imageBasket: imageBasket ^^^^^^^^^^^ .. container:: table-row Property imageBasket Data type file Description Default EXT:trade/res/cart.jpg .. _noImageAvailable: noImageAvailable ^^^^^^^^^^^^^^^^ .. container:: table-row Property noImageAvailable Data type file Description Default EXT:trade/res/no\_picture.gif .. _adminEmail: adminEmail ^^^^^^^^^^ .. container:: table-row Property adminEmail Data type string Description Email address of the shop administrator. Default .. _maxListRows: maxListRows ^^^^^^^^^^^ .. container:: table-row Property maxListRows Data type interger Description max number of products listed Default 20 .. _currencyCode: currencyCode ^^^^^^^^^^^^ .. container:: table-row Property currencyCode Data type string Description Currency Code Default AUD .. _currencySymbol: currencySymbol ^^^^^^^^^^^^^^ .. container:: table-row Property currencySymbol Data type string Description Currency Symbol Default $ .. _invoiceDescription: invoiceDescription ^^^^^^^^^^^^^^^^^^ .. container:: table-row Property invoiceDescription Data type string Description Default .. _confirmEmailTitle: confirmEmailTitle ^^^^^^^^^^^^^^^^^ .. container:: table-row Property confirmEmailTitle Data type string Description Subject matter for emailed order confirmation. Default Regarding your order .. _plainTextEmails: plainTextEmails ^^^^^^^^^^^^^^^ .. container:: table-row Property plainTextEmails Data type boolean Description Send emails in plain text. You will have to modify the email template to send in html Default 1 .. _shopOwnerDetails: shopOwnerDetails ^^^^^^^^^^^^^^^^ .. container:: table-row Property shopOwnerDetails Data type string Description Shop owner details to be included in invoices and confirmation emails. Default .. _userRequiredFields: userRequiredFields ^^^^^^^^^^^^^^^^^^ .. container:: table-row Property userRequiredFields Data type string Description Comma seperated list of fe\_user fields Default username,password,email,name .. _shippingRequiredFields: shippingRequiredFields ^^^^^^^^^^^^^^^^^^^^^^ .. container:: table-row Property shippingRequiredFields Data type string Description Comma seperated list Default tx\_trade\_shipping\_name .. _cmdList: cmdList ^^^^^^^ .. container:: table-row Property cmdList Data type string Description 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 Default .. _Unknown-Property: ((Unknown Property)) ^^^^^^^^^^^^^^^^^^^^ .. container:: table-row Property Data type Description Default .. _Unknown-Property: ((Unknown Property)) ^^^^^^^^^^^^^^^^^^^^ .. container:: table-row Property Data type Description Default .. ###### END~OF~TABLE ###### .. _Checkout-Basket: Checkout - Basket ^^^^^^^^^^^^^^^^^ plugin.tx\_trade\_pi1.checkout.basket .. ### BEGIN~OF~TABLE ### .. _condition: condition """"""""" .. container:: table-row a condition b string c 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; d .. _next: next """" .. container:: table-row a next b string c d user\_shipping\_details .. _templateSubpart: templateSubpart """"""""""""""" .. container:: table-row a templateSubpart b string c Subpart of the template to use d BASKET .. _Unknown-Property: ((Unknown Property)) """""""""""""""""""" .. container:: table-row a b c d .. ###### END~OF~TABLE ###### .. _Checkout-User-Shipping-Details: Checkout – User Shipping Details ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ plugin.tx\_trade\_pi1.checkout.user\_shipping\_details .. ### BEGIN~OF~TABLE ### .. _condition: condition """"""""" .. container:: table-row a condition b string c **Default:** :: if ($this->user['valid']==1 && $this->user['valid_shipping_details']==1) $testResult=true; d .. _next: next """" .. container:: table-row a next b string c d confirm .. _templateSubpart: templateSubpart """"""""""""""" .. container:: table-row a templateSubpart b string c d USER\_SHIPPING\_DETAILS .. _Unknown-Property: ((Unknown Property)) """""""""""""""""""" .. container:: table-row a b c d .. ###### END~OF~TABLE ###### .. _Checkout-Confirmation: Checkout - Confirmation ^^^^^^^^^^^^^^^^^^^^^^^ plugin.tx\_trade\_pi1.checkout.confirm .. ### BEGIN~OF~TABLE ### .. _condition: condition """"""""" .. container:: table-row a condition b string c Default: :: if ($this->order['status']==1) $testResult=true; d .. _next: next """" .. container:: table-row a next b string c d thanks .. _templateSubpart: templateSubpart """"""""""""""" .. container:: table-row a templateSubpart b string c d CONFIRM .. _Unknown-Property: ((Unknown Property)) """""""""""""""""""" .. container:: table-row a b c d .. ###### END~OF~TABLE ###### .. _Checkout-Thanks: Checkout - Thanks ^^^^^^^^^^^^^^^^^ plugin.tx\_trade\_pi1.checkout.thanks .. ### BEGIN~OF~TABLE ### .. _condition: condition """"""""" .. container:: table-row a condition b string c **Default:** :: $testResult=false; d .. _next: next """" .. container:: table-row a next b string c d NOT USED .. _templateSubpart: templateSubpart """"""""""""""" .. container:: table-row a templateSubpart b string c d THANKS .. ###### END~OF~TABLE ###### \# 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: 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: Known Problems -------------- There are fields in the database tables that are not yet in use. .. _Changelog: Changelog --------- .. _Administration: 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. in your TS config Records can be stored on a different page from the plugins by setting plugin.tx\_trade\_pi1.PID.storage .. _Configuration: 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: 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: 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: 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. |img-3| EXT: My Extension - 10 .. ######CUTTER_MARK_IMAGES###### .. |img-1| image:: img-1.png .. :align: left .. :border: 0 .. :height: 310 .. :id: graphics3 .. :name: graphics3 .. :width: 669 .. |img-2| image:: img-2.png .. :align: left .. :border: 0 .. :height: 386 .. :id: graphics1 .. :name: graphics1 .. :width: 669 .. |img-3| image:: img-3.png .. :align: left .. :border: 0 .. :height: 32 .. :id: Graphic1 .. :name: Graphic1 .. :width: 102