Similar content

Loading

Powered by Canoo FindIT.

Shop

The Magnolia Shop Module offers default e-commerce functionality for Magnolia CMS. At its core, it provides a flexible data structure and a set of classes for handling the data. It is then up to the integrator to define the look and behavior of the shop. It is delivered with a set of default paragraphs for the "pop" theme of the Magnolia Standard Templating Kit. fastforward initiated the project and developed the first version in collaboration with Magnolia International Ltd. and continues to extend the shop's functionality.

  • Products, product categories, prices and currencies are managed in AdminCentral.
  • All data is stored in the Data module except shopping carts in their own workspace.
  • Complete website structure with shop, product detail and shopping cart pages.
  • Teaser paragraphs for promoting featured products, campaigns and items on sale.
  • Checkout process implemented with multi-step form.
  • Run multiple shops in a single Magnolia CMS instance. Different products, countries and currencies.
  • Each shop can have its own security. Grant editors permission to shops they work with.

Downloading

Download the Shop module from Magnolia Store or Nexus repository.

Shop depends on the following modules which you also need. Magnolia CMS Enterprise Edition bundle already has them except for OCM. Update the Form module too.

Installing

To install the Shop module:

  1. Stop Magnolia CMS.
  2. Add the Shop module .jar file and any dependent modules that you don't have yet to WEB-INF/lib folder on all instances.
  3. Start Magnolia CMS and run the Web update.

Known limitations

  • Products in a given shop can be priced in only one currency at a time (default currency). To change this behavior, write a custom price category manager.
  • You cannot define different prices for different variants (sizes, colors) of the same product.
  • No payment processing is included.

Configuring a shop

The module ships with a sample shop that you can customize to your liking or create a new one. You can find the sample shop in the demo features project in /demo-features/modules/sample-shop.

To create a new shop:

  1. In AdminCentral, go to Shops Management.
  2. Click New Item.
  3. Give the shop a Name.
  4. Give the shop a Title.
  5. Click Save.
The system creates a dedicated menu item for your shop in AdminCentral. The menu provides shortcuts to all the shop's features such as products. You can access the same features under the shop content node in Shops Management but the dedicated menu is more convenient.

Tax categories

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.

To create a tax category:

  1. In AdminCentral, go to your shop menu and click Tax categories.
  2. Click New Item and fill in:
    • Tax category ID is a unique ID for the category. For example, 001-Books. The ID can contain letters, numbers and special characters with certain exceptions.
    • Title is the name of the tax category that is displayed to editors when they add products, for example Books.
    • Tax is a numerical value of the tax percentage. For example, if a VAT of 7.6% is levied on books, enter 7.6 into this box. The number format is Double where decimal point is a period.
  3. Click Save.

Currencies

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.

Important! While it is possible to configure multiple currencies, only one of them is used at a time. Customers cannot switch between currencies in the default implementation; all products are priced in the default currency.

To create a currency:

  1. In AdminCentral, go to your shop menu and click Currencies.
  2. Click New Item and fill in:
    • Currency ID is the unique ID of the currency such as USD, EUR or CHF. It is displayed to editors when they edit product details.
    • Title such as $, € or CHF. It is displayed to customers next to the product price in the shop.
    • Formatting convention. Set the format used to display currency so that it matches the currency's locale. Whole numbers are represented with a number sign # and parts with zero 0. For example, U.S. cents are separated from whole dollars with a period and a comma is used as thousands separator, such as in 1,234.56. Formatting for dollars is therefore ###,###.00. The corresponding convention for Swiss Francs is 1'234.55 (###'###.00) and for euros 1.234,56 (###.###,00).
  3. Click Save.

Price categories

Price category defines the currency in which a product is sold and whether tax should be applied.

To create a price category:

  1. In AdminCentral, go to your shop menu and click Price categories.
  2. Click New Item and fill in:
    • Price category is a unique ID for the category such as "Standard selling price" or "Tax-free Swiss franc". The ID is displayed in AdminCentral, not in the shop.
    • Title is displayed to editors who set product prices. Make the title descriptive and immediately understandable such Tax-free Swiss franc.
    • Currency. Select a currency. Options on this list are created in Currencies.
    • Tax. Whether the price includes tax or not.
  3. Click Save.

Setting a default currency

By default you can display products in only one currency at a time. Even if you define multiple currencies, only one of them is the default currency. The currency to use is inherited from the price category.

To set the default currency:

  1. In AdminCentral, go to Shops Management.
  2. Select the shop node from the tree and click Edit Item.
  3. Go to the System tab.
  4. Set the value of Default price category ID to the name of the price category node that uses your default currency such as Standard-selling-price.
  5. Click Save.

Customization example: Multiple currencies

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.

Recommended approach:

  1. Create two price categories.
  2. Write a custom price category manager class that allows switching between the categories. See DefaultPriceCategoryManagerImpl for the default implementation.
  3. Configure your shop to use the custom price category manager:
    1. In AdminCentral, go to Shops Management.
    2. Select a shop node on the right and click Edit Item.
    3. Go to the System tab and set the value of Price category manager class to the fully qualified name your custom class.
  4. Add a dropdown or link control on the shop Home page that allows the customer to switch between currencies.

Creating pages

The Shop module installs a sample shop that contains all the required Web pages. Use the sample for your shop as such or copy it. The pages are in /demo-features/modules/sample-shop.

Shop home

Shop home page is a typical section page. It teases a few selected products that you want to promote and provides navigation to product categories.

To create a home page:

  1. Go to Website workspace.
  2. Create a new page.
  3. Give the page a name and title.
  4. Double-click the Template column and set template to Shop Home.
  5. Open the page and click the Page Info button.
  6. From the Shop Name list, select the shop to display.
  7. Click Save.

Product category

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.

To create a product category page:

  1. In AdminCentral, go to Website.
  2. Browse to your shop home page and create a new child page.
  3. Give the new page a name and a title such as "Books".
  4. Double-click the Template column and set template to Product Category.

Product Details

Product Details page displays all information about the selected product, including the full description which is not displayed in teasers or search results.

To create a product detail page:

  1. In AdminCentral, go to Website.
  2. Browse to your shop home page and create a new child page.
  3. Give the new page a name such as product-detail and a title such as "Product Detail".
  4. Double-click the Template column and set template to Product Detail.

Shopping Cart

A customer lands on the Shopping Cart page when they start the checkout process. 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.

To create a shopping cart page:

  1. In AdminCentral, go to Website.
  2. Browse to your shop home page and create a new child page.
  3. Give the new page a name such as shopping-cart and a title such as "Shopping Cart".
  4. Double-click the Template column and set template to Shopping Cart.
  5. Optional: Edit the page, click Page Info and hide the page from navigation. Category and product detail pages already include a component that displays a summary of shopping cart contents and allows the customer to navigate into it.

Checkout form

Checkout is a three-step form that asks the customer to provide a shipping address, a billing address and confirmation.

Shipping address

To create a shipping address page:

  1. In AdminCentral, go to Website.
  2. Browse to your shopping cart page and create a new child page.
  3. Give the new page a name such as checkout-form and a title such as Shipping Address. This is the first step in the three-step process.
  4. Double-click the Template column and set template to Checkout Form.
  5. Open the page and create form fields for capturing a shipping address.

Billing address

To create a billing address page:

  1. In AdminCentral, go to Website.
  2. Browse to the Checkout Form page and create a new child page.
  3. Give the new page a name such as billing-address and a title such as Billing Address. This is the second step in the three-step process.
  4. Double-click the Template column and set template to Shop Form Step.
  5. Open the page and create form fields for capturing a shipping address.

Confirm Order

The third step of the form summarizes the order and asks the customer to confirm it.

To create a confirm order page:

  1. In AdminCentral, go to Website.
  2. Browse to the Checkout Form page and create a new child page.
  3. Give the new page a name such as confirm-order and a title such as Confirm Order. This is the final step in the three-step process.
  4. Double-click the Template column and set template to Confirm Order Form Step.
  5. Open the page. The order summary table is added automatically.
  6. Add a new field set and Previous and Next buttons inside it.

Confirmation

Once the order is successfully submitted, the customer is given an order number.

The order number matches the shopping cart node name in AdminCentral. Completed orders are stored in Shops Management > Shopping Carts.

The default 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.

Products

Products are the items sold in the shop: books in a book shop, songs in a music shop and so on.

To create a product:

  1. In AdminCentral, go to your shop menu and click Products.
  2. Click New Item and fill in:
    • Product is a unique ID for the product. In a book shop it could be the ISBN number of the book such as 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 CMS. Use IDs that make sense for your products. The ID is not displayed to customers in the shop by default.
    • Title is the product name displayed to customers. Use titles that customers would expect to find when searching for products.
    • Description (short) is a brief description of the product. It is displayed in product teasers, list paragraphs and search results.
    • Description (full) continues the short description. Don't repeat the text of the short description in the full description! The full description is appended immediately after the short description on the product detail page. If you repeat the text, it will be repeated in the shop.
    • Choose image type. Upload a product image from your computer or select one from the DMS. This is a standard Digital Asset Management (DAM) control that is configurable and extensible for selecting images also from other sources such as third party image repositories. The product image is displayed in teasers, lists and product detail paragraphs in the shop.
  3. Go to the Product categories tab and check the categories the product should belong to. The categories come from the category pages under the shop home page. When you check a box, the product will be displayed in that category page. For example, if you categorize a book such as A Guide to the Gardens of Kyoto as both Gardening and Travel, it will be displayed to customers on both category pages. Another example is a book that includes a CD. It could be categorized as a book and an audiobook.
  4. Go to the Pricing tab.
    • Enter the Prices.
    • Apply a Tax category.
  5. Go to the Keywords tab and add any keywords managed in the Categorization module. Keywords are displayed on the category page. They help users find related content.
  6. Click Save.
Tip! You can also edit products directly on the Web pages in edit mode. Click the Edit Product link on a category page to open the same dialog.

Product variants

Product variants are options within one product such as sizes or colors. For example, if you sell the same shirt in different sizes you can create variants S, M, L and XL. Or the same bicycle in red and black.

To create product variants:

  1. In AdminCentral, go to your shop menu and click Products.
  2. Select a product content node and click New Item. This is the variable such as color.
  3. Fill in:
    • Name is an internal name displayed in AdminCentral. It is not displayed in the shop. For example, color.
    • Title is displayed to customers in the shop. For example, Color.
    • Description is not displayed anywhere by default. You could customize the paragraph template to display the description as a tooltip such as “Click to select a color”.
  4. Click Save.
  5. For each option:
    1. Click New item.
    2. Fill in:
      • Name is an internal name displayed in AdminCentral. It is not displayed in the shop. For example, black.
      • Title is displayed to customers in the shop. For example, Satin black.
      • Description is not displayed anywhere by default.
    3. Click Save.

Teasing products

Use the Shop Product Teaser paragraph to showcase an item such as a product that is on sale. The purpose of a teaser is to promote the product and invite the customer to find out more.

To tease a product:

  1. Open the shop home page or a product category page.
  2. Add the Shop Product Teaser paragraph into the Main or Extras area.
  3. Select a product to tease.
  4. Optional: Overwrite the product title and description. This is a good place to write promotional text.
  5. Click Save.

Security

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 and editable to 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 the U.S. shop, a German editor to a euro shop, and a managing editor to both.

Access to shop resources is controlled with an access control list (ACL). 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. To learn more, see Magnolia CMS Security.

Create a shop editor role

To create a shop editor role:

  1. In AdminCentral, go to Security > Roles.
  2. Create a new role such as 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.
  3. Edit the role and go to the Access Control List tab.
  4. Set the following permissions:
    • In Website workspace, grant permission to the page hierarchy the role should be able to edit. Deny access to any pages they should not be able to edit. This controls whether the shop pages are editable in AdminCentral.
    • In Config workspace, grant permission to the shop menu and its sub nodes such as /modules/adminInterface/config/menu/sampleShop. This allows the role to see the menu in AdminCentral and click items in it.
    • In Data workspace, grant permission to relevant shops, shopCarts, shopProducts and shopProductCategories. 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.
  5. Click Save.

Assign editor role to a user

Assigning the role to a user grants that user permission to the controlled resources:

  1. Go to Security > Users.
  2. Edit a user.
  3. In Roles, assign the user to the role you just created.
  4. Click Save.
When the user assigned to 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 the Website workspace.

Integration

Payment gateways

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:

  • Sending client details and total amount to a page on the gateway site. Drawback of this approach is that the user will see that he is redirected to another site.
  • Creating a form processor that talks to the selected payment gateway API.

External product management applications

The easiest way to achieve integration with an external product repository is to import the data into Magnolia 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.