KonaKart Connector module

Magnolia KonaKart Connector module allows users to connect a KonaKart store to Magnolia. KonaKart is a Java-based eCommerce solution for retailers of all sizes. It offers features such as multiple stores and payment gateway integrations.

The KonaKart Connector module exposes the content of the store using standard Magnolia components that can be displayed on the website. Users (shoppers) can manage their account and wish list and complete the checkout process. The module installs a Products Browser app that allows users to browse stores. This documentation is based on the KonaKart Connector module 1.1 that is compatible with Magnolia 5.3.7+

Before installation

The Products Browser app uses KonaKart libraries to communicate with the KonaKart eCommerce solution. Configure the libraries using a .properties file. Put the file in the classpath such as /WEB-INF/classes or add it to your module under src/main/resources.

Example configuration file in the Demo module:

konakart_demo_json.properties

# -----------------------------------------------------------------------------------
#
#  K O N A K A R T _ J S O N   P R O P E R T I E S
#
#  For help on changing these parameters check the KonaKart User Guide
# -----------------------------------------------------------------------------------
# -----------------------------------------------------------------------------------
# Enterprise Feature
# KonaKart engine class used by the JSON services
# For the default engine use:   com.konakart.app.KKEng
# For the custom engine use:    com.konakart.app.KKCustomEng
konakart.app.json.engine.classname = com.konakart.app.KKEng
# -----------------------------------------------------------------------------------
# Enterprise Feature
# URL for the JSON engine servlet
konakart.json.engine.url = http://www.konakart.com/konakart/konakartjson
# Timeouts when calling the JSON Engine
konakart.json.connect.timeout = 20000
konakart.json.read.timeout = 30000
# Generate match Id on generated JSON Requests
konakart.json.generateMatchIds = false
# -----------------------------------------------------------------------------------
# Enterprise Feature
# Engine mode that the JSON engine will use
# 0 = Single Store (default)
# 1 = Multi-Store Multiple-Databases (add konakart.databases.used above as well)
# 2 = Multi-Store Single Database
konakart.json.mode = 0
# -----------------------------------------------------------------------------------
# Enterprise Feature
# Customers Shared / Products Shared mode that the JSON engine will use
# When in multi-store single database mode, the customers can be shared between stores
konakart.json.customersShared = false
# When in multi-store single database mode, the products can be shared between stores
konakart.json.productsShared = false
# When in multi-store single database mode, the categories can be shared between stores
konakart.json.categoriesShared = false

Installing KonaKart

The Magnolia KonaKart Commerce bundle consists of three modules:

Integration connects Magnolia with the KonaKart eCommerce server.
Theme provides a theme for the shop pages and components.
Demo contains a reference website and configuration examples.

See Installing a module on how to install the bundle using JARs or Maven dependencies. The KonaKart bundle is also provided as a .war file in our Nexus repository.

KonaKart Connector is not bundled with Magnolia by default.

<dependency>
  <groupId>info.magnolia.konakart</groupId>
  <artifactId>konakart-commerce-integration</artifactId>
  <version>1.1</version>
</dependency>

<dependency>
  <groupId>info.magnolia.konakart</groupId>
  <artifactId>konakart-commerce-theme</artifactId>
  <version>1.1</version>
</dependency>
 
<dependency>
  <!-- Optional. The demo module contains a reference website and configuration examples. -->
  <groupId>info.magnolia.konakart</groupId>
  <artifactId>konakart-commerce-demo</artifactId>
  <version>1.1</version>
</dependency>

Uninstalling

Click for uninstallation steps...

To uninstall a module, remove the module JAR file from the /WEB-INF/lib folder and restart Magnolia.

However, this is rarely enough. Modules add and modify configuration during installation. The use of a module also changes content. Removing all of these changes is difficult without knowing the installation tasks in detail.

To test a module, use the embedded Derby database and take a backup of your repositories folder. Install the module and try it. When you are done testing, remove the module JAR and restore the repositories folder from the backup. This way you can go back to square one.

We also recommend that you segregate the development and production environments. Take regular backups for disaster recovery so you can revert to a prior state in a routine fashion.

Configuration

Once you have installed the modules, configure a back-end JSON engine and front-end JavaScript engine.

KonaKart JSON engine configuration

In Magnolia, go to Configuration > /modules/konakart-commerce-integration and create the structure shown below.

Node name	Value
modules
konakart-commerce-integration
config
storeConfiguration
engineConfig
propertiesFileName	konakart_demo_json.properties
storeId	store1
stores
store1	Store 1
imagesUrl	http://www.konakart.com/konakart/images

Properties:

engineConfig
- propertiesFileName: Name of the engine configuration file.
- storeId: Default store ID.
stores: Store mapping as used in the Products Browser app.
- <store ID>
imagesUrl: URL for images used in the preview component.

Overriding the configuration from the properties file

You can override options configured in the .properties file in Configuration > /modules/konakart-integration-commerce/config/storeConfiguration/engineConfig. See KonaKart EngineConfig Javadoc for configuration options.

Javascript engine setup

The KonaKart Connector module installs a Setup app that allows you to configure a front-end JavaScript engine for KonaKart tiles. The configuration is saved under the site's parameters which allows you to have one store per site configuration.

A KonaKart tile is a building blocks for creating an eCommerce application which can be integrated into a front end system such as a CMS. Each tile has a template, a style sheet and a JavaScript file which control the look and feel as well as the functionality. The tiles communicate with a KonaKart server using the KonaKart JSON APIs called asynchronously from the JavaScript using AJAX.

Products Browser app

The KonaKart Connector module installs a Products Browser App that allows store administrators to browse all shops, categories and products. The product information is read-only since the KonaKart libraries do not expose the product update API. However, a store administrator can use the provided embedded IFrame app to use KonaKart administration within Magnolia to update products without leaving AdminCentral.

Templates

The KonaKart Connector module installs templates that integrate with existing STK templates.

The templates require HTML, CSS and JavaScript files from the KonaKart theme module to work correctly.>

Pages

The KonaKart Full Store template is the default page template. It displays a complete store. It is a standard STK Section template with some areas disabled as they are not needed.

Teasers

Product Teaser

The Product Teaser teases and links to individual products.

Configurable parameters:

Title
Product ID
"Add to basket" option
"Add to wish list" option

Promos

Configurable parameters:

Title
Product ID
"Add to basket" option
"Add to wish list" option

Category carousels

Category carousels display teasers to all products in a category.

Horizontal carousel:

Vertical carousel:

Configurable options:

Title
Category ID
Limit of products displayed in carousel

Store

Search

Allows users to search for products in the store.

Requires the products browser component.

Category menu

Displays categories from the store.

Requires the products browser component.

Products browser

Allows users to browse the store and filter products.

Configuration options:

Category ID

Shopping cart and checkout

Shopping cart popup

Displays a summary of the shopping cart with item price and total price.

Detailed shopping cart

Displays full content of the shopping cart, including taxes and discounts. Allows manipulation of the shopping cart content. Starts the checkout process

Checkout

Checkout tile allows to set delivery and billing addresses and choose shipping and payment methods.

Wish list

Wish list popup

Displays a summary of items in wish list with item prices and total price.

Detailed wish list

Displays full content of the wish list allowing to manage item priority, also allows to add items form wish list to the shopping cart.

Account management

Allows users to log in or register.

My account

Allows users to manage their account.

Asset API

KonaKart Connector uses Magnolia's Asset API which allows store administrators to work with products and categories as Assets.

Syntax for Assets is <provider>:<storeId>:<type>:<parentId>:<itemId>

provider: Identifier of the AssetProvider.
storeId: Store identifier in KonaKart.
type: Category or product.
parentId: ID of the parent category.
itemId: ID of the item (category or product)

KonaKart Java API

The KonaKart Connector provides a full KonaKart Java API which allows you to write your own actions and column formatters in the Products Browser app. You can also get products and categories as Java objects in templates instead of Javascript and work with them.

Caching and performance

The AssetProvider in the KonaKart Connector module caches every asset in order to reduce the number of calls and to make the Products Browser app and its choose dialog as responsive as possible. You can flush the in the Products Browser App with the Flush Cache action.

Lazy loading

The AssetProvider uses lazy loading of products by default. This means that products are loaded when they are requested.

You can turn lazy loading on/off in the configuration:

Node name	Value	Description
modules
konakart-commerce-integration
config
providerConfiguration
loadCategoriesOnDemand	true	set to true to load products from categories when they are requested set to false to load all products on module startup