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:

1. 'Product View' plugin
2. 'Shopping cart' plugin
3. 'First Step: Login' plugin
4. 'Second Step: Address Selection' plugin
5. 'Third Step: Payment and Shipping Selection' plugin
6. '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

---