Translations
Info
All page names need to be in English.
en da  de  fr  it  ja  km  nl  ru  zh

Commerce

From TYPO3Wiki
Jump to: navigation, search
Extension detail information
commerce
This shop-extension offers a solution that fullfills almost all current requirements for e-commerce software.
documentation state needs a review document state list
licence OCL
forgeproject
mailinglist http://lists.typo3.org/cgi-bin/mailman/listinfo/typo3-project-commerce
usergroups list of usergroups forAdmins, forIntermediates
author(s) Ingo Schmitt, Volker Graubaum
TER category fe
dependency tt_address, graytree, dynaflex, moneylib, static_info_tables

<< Back to Extension manuals page

[edit]


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

commerce_demoshop


Examples

(Yes you can add your Commerce TYPO3 installation here, please sort Alphabetically!)

Screenshots

Backend

category tree
page tree
product edit

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

extension manager, search 'commerce'
extension manager, commerce deps

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

include 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

currency records

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.

EUR currency record

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

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)

notice - Note

Please write down the PageID's for the settings in TS

notice - Note

You can quickly create a pagetree using the extension: wizard_crpagetree. Just paste the following into the textarea:
Shop,0,1
 Products,0,1
  detail,1,1
 Basket,0,1
  empty,1,1
 Checkout,0,1
  empty,1,1
 Invoice,1,1
 Address management,0,1
 Addresses,0,254
 User,0,254

And specify the extra columns: "nav_hide doktype" in the 'addittional fields' input.

The pagetree will now be created for you.

Create some groups

Create some 'website usergroups' in the 'User' sysfolder:

  • Clients
  • Special
  • Admin

Adjust the settings in the extension manager

install tool settings

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.

shell script:
 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:

TS TypoScript:
 # 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/

notice - Note

Please, check the extension manual for more info about the former constants.

Setup:

TS TypoScript:
 # 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

Create 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'.

product tree

Create as many sub categories as you like.

Create a product

Cheshire cat

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

Product list plugin

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.

Product list plugin

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 (probably in /typo3conf/realurl_autoconf.php). For detailed information about the configuration of this extension see the realUrl manual.

warning - Message

Only use the configuration below if you have only one domain (or one rootpage) in your realurl setup. If you have more starting-points, be careful, this configuration might break up your get parameter.
PHP script:
		'postVarSets' => 
		array (
			'_DEFAULT' =>
			array(
				# From https://wiki.typo3.org/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' => '-',
							),
							'languageExceptionUids' => '',
							'languageField' => 'sys_language_uid',
							'transOrigPointerField' => 'l18n_parent',
						),
					),
				 ),
			),
		),

CoolUri configuration

PHP script:
  <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

Default teaser image

 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:

TS TypoScript:
plugin.tx_fesearchintable_pi1 {
	searchTables {
		tx_commerce_products.pidList = 260
		tx_commerce_products.listItem {
			30.typolink.parameter = 277
		}
	}
}

Here is the complete TS:

TS TypoScript:
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|...&nbsp;
			30 = TEXT
			30.value = lees meer  &raquo;
			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 ;-).

shell script:
 #!/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

currently in the works

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/. If your language lacks a translation, go bug your chief translator about it.

FAQ

  1. How can i use commerce in multilanguage environment?
  1. You have to add in list modul an "alternative pagelanguage", after that you can use localisation mode in Commerce-Category-Module.


  1. There's a marker called ###NO_STOCK### displayed in the basket, product page/list, can I replace it with some data?
  1. 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'.
  1. 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.
  1. 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.
  1. Is there a possibility to config (or at least "shrink") the ORDERID ? Something like 46a9b74b915cc0.81208437 is not human readable.
  1. 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".
  1. How do I change the size of the category image in category view?
  1. Add the following to the 'setup' of your commerce template:
    // Category view
    plugin.tx_commerce_pi1.categoryListView {
    	categories {
    		fields.images {
    			file.maxW = 40
    		}
    	}
    }
    
  1. I am bored, can I do something?
  1. Oh yes, you can help completing the commerce documentation.
  1. How can I get the latest version from SVN?
  1. 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
    
  1. But I don't have those fancy SVN commands in Windows OR I don't have shell access at my provider.
  1. 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.
  1. How can I reorder products (make new subcategories etc).
  1. Open up the product record and change the 'parent' category.
  1. How can I make a link to 'terms and conditions'?
  1. 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 &lt;a href="/winkel/leveringsvoorwaarden/">leveringsvoorwaarden&lt;/a> heeft gelezen
    	}
    }
    
  1. How do I remove the p tags in the output?
  1. plugin.tx_commerce_pi1.singleView.categories.fields.description.parseFunc.nonTypoTagStdWrap.encapsLines.nonWrappedTag >
    


  1. Is there any possibility to enlarge a product image on click?
  1. 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] https://docs.typo3.org/typo3cms/TyposcriptReference/ContentObjects/Image/Index.html

    [2] https://docs.typo3.org/typo3cms/TyposcriptReference/Functions/Imagelinkwrap/Index.html
  1. How do I remove the page browser?
  1. plugin.tx_commerce_pi1.showPageBrowser = 0
    
  1. How do I link the teaser image to the product page?
  1. #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
    		}
    	}
    }
    
  1. How do I make a 'read more' link after the teaser text?
  1. 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 &raquo;
    			wrap = <div class="some class">&nbsp;|</div>
    			typolink.setCommerceValues = 1
    			typolink.useCacheHash = 1
    		} 
    	} 
    }
    
  1. How can I add a mini-basket (overview) to all pages?
  1. lib.minibasket = COA
    lib.minibasket {
      20 < plugin.tx_commerce_pi2
      20.defaultCode >
      20.defaultCode = QUICKVIEW
      20.templateFile = {$templatePathCommerce}basket.tmpl
    }
    
  1. Why does my category TypoScript haven't any impact?
  1. 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 (https://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 (https://forge.typo3.org/projects/extension-commerce/issues) project commerce.

Changelog

See https://forge.typo3.org/projects/extension-commerce/repository and https://forge.typo3.org/projects/extension-commerce/repository/changes/trunk/change.svn for a list of changes.

Current TER version is 0.13.12 (08.01.2013).


Version 0.9.0

  • First release in TER
  • Updated documentation