ConfigBox 2.6 for Joomla

Transcription

1 Shop Manager Manual ConfigBox 2.6 for Joomla

2 Table of Contents 1 INTRODUCTION INSTALLATION/UPGRADE How to check if ioncube Loader is installed What to do if ioncube Loader is not installed In which folders do I need ioncube loader to be active? Installation/upgrade procedure Steps after installation Activation of Joomla plugins Customer group setup Setup of user group permissions Allow user registration Enter your business information Enter an address for notifications about reviews Check tax settings for your country Integration of ConfigBox in Joomla ConfigBox Menu Item Types Native SEF URLs CONFIGURATOR Basics Languages Product Listings Products Configurator Pages Elements Options and their assignment to elements Compatibility Rules Calculations Calculation using Matrices Calculation using a Formula Calculations using the Calculation Editor One-time Prices and Recurring Prices Product Visualization ORDER MANAGEMENT Cart page Control what a customer can do on the cart page Set the Continue Shopping listing Rovexo (formerly Elovaris Applications) Version 2.6 Last update: March 13, 2017 Page 2

3 4.2 Customer Data Customer Groups Associated platform group Tax display mode Control display of prices Discount levels Shipping Management Payment Methods Bundled connectors to online payment service providers Notifications Notification Snippets Invoices Invoice layout and content Configuration of Invoicing Google Analytics Tracking and Reporting Prerequisites Google Analytics E-commerce Tracking Use of Google Analytics goals Reviews Countries and Shipping Tax Handling for Cities and States Predefined Cities Using IP Geolocation to prefill customer data and other purposes CUSTOMIZING CONFIGBOX Custom Quotation PDFs Custom Wording and Translations Understanding the concept of language files Workflow to find and customize a phrase Custom Behavior of Elements Custom Fields Custom CSS styling Custom JavaScript Custom Templates Custom Templates for Specific Listings, Products, Pages and Elements Custom Connectors Custom Notification snippets Rovexo (formerly Elovaris Applications) Version 2.6 Last update: March 13, 2017 Page 3

4 6 NOTES FOR CONFIGBOX UPGRADES Upgrade from ConfigBox versions prior version TROUBLESHOOTING Pricing and Product Visualization does not update The installation failed and uninstallation is not possible Payment method changes are not effective Issues with SH404SEF An error message occurred after uploading a package EXTENSIONS VirtueMart Connector Rovexo (formerly Elovaris Applications) Version 2.6 Last update: March 13, 2017 Page 4

5 1 Introduction ConfigBox is a multi-functional Product Configurator integrated in Joomla with order and customer management and implements a complete order and RFQ process. ConfigBox is a flexible system capable of configuring 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. Types of products that are handled with ConfigBox (non-exhaustive) Cars and car equipment Printing products Phone carrier contracts Blinds and shades Computer systems Furniture Promotion equipment Analytical instruments Boats Shop administration and data maintenance The graphic interfaces for shop administration and data maintenance are designed for easy learnability and user-friendliness and suitable for typical back office staff. This manual describes everything that is needed for running the software. Rovexo (formerly Elovaris Applications) Version 2.6 Last update: March 13, 2017 Page 5

6 2 Installation/Upgrade 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 On Joomla 3.x: In the admin area, go to System -> 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 What to do if ioncube Loader is not installed Please refer to your hosting provider in order to get ioncube Loader installed In which folders do I need ioncube loader to be active? Some hosting providers have ioncube loader enabled only in certain folders. If that s your case, ask your hosting provider or system admin to make the loader enabled for these folders: / (Joomla root folder) /administrator/ /components/com_configbox/ 2.2 Installation/upgrade procedure We implore you to create a backup of your website s files and database before installation/upgrade! We test our installation packages a lot, but we cannot make the installer check for everything that could go wrong, so please fare with caution. 1) Pick the right installer packages from your download: From the ConfigBox website, you got a zip file with installation package files. Starting from ConfigBox the packages work for both installation and upgrade and you got a separate set of files for PHP 5.6 and lower and for PHP 5.6 and higher. Be sure to pick the right set. 2) Install all packages: Go to Extensions -> Manage -> Install and install the components first then the modules and plugins last. If you do an update, it is the same (never mind the wording in Joomla, on the Install page you also upgrade). 3) Activate the plugins: See for details. What s with Joomla s Extensions: Update page? Rovexo (formerly Elovaris Applications) Version 2.6 Last update: March 13, 2017 Page 6

7 Joomla introduced a nice automatic update mechanism, but it requires us to serve the ConfigBox packages freely over the internet. We can t do that so we stick with the traditional upgrade method. 2.3 Steps after installation Activation of Joomla plugins When you install a plugin, it will be disabled by default. Enable them using the Plugin Manager at Extensions. Search for ConfigBox to find them easily. Click on both the red symbols and you re done Customer group setup This is not needed for Joomla 1.5 Go to Settings -> Customer Groups -> Default Group and set a Joomla user group at Platform Group (save once if already filled out). When customers get a customer account, CB creates a Joomla user account. The group you pick will be their Joomla group. Pick a group with the right permission (use Public or Registered if you are not sure). Make sure that this group has permission to login to the site at Joomla -> System -> Global Configuration -> Permissions. See for details Setup of user group permissions This is not needed for Joomla 1.5 When a customer requests a quotation or buys something in the store, ConfigBox creates a customer account and a Joomla user account (and connects those). Customers will be able to log in using Joomla login forms or ConfigBox login forms. Since Joomla 2.5 a few settings are necessary to make all that work: Rovexo (formerly Elovaris Applications) Version 2.6 Last update: March 13, 2017 Page 7

8 Allow Site Login for the Joomla guest user group On Joomla 2.5 On Joomla 3.x At System -> 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. Allow Site Login for user groups associated with customer groups If you create multiple ConfigBox customer groups, be sure to do the same for the associated Joomla user group Allow user registration Go to System -> Global Configuration -> Users and set Allow User Registration to Yes and New User Account Activation to None. Rovexo (formerly Elovaris Applications) Version 2.6 Last update: March 13, 2017 Page 8

9 2.3.5 Enter your business information At Store Information you need to enter information related to your business. This information is used for quotation headers, invoices, payment service providers etc Enter an address for notifications about reviews To receive notification when a customer made a product review, enter an address at Settings -> Reviews Check tax settings for your country By default, Austria is assumed to be the store s country. VAT is charged for customers in Austria and customers from other EU countries are VAT free (unless they provide a VATIN). You can change this to work for your country, to do it go to Countries and Delivery -> Countries and change the settings for Austria and your country. 2.4 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). Rovexo (formerly Elovaris Applications) Version 2.6 Last update: March 13, 2017 Page 9

10 2.4.1 ConfigBox Menu Item Types ConfigBox Configurator Page A link to a configurator page of a product. 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. 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) Native SEF URLs ConfigBox uses the Joomla framework to create SEF URLs. The use of third party tools to manipulate URLs is not supported and we recommend disabling them for ConfigBox and Order Management pages. Important note: You need to enable Search Engine Friendly URLs in the Joomla Global Configuration to benefit from ConfigBox SEF URLs. How ConfigBox SEF-URLs are built ConfigBox analyses the menu item structure and determines the optimal SEF-URL for pages. In general it uses the most specific menu item. When two equally specific menu items are found, parent menu items of the current page are prioritized. In the following you see the order in which pages are checked. Product listings: Menu item of type Product Listing with a matching listing id Menu item of type Product Listing with no defined listing id Product Page: Menu item of type Product Page with a matching product id Menu item of type Product Listing that contains the product (product alias is appended) Menu item of type Product Listing with no defined listing id (product alias is appended) Configurator page: Menu item of type Configurator Page with a matching page id Menu item of type Configurator Page with a matching product id (page alias is appended) Menu item of type Product Page with a matching product id (page alias is appended) Menu item of type Product Listing that contains the product (product and page alias is appended) Menu item of type Product Listing with no defined listing id (product and page alias is appended) Rovexo (formerly Elovaris Applications) Version 2.6 Last update: March 13, 2017 Page 10

11 3 Configurator 3.1 Basics Languages To use multiple languages in the configurator, you need to have set content languages in Joomla (See Extensions -> Language Manager -> Tab Content. You then choose the languages to use in the configurator at ConfigBox -> Settings -> Languages. Step by step: Install the language pack in the Joomla language manager (Extensions -> Language Manager) Add the content language for this language (Extensions -> Language Manager > Content) Activate the language in ConfigBox (ConfigBox -> Settings -> Active Languages). Important: Make sure you have set the language tag correctly the first time in the Joomla language manager. Changing the language tag (e.g. en-gb, de-de etc.) later will make all translations in ConfigBox disappear since the tag connects the Joomla language with the ConfigBox language. ConfigBox has the languages German and English built in. You can add translations yourself; you find detailed information on how to do it in the chapter Adding a language Product Listings Product listings are used to display 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 Products You can set up products that are configurable or non-configurable. To have a non-configurable product, add it and do not add any configuration pages to it. You add or edit products in the product tree view on the left hand side of the admin area. You can expand each entry and you see links to add products, pages, elements and options. You can drag pages and elements to adjust ordering. Rovexo (formerly Elovaris Applications) Version 2.6 Last update: March 13, 2017 Page 11

12 Display -> Product Alias The product alias is used for SEF URLs (see section How ConfigBox generates SEF URLs ) and has to consist of characters that are valid for URLs (if you are unsure, use a-z, 0-9 and minus only) Base price and Base price recurring At this section 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 in 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 Product Description 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 Product detail panes With product detail panes you show product details segmented in a tabbed interface. You can choose to display the product details in product pages and configurator pages. Rovexo (formerly Elovaris Applications) Version 2.6 Last update: March 13, 2017 Page 12

13 Example product detail panes These are example product detail panes. Actual font-sizes, colors and box widths may vary and may be influenced by the website s styling. Listing of product detail panes in product data entry form Important note: If you just added a new product, save once before you add product detail panes. You can enter heading, an optional icon, CSS classes and HTML content. CSS classes enable web designers to set specific styling for headings and pane contents. Customization of product details location To change the area where product details are displayed, create/edit your custom product or configurator page template and add/move this snippet: <?php if ($this->showproductdetailpanes) {?> <div class="product-detail-panes-wrapper"><?php echo $this->productdetailpanes;?></div> <?php }?> Rovexo (formerly Elovaris Applications) Version 2.6 Last update: March 13, 2017 Page 13

14 Product Visualization If you like to show a product visualization in configurator pages, the cart, the PDF-quotation and order confirmation, set up the dimensions of the visualization. Visualization images of one product should have the same dimensions. Display of the visualization in configurator pages: In Joomla you use the module called ConfigBox Product Visualization (mod_configboximages) and position it at the Joomla template position of your choice. Alternatively you can use this snippet in configurator page templates: <?php $view = KenedoView::getView('ConfigboxViewBlockVisualization'); $view->display();?> Important Note: You need to set the dimensions of the product visualization in the product edit screen (section Product Visualization). Otherwise it will not be visible Selection overview on configurator pages The selection overview is the price module that you can show on configurator pages. It summarizes the configuration, shows pricing and taxes and can have cart and quotation request buttons. The overview is configurable. You have global settings in the settings page, and settings specific to a product in the product edit screen. Display of the selection overview in configurator pages: In Joomla you use the module called ConfigBox Selection Overview (mod_configboxprices) and position it in the Joomla template position of your choice. Alternatively you can use this snippet in custom templates for configurator pages (see Custom Templates for reference). <?php $view = KenedoView::getView('ConfigboxViewBlockPricing'); $view->display();?> Configurator Pages Note: Configurator pages were called Categories in previous versions of ConfigBox. Configuration pages enable you to create a configurator with multiple steps. If you only need one step, you just create one page Visualization View Keyword In Visualization View Keyword you enter a keyword, the same field is present at the option assignment and enables you to show different product visualizations on each page. Only visualization images that match the visualization view text of the configurator page are shown. If the field is empty, only the visualization images with empty fields are shown. In pages like the cart or PDF quotation, the images with an empty visualization view are used. Rovexo (formerly Elovaris Applications) Version 2.6 Last update: March 13, 2017 Page 14

15 Other settings 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 activate the option Finish button on last page only Elements You set up an element for each choice the customer shall make in the configurator. If the customer should make a choice from a set of predefined options, you assign options to the element (see bottom of the edit screen for reference). If the customer is supposed to make a yes/no choice, you can assign a single option to display a checkbox or simply have 2 options with yes and no as you see fit. Otherwise you can let the customer make a free entry. You can choose a between various widgets to make customer entries more practical (see Settings for Custom Entries for details) and set validation rules to restrict entries Settings for custom entries These settings only apply if your element has no assigned options. You can then use a widget for easier customer entry and set restrictions on what can be entered for this element. 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. Calculated Minimum and Maximum Values allow you to make the restrictions dynamic, based on the current configuration. Calculations are described in detail in the manual section Calculations Widgets for custom entries There are multiple widgets that replace the regular text field with a more practical input, depending on your use of the element: Regular text field or text area Calendar for date entries Slider for number entries File upload field with file validation Popup Picker The Popup Picker is advanced You enter an HTML table and 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 Rovexo (formerly Elovaris Applications) Version 2.6 Last update: March 13, 2017 Page 15

16 Price Calculation on Elements Important note: You cannot assign options to an element with assigned price calculations. If you need an element that only calculates a price without acting as a choice for the customer, then you disable Display element in configurator. The element will not be displayed as a typical choice, but it s title and price will be displayed in overviews. Setting up calculation models is described in the manual section Calculations. The price multiplicator is used to multiply the result of the price calculation. Using element price calculation is only one way to calculate pricing. You can also set price calculations for each the assigned option if it is more practical for your application Options and their assignment to elements Options are the choices that the customer has in an element. An option can be assigned to multiple elements in order to accommodate stores where options stand for specific stock items and redundant data entry should be avoided. Therefore when you assign an option to an element, you see a combined edit form for the data specific to this assignment (left side) and the option itself (right side). Rovexo (formerly Elovaris Applications) Version 2.6 Last update: March 13, 2017 Page 16

17 About using price calculations in option assignments Without a price calculation, the price set in the option is used. If you assign a price calculation, the option s price will be ignored. About Visualization settings in the option assignment The image you upload at Visualization -> Visualization Image will be added to the product visualization if the customer selects the option. To control the position in the visualization stack, enter a number at the field Visualization Stacking Order (higher numbers make the image stacked higher up). See section Product Visualization for reference With Visualization View Keyword you define which visualization images should be shown on a configurator page. This enables you to display multiple views in the configurator. The field is present in the configurator page and the option assignment data. Only images with matching keywords will be shown in the visualization. In the cart, PDF quotation and order pages the images with no keyword are shown. Compatibility Rules Rovexo (formerly Elovaris Applications) Version 2.6 Last update: March 13, 2017 Page 17

18 Compatibility rules enable you to set conditions that have to be met to show the option. See section Compatibility Rules for reference. 3.2 Compatibility Rules Compatibility rules enable you to set conditions for elements and options to be visible to the customer. The system evaluates the conditions each time the customer makes a selection and shows/hides immediately. You set or edit rule for an element or option by clicking on the button Open Rule Editor in Rule in their respective edit screens. You can choose if the elements and options should become hidden or just greyed out with the element setting Rule -> Hide if not applying. Standard options can be auto-selected once the element becomes active if you activate Rule -> Automatic Pre-selection and/or Rule -> Preselect any Option. You can choose if automatic changes (because of elements/options) need to be confirmed by the customer with the setting Rule -> Confirm automatic changes. You set the conditions of your rule with a visual drag and drop editor. Rule editor: Rovexo (formerly Elovaris Applications) Version 2.6 Last update: March 13, 2017 Page 18

19 1) Pick an element on the lower left side to see all available conditions regarding it. 2) Drag the condition you need up to the rule area on top 3) Most conditions have settings. You can click on the text is to change it to Is not or enter a value 4) Drag combinators like AND or OR to combine conditions 5) Shift-Select conditions in the rule area and click Put in Brackets to combine them as one condition (in order to improve clarity when conditions are combined with a mix of ORs and ANDs). 3.3 Calculations With calculation models you can implement complex pricing structures with no need for programming. Depending on the pricing logic of your products you see if price matrices, formulas, static option prices or a combination of all of them is most suitable. Calculations are also used for dynamic weight calculation of options and for dynamic validation of customer entries in elements. You can add and set calculation for each element or option assignment in the section Calculations and you can display a list of all calculations with the link Calculations in the side menu. There are different types of calculations that you can use as you see fit for your application: Matrix Formula Editor Formula Matrices is a classic price table and useful for calculating a price when it depends on the combination of two customer choices or entries. The Formula Editor enables you to create formulas with customer entries custom field data of selected options. It also enables you to incorporate results of other calculations. Formula is a text-based tool that enables you to create formulas that the editor cannot create. It is a tool that is tough to learn and manage, but may help you to push the envelope when you need it Calculation using Matrices With a calculation matrix, you choose 2 elements or calculations as the axis parameters. The customer s selection for each of the elements (or the result of the calculations) will be used to look up the values in the matrix and returned as the result of the calculation. Rovexo (formerly Elovaris Applications) Version 2.6 Last update: March 13, 2017 Page 19

20 Typical workflow: Add a calculation Choose Matrix as type Choose an element for columns and one for rows (or calculations) Pick the values for column and rows in the grey fields Enter the desired prices Add rows or columns if needed Save the model and assign it to the option assignment or element of your choice Advanced settings: Lookup Value: Typically you won t have a price for each possible customer input, but scaled prices. For this you can change the setting Lookup Value. Use next higher or next lower to lookup the appropriate price in the table. Round Values: If you like to have the user input values rounded you can do it with this setting. Round to 1 means round to integers. Round to 10 would mean rounding to full 10s (e.g. 15 -> 20). Multiplicator: You can provide a factor to multiply the result of the calculation. This is useful to add margins to supplier prices or similar. Element Value Multiplicator: Here you can choose an element whose value (the value provided by the customer) multiplies the result of the calculation. Calculated Multiplicator: This is the same as the other multiplicator, but the result of another calculation is used. 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. Rovexo (formerly Elovaris Applications) Version 2.6 Last update: March 13, 2017 Page 20

21 3.3.2 Calculation using a Formula Calculation formulas follow a similar pattern like the calculation tables, but here you can use a mathematical formula with placeholders for customer input and specific keywords to include many settings from elements and options in the formula. 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). Important note: Always pad a placeholder with a space (before and after), so that the formula can be parsed properly. Example formulas: ( A * B ) + C ElementAttribute(95.selectedOption.assignment_custom_1, 0) Rovexo (formerly Elovaris Applications) Version 2.6 Last update: March 13, 2017 Page 21

22 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. 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 built-in price engine to make even more sophisticated price calculation. See chapter Customizing ConfigBox and Order Management for more info Calculations using the Calculation Editor Setting up a calculation with the editor works similar to the rule editor. You have operators, numbers, element values, calculations and assorted functions to drag into the calculation area. The entries in the text fields after or (e.g. Entry in Height or..) are fall-back values that are used if no entry was provided. Make sure you use the fall-back whenever a division by zero could occur. 3.4 One-time Prices and Recurring Prices ConfigBox supports two sets of prices enabling you to offer products that have a one-time fee and a recurring fee (or either one of them). This enables you to offer products that for instance have a monthly price and a setup price. Rovexo (formerly Elovaris Applications) Version 2.6 Last update: March 13, 2017 Page 22

23 Typical use cases Rental offers Webhosting products Phone contracts Settings for one-time pricing and recurring pricing You can label each price type individually on a per-product basis and define an interval for the recurring payments. Product page example using one-time and recurring prices Pricing is displayed according Rovexo (formerly Elovaris Applications) Version 2.6 Last update: March 13, 2017 Page 23

24 Configurator page display example Rovexo (formerly Elovaris Applications) Version 2.6 Last update: March 13, 2017 Page 24

25 Selection overview using one-time and recurring prices and settings You can configure the selection overview for each product individually and set global defaults in the ConfigBox configuration. Cart page showing one-time and recurring prices 3.5 Product Visualization ConfigBox enables you to present your product visually and have real time updates of the visualization during a customer s configuration. Instead of providing images for each combination of the product, you Rovexo (formerly Elovaris Applications) Version 2.6 Last update: March 13, 2017 Page 25

26 can upload outtakes of the parts with transparent background, ConfigBox stacks those images to produce the product visualization. Display of the Configuration page You display the product visualization in the configuration page with the supplied Joomla module ConfigBox Product Visualization (mod_configboximages) which you can place in the template position of your choice. Important note: You need to set the dimensions of the product visualization at product in the section Product visualization. Adding an image to the visualization You upload images at the option assignment that represents the part in the field Visualization Image (see manual section Elements). With Visualization Stacking Order you define the position of the image in the stack. Rovexo (formerly Elovaris Applications) Version 2.6 Last update: March 13, 2017 Page 26

27 4 Order Management 4.1 Cart page Control what a customer can do on the cart page A customer can perform the following tasks on the cart Request a quotation Save an order Checkout an order Request assistance You can control which tasks are available to the customer for each customer group. You find the settings in Settings -> Customer Groups Set the Continue Shopping listing At the cart and thank you page the customer sees a Continue Shopping button, leading to a product listing of your choice. You can set the product listing at Settings -> Checkout. Rovexo (formerly Elovaris Applications) Version 2.6 Last update: March 13, 2017 Page 27

28 4.2 Customer Data You can control what data can be entered and which shall be mandatory in the various customer data entry forms. These are Customer profile data Form for quotation requests Form for storing cart contents Form for assistance requests Form for ecommerce checkouts At Customer Fields you set the fields that shall be displayed or being mandatory. Important Note: The billing fields First Name, Last Name, , Salutation and Country are required by the system and cannot be made optional or hidden. 4.3 Customer Groups You can manage customer groups as Settings -> Customer Groups and set a default group for new customers at Settings -> Checkout. With customer groups you can do the following: Control what a customer can see or do in the shop system Set volume discount levels Set which platform user group the group is associated with (that is the user group of your CMS or ecommerce system, so Joomla if you use ConfigBox for Joomla). Rovexo (formerly Elovaris Applications) Version 2.6 Last update: March 13, 2017 Page 28

29 4.3.1 Associated platform group (Not available in Joomla 1.5) You also associate the customer group with a platform user group. When a new customer account is created, a platform user is created as well and will be assigned to that group. Benefits You can use the platform s permission system to set permissions for actions in the CMS and other extensions that support ACL. Important note: On Joomla, you need to allow Site Login for any associated group at Site -> Configuration -> Permissions Tax display mode You can control the way taxes are handled throughout the system. There are 2 modes B2C Business to customer In the configurator, item prices are displayed net In order overviews, item prices are displayed net and taxes are stated before the total (Plus X% tax) B2B Business to business In the configurator, item prices are displayed net In order overviews, item prices are displayed net and taxes are stated after the total (including X% tax) Control display of prices You can hide prices in the configurator and cart page. Prices will still show in quotations, notifications (if order overviews are included) and checkout pages Discount levels For each group you can set discount levels for the products. You have 5 levels, each with a minimum order value and a discount percentage or fixed amount to subtract from the product value. If a discount applies, it will be shown in order overview pages. Important note: The discount rate needs to be a negative number. 4.4 Shipping Management ConfigBox automatically calculates shipping costs from the total weight of the order, shipping country and chosen shipper. Setup of zones At Countries and Shipping -> Shipping Zones you define zones and assign countries to these. You use these zones in shipping rates to enable you be able to use a single shipping rate for multiple countries that have the same shipping costs. Rovexo (formerly Elovaris Applications) Version 2.6 Last update: March 13, 2017 Page 29

30 4.5 Payment Methods ConfigBox ships with various connectors to online payment service providers (PSPs) and supports offline bank transaction (showing a thank-you-page with bank information) and orders with no immediate payment. In ConfigBox you add payment methods with various settings, choose the regarding PSP, click save, and configure the connector at the settings on the right Bundled connectors to online payment service providers Autorize.Net SIM (USA and Canada only) BillSAFE Invoice (Germany only) mpay24 Classic (Autria only) MultiSafepay Connect (Netherlands and international) Paymill REST API (International) PayPal Payments Standard (International) PostFinance Basic, Startup and Professional (Switzerland only) QuickPay (International) Sage Pay Server Integration (International) SOFORT Überweisung Classic (International) VRPAY Virtuell (Germany only) Rovexo (formerly Elovaris Applications) Version 2.6 Last update: March 13, 2017 Page 30

31 Wirecard Checkout Page (International) WorldPay Business Gateway (UK and international) Since the website URLs of the providers are liable to change, please use a search engine for info about the regarding PSP. If you are not sure you got the right PSP or product, please refer to customer support. We are striving to extend our selection of PSP integrations. If you require a specific PSP integration, please contact customer support with the company and product name of the PSP. This helps us prioritizing Notifications notifications are automatically sent when the status of an order changes. You define which notifications are sent to the customer and/or to the shop manager and which subject and content the should contain. Store manager s go to the address you set up at Store Information -> Sales. Enter an internal name and choose the order status on which the should be sent. Rovexo (formerly Elovaris Applications) Version 2.6 Last update: March 13, 2017 Page 31

32 Subject and HTML is the content of your . You find a list of available placeholders on the right side of the edit form. You find the same functionality for the shop-manager notification beneath the Customer settings. Since ConfigBox 2.4.0: With the placeholder {element_order_overview} you can display an overview of the order Notification Snippets With notification snippets, you can insert precompiled data in your notification text. You add the placeholders in curly brackets in the HTML. See {element_order_overview} or {element_store_information} for reference. Important note: To avoid layout problems in clients, place snippet placeholders in a <div> element. Select the placeholder and click Formats -> Blocks -> Div (see screenshot below). 4.7 Invoices Invoice layout and content At Store Information you can choose to define a custom invoice template (otherwise a template-based default invoice). You can insert customer and order data like in notifications. With the placeholder {orderitems} you insert the table with the order data Configuration of Invoicing Rovexo (formerly Elovaris Applications) Version 2.6 Last update: March 13, 2017 Page 32

33 In Settings -> Invoicing you can configure the way invoices shall be handled. With Send invoice activated, your customers get their PDF invoice per as soon as the invoice is released. Invoice generation If Automatic after clearance is activated, you release the invoice in the order detail page at Order Management -> Orders. The invoice will be available and downloadable by the customer in the customer profile page. If Automatic is activated, invoices are generated automatically once the status of the order is set to paid (manual status change or status change by automatic transaction feedback). If After manual download is activated, you upload a PDF in the order detail page. Rovexo (formerly Elovaris Applications) Version 2.6 Last update: March 13, 2017 Page 33

34 Example of the order detail page using `After manual download Invoice download link in customer profile page 4.8 Google Analytics Tracking and Reporting Prerequisites To use the Google Analytics integration features of ConfigBox, you need to have regular Google Analytics tracking code integrated in your website using the asynchronous syntax or (since ConfigBox ) Universal Analytics. For ConfigBox and earlier: Setup Asynchronous Google Analytics Web Tracking For ConfigBox and later: Setup Universal Analytics If you switch from Asynchronous to Universal Analytics tracking, you do not need to change settings in ConfigBox. Important note: We support E-commerce Tracking, but NOT Enhanced Ecommerce Tracking. Enable only Ecommerce Tracking. Rovexo (formerly Elovaris Applications) Version 2.6 Last update: March 13, 2017 Page 34

35 4.8.2 Google Analytics E-commerce Tracking GA E-commerce Tracking is integrated by default. You need to enable E-commerce Tracking in your Google Analytics profile Setting. Setup Google Analytics E-commerce Tracking on your web property s profile Important: Do not enable Enhanced E-commerce. It is not supported. When does tracking take place? Since GA E-commerce tracking relies on the customer to return to the shop after payment there is no guarantee that the tracking will take place. ConfigBox raises the probability by scheduling the tracking for the next visit to a ConfigBox shop page (given the customer logs in). There are 2 scenarios: Customer returns to the order page after payment: Tracking takes place immediately. Rovexo (formerly Elovaris Applications) Version 2.6 Last update: March 13, 2017 Page 35

36 Customer does not return after payment or the right order status is set manually: Tracking will be scheduled for the next time the customer visits and logs in. Caveat: The date of purchase will be the tracking date (GA E-commerce Tracking limitation), distorting statistics to some extend Use of Google Analytics goals If you set up a goal for analyzing conversion in Google Analytics, you can use event tracking as goal type. The goal value is the total payable amount (including merchandise price, shipping, payment fee and taxes; in case of deposit payment only the deposit payment is used). Important notes: Please note that only paid orders are tracked; e.g. orders with status change to ordered are not tracked. We plan to extend the goal integration to other order statuses in the future. Also the event is tracked on the same conditions as E-commerce Tracking (see Google Analytics E- commerce Tracking). Setup in Google Analytics Profile: Goal Type: Event Category: configbox_goals Action: order_payment Label: leave empty Value: leave empty Goal Value: Use the actual event value Always use that is equal to Rovexo (formerly Elovaris Applications) Version 2.6 Last update: March 13, 2017 Page 36

37 4.9 Reviews Customers can write reviews and set ratings on products and options. You enable or disable reviews globally at ConfigBox -> Configuration -> Reviews or enable or disable them for specific products or options at the product or option settings. New reviews are inactive initially and need to be approved. A notification on new reviews is dispatched to alert staff. At Settings -> Reviews you enter the notification address. At Reviews you have a list of all reviews where you can filter, approve and edit reviews Countries and Shipping Besides shipping management, in the screens for Countries and Shipping you set up all available countries, states, counties and cities. Countries and States are pre-filled out of the box, if you want to make the customer choose his county or have him select a city instead of entering the city name, you can add this information Tax Handling for Cities and States For each country (or state) you can define if VAT has to be charged (for countries you also define if it shall be charged only if a VAT-IN was supplied). In countries and states you can also OVERRIDE the tax rate for each tax class you have set up. In counties and cities you can enter a percentage that will be ADDED to the country/state tax rate. This accommodates the tax system for the United States, Canada and other countries. Please note that the individual taxes are not displayed separately, but as one compound tax rate Predefined Cities Adding cities at Countries and Shipping -> Cities forces the customer to select a city from a searchable drop-down list instead of letting him enter the city name in a text field. Cities are connected to counties, so you need to enter counties and their cities. Please note that you need to have a complete city list for a county, otherwise customers from other cities cannot order or request quotes. You can have a mix of counties with and without predefined cities. The forms will show the appropriate form field as the customer selects the county. Please note that IP Geolocation cannot determine the county in any case and cannot determine the city if you use predefined cities Using IP Geolocation to prefill customer data and other purposes ConfigBox enables you to have customer forms prefilled to the best extend possible. This feature covers RFQ forms, save order forms and the checkout. You need an account and a contingent for GeoIP2 Precision: City with MaxMind ( a trusted and industry-leading provider of IP-Geolocation data. As of the link to the purchase page is: You get a license key (in form of a text-code) by MaxMind. You enter it at ConfigBox -> Settings -> IP Geolocation Tracking -> MaxMind License Key, then activate the feature. Rovexo (formerly Elovaris Applications) Version 2.6 Last update: March 13, 2017 Page 37

38 5 Customizing ConfigBox Customization of ConfigBox is straightforward, well organized, requires no modification of the base software and enables you to make profound extensions and modifications to functionality of the software: Design of products and configurators Individual configurator designs for each product Output of custom, non-standard product data Modification and extension of the base functionality Customization of wording used in the application Translation in non-bundled languages Integration with third party software Important: Any customization you make or delegate needs to be checked for compatibility on software updates and revised if necessary. On minor software updates we make an effort to minimize breaking changes and if need be provide detailed information about them on our website (on the download page for each version). For major software updates (e.g. 2.6 to 2.7) you need to be prepared for a complete rewrite as worst-case scenario. 5.1 Custom Quotation PDFs Note for customers using custom quote PDFs in versions before 2.6: As opposed to earlier releases of ConfigBox, it is no longer necessary to override both PDF download and PDF attachment. You can override the output of quotation PDFs in the same way as other templates (see Custom Templates for reference). However, templates used for PDF generation are more delicate: The produced HTML and CSS needs to adhere strictly to HTML 1.1 strict and CSS level 3. Using CSS float is not supported Nested tables (<table> within a <table>) need to be avoided because you get bad results if the either table spans over multiple pages. In case your customizations have led to a sizable custom CSS file, consider creating a separate stylesheet for the quotation PDF for performance reasons (set the URL to that stylesheet in the <head> block). Since ConfigBox we moved the header/footer PHP to a separate template file (header_footer) for easier customization. If you override something and don t need changes to the header/footer, simply don t copy the header_footer.php template to your customization folder. The system will load the original template then. Mind that if you want to adjust page margins, set margins on the <body> tag. This is the reliable way to have margins set on each PDF page. Since there are CSS classes on the <body> tag (body-pdf and a class for each type body-pdf-quotation, body-pdf-invoice and body-pdf-orderslip). Do margin styling on these classes to avoid changing <body> styling on normal website pages. Location of the original template: /components/com_cbcheckout/views/quotation/tmpl/default.php Rovexo (formerly Elovaris Applications) Version 2.6 Last update: March 13, 2017 Page 38

39 Location of the custom template: /components/com_configbox/data/customization/templates/quotation/default.php The template uses output of other views The template uses the output of other views (namely record and positions from com_cbcheckout. If you need to alter this part of the quotation, you can make overrides of these templates, but be mindful about the fact that these views are used elsewhere (admin order page, user order page, checkout page and possible more in the future). 5.2 Custom Wording and Translations Customizing wording is rather easy. You need to come prepared with knowledge on editing files on your web server and on editing plain text files with a specific encoding (UTF-8). The latter is explained later in this section Understanding the concept of language files How wording and translation is handled in ConfigBox Texts you see on the pages handled by ConfigBox are customizable. To accomplish this, the software uses plain text files called system language files to find and output the right phrase in the right language. On top of system language files, the system looks for custom language files that you can use to customize specific phrases. These files can also be used to add a new translation of ConfigBox or to translate texts that you have in custom templates. How does a language file look like? Language files are the same as the Joomla framework (.ini files) A typical line in a language file looks like this: REQUEST QUOTATION="Angebot anfordern" On the left in uppercase you see the keyword of the phrase the system looks for. On the right within double quotes you see the phrase that the system will display. You will see code like this in the built-in templates and other source code files: <?php echo KText::_("Request Quotation");?> Nevermind that the parameter in the code example isn t uppercase. While the keyword in the.ini file must be uppercase, the parameter for KText::_() can be mixed case. Locations of system language files /components/com_configbox/language/en-gb/configbox_frontend.ini /components/com_configbox/language/en-gb/configbox_backend.ini /components/com_cbcheckout/language/en-gb/cbcheckout_frontend.ini /components/com_cbcheckout/language/en-gb/cbcheckout_backend.ini Note: There are additional language files. You can ignore them because they are not relevant for understanding the concept. Rovexo (formerly Elovaris Applications) Version 2.6 Last update: March 13, 2017 Page 39

40 Locations of custom language files /components/com_configbox/data/customization/language_overrides/en-gb/configbox_frontend.ini /components/com_configbox/data/customization/language_overrides/en-gb/configbox_backend.ini /components/com_configbox/data/customization/language_overrides/en-gb/cbcheckout_frontend.ini /components/com_configbox/data/customization/language_overrides/en-gb/cbcheckout_backend.ini Note: Custom language files are stored together in the one folder. How to figure out which language file contains the phrase I search for? You may have trouble figuring out if you need the cbcheckout_frontend or the configbox_frontend override file. If the phrase is on the cart page or a page before that, expect it to be in configbox_frontend.ini Otherwise expect the phrase to be in cbcheckout_frontend.ini. Exception: Phrases on the RFQ/save/login forms belong to it as well. Which editor should I use to edit custom language files? Files need to be saved as plain text with UTF-8 encoding (no BOM) and only use regular double quotes (like this: ") for wrapping phrases. If you are not sure what that means, take the safe route and use one of these editors with default settings: Windows: Notepad++ ( Mac OS X: TextWrangler ( Workflow to find and customize a phrase Search for the phrase in the system language files of the right language Copy the line to the corresponding custom language file and change the phrase (a phrase may appear in multiple files, in that case, copy each of them to avoid complicated situations) Notes: The keyword must remain unaltered and make sure to have your phrase wrapped in double quotes. Do not put line breaks in your phrases, if you need one, add \n or <br /> If you need double quotes in your phrase, write them as \" When changing phrases in English, you may not always find the phrase in the system language files. That is because the English language files only contain phrases if the keyword differs from the phrase. In that case you can expect the keyword to be the uppercase form of the phrase. Example: The phrase Select Product is done like this: SELECT PRODUCT="Your own wording" Phrases may change in major software updates without notice. It is up to you to check and revise your customizations if necessary. 5.3 Custom Behavior of Elements Working with custom element classes requires a seasoned PHP developer and a proper local development site is recommended. We offer workshops to get your development team up to speed. Please contact customer support for pricing and scheduling. Using the element class API you can implement specific functionality in your configurator. For instance: Determine pricing with your own PHP code; e.g. fetch pricing from external data sources Store configuration element values in other systems Rovexo (formerly Elovaris Applications) Version 2.6 Last update: March 13, 2017 Page 40

41 How is the element class API used? You add PHP files with classes that extend the original ConfigBox element class ConfigBoxElement (the source code file is located in components/com_configbox/classes/element.php). The methods of that class return pricing, the element s HTML output on configurator pages, selection overview blocks and the cart page and store selections made by the customer. After you added a class file, you can select the element class in the element s edit-screen. The element class file name and the PHP class name follow a naming convention. The files are stored in ConfigBox data folder to avoid overwriting on updates. File folder and naming convention: Base folder: components/com_configbox/data/customization/element_classes Each element class has a sub-folder. In it you put the PHP class file with the same name. Example for element class name upload : PHP class name: ConfigboxElementUpload File system path: components/com_configbox/data/customization/element_classes/upload/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 current system default has to be used (use the value of constant CONFIGBOX_SHOW_NET_PRICES), if parameter 2 is missing, then false is assumed. getpricerecurring($getnetprice, $getinbasecurrency) Analogue to getprice(), but used for the recurring price. loadtemplate() Use this method to output your own HTML instead of the default HTML output of the element in configurator pages. The implementation of this method writes the frontend HTML output of the element in the configurator into the output buffer. 5.4 Custom Fields Products, elements, options and option assignments have 4 to 6 custom fields you can use to enter any kind of additional. The purpose of these fields is not specific. Typical useful applications are: Usage in price calculations (see onscreen-help for detailed info) Usage in compatibility rules Usage in custom templates or element classes for output or applying custom logic Usage in connectors for integration with third party software For practical reasons, you can set your own labels of these fields in Settings -> Custom Fields. 5.5 Custom CSS styling Customizing CSS styling requires basic to moderate HTML and CSS skills. Custom styling can either be sufficient to amend styling of the shop or be used in combination with customized templates. Rovexo (formerly Elovaris Applications) Version 2.6 Last update: March 13, 2017 Page 41

42 ConfigBox comes with a style sheet specifically made for styling customizations. As all files in the customization folder, it is not overwritten during software updates. Location: /components/com_configbox/data/customization/style_overrides/css/style_overrides.css Tips: Use conventions for rule selectors When looking at one of the style sheets, you see that most CSS selectors start with #com_configbox #view-x or #com_cbcheckout #view-x with x standing for the view s name. While barely avoidable anyways, we recommend you adopt that convention for your customizations. It makes it immediately clear what you intend to change and it avoids unwanted changes on other page types. 5.6 Custom JavaScript Custom JavaScript requires basic to moderate HTML/JS skills. Custom JavaScript can be useful in combination with custom templates. Location: /components/com_configbox/data/customization/style_overrides/javascript/extra_functionality.js Tips: You have jquery available You can use jquery with cbj in the global scope. Mind that the jquery version may change with any software update. 5.7 Custom Templates Customizing templates requires moderate PHP programming skills and related skills like HTML/JS/CSS (plus/minus depending on the kind of customization you need). ConfigBox is organized in page types (e.g. product listing, cart, checkout, admin order page etc.) and each page type makes use of a view (or multiple views). Each view has a template file (or multiple ones) responsible for output in the browser and these template files can be customized. Important: As with any customization, custom templates may need to be checked and changed for compatibility on software updates. On the download page you find detailed information on breaking changes for each software update. Notes if you are familiar with Joomla s MVC and template override system: Our concept is similar and practically transparent to the way Joomla handles views and templates. The difference is that overrides are not searched for in the Joomla template folder, but in ConfigBox s data folder (location see later in this section) and that view functions (like Class::loadTemplate()) are named and behave differently. Understanding the concept of template customization In /components/com_configbox/views you find sub-folders for each view that ConfigBox uses for displaying pages. This is called a view folder. Each view folder contains a PHP file called view.html.php (or view.raw.php in some cases) that handles preparation of the data that is used for displaying content. Rovexo (formerly Elovaris Applications) Version 2.6 Last update: March 13, 2017 Page 42

43 Each view folder also contains a sub-folder called tmpl that contains a template file that is typically named default.php. The HTML produced in this template file is what you are going to see as content on your page. Some views split the content into multiple template files when it is more practical and use the output of other views within their template files when it makes sense. An example of this is the quotation view where order record information and position details come from the views record and positions. Workflow for overriding a template file 1) First you locate the view for which you want to make a customization. Take the cart as example: /components/com_configbox/views/cart The cart view uses a single template file, named default.php (Future releases may have it split in multiple template files). Download or copy the template file, you typically want to use it as base of your customization. 2) Navigate to the folder for customized templates. The location is: /components/com_configbox/data/customization/templates/ 3) In this folder you create a folder with the name of the view you like to override: /components/com_configbox/data/customization/templates/cart 4) In this folder, you place the template file you like to override. Mind that you do not create the subfolder tmpl like you have it in the view folder. /components/com_configbox/data/customization/templates/cart/default.php 5) You then make your customizations to that file as you see fit. Tips: ConfigBox consists of two components (com_configbox and com_cbcheckout) This means that you find views in /components/com_cbcheckout/views as well. The system for overriding is the same. But the custom templates are in the same folder as for com_configbox. In views with multiple template files, you can choose which ones to customize If you override only certain template files, the others will be loaded from the original view folder. This helps minimizing your efforts in case of breaking changes in software updates. Avoid CSS styling, adding images in places other than the customization folder Have a look at the chapter on custom CSS styling. You also have an image folder in your customization folder. This helps keeping your work well organized and quick to comprehend for colleagues and service providers. Make use of custom fields See section on custom fields for reference. You can access the data of these fields in the appropriate templates and use them for output, calculations or other logic. See tip on investigating template data for the best way to see where the data is stored. For multilingual sites, check the chapter on custom wording The software has an engine to make translated texts straightforward. Managing translated phrases is explained in that chapter. To make use of it for your own wording, you have a static PHP class method to output your translated phrases. Rovexo (formerly Elovaris Applications) Version 2.6 Last update: March 13, 2017 Page 43

44 Example: (Obviously, this code snippet needs to be placed within PHP tags). echo KText::_('Your phrase'); The phrase you use here must match the keyword used in your custom language file. So the line in your language file would look like this: YOUR PHRASE="Your translation of the phrase" Investigating data provided in the template files There is a very useful Joomla extension that lets you output the data of any variable in a browser popup. It is called JDump and can be found in the JED: Example (Obviously the variable used here must exist and the call be placed in PHP tags): dump($this->elements); Make use of the log files for debugging ConfigBox logs errors and other things extensively. The log files can be useful in case you work directly on a webserver and do not have access to the server s error log. Logs are located in your website s log folder in a sub-folder called configbox. You may see plenty of messages in some error log files. 5.8 Custom Templates for Specific Listings, Products, Pages and Elements This section is about the template editor that is essentially a graphic interface for creating custom template files with some extras. Conveniently add or modify template files in the admin area Create template files for specific products, configurator pages or elements. In the edit forms of the corresponding types you can assign the template using the field Template. Rovexo (formerly Elovaris Applications) Version 2.6 Last update: March 13, 2017 Page 44

45 Edit form for templates You edit templates using code coloring and formatting and you can also edit these files on the file system. 5.9 Custom Connectors What are connectors for? Connectors are used to integrate third party software with ConfigBox to extend or replace functionality. Example tasks: Process an order an bring the customer to a custom cart page Checkout a cart Create a quotation file Perform actions on order status changes What are connectors technically? A connector is basically a PHP file containing a PHP class with a set of methods. ConfigBox calls these methods (if they exist) and provide standardized data as parameter to perform various processes. This is done using the observer pattern. Depending on the nature of the task the system calls only the first connector or all connectors. Example connector: /components/com_configbox/observers/cbcheckout.php How to manage connectors Rovexo (formerly Elovaris Applications) Version 2.6 Last update: March 13, 2017 Page 45

46 ConfigBox -> Settings -> Connectors: Here you can enable or disable connectors and add or remove them. Adding a connector After clicking add you enter name of the connector, the settings and provide the file. Enter the form as per installation instructions of the connector provider. How to develop a connector First you pick a name for your connector. In this example we use ecomsystem. Create a PHP file with a PHP class called ObserverEcomsystem. <?php class ObserverEcomsystem { } Save the file and add it as connector (see 6.8.3). Custom connectors are stored in this path: /components/com_configbox/data/customization/custom_observers Connector to place a configured product in a third party ecommerce cart Add the method onconfigboxaddtocart with one parameter (passed by reference). function onconfigboxaddtocart(&$grandorderdetails) { // Code to add product to shop system } $grandorderdetails->redirecturl = 'URL TO THIRD PARTY CART'; return true; Rovexo (formerly Elovaris Applications) Version 2.6 Last update: March 13, 2017 Page 46

47 About $grandorderdetails The parameter $grandorderdetails is a PHP object containing the information of the current cart and all positions in it. Use var_dump(), print_r() or dump() (install JDump from the JED) to see the structure and data of the object. About $grandorderdetails->redirecturl Set the member redirecturl to the URL of your ecommerce system s cart page. ConfigBox reads this member and redirects the customer to the given URL (can be a complete URL or a relative/absolute URI). Connector to place ConfigBox cart contents in a third party ecommerce checkout page The same procedure applies as for onconfigboxaddtocart, the method name for this is onconfigboxcheckout. function onconfigboxcheckout(&$orderdetails) { // Code to add product to shop system } $orderdetails->redirecturl = 'URL TO THIRD PARTY CHECKOUT PAGE'; return true; 5.10 Custom Notification snippets You can add custom notification snippets to output custom data in your notifications. A snippet is a simple PHP file that is included and the buffer output generated will be inserted where the placeholder is set. Location of the custom snippet folder /components /com_configbox/data/customization/notification_snippets In ConfigBox and earlier: /components/com_cbcheckout/data/notification_elements/ Snippet and file name convention Say you call your snippet customsnippet. The file name has to be called customsnippet.html.php, the placeholder {element_customsnippet}. Data available in the snippet file $orderrecord Object holding all order data (see $orderrecord->orderaddress for order customer data) $shopdata Object holding the shop data Helpful tips See the code for the order overview for reference in /components/com_configbox/observers/notifications/elements/order_overview.html.php There is a very useful Joomla extension that lets you output the data of any variable in a tree structure in a popup. It is called JDump and can be found in the JED: Example call: Rovexo (formerly Elovaris Applications) Version 2.6 Last update: March 13, 2017 Page 47

48 dump($orderrecord); 6 Notes for ConfigBox upgrades Please check the compatibility notes at the download pages on for notes on compatibility on custom templates. 6.1 Upgrade from ConfigBox versions prior version 2.2 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 configurator page by creating a "Configurator page" menu item with fitting parameters for product and configurator page. If you do not need this fine-grained control over your module display, you can still use a menu item with product and configurator page unset. 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 Troubleshooting Always check if you read and followed the instructions in the section Installation and the section ConfigBox upgrades. 7.1 Pricing and Product Visualization does not update Checklist: Page Caching plugins are active on configurator pages Page caching plugins like Yot-Cache or JoomlArt T3 Template Caches and others prevent ConfigBox from preparing configurations before displaying the configurator page. Solution: Deactivate the caching in general or disable it for the components com_configbox and com_cbcheckout. Rovexo (formerly Elovaris Applications) Version 2.6 Last update: March 13, 2017 Page 48

49 Links and buttons do not redirect to the intended page Third party SEF-URLs like AceSEF, SH404SEF and others manipulate URLs that can lead to incorrect redirections. Solution: Fine tune the SEF tool or disable these tools for the components com_configbox and com_cbcheckout. Admin Tools do not allow direct access to components/com_configbox/configbox.php There is an extension called Admin Tools that creates restrictions for improved security. You need to set up an exception that allows direct access to the mentioned file (Configurator updates to directly to the component instead of through Joomla because of significant performance improvement). Solution: Go to Components -> Admin Tools ->.htaccess Maker -> Exceptions and add this line to the field Allow direct access, including.php files, to these directories : components/com_configbox IonCube Loader is only active for certain directories Solution: See the chapter on Installation -> IonCube Loader on how to set up ioncube Loader correctly. 7.2 The installation failed and uninstallation 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 7.3 Payment method changes are not effective When an order is checked out, ConfigBox creates a copy of all payment method settings for that order. If you make changes to the payment methods you won t see those changes in an already checked out order. Check out a new order to see the current setup. 7.4 Issues with SH404SEF If you got issues with SEF URLs on ConfigBox and Order Management pages, configure SH404SEF like this: Go to Components -> SH404SEF -> Configuration (top right corner) -> General -> By component Rovexo (formerly Elovaris Applications) Version 2.6 Last update: March 13, 2017 Page 49

50 For cbcheckout and configbox, use the settings Use Joomla router, Translate URL, Insert language code, Use Joomla router, Disable shurl (see screenshot for reference) In order to use SEF URLs for ConfigBox pages, use the Joomla native SEF techniques. Create menu items for product listings, cart page etc. 7.5 An error message occurred after uploading a package Check the following things: Make sure your folder for temporary files is correct and writable (Joomla global configuration) Make sure the target folders are writable (e.g. components, modules, plugins/*, administrator/components) Make sure your webserver allows upload of bigger files (see php.ini settings post_max_size and upload_max_filesize). Use a setting bigger than the regarding package size. Check for any warnings on the Joomla extension manager page. Rovexo (formerly Elovaris Applications) Version 2.6 Last update: March 13, 2017 Page 50