Welcome to the Sulu E-Commerce documentation!¶

What is Sulu E-Commerce?¶

Sulu E-Commerce is an extension for Sulu CMF. It is designed to help you build any online e-commerce system you need. The main goal is to provide an online shop where you can present your products and offer the ability to buy certain products.

Sulu E-Commerce strategy for large scale usage¶

Unlike small B2C shops which usually have to maintain just about one hundred products, this strategy is designed for large online shops with thousands or even millions of products. This is a regular usecase for marketplaces or large B2B online shops. Where products in a B2C shop with less than one hundred products could be maintained manually, this is simply impossible for large marketplaces. However the functionality in the admin interface is the same for all of our Sulu E-Commerce strategies. Which means products can still be edited manually if needed.

Check the Products section for more information.

Change password¶

To change the password, a user must be logged in. On the top right corner there is a link to Password change. Clicking on it opens a new overlay to change the password. The current password must be given and a valid new password. After completing this process, the new password is stored and the user stays logged in.

Forgotten password¶

If a user is not logged in there is a password forgotten link on the sulu login screen domain.tld/admin. By quoting the users email address, an email with a password reset link is sent to that address.

Where to find the navigation¶

The shop navigation is defined by content pages in the admin interface. Once a new item is added it can be set as a navigation element in the settings tab. The first two levels of content elements are displayed as parent - child navigation.

How to create a navigation¶

Open the admin interface and click on the content area of your shop webspace where you want to add a navigation. Initially there are no content items. Click on the new button and add a new content item. There are two important things you need: a title which is displayed as your navigation title and an url where this item is pointing to. Click save once you are finished. Alright now you have created a new content item which can be opened with the url you have chosen. To make it a navigation item choose the category template in the dropdown and make sure your content item has the state published. We are almost done, now switch to the settings tab and add your content item to the main navigation in the navigation dropdown. Make sure you have changed your settings. Check out your shop and you will notice your first navigation item is displayed.

How to create a sub navigation¶

Open the admin interface and click on the content area of your shop webspace you want to add a sub navigation. Choose an item and highlight it by clicking on its name. In the column on the right it is possible to add a new sub navigation item by clicking on the add button. Now repeat the steps of creating a navigation item and save it. Refresh your shop and you will find a new sub navigation item in your navigation.

Link navigation to categories¶

In order to find products for a specific navigation item you have to link it with a category. Therefore visit the admin interface and navigate to the content page you want to connect with a category. Click the edit button and switch to the category tab. Now choose one or many categories and save the item.

How it works¶

The product search is based on elasticsearch. This means all searchable products must be indexed. The search API is split in two main parts. There is a live search api which provides functionallity to be used in e.g. a typeahead. The main search lists all products which match for a given query string. This result can also be filtered by additional information such as the category or the supplier.

Search widget¶

The search widget is one of the main parts of each shop. It helps the user to find products and more. If the user starts typing, additional ajax requests are placed in the background asynchronously to display suggestions. Once you click on a suggestion, you are redirected to the product detail page. If you just type in a query string and hit enter, a fulltext search is placed and matching products are returned in a batched list.

Prefilter Categories¶

Sometimes it makes sense to search a product within a certain category only. For example it would make propably no sense to search a fridge within sporting goods. Nor you want loads of other products to be found if you already know what you are looking for. Therefore it is possible to select a category and prefilter the search results.

Import products¶

The most efficient way to add new products is to import them via the csv importer. To do so, you have to provide a valid csv file with your products. In order to provide a valid data structure you have to map your csv headers to our database properties. This is done by the importer widget. Simply add your csv file and upload it.

Once the file is uploaded the screen is changed to a mapper interface where you can choose which of our database properties matches with your csv headers.

Required fields are:

• Productnumber
• Name
• Order unit
• Price

This is a very important step so please take your time for a careful mapping. As this step takes quite some time we have created an intelligent mapping. We try to indentify common mappings for you and preselect them in the interface. And to make it even more convenient we will store your mapping, so once you upload another file with new products you can reuse your personal mapping in order to safe time.

Once you successfully have created the mapping, the csv file is ready to be imported. However this is not done directly. As creating new products with all their dependencies, e.g. media files, can take some time this import job is passed to a gearman worker which starts to import your products once the system is ready to do so. Once the import is finished an email will be send to the email address defined in your sulu account and a reindex script for elasticsearch will push your products to the elasticsearch index.

Add Product manually¶

Adding a new product manually is very easy. Open your Sulu admin interface and navigate to the PIM section. Add a new product and make sure you support at least the required fields. Once you click save, the product is stored to the database. There are two product states activ and inactive to choose if your product should be visible in the shop or not.

How to reach it¶

All product detail pages can be opened by browsing /products/<productId>. This is the permanent product url. It will be extended by the urlencoded product title in order to improve the seo behavoir of the shop.

Product details¶

The basic product details are shown on the detail page such as title, short and long description, product number, existing product attributes. These information are fetched by the database as it is very important to display the real up to date data to the user.

Image gallery¶

There is an image gallery on the detail page to display all given product images. By Default, the first image is displayed as a large cover image. For all images there is a thumbnails beyond the cover image. By clicking on it, the thumbnail is switching place with the cover image. By moving the mouse over the cover image it is zoomed in if the image is large enough. If no image exists a fallback image is displayed which is not zoomable.

Ratings box¶

The ratings box shows the product rating based on all rates been given for this product and a link to customer reviews. Each user is allowed to rate a product once.

Supplier box¶

The supplier is displayed on the detail page. All important information is shown such as the name, the address and the contact data.

Cart widget - prices¶

All product detail pages provide the cart widget which enables the user to add a certain product to his shopping cart. The cart widget also displays the product prices. Prices means that there is generally a basic price, however there could also be a scale price.

Check the Shopping Cart section for more information.

Other supplier widget¶

As many different suppliers can offer the same product, there is a other supplier widget to show the user some more offers for the same product. To detect identical products a product must provide a global trading number. To improve the loading speed and the query time this list is provided by elasticsearch.

Similar products widget¶

For helping the user to find more products, there is a very useful widget which displays a list of similar prodcuts. This feature is implemented by an elasticsearch more like this query which compares the current product with other products in the index. If products with a similarity are detected they are returned and displayed.

Where does the data come from¶

To provide best performance the product list is provided by elasticsearch. Therefore only products which are in the current index can be found in the list. To increase the applicability of the list, the basic function to get products is a high generalized elasticsearch search function which can be used in many different ways. Since always the same data structure is returned by the elasticsearch layer, we can provide a high level of consistency.

The default list¶

The default list provides a batched search result where each item represents a real product. The following information is shown if exists:

• Title
• Short description
• Image
• Price
• Price per order unit
• Global Trading Number (GTIN, EAN)
• Product ratings

A click on a single item leads to the product detail page.

Usage¶

Currently product lists are shown at:

• Filtered products for category navigation
• Filtered products for live product search
• List for other suppliers for a specific product
• List for similar products

Cart widget¶

The cart widget allows a user to put a product into the shopping cart. The widget consists of an input field for the quantity and a button to finally add it. Quantity must be a valid number, therefore this field is validated. If an invalid input is made a discreet error is displayed. Default quantity is one. So if the button is clicked without any other action, one product is added to the shopping cart.

Cart display widget¶

This widget is used to display what is currently in the cart. Behind the scenes it triggers an ajax call to get the shopping cart information. It then displays the current total sum and the amount of product items in the shopping cart.

Cart detail page¶

The shopping cart detail page gives an overview for all products in the cart. It is possible to increase or decrease the quantity of a specific product, change the invoice and shipping address or if a product got accidentally into the cart, remove it. Also the total prices and the shipping costs are properly displayed. As an user can have exactly one cart, the current cart content is stored for later reuse. Once the order is completed, the shopping cart is emptied and a success screen is shown to the user. A permanent url endpoint for the detail page exists and can be opened manually via /shoppingcart.