Ext: sg_shop
License: GNU GPL, Version 2
Repository: https://gitlab.sgalinski.de/typo3/sg_shop
Please report bugs here: https://gitlab.sgalinski.de/typo3/sg_shop
TYPO3 version: >9.5
About
This extension provides online shop functionality for a TYPO3 installation.
Create the order process
To set up your shop, you have to create the pages that are necessary for the ordering process. Therefor you need a page, that includes the:
- 'Product View' plugin
- 'Shopping cart' plugin
- 'First Step: Login' plugin
- 'Second Step: Address Selection' plugin
- 'Third Step: Payment and Shipping Selection' plugin
- 'Fourth Step: Overview' plugin
Each plugin must be included on a separate page. More information on how to use these plugins can be seen under 'Plugins'. After the pages are created, the typoscript settings need to be adapted with the correct IDs, so you will be redirected correctly during the order process.
cartPageId =
checkoutPageId =
checkout {
login =
addressSelection =
paymentSelection =
overview =
}
Plugins
Product View
This plugin needs to be used on a page that displays a product. When using this plugin a product has to be selected. The plugin itself then displays the product information of the selected product on the page.
Enable direct checkout for order alone products
You can configure that products that can only be ordered alone, have a "quick" checkout implemented.
In your typoscript settings:
settings.checkout.directCheckoutEnabled = 1
Now if the product can only be ordered alone, you will be redirected to the checkout overview if every information is there. If you are not logged in or shipping/payment information is missing, you will be redirected to the appropriate checkout step instead.
To extend the functionality for products without the order-alone restriction set the following typoscript setting:
settings.checkout.directCheckoutOnlyForOrderAloneProducts = 0
Shopping Cart
Add this plugin to the page that should represent the shopping cart. The plugin then will list all products that were added to the shopping cart, with the selected amount, the article name, and the article price. Furthermore, a voucher code can be entered and the total price is displayed at the bottom.
Product List
This plugin shows a list of products. The products can be filtered by category or directly. A detail page id needs to be seted as well, with a Product List Detail plugin on it. This list also has a page browser with a scroll browser.
Product List Detail View
This plugin shows a single product with a return button to a page with a product list.
Checkout Plugins
Checkout Login
This plugin is used when a user clicks on "Checkout" in the shopping cart and is not logged in yet. The user will then be redirected to a login page. The plugin has to be used on this login page. The id of this login page needs to be added to constants.ts of the extension.
Address Selection
Add this plugin to the page where you want the address selection to happen. It is used on the second step of the process. It displays two forms that enable a shipping and invoice address selection.
Payment & Shipping Selection
Add this plugin to the page where you want the user to select the payment and the shipping type for the order. This plugin is used on the third step of the checkout process. It displays the payment and shipping types that are possible to use for the selected products.
Overview
This plugin is used on the forth step of the checkout process and shows an overview of the order.
Manage your Shop
For a functioning shop, you need products, product categories, payment and shipping types and vouchers. Create them in extra folders by going to the list module and click the plus icon. You also need a orders folder where the orders will be stored.
Product Categories
Configurations:
- Order alone only: If selected, each product of this category can only be ordered alone
- Allow quantity selection: If selected, there will be a quantity selection in the Product View plugin for each product of this category. # Otherwise it is only possible to add 1 instance of the product to the shopping cart. This value can be overwritten by each product.
- Allowed voucher type (can be overwritten by products):
- none : No vouchers are allowed for this category
- all : All voucher types are allowed
- code : Only code voucher types are allowed
- auto apply : Only auto apply vouchers are allowed (see Vouchers for more details)
Products & Variations
A product needs to belong to a product category. A product can have multiple variations, but only one parent product.
Some product settings can overwrite the category settings, but are inherited by default:
- Allow quantity selection
- Allowed voucher type
Configurations:
- Type:
- Normal: The Product will be shipped once.
- Subscription: The prdouct will be shipped in a recurring manner. When this option is selected the field 'Subscription Period' will be displayed. There you can choose how the subscription will be handled.
If a product has variations, the parent product won't be rendered in the frontend in any way. Instead you get a variation selection dropdown in the Product View.
Vouchers
There are two types of vouchers. 'Code' and 'Apply automatically':
- code : This type of voucher is applied by entering a code in the corresponding field on the cart page. The discount of the voucher will be applied to the total amount in the shopping cart. Only one code can be used per order. The amount of the voucher will be given on the total including the vat. The reason is, that we need to lower the vat in a equal way, if there are more than one product in the cart with different tax rates.
- apply automatically : This type of voucher is applied automatically to the specified products and user groups. The discount of the voucher will be applied to the price of the selected product. This voucher won't appear as an position. Instead, the applied discount is displayed directly as a strikethrough price on the product page. 'Apply automatically'-vouchers can also be assigned a code that can be entered in the corresponding field on the shopping cart page. When a code is entered, the voucher is handled like the code-voucher.
The two voucher types can be used in combination. Voucher types can be overwritten in "Products & Variations".
Payment Types
Configurations:
- Provider: For each payment type, a provider must be selected that handles the payment.
- PayPal: You can read more on how to setting up a paypal payment provider correctly by having a look a the readme of the sg_shop_paypal extension.
- Handling
- Single: The whole price is paid once in full
- Rates: The price is paid off in several steps
- Recurring: A price is paid recurringly, e.g. paying for a subscription If the payment is handled recurringly or by rate, a payment frequency needs to be selected.
- Surcharge: A surcharge can be defined for the payment type, which is added absolut or percentage-based to the total price.
Email templates: Email templates can be selected in the 'Templates' tab. The selected templates are either send to the user or to the admin during different stages of the ordering process.
- payment: This Email confirms that the payment is completed.
- invoice: This Email sends an invoice as soon as one is created.
- pending: This Email comfirms that the order is completed.
Shipping Types
Configurations:
- Price: A price can be defined for the shipping type. This price is added to the total price.
- Price from, Price to: Defines a range in which the previously defined price is applied to the shipping type.
Country
Configurations:
- Country: A new country can be added to the drop-down in the address selection form by selecting one here.
Implement proper urls in TYPO3 9
To enable the good-looking urls in TYPO3 9, you need to add this routeEnhancer configuration to your config.yaml.
...
routeEnhancers:
SgShopProductListDetail:
type: Extbase
extension: SgShop
plugin: ProductListDetail
routes:
- {routePath: '/productdetails/{article}', _controller: 'List::showProduct', _arguments: {article: 'articleId'}}
- {routePath: '/productdetails/{article}/{variant}', _controller: 'List::showProduct', _arguments: {article: 'articleId', variant: 'variantId'}}
defaultController: 'List::showProduct'
aspects:
article:
type: ProductTitleMapper
variant:
type: ProductTitleMapper
SgShopPurchase:
type: Extbase
extension: SgShop
plugin: Purchase
routes:
- {routePath: '/product/{article}/{variant}', _controller: 'Purchase::index', _arguments: {article: 'articleId', variant: 'variantId'}}
defaultController: 'Purchase::index'
aspects:
article:
type: ProductTitleMapper
variant:
type: ProductTitleMapper
This configuration will use the ProductTitleMapper to map the product title to the product id. The routePath represents the speaking URL part where {product_title} is the placeholder for the product title. The ProductTitleMapper is assigned to the product_title placeholder via aspects and will take care of the encoding and decoding the product title and the according product id.
PageBrowser
Automatically adds a pagination to the Product List plugin. You find the settings in the Frontend/constants.typoscript configuration file:
pagebrowser.settings {
# Number of page links to show before the current page
pagesBefore = 1
# Number of page links to show before the current page
pagesAfter = 1
# Enables section for "more" pages. This section is shown after links to next pages, normally like three dots (1 2 3 ...). Notice that you can also hide it by emptying corresponding template section.
enableMorePages = 1
# Enables section for "less" pages. This section is shown after links to next pages, normally like three dots (... 1 2 3) Notice that you can also hide it by emptying corresponding template section.
enableLessPages = 1
}
Validators
ProductPrice
fails when a price has changed
ProductStock
fails when the stock is lower than the ordered amount
ProductAlone
fails when other products are in the order, but the product itself can only be ordered alone
ProductMaxQuantity
fails when the maximum order amount for a product is exceeded
PaymentTypeNotCommon
fails when there are no common payment types between the products
PaymentTypeNotAvailable
fails when the payment type is not available anymore (hidden or deleted)
ShippingTypeNotCommon
fails when there are no common shipping types between the products
ShippingTypeNotAllowed
fails when the shipping type is not allowed for all the items in the order
ShippingTypeNotAvailable
fails when the shipping type is not available for all the items in the order
VoucherNumberOfUsages
fails when the number of usages of a voucher is exceeded
VoucherValidFrom
fails when the "valid from" date of a voucher is not yet reached
VoucherValidUntil
fails when the "valid until" date of a voucher is exceeded
TermsAndConditions
fails if the user did not agree to terms & conditions
With the sg_shop extension you can integrate and operate a shop in your TYPO3 instance. In a separate tutorial we explain how to work with the orders module and the shop plugins.