Shop System tt_products 

Shop system extension for the TYPO3 CMS

Where to get help 

You can get help in the TYPO3 Slack https://typo3.org/community/meet/chat-slack, Ask a question in the official TYPO3 forum, https://talk.typo3.org/c/typo3-questions/19 or contact the extension author.

Installation 

composer req jambagecom/tt-products

Introduction 

You should read the German tutorial or Italian tutorial or one of the books 'Der TYPO3 Webshop' and 'TYPO3 4.2 E-Commerce ' before you start with it. Watch this introduction video . See the extension addons_tt_products for newer example template files.

This extension only works with PHP5.

Version 

This document is for version 2.12.0 of tt_products. You can get the code of the next version of tt_products at ttproducts.de .

Cease and Desist Letters 

Do not use trademarks, photographs and maps in your shop which you do not own and made by yourself. Do not forget any texts in your shops which are required. Be very careful when you link to other pages. Hundreds of lawyers are continuously searching the Internet for your mistakes in order to get much more money from you than you could ever imagine. That would be damn stupid for you.

http://www.legalshop.co.uk

Translations 

A German translation of this document is available under the extension key doc_ttproducts_de . A French translation is under development at doc_ttproducts_fr .

Upgrade 

If you upgrade from Version 1.2.7 you have to do all the administrative steps under the topic 'Important'.

What does it do? 

The Typo3 shop extension gives you the facility for...

• Product listings with multiple images, details and languages
• Shopping basket
• Payment page - The orders will be indicated and can be checked over before the products are finalized.
• sponsors only: Payment gateways with Payment Library extension - Paypal and Transaction Central
• Tracking customers order status
• Automatic creation of bill and delivery sheet
• Different tax percentages per item, shipping and payment
• basic stock management
• Send a CSV for each order to the shop admin (2 choosable file formats)
• E-Mail-Attachments for the confirmation mails (for example AGB in German = General trading conditions)
• choosable item variants (colours, sizes, gradings, descriptions, materials and qualities)
• Force customer to accept the General trading conditions (AGB) per checkbox
• Offers, highlights and newly added items
• Special preparation, weight and bulkily (can be used to calculate the shipping fee)
• Ability to limit payment methods to specific user groups
• Automatic creation of frontend users at first order
• Remember items in a memo, when a user is logged in
• Discount percentage per user
• Some methods for price calculation with rebate for resellers
• Display orders: order can be displayed on per fe-user basis (CODE=ORDERS)
• Creditpoint system: customers can save credit points per each order. Saved points will give them a discount for newer orders or certain products can be "bought" with these points.
• Voucher system: if a new customer indicates when registrating that she/he was tipped by another existing customer, this customers gets a credit point bonus. The new customer gets a discount on first order.
• Gift certificate: Users can buy certificates and send them as gifts to their friends. After signing on as front end users they can transform their gift certificates into creditpoints.

Developers 

• Kasper Skårhøj: 1st developer 1.2.7 / TYPO3 3.8
• René Fritz: 1st developer 1.2.7 / TYPO3 3.8
• Franz Holzinger (trainer): price calculation, discount price, gift certificates, e-mail table for notification, error correction, billing, receipts, multi-column listings, product/articles tables, multiple languages, DAM list and category list
• Klaus Zierer (trainer of zk_products): more sizes and colours, entry lists, automatic registration of front-end users, category pages. In zk_products you can find a good example shop template.

Sponsors 

• pil.dk - Professionelle Internet Løsninger ApS is a main sponsor of the code for the Payment Library extension.
• Multi-categories per product with multilingual listings, import scripts for XML files from inventory control systems, custom shop tables, advanced search mask with producer select box, traffic light symbols to display the availability of articles. Sponsored by Geo.net IT GmbH .
• Websolutions für Apotheke und Pharmazie TYPO3 FullService * Konzeptionierung * Realisierung * TYPO3 Hosting * pharmaline - Internet für die Apotheke, Apotheker Christian Platt, Kupferdreher Str 150, 45257 Essen

Support 

You can get support for this extension at http://www.jambage.com/kontakt/forum.html .

You can download all needed extensions from the TYPO3 TER, http://typo3.org or from http://www.jambage.com/typo3-cms/shop.html .

Users manual 

Note: 

The data path is renamed from 'pi' to 'pi1', thereby tt_products will now be put together like standard TYPO3 extensions. If paths have been employed from previous versions 1.2.x of tt_products then these must now be renamed in TypoScript setup. If you newly installl or update the extension, please observe the Depencies in TER (online repository of the extension manager).

You must fill in the product's 'In Stock (pcs)' field of your product properties, or no item will be shown in your frontend list if set to 0. This has been changed to the older version.

However, you should store the prices with included tax in the database; it makes it easier for you to reenter the price as well as for the customer to see the prices as you entered them. These prices should finally have the convention of pricing like 89.99 and not 89.72.

Before you start entering the prices of your products you have to decide whether you want to enter the prices with or without tax (see TAXincluded). All the calculations and configurations will use the prices as they have been stored into the price field of the tt_products table. You should use a template with multiple columns (

plugin.tt_products.conf.tt_products.LIST.displayColumns.1 = 3 

or higher) even if you only have one column in the list table.

Use an example template from the directory tt_products/template, like the template, example_template_bill_de.tmpl, when you start your shop. You have to change the page id in the links (after the 'id=...') to the page id of the basket on your site. The marker ###DOMAIN### is the placeholder for your url. There are several placeholders for the different page ids of the shop. This is sensible because different hosting environments will be used. In the setup of the shop templates, the domain marker must become mydomain.com by using the following TypoScript : plugin.domain=mydomain.com).

tt_products is based on the Table Library (table) and Static Methods for Extensions since 2007 (div2007). So you have to always update to the latest versions of these extensions when you update tt_products.

If you want to use the variant fields (colour, quantity ...), you must also set the constants 'selectColor' and 'selectSize' at 0 or 1, 2, 3. Otherwise, the count in the product list of articles will be calculated incorrectly.

Many adaptations can be undertaken by way of the constant editor. For entering in the shop page, most should be directed in the template's setup field and constant editor.

Calculation script: 

If you write and use your own calculation scripts, then you should always use only the price variables. The priceTax and priceNoTax variables will be deleted in August 2008 because they can be calculated from the price variables and the TAXpercentage and TAXincluded constants. You can use the global PHP variables $this->calculatedArray and $this->itemArray to make your own price calculations.

10.calculationScript = EXT:tt_products/pi1/products_comp_calcScript.inc

Discount: 

There are several methods to get a discount.

1. Use the discount field for a frontend user and enter the percent of discount.
2. Use the price2 field for special feuser groups or other things. This setting is done in TypoScript via the IF-statement.
3. Use the discountprice calculation where the discount depends on the value of the total number of the products which have a special price. This will be available for the frontend user group 'discountGroupName'.

Link for products of the last X days 

This is practical for “What is new?” pages. Create simply a link to the SEARCH page and add "newitemdays" as parameters. http://www.big-typo3-shop.com/index.php?id=8&newitemdays=10 The search result will contain all the products of the last 10 days. You have to use the plugin code LISTNEWITEMS. You can also set the constant "newItemDays ".

Offers and highlights 

You have to use the plugin code LISTOFFERS for the items marked as 'offer' and LISTHIGHLIGHTS for the newest items.

AGB General Trading Conditions 

You have to accept the general trading conditions before you can make an order and continue with the process. A page can be defined for this with "PIDagb". The AGBs have to be displayed there. You can set the target for a link by "AGBtarget".

A document (e.g. a PDF file) on the server containing the AGB can be set by "AGBattachment". This will be set to the customer as an email with an attachment to the order confirmation. The shop administration will not get this file. (he can get a CSV file of the order data instead, if wanted).

Right of Revocation 

In Germany you must add a link to a page with the display of the right of revocation. A page can be defined for this with "PIDrevocation". The right of revocation has to be displayed there.

MEMO page 

You can add items to a memo page when a user is logged in or not. This memo page will be saved in the fe_user table or in the FE session. Simply create a new page with the Shop plugin as content and enter the code "MEMO". You must set the starting point there too, like in the SEARCH pages.

Voucher System 

An interested customer is obtained through invitation by e-mail to visit a shop and purchase products. This e-mail is attached to a unique code which corresponds to a certain amount of credit points (voucher). When they make a purchase, they can redeem these credit points by inputing the unique code.

If a customer states in his registration that he has been recruited by another customer, then the referring customer gets credit points. The new customer gets a discount with his first order.

Somebody (lets say user 1) can enter a voucher code if he concludes an order. Then user 1 will obtain a discount. This credit entry code undergoes a change with each different user name (which is the e-mail address). Let's say user 2 gets 5 credit points altogether and applies his code to his purchase. Only one entry code out of a voucher system can be used by each user. In fe_users table there is a field given for this "tt_products_vouchercode" which contains the used credit entry code (e-mail of user 2).

Creditpoint System 

If a customer purchases a certain number of items, then he gains credit points which are stored in his user's account. If he purchases more items at a later time, he can redeem credit points against the purchase price. The customer can gather credit points with each purchase.

creditpoints { pricefactor = 0.5 

10.type = price 10.prod.1 = 0.02 10.prod.101 = 0.04 10.prod.501 = 0.06 } 

Gift Certificates 

A shop manager can sell, for example, electronic gift certificates for wine bottles. A client may order a certificate that corresponds to 50 credit points (=25 Euros) to send to someone as a gift. To redeem this gift certificate, then one must register as a shop customer and input the certificate code. Thereby, haveing 50 credit points credited to his account. This customer can purchase a particular product with these credit points.

Anyone can buy, for example:

• 3 certificates @ 25 credit points
• 5 certificates @ 50 credit points
• 8 certificates @ 75 credit points ...all within the same order.

Modify the page menu 

You can add the number of products found in the subpages to your page menu. 

Administration 

In the normal case the categories from the category table and its enhancements are used. You have to set

$TYPO3_CONF_VARS['EXTCONF']['tt_products']['pageAsCategory'] = 0;

to be able to use them. Otherwise the pages will form the category and the category will be used as subcategory ( = 1) or not used at all but replaced by the page ( = 2).

The flexforms in the backup are always activated automatically.

Installation 

Install the extension with the Extension Manager. If you already use an older version of tt_products that is installed in the “global” location (typo3/ext/), it is recommended to install the new extension into the “local” folder (typo3conf/ext/) without overwriting the old one. By doing this you can easily switch back to the former version.

Deinstall the extension from the Extension Manager. Then download the version of your choice from the TYPO3 Online Repository with the Extension Manager. Then use the Extension Manager's "Available extensions to install" menu entry and add the shop system again.

This extension works best in union with static_info_tables, static_info_tables_taxes, agency, rtehtmlarea, mbi_products_categories, transactor and taxajax.

Handling of Categories 

There are multiple ways to create a shop. The usual way is to create sysfolders for the products and lists and single sites where the products are displayed. If you want to build a bigger shop with TYPO3, this will become a little bit unhandy.

If you want to make bigger shops with hierarchical categories you shall install the mbi_products_categories and maybe also the nsb_cat2menu extension. Sponsors will get a working version of mbi_products_categories with which you can assign many categories to one products via a mm-table. Only with this it will be possible to show a product in the list view under multiple categories.

Example:

$TYPO3_CONF_VARS['EXTCONF']['tt_products']['pageAsCategory'] = 0;

Template markers 

The following template markers for the tmpl-file are used. You have to put ### before and after them. There are more markers, so look into the example template files.

See: http://wiki.typo3.org/Tt_products_marker

area markers: 

single markers 

Example for a wrap:

<!-- ###PRODUCT_LINK_DATASHEET### begin --> datasheet for the product <!-- ###PRODUCT_LINK_DATASHEET### end -->

global markers 

The global markers are allowed to be used with all subparts. You can even define new markers.

Example:

plugin.tt_products.marks {
    my_marker = Come soon back to our shop!
}

###MY_MARKER###

:

plugin.tt_products.marks {
  my_marker = Come soon back to our shop!
}

###MY_MARKER###

Automatic creation of frontend users and address fields 

It is possible to create frontend users automatically after each order. You have to set "createUsers" to "1", enter the PID of the sysfolder as PIDuserFolder in the Setup field. Then you have to set memberOfGroup to the ID of your front end user group. The customer will get an email with his account data after his first order. This email will contain his account name which is his email address, and his automatically created password.

If you do not want to use a single address field, but a separate address field for the name of the street, the housenumber and additional fields for the ZIP, city and country, then you have to insert these in your template file. If you install static_info_tables and set "useStaticInfoCountry=1" then the small field static_info_country of the fe_users will be used instead of a country string. It is useful to make a select box for the country.

TypoScript Setup 

Configuration 

FAQ 

• If you do not use the Constant Editor to configure the extension, please note the form of the constants assignments in the constants section of your TS template:

Files 

[tsref:(cObject).TEST]

Basket 

Description 

Built-in shopping basket and products display within TYPO3. Has a clearing interface which lets you write your own implementation with existing payment-gateways.

Currently there's an implementation with DIBS in Denmark, found at www.architrade.dk .

Reference 

[tsref:(script).class.tt_products.php]

Display Modes (CODE) 

Here comes a list of the possible display types of the plugin.

Code to define, what the script does. In the backend these entries are made using flexforms instead of the Codes (capital letters). Use the codefields ony in TypoScript setup.

Articles, Products, Categories, Pages, Addresses and Images 

Setup only.

The last but one/two value will be the name of the view. It can be ALL, if it is valid for all views.

Views correspond to the code field:

• SINGLE
• LIST
• BASKET

additional possible values are

• EMAIL
• PAYMENT
• LISTRELATED ( LIST for related products)

Example:

plugin.tt_products.conf.tt_products_articles.LIST.generatePath.base = fileadmin/images
plugin.tt_products.conf.tt_products.LIST.orderBy = sorting

Form configuration 

Setup only.

There are several forms which can be configured. Put the code after the form settings.

Example:

searchform for the shop

plugin.tt_products.form.SEARCH.data.name = ShopSearchForm

Copied!

Control configuration 

Setup only.

You can configure the behaviour of the views here. Insert the CODE after control.

Example:

Download configuration 

Setup only.

You can configure the generation of downloads here.

Payment, shipping and handling configuration 

Setup only.

Payment and shipping are very similar in configuration and therefore shared the same property list with special notes if something is for the one type only. The configuration of payment and shipping is in short a question of defining the items to choose from on the basket page. That is, a choice of one out of many transportation methods and one out of many payment methods. Therefore you can for instance select either radio-button representation or selector box. The number of the selected payment method or shipping method is reflected in the html-template certain places and you may also want special PHP scripts executed based on the settings. That's all allowed.

Example:

plugin.tt_products.payment {
    radio = 1
    TAXpercentage = 19
    10.title = Prepaid
    20.title = PayPal
    20.percentOfTotalShipping = 0.04
    30.title = Cash on Delivery
    30.price.1 = 4
    30.price.6 = 5.8
    30.showLimit = 99
}

plugin.tt_products.shipping {
    radio = 0
    TAXpercentage = 19
    10.title = Deutschland
    10.image.params = align=absmiddle
    10.price.type = count
    10.price.1 = 2.5
    10.price.20 = 4.8
    10.price.50 = 10
    10.price.100 = 25
    10.price.120 = 30
    10.price.300 = 150
    10.percentOfGoodstotal = 0

    20.title = Europa (nicht Deutschland)
    20.image.params = align=absmiddle
    20.price.type = count
    20.price.1 = 8.8
    20.price.20 = 11.8
    20.price.50 = 11.8
    20.price.100 = 25
    20.price.120 = 30
    20.price.300 = 150
    20.percentOfGoodstotal = 0

    30.title = Selbstabholung
    30.type = pick_store
    30.price.1 = 0
}

plugin.tt_products.handling {
    10 {
        TAXpercentage = 19
        10.title = Printing Costs
        10.price = 17
    }
    20 {
        TAXpercentage = 19
        10.title = Small Volume Addition
        10.price = 5
    }
    30 {
        TAXpercentage = 19
        10.title = Packaging Costs
        10.price = 1.95
    }
}

Selectable Payment / Shipping / Handling Items 

. _configuration-payment-shipping-handling-show:

. _configuration-payment-shipping-handling-show-limit:

. _configuration-payment-shipping-handling-type:

. _configuration-payment-shipping-handling-visible-for-group-id:

. _configuration-payment-shipping-handling-add-required-info-fields:

. _configuration-payment-shipping-handling-where-static-countries:

Payment / Shipping / Handling Item Prices 

Shipping Cost Calculation shippingcalc / handlingcalc 

Setup only.

The calculation of the shipping costs can be even more complex. Even the order of the calculation is relevant. This is necessary if you use two different calculation modes simultaneously. The highest price will be used by default.

Pricecalc, discountprice and creditpoints configuration 

Setup only.

The pricecalc gives you the possibility to build the price sum of products using a calculation table. The discount price will be used for all users who belong to the group set in discountGroupName.

Voucher System 

Setup only.

The voucher codes must be stored in a database table. Normally the fe_users table will be used. A voucher will be used as the FE user name of the person who has invited another one to the shop. The customer who has invited his friend will get a price reduction at his next shopping. If another table is set here then this will work only together with the voucher extension and the voucher code can be anything hard to guess to obtain a price reduction.

Order Confirmation Configuration 

Setup only.

These are some settings if you want to change the behaviour of the order confirmation.

Example:

plugin.tt_products.finalize {
    productsFilter {
        10 {
             pid = 12
             email = myemail@mytypo3site1.com
        }
        20 {
             pid = 12
             email = myemail@mytypo3site2.com
        }
    }
}

Bill and Delivery Configuration 

Setup only.

These are some settings if you want to use the feature of the creation and usage of bill and delivery sheets. They are generated in the folder fileadmin/data/bill.

Tracking 

Setup only.

These are some settings if you want to change the display of the tracking page.

Graduated Price 

Setup only

The graduated prices gives you the possibility to add special prices for a list of amount of products.

Example:

use the subtitle for translations

plugin.tt_products.graduate {
    10.type = count
    10.sql.where = category = 12
    10.marks {
	    factor = 3
    }
}

Copied!

Error configuration 

Setup only.

You can set the behaviour of tt_products in case of errors. The file pi1/locallang.xml contains the list of tags for the error messages.

Known problems 

Checklist: 

• include a 'Shop System' or 'Shop System Variable Content' from "Advanced Options" -> "Include TypoScript sets"
• set 'in stock' greater 0 for the products and articles
• do not use languages or have products in the products alternative languages tables
• the shop template file is found
• an error in the shop produces an entry in the PHP error_log file (activate this in Install Tool and php.ini, .user.ini or .htaccess)
• the TYPO3 cache has been cleared before
• the web browser cache has been cleared before
• the cookies have been deleted
• set the pid_list and recursive in TypoScript or set the "Record Storage Page" / "Recursive" inside of the shop plugins

To-Do list 

• Wishlist: http://wiki.typo3.org/index.php/Ext_tt_products#Wishlist

Frequently Asked Questions (FAQ) 

Sitemap 

Important 

You have to rename the marker ###FIELD_NAME### to ###FIELD_NAME_BASKET### in the BASKET_TEMPLATE.

Some of the TypoScript settings do not function via the constants field and must be entered in the setup field. Only those settings which can be found using the Constants Editor or in the file "static/css_styled/constants.txt" are valid constants. You must include the "Shop System CSS Styled" into your "static template records" of your TYPO3 template.

A negative value of a product at "in stock" does not have any more a special function. This has been replaced by a checkbox "always on stock".

Change the former input fields for a search into

<INPUT size="30" maxlength="100" type="text" name="sword" value="###SWORD###">

The marker ###SWORDS### must be changed into ###SWORD###, and the name attribute into "sword".

Template files 

You need to make the following settings in the template files for the shop so it will work:

<input type="hidden" name="mode_update" value="1">

<input type="submit" name="products_update" value="update basket">

Put this into your FORM html of the BASKET_TEMPLATE.