ConfigBox Manual 2.5-EN · 2015-10-09 · ConfigBox–)ShopManager)Manual) Version!2.5! ! Page!2!...

Shop Manager Manual

ConfigBox 2.5

_________________________________________________________________________________________

ConfigBox – Shop Manager Manual

Version 2.5 Page 2

Table of Content

1 Introduction ........................................................................................................................... 5

2 Installation ............................................................................................................................ 6

2.1 How to check if ionCube Loader is installed ............................................................................................................ 6

2.1.1 What to do if ionCube Loader is not installed ....................................................................................................... 6 2.2 Installation procedure ....................................................................................................................................................... 6

2.3 Steps after installation ....................................................................................................................................................... 7

2.4 Automatic Database Updates .......................................................................................................................................... 8

2.5 ConfigBox module Price Overview ............................................................................................................................... 8

2.6 Setup of permissions (Joomla 1.6 and above only) ............................................................................................... 9

3 Integration of ConfigBox in Joomla ...................................................................................... 10

3.1 ConfigBox Menu Item Types ......................................................................................................................................... 10

4 ConfigBox ............................................................................................................................ 12

4.1 Overview ................................................................................................................................................................................ 12

4.2 Product Listings .................................................................................................................................................................. 13

4.3 Setup of a product including configuration elements ........................................................................................ 14

4.3.1 Product ................................................................................................................................................................................. 14 4.3.2 Section .................................................................................................................................................................................. 15 4.3.3 Configuration Page (formerly called ‘Category’) .............................................................................................. 15 4.3.4 Elements .............................................................................................................................................................................. 17

4.4 Element widgets for custom entries .......................................................................................................................... 20

4.5 Compatibility Rules ........................................................................................................................................................... 21

4.6 Price Calculation ................................................................................................................................................................. 23

4.6.1 Calculation using Tables .............................................................................................................................................. 24 4.6.2 Calculation using Formulas ........................................................................................................................................ 26

4.7 One-‐time Prices and Recurring Prices ...................................................................................................................... 26

4.8 Product Visualization ....................................................................................................................................................... 30

_________________________________________________________________________________________


Version 2.5 Page 3

4.9 How SEF URLs are built in ConfigBox ....................................................................................................................... 31

4.9.1 Product Details Pages: .................................................................................................................................................. 31 4.9.2 Configuration Page: ........................................................................................................................................................ 31 4.9.3 Configuration Page Module Assignment Trick ................................................................................................... 31

5 Order Management ............................................................................................................. 33

5.1 Shipping Management ..................................................................................................................................................... 33

5.2 Integration of Payment Systems ................................................................................................................................. 33

5.3 Email Notifications ............................................................................................................................................................ 36

5.4 Invoices .................................................................................................................................................................................. 36

6 Customizing ConfigBox and Order Management .................................................................. 37

6.1 Quotation PDFs ................................................................................................................................................................... 37

6.2 Change default system texts .......................................................................................................................................... 37

6.3 Custom programming in configuration elements ................................................................................................ 37

6.4 Use of custom data fields ................................................................................................................................................ 39

6.5 CSS style overrides ............................................................................................................................................................ 39

6.6 Custom templates for display ....................................................................................................................................... 39

6.6.1 Element Template “default” ....................................................................................................................................... 39

7 Notes for ConfigBox upgrades .............................................................................................. 40

7.1 Upgrade of ConfigBox versions older than 2.2 ...................................................................................................... 40

7.2 Upgrade to ConfigBox 2.3.0 ........................................................................................................................................... 41

8 Troubleshooting .................................................................................................................. 41

8.1 Option description popups do not show in a box ................................................................................................ 41

8.2 Pricing and Product Visualisation does not update ............................................................................................ 42

9 Extensions ........................................................................................................................... 43

9.1 VirtueMart Connector ...................................................................................................................................................... 43

9.1.1 Installation ......................................................................................................................................................................... 43 9.1.2 Setup in ConfigBox and VirtueMart 1.1.x .............................................................................................................. 44 9.1.3 Setup in ConfigBox and VirtueMart 2.x .................................................................................................................. 45

_________________________________________________________________________________________


Version 2.5 Page 4

_________________________________________________________________________________________


Version 2.5 Page 5

1 Introduction

ConfigBox is a multi-‐functional Product Configurator for Joomla 1.5 to Joomla 1.7 with integrated Order

Management and implements the whole order process from product configuration, request for quotation

(RFQ), ordering and shipping.

ConfigBox can handle a wide scope of products and services and is designed for companies seeking a way

to present complex products with a user-‐friendly and transparent experience. Configbox is a product

configurator with a full featured e-‐commerce framework for order management.

• Calculate pricing from formulas and tables in real-‐time

• Manages incompatibilities for optimal experience

• Requests for quotation and typical order processing

With a ConfigBox license you do not need any additional software for a complete ecommerce solution.

There are extra packages for integration with third party systems and open interfaces to create adapters for

other ERP or CRM system.

ConfigBox enables you to present complex products and services in a simple and professional fashion and

prevents incompatibilities and calculates intelligent pricing automatically. All this comes in full integration

in the Joomla CMS.

Product data entry is done with an interface that is specifically designed for user-‐friendliness and intuitive

handling. This enables anybody with even minimal technical background knowledge to manage the product

configurator, even for advanced tasks like pricing table and calculation formula entry.

_________________________________________________________________________________________


Version 2.5 Page 6

2 Installation

This section covers the installation of ConfigBox. For this you log into the administration panel of Joomla and go to “Extensions – Extension Manager” (or in Joomla 1.5 “Install/Uninstall”).

IMPORTANT NOTE: PLEASE MAKE SURE THAT THE PHP EXTENSION IONCUBE LOADER IS INSTALLED ON YOUR SERVER BEFORE YOU INSTALL CONFIGBOX.

2.1 How to check if ionCube Loader is installed

On Joomla 1.5: In the admin area, go to Help -‐> System Info -‐> PHP Information

On Joomla 2.5: In the admin area, go to Site -‐> System Information -‐> PHP Information

In the first section of the page, you see an information block similar to this screenshot (the actual logo and exact text differs between webservers):

If you see the line with the ionCube PHP Loader […], your webserver has ionCube loader installed.

2.1.1 What to do if ionCube Loader is not installed Please refer to your hosting provider in order to get ionCube Loader installed.

2.2 Installation procedure

If you upgrade ConfigBox you must create a backup of your website before upgrading to prevent data loss or downtimes of your store. This is a safety measure in case of an interrupted upgrade process.

To install ConfigBox, have your installation packages ready, they consist of multiple files of the type .tar.gz or .zip – You downloaded ConfigBox as one .zip file, you need to unzip it and use the packages in the folder “Installation” or “Upgrade”.

At the Extension Manager, select your first package with the file upload element and click on “Upload & Install”.

_________________________________________________________________________________________


Version 2.5 Page 7

After installation of the package com_configbox.tar.gz you will be asked to enter your license key. You should have gotten this key by e-‐mail from Elovaris Application or your service partner.

Continue installing all the packages. If any error occurs during installation check the troubleshooting section. If you find no solution please consult your service partner or Elovaris Applications.

After successful installation of all packages, you have to additional entries in your components menu – “ConfigBox“ and “Order Management”. All product setup related tasks are in ConfigBox. All tasks related to orders, payments, customer data and similar are found at “Order Management”.

2.3 Steps after installation

Activation of Joomla plugins

Joomla requires you to manually activate new plugins using the Plugin Manager at Extensions. Click on the red symbol next to the newly installed plugins.

Setup of permissions (Joomla 1.6 and above only)

On the Joomla 1.6 (and above) platform Joomla group permissions are used to allow or display certain tasks or features. After installation your public group has no permissions for any of these tasks, you need to set these manually.

_________________________________________________________________________________________


Version 2.5 Page 8

Allow Site Login for the Joomla guest user group

At Site -‐> Global Configuration -‐> Permissions you need to allow the guest user group (by default called ‘Public’ to login to the site. This enables ConfigBox to automatically login users after a request for quotation or customer data entry.

If you create customer groups and associate other groups, you need to set the same permissions.

2.4 Automatic Database Updates

ConfigBox updates often include changes to the database structure. These changes are done automatically in the background. After installation or update please open a ConfigBox admin page once to let ConfigBox do all changes.

2.5 ConfigBox module Price Overview

The most powerful ConfigBox module is ConfigBox Prices. This module is meant to be displayed on configuration pages and will show an outline of the current configuration and the pricing of each element and the total.

It updates in real-‐time as soon as the customer makes selections and can be configured in fine detail to fit perfectly for each of your products. The global settings are found in the module parameters through the Joomla Module Manager. These settings can be overridden for each product at the product edit form at the section “Price Module Overrides”.

To add the price overview module to your website, go to the Joomla Module Manager, click “Add” and choose the module by the name. Use it like any standard module, at the right side pane you have settings for your preferred display. See popup descriptions when hovering over the field labels.

_________________________________________________________________________________________


Version 2.5 Page 9

Figure 1 -‐ Price Overview Module

2.6 Setup of permissions (Joomla 1.6 and above only)

On the Joomla 1.6 (and above) platform Joomla group permissions are used to allow or display certain tasks or features. After installation your public group has no permissions for any of these tasks, you need to set these manually.

• Go to Components -‐> ConfigBox -‐> Configuration

• Click Permissions on the top right corner

• Pick the Joomla user groups you like to set permissions for

• Set ‘See pricing’, ‘save order’, ‘checkout order’, ‘request quotation’ and ‘request assistance’ to allowed (or keep these tasks denied in case you don’t intend to use these features).

_________________________________________________________________________________________


Version 2.5 Page 10

3 Integration of ConfigBox in Joomla

To display ConfigBox pages on your website, you use menu items just as any other component.

Go to “Menus – Your Menu” and click “New”, then choose the menu type. ConfigBox offers multiple menu

item types with parameters. The most important one is the type “ConfigBox – Product Listing” which will

show all your products or a listing of certain products (grouped by product listings).

Choose “ConfigBox – Product Listing” and leave the parameter “Product listing” empty for now (since you

have not added any product listings or products”

3.1 ConfigBox Menu Item Types

• ConfigBox – Configuration-‐Page

A link to a configuration page of a product. Check the section “SEF Links in ConfigBox” for special

use of this menu item.

• ConfigBox – Cart

Link to the ConfigBox shopping cart.

• ConfigBox – Product Details

Link to a defined product details page.

• ConfigBox – Product Listing

Link to a page that shows all your products or products of a certain listing if defined.

Firgure 2 – Menu Items in the Joomla Menu Manager

_________________________________________________________________________________________


Version 2.5 Page 11

• Order Management – Refund Policy Page

Link to the RP as defined in the Shop Data of ConfigBox Order Management.

• Order Management – Terms and Conditions

Link to the TOC as defined in the Shop Data.

• Order Management – Customer Profile Page

• Order Management – Edit Profile Page

• Order Management – Login Form (you can also use a standard Joomla login form)

• Order Management – Register Form (you can also use a standard Joomla registration form)

_________________________________________________________________________________________


Version 2.5 Page 12

4 ConfigBox

This section will give you step-‐by-‐step instructions on how to set up a product with configuration elements.

4.1 Overview

This figure shows you how products are structured in ConfigBox.

Product Structure in ConfigBox

_________________________________________________________________________________________


Version 2.5 Page 13

The customer will do the configuration on configuration-‐pages. If you add more than one configuration

page to a product then the customer will navigate to multiple pages with “next“ and “back” (step by step

configuration”. A customer makes his selections on elements which have assigned options (element could

be “Car Paint”, assigned options are “Red”, “Green” and “Blue”. Sections simply group category-‐pages but

do not affect the configuration process. They merely act as groupings useful for configurations that span

over many pages.

4.2 Product Listings

Product listings are used to display certain products together on overview pages (like household goods,

power tools or accessories). You can assign products to listings and you can assign a product to multiple

listings.

To add a listing, go to “ConfigBox -‐ Product Listings” and click “Add”. Set a name and save. You can then

add a menu item with the Joomla Menu Manager to show the listing on your website.

Overview of product listings

_________________________________________________________________________________________


Version 2.5 Page 14

4.3 Setup of a product including configuration elements

4.3.1 Product Add a product at the products view in the admin panel (ConfigBox – Products).

Click on “New” to create a new product. At the section ‘General’ you enter values for the required fields like title and assign the product to a product listing. For this example use ‘car 1’.

The product alias is used for SEF URLs (see section ‘how ConfigBox generates SEF URLs’) and has to consist of letters valid for entry in browser address bars.

Also enter the VAT tax rate of the product and a base weight (which can be used to calculate shipping costs).

New product screen

At the section ‘Base Price’ you can assign a base price on which all extras during configuration are added to.

With a price label you can decorate your price, especially useful if you use setup and recurring costs

parallel. With a custom price text, you can present a price with your own wording and insert the price value

using the placeholder %s. This enables you to display your price as ‘Starting from €100’. For the ‘Recurring

base price’ you can do the same analogous.

_________________________________________________________________________________________


Version 2.5 Page 15

If you use product visualization, set up the dimensions if you dynamic visualization at the section ‘Product

Visualization’. Dynamic visualization images of one product should have the same dimensions. Not setting

dimensions here results in not seeing the image since the frame is set to these measures.

Product descriptions are shown in the product listing and details page. You have separate product listing

description and product details description. If you set ‘Use product details description as template`, all your

entered HTML will be used as-‐is in the product details giving you full control over the layout. You can then

use placeholders for dynamic fields like price and ‘add to cart’ or ‘configure’ buttons. See the field’s tooltip

for the placeholder names.

Price Module Overrides: You can override the settings for the price overview module for each product, at

this section you find the same parameters as in the module itself. Set to “Use Default” for standard module

settings.

4.3.2 Section Every configurable product needs at least one section and subsequently a configuration page with elements.

A section is a grouping of configuration pages and is useful for organisation of big amounts of configuration pages of a product. Since sections are mandatory please set up one section and assign all your product’s pages to it if you have no need for groupings.

Click on the tab ‘Sections’ and click ‘New’ to add a section. Use a title and product and click ‘Save’.

Section Edit Screen

4.3.3 Configuration Page (formerly called ‘Category’) All your configuration elements are shown on configuration pages. You can have multiple configuration

pages for a product to have a step-‐by-‐step configuration, where customers click ‘Next’ and ‘Previous’ until

the reach the last page of the configuration. We recommend to group similar elements and order them in

the order of their compatibility rules.

_________________________________________________________________________________________


Version 2.5 Page 16

Configuration Page Edit Screen

Click on the tab ‘Configuration Pages’ and click on ‘New’ to add a configuration page. Set up a title and the

parent section.

The visualization view is a text field, which is also found at the option assignment and deals with the

product visualization. Only those images which match the image scope text of the configuration page are

shown, which makes different angles or detail views possible.

If you like to block the customer from going to the next step if mandatory elements have no selection,

check ‘Block continuing if missing elements’. You set elements to be mandatory at the element screen

later.

By default, the ‘Finish Configuration’ button is displayed on each page, to change that set ‘Finish button on

last page only’ accordingly.

_________________________________________________________________________________________


Version 2.5 Page 17

4.3.4 Elements Elements (and their assigned options) are the components on which the customer makes his selections. An

element can be a text-‐field, checkbox or radio-‐button depending on the number of assigned options. Using

custom element templates (some templates are bundled) you can add special functionality and display

styles to them.

Examples of elements for illustration

• Car paint (with assigned options red, blue and black)

• Width of brochure (no options, will be a text-‐field)

• Including insurance (checkbox, one assigned option)

4.3.4.1 Text Field Element To display the element as text field, you only need to set the title and configuration page and click “Apply”

and see it on your website. If you want to restrict possible entry values, see the section ‘Text Field Settings’.

Text field settings on the element edit screen

If you like to allow numbers only (e.g. for measurement entries), set ‘Allow integer values only’ and

optionally set a minimum and maximum value and default value (which is pre-‐set at the configuration

start – but not if the element is inactive by compatibility rules initially). If you set a minimum value,

ConfigBox automatically takes care of language dependent decimal point translation (in some languages a

comma is used).

_________________________________________________________________________________________


Version 2.5 Page 18

Price Calculation on elements – ‘calculation element’

Normally you would set price calculation on the option assignments, but you can also assign a calculation

model to the element itself. Doing so will make the element disappear from the configuration page and

only affect the price of the order (it will be shown with its title in order overviews like the price overview

model, cart and similar pages). This is called a calculation element. Do not assign any options to an

element with assigned calculation models.

Price calculation settings on the edit element screen

If you set ‘Display as text field’, the element will not disappear and act as a combination of a text field and

calculation element (Since version 2.3.0).

Setting up calculation models is described in the manual section ‘Calculation Models’. The multiplicator is

used to multiply the resulting price from the calculation.

4.3.4.2 Checkbox Elements After you add a new element and save (or apply) you will see a section called ‘Option Assignments’ on the

bottom of the edit screen. This allows you set up items that the customer can choose from. One

assignment makes the element display as checkbox, more assignments make it display as radio-‐button

field.

Option assignments on the element edit screen

_________________________________________________________________________________________


Version 2.5 Page 19

Option assignments: Options belong to elements and can be reused for multiple products. An option has

global settings and settings (like title, price, description and others) that only apply to the specific

assignments (calculation models, compatibility rules, visualization image and others).

To make the element a checkbox, click on ‘New option’. A popup with the global option settings appars.

New option popup at element edit screen

Add the mandatory Title field and optionally SKU (inventory identification code) and a price. The option’s

description will be shown in a tool-‐tip on the website.

After saving, the option will be automatically assigned to your element. You can review the assignment

settings by clicking on the title of the option.

Option assignment settings:

For checkboxes you can set ‘Default option’ to yes to make the checkbox pre-‐checked.

Here you can assign a calculation model for price and recurring price. If set, the static price set at the global

option settings are ignored.

_________________________________________________________________________________________


Version 2.5 Page 20

Here you upload the image for the dynamic product visualization. To control the stacking order of this

image, enter a number at the field ‘Layer’ (higher numbers make the image stacked higher up). Entering an

image scope text makes the image only show if the text matches the text set at the configuration page.

Compatibility rules are described in the section ‘Compatibility Rules’.

Option assignment settings popup at element edit screen

4.3.4.3 Radio-‐Button Field Elements You can setup an element just like a checkbox element, but with more than one option assignments.

Clicking on the form element next to the title sets the pre-‐selected standard option.

4.4 Element widgets for custom entries

When using text fields for entries, you might want to give your customers a more appropriate way to enter their information. For this we got widgets for these kinds of entry:

• Regular text field with validation and minimum and maximum value • Calendar for date entry • Slider for number entry • File upload field with file validation • Popup with a custom Joomla article to pick a predefined text value (pick a Joomla article with a

HTML table. In the cells you put in a text inside a <span> Element, when the customer clicks on the table cell, the value in the <span> will be entered in the text field

_________________________________________________________________________________________


Version 2.5 Page 21

4.5 Compatibility Rules

Compatibility rules enable you to let elements and options automatically appear and disappear (called

becoming active or inactive in this manual) depending on the customer’s current selections. The elements

and options can be greyed out or completely hidden. Standard options can be auto-‐selected once the

element becomes active.

In the following, we refer to options – all applies to elements as well.

The rules are entered with a visual editor. You open the option you like to become active/inactive and click

on edit at the section/field compatibility rules and the compatibility rules editor popup.

Compatibility rules editor in ConfigBox prior to 2.4.0

Rule editor before ConfigBox 2.4.0: You can use the filters on the top of the editor to narrow down your

selection of elements. Select the involved element, an operator (equals, does not equal etc.) and the option

that has to be selected. If you choose a text field element, you have additional operators (greater than

etc.).

Click on “add” to let the condition become effective. You can add multiple conditions to the rule with OR or

AND to make a complex rule.

_________________________________________________________________________________________


Version 2.5 Page 22

Rule editor since ConfigBox 2.4.0

Rule editor since ConfigBox 2.4.0: Pick an element in the grey area and you get the available conditions to

be dragged into the rule. Once you click and hold on a condition, you see drop areas in the rule area where

you drag and drop it. You find more info in the onscreen help at the rule editor. You can use the values of

the custom fields in options and option assignments to determine your rules. Click on “is” to change the

operator to “is not” or “is lower” etc. (where applicable).

In the editor you set the conditions under which the option shall be active. If the conditions are not met the

element will become inactive.

If the conditions for an option are not met anymore and the option was selected, it will be automatically

deselected.

You can make the option disappear by setting ‘Hide if not

applying’ to yes. If you like the customer to confirm

automated deselection if the conditions of the display are

not met anymore, set ‘confirm deselect’ to yes.

For compatibility rules on elements you can set that the

_________________________________________________________________________________________


Version 2.5 Page 23

default option (if set) will be auto-‐selected once the element becomes active.

4.6 Price Calculation

With calculation models you can implement complex pricing structures with no need for programming.

Depending on the pricing scheme you can use price tables or formulas to output pricing depending on

customer input.

In general calculation models take the number input from text field elements, but you can also use tables

to make prices for combinations of 2 radio button elements.

At the tab ‘Calculation Models’ you find a listing of all your calculation models. Setting up a model is one

step, you also have to assign your calculation model to an element or option afterwards. See descriptions at

the manual section element.

Assignment of a model to an element:

If you assign the calculation model to an element, it will not be displayed as a configuration element

anymore, it will only be shown on overview pages (e.g. price module, cart etc) with the price calculated in

the model. This is referred to as ‘calculation element’.

If you set ‘Display as text field’ to yes, the element will show the calculated pricing and will be displayed as

text field.

If you assign an calculation model to an element, the element needs to be a text field (no options assigned).

Price calculation section at element

_________________________________________________________________________________________


Version 2.5 Page 24

Assignment to an option assignment:

You can also assign a model to an option. In that case the static price is ignored and the price from the

model will be displayed instead.

Price calculation at option assignment

4.6.1 Calculation using Tables With calculation tables, you choose 2 elements as input parameters. The selection of the elements is used

to look up the values in the table, the cells of the table are the price output.

_________________________________________________________________________________________


Version 2.5 Page 25

Calculation table

A typical example of an calculation table is usage of 2 text field elements (e.g. for input of width and height)

which is used in the table for columns and rows. At the bottom of the screen you can add your axis values

(‘Add in columns’, ‘Add in Rows’) – you can add multiple values at once by separating with commas.

After clicking ‘go’ the table is created with zero values (as in the figure above). You can now enter prices for

each combination of the 2 inputs.

Set ‘use next higher value’ to look up the next existing value in the table (e.g. customer entered 13, next

axis value in the table is 20 – so the value for 20 is used).

‘Round values to’ makes the customer input rounded to integers, tens, hundreds etc. (only enter 1, 10,

100, etc.).

‘Multiplicator’ simple multiplies the result of the calculation with the entered value. Useful when entering

supplier prices and multiply it with your margin.

‘Dynamic Multiplicator’ can be used to define another text-‐field element whose value will be used to

multiply the result of the calculation.

_________________________________________________________________________________________


Version 2.5 Page 26

Note: If you set up text field elements meant for numbers, make sure you set up validation of the user

input at the element under section ‘Text field settings’. This makes sure the price calculation won’t break

when customers enter non-‐numeric values. ConfigBox automatically deals with decimal symbols from

different languages.

4.6.2 Calculation using Formulas Calculation formulas follow a similar pattern like the calculation tables, but here you can use a

mathematical formula with placeholders for customer input.

After adding a new calculation model, select the type ‘Formula’ to toggle. You can add up to 4 placeholders

that will be used in the formula with the letters A to D. The placeholders get replaced with the value

entered by the customer for that element (or zero if no input is there).

Always pad a placeholder with a space (before and after), so that the formula can be parsed properly.

Example formula: ( A * B ) + C

4.6.2.1 Formula Keywords You can use keywords to use values other than user input for your formula (e.g. Total for the price total of

the current product). A list of keywords is found in the on-‐screen notes at the formula editor.

With the keyword ElementAttribute you can use metadata of an element and its assigned options. E.g. use

ElementAttribute(10.selectionPrice) to get the current price for the element with ID 10. You can look up

element IDs at the element list screen or at the placeholder dropdowns.

Since ConfigBox 2.4.0: You will see the available placeholders in the onscreen-‐help. You can use the custom

fields in elements, options and option assignments in your formula as in the compatibility rules.

You can also enter PHP code to make more complex calculations here. Also there is an element class API

that lets you write your own element PHP classes that override the calculation method to make even more

sophisticated price calculation.

4.7 One-‐time Prices and Recurring Prices

ConfigBox supports 2 parallel prices for each entity enabling you to offer products that have a one time fee

and a recurring fee (or either one of them). This is meant for cases like hosting contracts, phone carrier

plans and similar but can be used for any kind of project.

All pricing (including price calculation) can have both one-‐time fees and recurring fees at once. At the

product settings you can label the pricing (e.g. ‘monthly service charge’).

_________________________________________________________________________________________


Version 2.5 Page 27

Recurring pricing options at product edit screen

Display on website at product listing

_________________________________________________________________________________________


Version 2.5 Page 28

Display of recurring and one-‐time prices during the configuration

_________________________________________________________________________________________


Version 2.5 Page 29

Price Overview Module showing recurring and setup prices

The price module can be set up to display recurring pricing together with regular pricing. You can also show totals for recurring pricing only.

Cart page order overview displaying recurring and normal prices

Depending on the product’s recurring pricing, the cart overview shows both pricing.

_________________________________________________________________________________________


Version 2.5 Page 30

4.8 Product Visualization

ConfigBox enables you to present your product visually and to update it’s display during configuration in

real-‐time. Instead of having images for each combination of elements, you can upload outtakes of your

options with transparent background, ConfigBox stacks those images to produce a complete product image

consisting of the selected options.

You display the product visualization with the supplied Joomla module ‘ConfigBox – Images’ which you can

place in the template position of your choice.

You need to set up the visualization dimensions in your product’s settings (see manual section ‘products’)

and you can set a base image there as well.

To add an image, go to the option assignment and upload an image at the field ‘visualization image’ (see

manual section ‘elements’). The ‘visualization stacking order` field determines how high up in the stack the

image will be.

Simple product visualization (without multiple layers)

_________________________________________________________________________________________


Version 2.5 Page 31

4.9 How SEF URLs are built in ConfigBox

ConfigBox uses the native Joomla framework functions to create SEF URLs. There is no need for third party

extensions for this.

In general, ConfigBox analyses your menu item structure and determines the best URL for any page. It takes

the most specific menu item (exception are configuration page items) and appends aliases defined in

ConfigBox as necessary.

Menu items that are currently active or being parents of the currently active menu item are prioritized.

Please note that you need to enable Search Engine Friendly URLs in the Joomla Global Configuration to

benefit from ConfigBox SEF URLs.

4.9.1 Product Details Pages: ConfigBox searches for a matching product menu item or a product listing menu item that shows the

product.

1. A product page menu item with matching product id

2. A product listing menu item that shows the product

3. A product listing with no defined listing id

4.9.2 Configuration Page: ConfigBox searches for a matching product menu item, then for a matching product listing, then for a

matching configuration menu item.

1. A product menu item with matching product id

2. A product listing menu item where the product belongs to

3. A product listing menu item with no defined listing id

4. A configuration page menu item with matching product and category id

5. A configuration page menu item with matching product id and no category id

6. A configuration page menu item with no defined product and category

4.9.3 Configuration Page Module Assignment Trick Even though the URL and breadcrumbs are set like described above, once the link is visited, ConfigBox will

find a matching configuration page menu item and fool Joomla into thinking that this menu item is the

active menu item, therefor display the modules (like the Price Module) assigned to it, while Joomla will still

display the right breadcrumbs and URL.

_________________________________________________________________________________________


Version 2.5 Page 32

By setting up configuration page menu items with a product id and/or category id and assigning modules to

those menu items, ConfigBox will choose the most specific matching menu item and Joomla will load the

assigned modules.

You can leave the category parameter or both parameters blank. ConfigBox will then use the menu item for

all categories of a product or for all products respectively unless there is another more specific menu item.

Please do not set a category with setting a product id.

Only drawback is that the "actual" active menu item will not be displayed as such in menus in Joomla 1.5,

but you can correct this manually with some JavaScript or use hidden child menu items if it is important to

you. In Joomla 1.7, this problem does not exist.

_________________________________________________________________________________________


Version 2.5 Page 33

5 Order Management

5.1 Shipping Management

ConfigBox automatically calculates shipping costs. Using total weight of the order, shipping country and

chosen shipper, ConfigBox calculates shipping rates automatically. All shipping related data is entered in

user-‐friendly and uncomplicated administration forms.

Over the tab ‘Order Management – Shipping’ you can define zones and assign countries to these. Also you

define shippers (like UPS, DHL etc.).

When this is done you define shipping rates.

You define a title that will be shown to your customer at the shipping method selection, then the shipper

and the zone in which the shipper operates.

With the minimum and maximum weight you set in which weight range the order weight needs to fall to

apply for this rate.

You can define the number days delivery will take, price and the tax rate for shipping.

5.2 Integration of Payment Systems

You have various adapters for payment gateways bundled. To extend your choice of payment gateways,

you can use the VirtueMart Integration Plugin (sold separately) to use VirtueMart as order management

with its vast amount of payment gateway adapters.

_________________________________________________________________________________________


Version 2.5 Page 34

At ‘Order Management – Payment Options’ you can set up payment methods using different payment

gateway providers.

Enter a title that will be displayed to the customer, a price and tax rate (to be added to the order price) and a payment class. After clicking apply you see additional options at the bottom for most payment classes.

After the description you can select the countries for which the payment method is available in.

Following payment gateway providers is bundled with ConfigBox:

• PayPal

_________________________________________________________________________________________


Version 2.5 Page 35

• Authorize.net

• MPAY24

• QPAY

• Bank transfer (offline)

• Cash on delivery

ConfigBox has an API to make integrations with additional gateways in a cost efficient way. We are glad to

give you documentation on how to develop an adapter or give you an estimate for development.

_________________________________________________________________________________________


Version 2.5 Page 36

5.3 Email Notifications

You can set email notifications for customers and shop managers for any order status change. You find a listing of current notifications at Components -‐> Order Management -‐> Emails.

Email notification edit screen

Enter an internal name and choose the order status on which the email should be sent.

Subject and email HTML is the content of your email. You can use placeholders in the form {firstname} to include customer data. You find a listing of available placeholders on the right side of the edit form.

You also have an email to the shop manager analogous to the customer email.

Since ConfigBox 2.4.0: With the placeholder {element_order_overview} you can display an overview of the order.

5.4 Invoices

In Components -‐> Order Management -‐> Shop Data you can define your invoice template. You can insert customer and order data analogous to the email notifications. With the special placeholder {orderitems} you insert a table with the order data.

_________________________________________________________________________________________


Version 2.5 Page 37

6 Customizing ConfigBox and Order Management

6.1 Quotation PDFs

To change the layout and contents of your PDF quotation you can use the Joomla Template Override System.

There are 2 different quotation PDFs: The download and the email attachment.

Override the download: Copy the original template file from /components/com_cbcheckout/views/quotation/default.php and copy it to your template folder’s override folder (/templates/[your template]/html/com_cbcheckout/quotation/).

In this location you can edit the file any way you need it. Be careful to keep the HTML valid since the PDF generator is error-‐intolerant. CSS floats are not supported by the PDF parser, use table-‐layouts if necessary.

Locale-‐dependent texts are found in the language file for com_cbcheckout (not com_configbox).

Override the email attachment: Copy the original from /plugins/configbox/notifications/notification_attachments/customer_11.pdf.php) to the override folder in /components/com_cbcheckout/data/notification_attachments/ and make changes there. The same implications apply as for the PDF download.

6.2 Change default system texts

All text output comes from language files found in /language/[yourlanguage]/ and administrator/language/[yourlanguage]/.

For ConfigBox pages you find the texts in the file called en-‐GB.com_configbox.ini, order management files in en-‐GB.com_configbox.ini.

The format of these files is like this:

BACK=”Back”

Most texts are not in the English language files since the original is English, for instance if you like to change the text for “Add to cart”, write

ADD TO CART=”Go to overview”

You can add these changes in the language override files for ConfigBox pages found in

/components/com_configbox/data/customization/language_overrides/frontend/language/[your-‐language]/xx.com_configbox.ini

You also find overrides for the modules ConfigBox Prices and ConfigBox Currencies in the language_overrides folder.

For order management pages you find the language overrides in

/components/com_cbcheckout/data/customization/language_overrides/frontend/language/[your-‐language]/xx.com_cbcheckout.ini

6.3 Custom programming in configuration elements

Using the element class API you can implement specific functionality in your configurator. For instance:

_________________________________________________________________________________________


Version 2.5 Page 38

• Determine element pricing with your own PHP code; e.g. fetch pricing from external data sources

• Store configuration element values in other systems

• Do any modification of the standard functionality by overriding any element method (not to be confused by the template override system).

How is the element class API used?

Technically you create PHP files with classes that extend the

original ConfigBox element class. There are methods that

determine pricing, the element output, storing of the

element’s value and much more. After you created a class

file, you can pick the element class in the element’s edit-‐

screen to give it the intended functionality.

The element class file name and the PHP class name follows

a naming convention. The files are stored in ConfigBox’ data

folder to avoid overwriting on updates.

Your element class extends the class ConfigboxElement.

File folder and naming convention:

Base folder: components/com_configbox/data/customization/element_classes

Each element class has a subfolder, in it you have a PHP file with the same name.

Example:

PHP class name: ConfigboxElementUpload Subfolder name: upload Filename: upload.php

Methods you can extend:

getPrice($getNetPrice, $getInBaseCurrency)

This method returns the price in the base currency, either gross or net (depending on the 2 parameters). The method must return a number of type float. If parameter 1 is not entered, the system default has to be used (using CONFIGBOX_SHOW_NET_PRICES), if parameter 2 is missing, false is assumed.

getPriceRecurring($getNetPrice, $getInBaseCurrency)

analogue to getPrice(), for the recurring price.

loadTemplate()

This method writes the frontend HTML output of the element in the configurator. Anything written to the output buffer will be shown in the browser.

_________________________________________________________________________________________


Version 2.5 Page 39

6.4 Use of custom data fields

Elements, options and option assignments have 4 custom fields you can use to enter any additional data of your products or useful data for your order processing. You can use these fields for various tasks:

• Use the values in calculation formulas (see onscreen-‐help for detailed info) • Use the values in custom templates or element classes • Use the values for integrating with 3rd party software

6.5 CSS style overrides

There is an empty CSS stylesheet, where you can make change to the design of any configurator page. It is located at:

components/com_configbox/data/customization/style_overrides/css/style_overrides.css

This file (as any file in the customization folder) is not overwritten with ConfigBox updates and helps you keep your changes organized.

6.6 Custom templates for display

If you want to make design changes that are not possible using CSS overrides or even want certain pages or individual elements have a different look and feel you can use the ConfigBox template system. At Components -‐> ConfigBox -‐> Templates you can see the original templates for

• Product listings • Product detail pages • Configuration pages • Elements

You can copy the template markup of any of these templates, create a new template, make your changes and then you can assign the template to your element, page etc. There is a drop-‐down item called ‘Template’ for elements and all other corresponding items.

Note: These custom templates may need to be modified for new ConfigBox versions in case we have to make changes to the original templates.

6.6.1 Element Template “default” This is the standard display of a checkbox element.

_________________________________________________________________________________________


Version 2.5 Page 40

Using more than one option assignment makes the element look like this.

Text fields with widget ‘text’ look like this:

7 Notes for ConfigBox upgrades

7.1 Upgrade of ConfigBox versions older than 2.2

Templates

Custom Templates from ConfigBox 2.x are still compatible with ConfigBox 2.2.0 although the new features

and improvements in the cart, product listing and product details page are only available if you adapt your

cart template.

Calculation Formulas

The placeholders A, B, C, D now need to be written with a prepended and appended space and in capital

letters. So A*B is not possible anymore and has to be written A * B. This is necessary because of clashes

with keywords like ElementAttribute, where the A would get replaced in case the placeholder A is defined.

Please check your formulas before updating.

New SEF URL routing

ConfigBox has a new router for SEF links, finally removing the /configuration part from the URL and

dropping the requirement to have a product listing menu item with no product listing parameter set. Also it

is now possible to have different module assignments for each product or each category by creating a

"Configuration Page" menu item with fitting parameters for product and category. If you do not need this

fine-‐grained control over your module display, you can still use a menu item with product and category

unset.

_________________________________________________________________________________________


Version 2.5 Page 41

This is a one-‐time change of URL routing and will not be changed again in the mid-‐future. We found that

this step was absolutely necessary to make links more flexible and easier to handle.

7.2 Upgrade to ConfigBox 2.3.0

Setup of permissions when using Joomla 1.6 or above

When using Joomla 1.6 or above please open up the permission screen at ConfigBox -‐> Configuration -‐>

Permissions (top right corner) and set the price display and other permissions for public groups. Otherwise

none of your users (except super users) will be able to see pricing and cart buttons.

Uninstall Plugin “ConfigBox – Request Handler”

When upgrading to version 2.3.0 (any Joomla version) you need to uninstall the plugin ‘Configbox –

Request Handler’ – it is not needed anymore. You find the plugin in the group ‘configbox’.

Rename E-‐Mail notification placeholder {order_id}

In the E-‐Mail Templates at ‘Order Management -‐> Emails’ you need to rename the placeholder {order_id}

with {cb_order_id}. The new features in the notification-‐system made this necessary.

8 Troubleshooting

Always check if you read and followed the instructions in the section Installation and the section ConfigBox upgrades.

8.1 Option description popups do not show in a box

Joomla templates normally include CSS styles that define the display of your popups in harmony of your template’s overall design. That is why ConfigBox does not interfere by setting it’s own styles. If your Joomla template lacks styling for popups (also called tool tips or just tips), you need to add the CSS styling yourself in your template’s stylesheet.

The typical tool-‐tip styling CSS for Joomla 1.5 is:

.tool-tip { float: left; border: 1px solid #D4D5AA; padding: 5px; background: #FFFFCC; max-width: 200px; } .tool-title { padding: 0; margin: 0; margin-top: -15px; padding-top: 15px;

_________________________________________________________________________________________


Version 2.5 Page 42

padding-bottom: 5px; background: url(../../system/images/selector-arrow.png) no-repeat; font-size: 100%; font-weight: bold; } .tool-text { margin: 0; font-size: 100%;

}

For Joomla 1.6 and above it is:

.tip { float: left; background: #ffc; border: 1px solid #D4D5AA; padding: 5px; max-width: 400px; z-index: 50; } .tip-title { padding: 0; margin: 0; font-size: 1em; font-weight: bold; margin-top: -15px; padding-top: 15px; padding-bottom: 5px; background: url(../images/selector-arrow.png) no-repeat; } .tip-text { font-size: 1em; margin: 0;

}

These CSS styles are from the Joomla supplied template stylesheets and probably GPL licensed.

8.2 Pricing and Product Visualisation does not update

In most cases this happens when,

-‐ the jQuery JavaScript library (integrated with the Plugin jQuery Includer) is overwritten by another Joomla extension. Most YooTheme Modules load jQuery and have module parameters to disable loading it themselves. Navigate to the Module Manager, open the regarding module(s) and search for a parameter allowing you to disable loading jQuery. These modules should work fine with the jQuery library loaded by our plugin.

_________________________________________________________________________________________


Version 2.5 Page 43

-‐ The jQuery Includer plugin is not installed or activated. Navigate to Plugin Manager -‐> Filter for group system. Check if the plugin ‘System – jQuery Includer’ exists and is activated. If not, install and/or activate it. See section Installation.

-‐ Your Joomla template removes all JavaScript files loaded via the Joomla framework. This is a rather rare case nowadays and happens on some free templates or bargain-‐templates. Open the file index.php in your Joomla template folder and search for regarding code in the <head> section of the file. ConfigBox cannot guarantee proper functionality if the template tampers with files loaded via the Joomla framework.

-‐ Page Caching plugins are active on configuration pages Page caching plugins like Yot-‐Cache or JoomlArt T3 Template Caches prevent ConfigBox from preparing orders before displaying the configuration page. Deactivate the caching in general or disable it for the components com_configbox and com_cbcheckout.

8.3 The installation failed and uninstallation, reinstallation is not possible

If the installation failed there is a known issue with Joomla 2.5 leaving database table rows about the extension behind, making uninstallation, launch and reinstallations impossible.

Solution

• Launch phpMyAdmin in your server hosting panel • Go to the table jos_assets • Search for rows with name ‘com_configbox’ and remove the rows • Search for rows with name ‘com_cbcheckout’ and remove the rows • Go to the table jos_extensions • Search for rows with name ‘com_configbox’ and remove the rows • Search for rows with name ‘com_cbcheckout’ and remove the rows

9 Extensions

9.1 VirtueMart Connector

Please note that we discontinue sale of the VirtueMart Connector until further notice. Customers that already have purchased the connector get support and technical assistance on incompatibilities.

9.1.1 Installation You install the VM connector as Joomla plugin. You find the plugin in the group ‘configbox’ by the name ‘ConfigBox – VirtueMart Integration’.

Important note: You need to activate the plugin in the Plugin Manager.

_________________________________________________________________________________________


Version 2.5 Page 44

9.1.2 Setup in ConfigBox and VirtueMart 1.1.x Setup in VirtueMart configuration:

At Components -‐> VirtueMart -‐> Configuration -‐> Security activate ‘Allow the inclusion of extended classes from the theme-‐directory’.

VM connector plugin parameters

You find the plugin in the group ‘configbox’ by the name ‘ConfigBox – VirtueMart Integration’. Ignore the settings for VirtueMart 2.x.

• VM category ID: Set the ID of the product category

_________________________________________________________________________________________


Version 2.5 Page 45

• VM vendor ID: Set your vendor ID (default is 1) • VM manufacturer ID: Set the manufacturer ID of the ConfigBox products (default is 1) • VM shopper group ID: Set the shopper group ID for the ConfigBox products (default is 1) • VM theme name: Set the VM theme name (default is ‘default’, set another name if you use a

custom VM theme). • VM table prefix: If your VM installation uses a different table prefix, enter it here.

9.1.3 Setup in ConfigBox and VirtueMart 2.x Setup in VirtueMart configuration:

Set up a tax calculation that calculates the tax amount for the ConfigBox products added to VM. You enter the calculation ID in the VM connector plugin settings (described below). The ID is found on the far right side of the calculations table).

The tax calculations are found at Components -‐> VirtueMart -‐> Products -‐> Tax & Calculation Rules.

VM Connector plugin settings:

You find the plugin in the group ‘configbox’ by the name ‘ConfigBox – VirtueMart Integration’. Ignore the settings for VirtueMart 1.1.x.

• VM Calculation ID: Enter the calculation ID set in the step before.

Date post:	24-Jun-2020
Category:	Documents
Upload:	others
View:	5 times
Download:	0 times

ConfigBox Manual 2.5-EN · 2015-10-09 · ConfigBox–)ShopManager)Manual) Version!2.5! ! Page!2!...

Documents