Magnolia 4.5 reached end of life on June 30, 2016. This branch is no longer supported, see End-of-life policy.
The Shop module offers basic e-commerce functionality for Magnolia. The module provides a flexible data structure and a set of classes for handling the data. You define the look and behavior of the shop. The module includes templates and components that adhere to the pop theme. Magnolia partner fastforward started the Shop module and developed the first version in collaboration with Magnolia International Ltd. The module ships with a sample shop that you can customize to your liking.
Features:
You can view the sample shop in Pages > /demo-features/modules/sample-shop
.
The Shop module is not part of the Magnolia bundle. Download the Shop bundle from our Nexus repository and install the following jars:
magnolia-module-shop
magnolia-module-ocm
: saves the shopping cart bean and cart items to JCR nodes, distributes order numbers, and configures what to save.jackrabbit-ocm
Shop is a Community Edition module. It is typically not installed. Go to Magnolia Store > Installed modules in AdminCentral to check. To install the individual modules, see the general module installation instructions .
See the general module uninstalling instructions and advice.
The Shop module is configured in /modules/shop
.
The Magnolia OCM module is used to save the shopping cart bean and cart items to nodes, to distribute order numbers (order number is the name of the cart node), and to configure what to save. It implements the shopping cart functionality and is configured in /modules/ocm
. Here's the configuration of the defaultShoppingCart
.
Shop related items are stored in the data workspace. Data types are configured in the Data module for:
shops
: Stores configuration for all shops.shopProducts
: Stores the product details for all shops.shopProductSupplier
: Stores the supplier details for all shops.In addition, the module creates the shoppingCarts
workspace that stores shopping carts for all shops.
All shop related items, except product categories, are managed in a shop-specific menu in AdminCentral, for example Sample Shop and New Shop in the screenshot below. When you create a shop, a dedicated menu and sub items is created automatically for the shop. New shops are created and configured in Shops Management.
To create a new shop, go to Shops Management and click New Item.
Fields:
locale
. The default classes and cart session variable are auto filled. Do not change these unless you have a customized implementation.
ocm
module configuration. The implementation includes order, billing and shipping addresses, and allows only one cart item per product (i.e. when adding the same product multiple times, the quantity of the cart item will be increased).When you save the new shop parent nodes for the various configuration options are created automatically. You can add as many tax and price categories, currencies, countries and shipping options as necessary by selecting the parent item and adding relevant sub items. The configured options are assigned on a product-by-product basis when adding products.
Value added tax (VAT) is levied at different rates on different products. It is calculated as a percentage of the net price. You can create several tax categories such as normal goods at 7.6%, reduced at 2.4% and so on. Tax is added to the price at checkout. The amount of tax applied to a particular product depends on the price category the product belongs to.
Fields:
001-Books
. The ID can contain letters, numbers and special characters with certain exceptions.Books
.7.6
into this box. The number format is Double where period is a decimal point.The Shop module supports multiple currencies. This is useful for large shops with a global customer base, and shops that are located near a two-country border.
While it is possible to configure multiple currencies, only one currency is used at a time. Customers cannot switch between currencies in the default implementation; all products are priced in the currency defined in the default price category.
Fields:
USD
, EUR
or CHF
. It is displayed to editors when they edit product details.$
, €
or CHF
. It is displayed to customers next to the product price in the shop.###,###.00
. The corresponding convention for Swiss Francs is 1'234.55 (###'###.00
) and for euros 1.234,56 (###.###,00
).Price category defines the currency in which a product is sold and whether tax should be applied.
Fields:
Tax-free Swiss franc
.Once your price categories are set up, edit the shop and include the default currency in the Systems tab.
DefaultPriceCategoryManagerImpl is the default implementation of the PriceCategoryManager interface and allows to display one price category at a time. To sell the same product in different currencies and tax scenarios, for example, you need to write a custom price category class that allows switching between price categories. Suppose you sell the same product in two different currencies: euros and Swiss francs. Customers who pay euros come from the euro area where your shop is located so they need to pay value-added tax (VAT). Swiss franc customers come from across the border in Switzerland so no tax is levied on their purchases. You need two price categories: Standard selling price and Tax-free Swiss franc. You also need to allow customers to choose the currency in which they wish to pay for products.
You can set up different shipping options for different countries.
Shipping options are currently not used by the default shopping cart implementation.
Fields:
Define the countries you ship to.
Countries are currently not used by the default shopping cart implementation.
Fields:
Fields:
Define product supplier details. Select Suppliers in the dedicated shop menu to add a supplier. Editors select suppliers for each product when adding products. The Supplier and Logo tabs include fields for complete supplier details.
Supplier content is currently not rendered on the product category and detail pages, but you can customize the components to render it.
The module includes page templates to display a shop on your site. A shop has its own navigation. For this reason, all pages except the shop home and category pages should be hidden from navigation in the page properties dialogs. The page templates are configured in /modules/shop/templates/pages
.
When you add a page based on the Shop Home template the system creates a basic shop structure automatically. In the page properties dialog you can select the relevant shop.
At minimum, a shop requires these pages:
Page | Template | Description |
---|---|---|
<shop name> | Shop Home | Shop home page. |
| Product Category | One page for each product category. |
| Product Detail | A single page. Renders details of all products |
| Shop Search Result | A single page. Renders product search results. |
| Shop Keyword Search Result | A single page. Renders keyword search results. Keywords are set when adding products and rendered in the extras tag cloud component. |
| Shopping Cart | Adds a shopping cart. |
| Checkout Form | Step one of the checkout process. Includes a shipping address form. |
| Shop Form Step | Step two of the checkout process. Includes a billing address form. |
| Confirm Order Form Step | Step three of the checkout process. Allows user to confirm order and address information. |
| Confirmation Page | Confirms order and provides an order number. |
Categories organize the products sold in the shop. A book shop might have categories such as Travel, Gardening and Audiobooks. The Travel category might split further into Europe, Latin America and Middle East. The purpose of categories is to help customers browse the shop and find products they are interested in. Each category is a page in the shop site hierarchy. Make sure your category taxonomy is logical. It makes finding products quicker.
Product categories are created automatically for each page based on the Product Category template. The product category page structure determines the navigational structure in the shop. The module automatically creates a list of categories in the Data > Category for selection when adding products.
Here's the page structure for our T Shirt shop example.
This is what the shop navigation looks like to the visitor:
The Shop module uses Data > Categories to assign keywords to products. See Creating categories for more information.
You can select keywords as you add products. The extras tag cloud component that is autogenerated on the Product Category template renders links for all keywords assigned to products within the product category. When clicked, products that have the keyword are displayed.
Products are the items sold in the shop: books in a book shop, songs in a music shop and so on.
Add products in <Shop name> > Products. The Product Detail template renders products on pages. You can organize products in folders to match your categories or any other suitable structure, for example by supplier. The structure has no bearing on functionality.
The Product dialog contains all the necessary fields for your products. All shop configuration options such as price categories, shipping options and countries, and suppliers can be linked to individual products.
Product details:
978-1613820773
for A Tale of Two Cities by Charles Dickens. The ID can also match a product ID in an external warehousing system if you import products into Magnolia. Use IDs that make sense for your products. The ID is not displayed to customers in the shop by default.Categories:
Pricing:
Weight and size:
Keywords:
The product looks like this on the category page:
And like this on the detail page:
You can also edit products directly on Web pages in the page editor. Click the Edit Product link on a category page to open the dialog in the Products app.
Product options are variations within one product such as sizes or colors. For example, if you sell the same shirt in different sizes and colors create variants such as S, M, L, XL, red, white, yellow etc. Different options can be created for each product.
The options display in dropdowns on the product category and detail pages.
The Shopping Cart component is autogenerated in the extras area on product category and detail pages. The component allows users to add products to the cart as they browse. You can make the component available on any template.
The View Shopping Cart link opens the Shopping Cart page that is based on the Shopping Cart template. Prices of all units are totaled and VAT is added if applicable. In the cart the customer can add and remove units of a product using the plus ( + ), minus ( - ) and delete buttons.
Checkout is a three-step form that asks the customer to provide a shipping address, billing address and confirmation. Once the order is successfully submitted, the customer is given an order number.
You can configure the form on the shipping address page (Checkout Form template) to send emails to the user and a shop administrator. Here's a Freemarker example you can use to render product and cart details in the confirmation email. See Form module and Form component for more.
Thank you for your order: Your order number is: ${cartId} [#list cart.getCartItems() as product] Product Name: ${product.productTitle} Quantity: ${product.quantity} Unit Price: ${product.unitPrice?string("0.00")} Total: ${product.itemTotal?string("0.00")} [/#list] Subtotal: ${cart.grossTotalExclTax?string("0.00")} Vat: ${cart.itemTaxTotal?string("0.00")} Total: ${cart.grossTotalInclTax?string("0.00")}
Full details of the order are stored in Shops Management > Shopping Carts. The order number matches the shopping cart node name.
The SaveAndConfirmFormProcessor class converts the order JavaBean object to nodes and properties using Jackrabbit's Object Content Manager (OCM) framework. This functionality is provided by the Magnolia OCM module which is required. You can export the order to a third party warehouse or ERP system by writing a custom shopping cart processor.
Use the Shop Product Teaser component to showcase products. The component is available in main area on the shop home page and in extras area on other appropriate shop templates. The purpose of a teaser is to promote the product and invite the customer to find out more.
The shop module is fully integrated with the STK. It is a good example of how to extend the STK to provide additional functionality.
Templates are made available in Templating Kit > Site Definitions /default/templates/availability/templates
.
Page templates are configured in /modules/shop/templates/pages
. They are STK templates and define only modifications to the template prototype.
category
: feature
. This is relevant to their availability within the page hierarchy. See Categories and subcategories for more.class
:
STKPage
. See Template properties for more.renderType
: stk
. (
STKRenderer
).shopHome
, are assigned:modelClass
:
ShopSingletonParagraphTemplateModel
that extends
STKPageModel
to add shopping cart functionality.bodyID
: shop
. This is relevant to CSS styling. See Themes (below) and Body classes and ids for more.Here's the template definition of the shopProductCategory
template.
The shop home template is essentially a section template.
Properties:
bodyID
: section
.dialog
: shop:pages/shopSectionProperties
(see below).modelClass
:
ShopHomeParagraphTemplateModel
that extends
STKPageModel
to generate the basic shop page structure automatically. The structure includes one product category, product detail, product search result, keyword search result and checkout form pages. Here's the code snippet that achieves this.createShopPage(content, "sample-category", "shop:pages/shopProductCategory"); createShopPage(content, "product-detail", "shop:pages/shopProductDetail"); createShopPage(content, "product-search-result", "shop:pages/shopProductSearchResult"); createShopPage(content, "keyword-search-result", "shop:pages/shopProductKeywordResult"); Node shoppingCart = createShopPage(content, "shopping-cart", "shop:pages/shopShoppingCart"); Node checkout = createShopPage(shoppingCart, "check-out", "shop:pages/shopCheckoutForm"); createShopPage(shoppingCart, "confirmation", "shop:pages/shopConfirmationPage"); createShopPage(checkout, "form-step", "shop:pages/shopFormStep"); createShopPage(checkout, "confirm-order", "shop:pages/shopFormStepConfirmOrder");
The shopSectionProperties
dialog is configured in /modules/shop/dialogs/shopSectionProperties
. The configuration adds a Shop tab to the standard properties dialog that allows for the selection on the appropriate shop.
The page templates (except shopHome
) use the autogeneration feature in the same way as STK feature templates. Functionality is provided by components that are autogenerated on the page template.
Here's the configuration for content
area in the shopShoppingCart
template.
Component templates are configured in /modules/shop/templates/components
.
The names of the feature component definitions correspond with the names of the templates they are used on, for example the shopShoppingCart
template autogenerates the shopShoppingCart
component in content
area.
Here's the definition of the shopProductDetail
component.
The shopForm
component, autogenerated on the shopCheckoutForm
template, is a standard Magnolia multistep form customized for shop functionality. See the /demo-features/modules/sample-shop/shopping-cart
page for the default form settings and email code. Configure valid SMTP settings to test the form.
formProcessors
: There are three custom form processors that are not enabled by default:modelClass
:
ShopFormModel
ensures that the ShopStartStepFormEngine
is in use. The engine checks the shopping cart for a form token. This allows users to continue browsing without losing checkout out form data.Here's the shopForm.ftl
script that renders the component
[#assign shoppingCart = model.getShoppingCart()] [#if (!shoppingCart?has_content || shoppingCart.getCartItemsCount() == 0) && !cmsfn.isEditMode() ] <p>${i18n['shoppingcart.empty']}</p> [#else] [#include "/form/components/form.ftl"] [/#if]
The module includes four custom teaser components.
shopExtrasProduct
and shopProductTeaser
are demonstrated above in Teasing products.extras
area is enabled.shopExtrasCart
adds the shopping cart.shopExtrasTagCloud
renders a list of keywords and product count.
shopExtrasProductSearch
allows a user to search for products.
The module adds CSS styles and theme images to the default pop
theme in the STK.
The shop.css
sheet is referenced In Templating Kit > Themes /pop/cssFiles/shop
.
You can access the resources in Templating Kit > Resources /templating-kit/themes/pop/css/shop.css
and /images/shop
.
By default, editors do not have permission to access shop configuration. Shop specific menus in AdminCentral are not visible to editors.
Shop pages are visible to and editable by editors in the site hierarchy. This means that editors can edit products through the Edit Product link.
Each shop can have its own security. This allows you to grant editors permissions selectively to the shops they work with. For example, a U.S. editor can have permission to a U.S. shop, a German editor to a euro shop, and a managing editor to both.
Access to shop resources is controlled with access control lists (ACLs). An ACL consists of one or more rules where permissions are applied to the controlled resource. The ACL itself defines what permission is granted. Attaching the ACL to a role defines who has the permission. See Security for more.
To create a shop editor role:
sample-shop-editor
. This role will be granted permissions to a particular shop. Any groups and users who belong to the role inherit the permission.Set the following permissions:
/modules/adminInterface/config/menu/sampleShop
. This allows the role to see the menu in AdminCentral and click items in it.shops
, shopProducts
and shopProductSuppliers
. You can for example use the open/close strategy where you first deny access to all shops, then grant specific access to a particular shop. This allows the role to edit the data items such as products and currencies.Assigning the role to a user grants that user permission to the controlled resources:
When the user assigned the role logs into AdminCentral they can see the shop menu the role grants them permissions to. They can also edit the shop's products and the shop pages in Website.
The Shop module does not have payment processing. Integrating with a payment gateway is a customization task for the implementer. It can be achieved by:
The easiest way to achieve integration with an external product repository is to import the data into the Data module adhering to the data structure the Shop module uses to store products. This requires a custom import handler. The import mechanism can be scheduled so the data will be automatically updated.