Commerce
<< Back to Extension manuals page
Currently this documentation is geared towards TYPO3 admins more than it is to editors. We need a section explaining how to set up a small shop using a 1-2-3 approach when commerce has already been installed by the site admin.
See the old version of the documentation - and please help to merge.
Demo
Examples
(Yes you can add your Commerce TYPO3 installation here, please sort Alphabetically!)
- http://www.maxversand.ch/ -> shop
- http://allnet.de/ -> catalog + extranet-shop 16.000 Products in 12 languages
- http://www.bauhorizont.de/ -> german shop for construction business
- http://www.domoluce.com/ -> shop with related articles, accessories and many functions in 2 languages
- http://www.expressaufkleber.de/ -> shop with dynamic image colour and text replacement
- http://www.fakieshop.com/ -> shop for snow - skate - streetware
- http://frucha.de/ -> shop
- http://www.galabautechnik.de/ -> catalog
- http://www.gdata.de -> shop ESD
- http://www.hoermann-haendlerforum.de -> extranet-shop, login needed
- http://www.kirschenshop.de/ -> shop
- http://www.kneipp.de -> shop
- http://www.lichtstudio.com/shop/ -> multilingual shop using jquery extensively
- http://www.living-trends.nl
- http://www.magicmaps.de -> German shop for GPS hardware and 3D maps software
- http://www.mawa-design.de/leuchten.html
- http://www.Mein-Name.info -> Produkte (German), V0.9.8 with own extension to allow names on products
- http://www.metabo.com -> product catalog
- http://www.pattex.de -> product catalog
- http://www.regattaservice.net -> shop
- http://www.securitas-aurum.com/ -> shop
- http://www.sie.de/ -> shop
- http://www.simbolica.net/ -> Fair Trade multilingual shop for wholesale and consumers.
- http://www.smalland.de/ -> shop
- http://www.snillo.it/ -> shop for personalized products like t-shirt ecc.
- http://www.spobu.de -> multilanguage product catalogue
- http://www.wein-bauer.de -> german shop for wine
- http://www.xenos-verlag.de/ -> product catalog
Screenshots
Backend
User manual
- Documentation of how to use the extension, how it works, how to apply it if it's a website plugin. A user manual.
- Language should be non-technical, explaining, using small examples.
- Examples: For the "News" plugin this would be a manual showing how to create the news-items, explaining the options etc.
- Target group: Users, Administrators or Developers in that priority. Depends on the extension.
Administration
- Describes how to manage the extension from a superuser point of view. That relates to Page/User TSconfig, permissions, configuration etc. which administrator level users have access to.
- language should be non/semi-technical, explaining, using small examples.
- Target group: Administrators
Installation
This installation procedure is based on: http://www.sk-typo3.de/Shop-aufsetzen-mit-commerce-Quickt.286.0.html
Install the commerce extension
From the extension manager
Install the commerce extension, it will nag you about all the missing prerequisites and give you the opportunity to install them. You can find the latest stable release in the extension repository under the key: 'commerce'.
Install the 'cutting edge' version
As an alternative to getting commerce from the typo3 forge repository, you can also try to work with the cutting edge development version from svn. You can checkout a svn trunk version like so: Go to your TYPO3 installation and then:
cd typo3conf/ext/ # Move your current commerce install out of the way: mv commerce commerce.old # Then issue: svn co https://svn.typo3.org/TYPO3v4/Extensions/commerce/trunk/ commerce
Install the static template
Commerce comes with a static template which you can include into your site template. The easiest way to do this is to go to your root template using Web->List, and then edit your template. Scroll down to the bit that says: "Include static (from extensions)" and include the 'commerce' template. Don't forget to clear your FE cache when using the list module for changing templates.
Fix the EUR currency
The EUR symbol is broken in some installations of static_info_tables. We need to fix this manually. Browse to the 'globe' (TYPO3 root) and then go into list view.
Choose the EUR currency record and fix the values to reflect the image on the right.
Remark: It's not broken it just depends on if your charset settings are correct. I. e. if your database is utf-8 and your backend is utf-8 and you imported static_info_tables as utf-8 everthing is fine. So better don't change it by hand but check if everthing is fine with charsets in your Typo3 installation.
Create a page tree
Shop <-- shop root site
Products <-- insert plugin "Commerce: Product Listing"
detail <-- product detail view (not in menu)
Basket <-- insert plugin "Commerce: Basket"
empty <-- page that is shown if the basket is empty (not in menu)
Checkout <-- insert plugin "Commerce: Checkout"
this page shows the final overview for the purchased items (not in menu)
empty <-- page that is shown if the checkout is empty (not in menu)
Invoice <-- insert plugin "Commerce: Invoice" - (not in menu)
Address management <-- insert plugin "Commerce: Address Management"
address management for returning customers
Addresses <-- container for address records (SysFolder)
User <-- container for customers (SysFolder)
Create some groups
Create some 'website usergroups' in the 'User' sysfolder:
- Clients
- Special
- Admin
Adjust the settings in the extension manager
Now that you have set up the page tree, go to the extension manager and adjust the settings to your liking. Required:
- Page id for new address records
Recommended:
- Simple mode for products (check)
- Page id for invoice
The previewPageID is the ID of the Products page where you put your plugin: Commerce: Product Listing.
After you have finished, clear all the cache and reload the backend.
Copy the default templates to your template storage folder
You can skip this step if you want to use the default templates. If you would like to change the default templates you can copy them to the fileadmin so you can change them to fit your needs.
cd typo3conf/ext/commerce T=../../../fileadmin/templates/commerce/ mkdir $T cp pi1/category_product.tpl $T/product.tmpl cp pi2/shoppingcart.tpl $T/basket.tmpl cp pi3/template_checkout.tpl $T/checkout.tmpl cp pi3/template_adminmail.tpl $T/checkout_adminmail.tmpl cp pi3/template_usermail.tpl $T/checkout_usermail.tmpl cp pi4/template_addresses.tpl $T/addresses.tmpl cp pi6/invoice.tpl $T/invoice.tmpl
Create a TypoScript ext Template for commerce
Here is an example for setting some basic TS. The page id's, paths and filenames can be different in your installation. To get a minimal setup running you only need to add the tx_commerce_lib constants to your template, the rest is optional. You also have to add the Static Template "COMMERCE" to your ext Template.
Constants:
# This is just an example, use your own Pids! plugin.tx_commerce_lib { addressPid = 170 userPid = 171 editAddressPid = 163 basketPid = 179 # overridePid is the Product Detail page overridePid = 180 checkoutPid = 178 emptyBasketPid = 174 emptyCheckoutPid = 173 userGroup = 8 } templatePathCommerce = fileadmin/templates/commerce/
Setup:
# product listing plugin.tx_commerce_pi1 { maxRecords = 6 templateFile = {$templatePathCommerce}product.tmpl } # basket plugin.tx_commerce_pi2.templateFile = {$templatePathCommerce}basket.tmpl # checkout plugin.tx_commerce_pi3 { adminmail { from = user@mydomain.local from_name = Shop Owner mailto = user@mydomain.local templateFile = {$templatePathCommerce}checkout_adminmail.tmpl } usermail { from = user@mydomain.local from_name = Shop Owner templateFile = {$templatePathCommerce}checkout_usermail.tmpl } templateFile = {$templatePathCommerce}checkout.tmpl } # address forms plugin.tx_commerce_pi4.templateFile = {$templatePathCommerce}addresses.tmpl # invoice plugin.tx_commerce_pi6.templateFile = {$templatePathCommerce}invoice.tmpl
Create some products
Create a product catalog
To create a product catalog, go to Commerce->Category and click on the main 'Category'. Choose to create a subcategory. Call it 'Product catalog'.
Create as many sub categories as you like.
Create a product
If you have set 'Simple Mode for products' to 1 in the extension manager, then commerce will create one article if you create a product. This article will have the same title and description as the product. You can place the product images in a nice hierarchical structure in the filemanager.
Change the product and the article as you see fit. Optionally enter a short teaser text in the teaser field.
Place the commerce plugins on the pages
We have created several pages in your page tree. We need to place the appropriate plugins on each page. You need to place a product list plugin on the 'Products' page. You can optionally select a category you want to show in the list.
You can implement the Basket, Checkout and Address management plugins in a similar manner.
The 'empty' pages under Basket and Checkout can be filled with normal content. The user is redirected to these pages when the Basket is empty or he has nothing to checkout.
That's basically it. You should now have a working shop.
The result of all our hard work:
Cleaning up
As you can see in the screen shot there is an ugly marker '###NO_STOCK###'. You can get rid of this marker by removing it from your product.tmpl template. You can also see that the 'add to basket' button reads 'abschicken' by default. You need to change this hard coded string in the product.tmpl on line 65, 80, 109, 124, 152, 169, 208 and 225.
Configuration
Using your Own Mail templates
You can use your own Mailtemplates for the Admin and User mail. The first line of the template is the subject of the Mail send. Hint: The usage of page2tmpl extension can save you a lot of time, especially in a multi-language setup.
RealUrl configuration
Copy the contents of the textbox below to your realurl configuration in /typo3conf/localconf.php. For detailed information about the configuration of this extension see the realUrl manual.
'postVarSets' => array ( '_DEFAULT' => array( # From http://wiki.typo3.org/index.php/Commerce#RealUrl_configuration // . . . using just products (without articles). cHash and BasketHash remain as ordinary GETVars. // product categories 'c' => array( array( 'GETvar' => 'tx_commerce_pi1[catUid]', 'lookUpTable' => array( 'table' => 'tx_commerce_categories', 'id_field' => 'uid', 'alias_field' => 'title', 'addWhereClause' => ' AND NOT deleted', 'enable404forInvalidAlias' => '1', 'useUniqueCache' => 1, 'useUniqueCache_conf' => array( 'strtolower' => 1, 'spaceCharacter' => '-', ), ), ), ), // product 'p' => array( array( 'GETvar' => 'tx_commerce_pi1[showUid]', 'lookUpTable' => array( 'table' => 'tx_commerce_products', 'id_field' => 'uid', 'alias_field' => 'title', 'addWhereClause' => ' AND NOT deleted', 'enable404forInvalidAlias' => '1', 'useUniqueCache' => 1, 'useUniqueCache_conf' => array( 'strtolower' => 1, 'spaceCharacter' => '-', ), # See languageGetVar in http://typo3.org/documentation/document-library/extension-manuals/realurl/1.9.3/view/1/2/ 'languageGetVar' => 'L', 'languageExceptionUids' => '', 'languageField' => 'sys_language_uid', 'transOrigPointerField' => 'l18n_parent', ), ), ), ), ),
CoolUri configuration
<uriparts> <part> <parameter>tx_ttnews[tt_news]</parameter> <lookindb> <to>SELECT title FROM tt_news WHERE uid=$1</to> <translatetoif> <match>^[0-9]+$</match> </translatetoif> <t3conv>1</t3conv> </lookindb> </part> <part> <parameter>tx_commerce_pi1[catUid]</parameter> <lookindb> <to>SELECT title FROM tx_commerce_categories WHERE uid=$1</to> <translatetoif> <match>^[0-9]+$</match> </translatetoif> <t3conv>1</t3conv> </lookindb> </part> <part> <parameter>tx_commerce_pi1[showUid]</parameter> <lookindb> <to>SELECT title FROM tx_commerce_products WHERE uid=$1</to> <translatetoif> <match>^[0-9]+$</match> </translatetoif> <t3conv>1</t3conv> </lookindb> </part> </uriparts>
Typoscript
plugin.tx_commerce_pi1.listView.products.fields.teaserimages {
file.import >
file = fileadmin/images/default.png
file.override.import.current = 1
}
Search
The fesearchintable was in August 2009 in the security bulletin: [1] Till now there is no update.
You can search for articles using fesearchintable. The description says it is a:
"Front End Search tool to help find items within any table and/or tables."
So I decided to try that and discovered that it indeed works. I am interested in expanding on the TS to get it to show teaser images etc. in the result listing.
The important bits are the pidList which you should set to the ID of your commerce folder and the typolink parameter which you should set to the ID of your 'singleview' page:
plugin.tx_fesearchintable_pi1 { searchTables { tx_commerce_products.pidList = 260 tx_commerce_products.listItem { 30.typolink.parameter = 277 } } }
Here is the complete TS:
plugin.tx_fesearchintable_pi1 { searchTables { tt_news > tx_commerce_products = 1 tx_commerce_products.name = Products tx_commerce_products.fields = title,description,teaser,subtitle,keywords tx_commerce_products.selectAdditionalParams = AND 1=1 tx_commerce_products.pidList = 260 tx_commerce_products.recursive = 1 tx_commerce_products.listHeader = COA tx_commerce_products.listHeader { 10 = TEXT 10.value = Produkten 10.wrap = <h3 style="background-color:#FFCC66; color:white; padding: 4px">|</h3> } tx_commerce_products.listItem = COA tx_commerce_products.listItem { stdWrap.wrap = <li>|</li> 10 = TEXT 10.field = title 10.wrap = <strong>Produkt: </strong><strong style='color:#006699;'>|</strong><br> 20 = TEXT 20.field = teaser//description 20.crop = 120|... 30 = TEXT 30.value = lees meer » 30.typolink.parameter = 277 30.typolink.wrap = <em>|</em> 30.typolink.ATagBeforeWrap = 1 30.typolink.additionalParams.dataWrap = &tx_commerce_pi1[showUid]={field:uid} } tx_commerce_products.listStdWrap.wrap = <ol style="margin-top:-10px">|</ol> tx_commerce_products.singleView < plugin.tx_commerce_products tx_commerce_products.singleView.code > tx_commerce_products.singleView.code = SINGLE } }
Extending
Hooks
The following sh snippet will help you to find the hooks in commerce. Cd to your commerce extension dir and run this script. It will spit out a hooks.txt file which contains all the entries of which the script thinks they are hooks hooks (some are not actually hooks ;-).
#!/bin/sh if [ -e hooks.txt ] then rm hooks.txt fi for f in `grep -rl EXTCONF \`find . \( -type f -name "*php" -and \! -name "ext_emconf.php" \)\``; do echo "" >> hooks.txt; echo $f >> hooks.txt; grep -nh EXTCONF $f | grep -v foreach | grep -v getUserObj >> hooks.txt; done;
You can also try the nc_commerce_hookinspector extension. This extension hooks into the commerce hooks and then outputs debug() statements so you can seen when what hooks are actually called. You get the best results if you use it in combination with cc_debug (remember to set config.debug to 1 in your TypoScritp Setup and optionally give your devIPMask in the install tool a proper list of IP's).
list of existing extensions to commerce
- paypal2commerce - Paypal Express-Checkout for commerce, paypal2commerce manual
- wt_commerce_import - Product import for commerce Extension, wt_commerce_import
- dam_commerce - Commerce DAM connector, Extends the commerce extension with the possibility to use DAM for images, dam_commerce
- com_defaultstock - Default stockhandling for commerce, com_defaultstock
- com_ordernumber - Commerce Ordernumber, com_ordernumber
- nc_commerce_hookinspector - Commerce Hook inspector, nc_commerce_hookinspector
- commerce__germantax - Commerce German tax rates, commerce__germantax
- wt_individualshippingcost - Enter different delivery classes per product, wt_individualshippingcost
- wt_commerce_preview - Shows one of the last X tx_commerce products via random function, wt_commerce_preview
- wt_commerce_tipafriend - Tipafriend link within commerce product view, wt_commerce_tipafriend
- wt_commerce2ebay - List your commerce article in ebay via API, wt_commerce2ebay
currently in the works
- coupons/vouchers extension, snapshots from SVN available at http://typo3xdev.sourceforge.net/
- comments / reviews (through Dmitri's generic comments extension)
Integrating payment methods
After adding a payment method to the database, you have to add a price for it in the Commerce backend. Simply click "Add new price" and save, that's all (unless you actually want to add a real price for it). Then Yellowpay (see below) and Paymentlib should work out of the box. Using Paymentlib requires paymentlib, paysuite (for paymentlib < 0.4) idefa_commerce_paymentlib and of course at least one suitable Paymentlib plugin.
Tutorials
Translating
Commerce can be translated by TYPO3 translators on: http://translation.typo3.org/translation/typo3/. If your language lacks a translation, go bug your chief translator about it.
FAQ
- How can i use commerce in multilanguage environment?
- You have to add in list modul an "alternative pagelanguage", after that you can use localisation mode in Commerce-Category-Module.
- There's a marker called ###NO_STOCK### displayed in the basket, product page/list, can I replace it with some data?
- You need to remove the ###NO_STOCK### marker from your template (until commerce code gets smarter). Also, if you don't use stock, you can set the following constant in your template: 'plugin.tx_commerce_lib.useStockHandling = 0'.
- I can put stuff into the basket but I never arrive at the checkout. The checkout link in the basket is not a link. I always arrive at 'empty checkout' page.
- You most likely have template issues which prevent the system from knowing your checkoutPid. Use the Template Object Browser and have a look in: Constants -> plugin -> tx_commerce_lib -> checkoutPid. If the checkoutPid has the value 0 then your template (where you set up your page id's) is not being parsed. Or . . . you are trying to go to checkout from a QUICKVIEW basket. This does not work, go to the checkout from a normal basket.
- Is there a possibility to config (or at least "shrink") the ORDERID ? Something like 46a9b74b915cc0.81208437 is not human readable.
- Yes. You can cook your own. The file /pi3/class.tx_commerce_pi3.php contains a hook that you can use for this purpose: "generateOrderId".
- How do I change the size of the category image in category view?
- Add the following to the 'setup' of your commerce template:
// Category view plugin.tx_commerce_pi1.categoryListView { categories { fields.images { file.maxW = 40 } } }
- I am bored, can I do something?
- Oh yes, you can help completing the commerce documentation.
- How can I get the latest version from SVN?
- Go to your TYPO3 installation and then:
cd typo3conf/ext/ # Now Move your current commerce install out of the way: mv commerce commerce.old # Then issue: svn co https://svn.typo3.org/TYPO3v4/Extensions/commerce/trunk/ commerce
- But I don't have those fancy SVN commands in Windows OR I don't have shell access at my provider.
- Get "Tortoise SVN" from http://tortoisesvn.tigris.org/. It includes then into context menu in Windows Explorer. Rightclick an empty folder and click on "SVN Checkout..." You will get a popup where you can insert the URL mentioned above. After checking out commerce transfer it to your site with FTP.
- How can I reorder products (make new subcategories etc).
- Open up the product record and change the 'parent' category.
- How can I make a link to 'terms and conditions'?
- Create a page in your shop and link to it in the local lang label. On your terms and conditions page you can include a back link using javascript:history.back();.
plugin.tx_commerce_pi3 { _LOCAL_LANG.nl { termstext = Bevestig hier dat u onze <a href="/winkel/leveringsvoorwaarden/">leveringsvoorwaarden</a> heeft gelezen } }
- How do I remove the p tags in the output?
plugin.tx_commerce_pi1.singleView.categories.fields.description.parseFunc.nonTypoTagStdWrap.encapsLines.nonWrappedTag >
- Is there any possibility to enlarge a product image on click?
- Yes there is - you can apply clickEnlarge by adding the appropriate TS values. For further details have a look here [1] and here [2] on imageLinkWrap for configuration.
This is well documented basic TS knowledge which is not really a special trick for commerce (except for the multi-image solution).
you can apply it like this (depending on which stage you want to apply the clickenlarge feature):
Example for enlarging in singleView
You can either copy the configuration from tt_content:
plugin.tx_commerce_pi1 { singleView.products.fields { images { imageLinkWrap < tt_content.image.20.1.imageLinkWrap imageLinkWrap.enable > imageLinkWrap.enable = 1 } } }
Or, you can configure it for your special needs:
plugin.tx_commerce_pi1 { singleView.products.fields { images { imageLinkWrap = 1 imageLinkWrap { enable = 1 # ... for configuration see [2] } } } }
For a much more image manipulation and multiple images per product have a look at the topic with the title 'How-To: multiple images' in the commerce newsgroup. If you use the above solution you can use multliple images by only changing the TS without any need for external php functions.
[1] http://typo3.org/documentation/document-library/references/doc_core_tsref/4.1.0/view/8/6/
[2] http://typo3.org/documentation/document-library/references/doc_core_tsref/4.1.0/view/5/3/
- How do I remove the page browser?
plugin.tx_commerce_pi1.showPageBrowser = 0
- How do I link the teaser image to the product page?
#settings for product listing plugin.tx_commerce_pi1 { # Choose the view you use for teasers below: listView.products.fields { images { # enable click-enlarge for article image imageLinkWrap < tt_content.image.20.1.imageLinkWrap imageLinkWrap.enable > imageLinkWrap.enable = 1 } teaserimages > teaserimages = stdWrap teaserimages { cObject = IMAGE cObject { file { import.current = 1 maxW = 150 } border = 0 params = border=0 } typolink.setCommerceValues = 1 typolink.useCacheHash = 1 typolink.if.isTrue.current = 1 } } }
- How do I make a 'read more' link after the teaser text?
plugin.tx_commerce_pi1 { # Choose the view you use for teasers below: listView.products.fields { teaser > teaser = TEXT teaser { setContentToCurrent = 1 # teaser prepend = TEXT prepend.current = 1 # the more link cObject = TEXT cObject.value = lees meer » wrap = <div class="some class"> |</div> typolink.setCommerceValues = 1 typolink.useCacheHash = 1 } } }
- How can I add a mini-basket (overview) to all pages?
lib.minibasket = COA lib.minibasket { 20 < plugin.tx_commerce_pi2 20.defaultCode > 20.defaultCode = QUICKVIEW 20.templateFile = {$templatePathCommerce}basket.tmpl }
- Why does my category TypoScript haven't any impact?
- you have to write catTS. in front of it.
catTS.templateFile = fileadmin/template/commerce/my_special_category.tmpl
Known problems
- bad documentation :-)
If you find problems, that are not listed here, please post them at the bugtracker (http://forge.typo3.org/projects/extension-commerce/issues) project commerce or in the commerce newsgroup (news://news.typo3.org/typo3.projects.commerce )
TODO
- Add some more documentation
If you have a feature request, please post it at the bugtracker (http://forge.typo3.org/projects/extension-commerce/issues) project commerce.
Changelog
See http://forge.typo3.org/projects/changelog/extension-commerce and http://forge.typo3.org/repositories/entry/extension-commerce/trunk/change.svn for a list of changes.
Current TER version is 0.12.7 (26.05.2011).
Version 0.9.0
- First release in TER
- Updated documentation




