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 Magnolia KonaKart Commerce bundle consists of two modules:

• Integration: Connects Magnolia with the KonaKart eCommerce server

• Demo: Contains a reference website and configuration examples.

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 2.0 that is compatible with Magnolia 5.4 and newer.

Installing

Before installing, please be aware of:

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

<dependency>
  <groupId>info.magnolia.konakart</groupId>
  <artifactId>konakart-commerce-demo</artifactId>
  <version>2.1.1</version>
</dependency>

• konakart-commerce-integration.jar
• konakart-commerce-demo.jar

You can also download the modules as a WAR file:

• konakart-commerce-webapp.war

Configuration

Configuring the konakart module includes the following steps:

• JSON engine configuration
• Customizing konakart_json.properties 

KonaKart JSON engine configuration

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

Customizing konakart_json.properties 

The Products Browser app and KonaKartTemplatingFunctions uses KonaKart libraries to communicate with the KonaKart eCommerce solution. Configure the libraries using a .properties file. Default configuration file shipped with Magnolia is located in the integration module and is set to point to KonaKart demo. In order to use your own configuration, put the file in the classpath such as /WEB-INF/classes or add it to your module under src/main/resources.  For example, if would have maven module called myModule, location of the .properties file could be /myModule/src/main/resources/my_konakart_json.properties, and value of the propertiesFileName would be my_konakart_json.properties.

See default configuration of the .properties file below:

The default configuration points to konakart_json.properties - this file is in src/main/resources/konakart_json.properties of the Magnolia Konakart module. 

# -----------------------------------------------------------------------------------
#
#  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

 Once the fresh installed module works with the default konakart_json.properties - we recommend creating a custom properties file on a different location. When using a custom properties file, make sure to change the property /modules/konakart-commerce-integration/config/storeConfiguration/engineConfig/@propertiesFileName accordingly.

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 block 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 via JavaScript.

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 templates have no dependencies to templates from other modules. (No need for STK or MTE.)

Pages

The KonaKart Store  Demo template is the default page template. It displays a complete store.

The KonaKart Store Components Showcase is simple page displaying one or more components.

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

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

Login / Logout

Allows users to log in or register.

My account

Allows users to manage their account.

KonaKart templating functions

The KonaKartTemplatingFunctions can be used for obtaining product or category IDs, product and category beans, store ID assigned to the current site, etc. See API for all available functions. Templating functions are available in all templates by default under kkfn abbreviation.

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.

• Product API
• Category API

Caching and performance

Caching is enabled in the Product Browser app to reduce the number of calls and to make the Products Browser app and its choose dialog as responsive as possible. Cache is cleared when user closes the app.

Lazy loading

Categories and products in the Product Browser app are loaded lazily (for example when expanding category) to make Products Browser more responsive.

Related pages

• Konakart eCommerce
• Konakart Integration GIT Repository
• Konakart Integration JIRA