Shop Manager Manual ConfigBox 2.6 for Joomla

Transcription

1 Shop Manager Manual ConfigBox 2.6 for Joomla

2 Table of Contents 1 INTRODUCTION INSTALLATION 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 procedure Steps after installation Activation of Joomla plugins Customer group setup Setup of user group permissions 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 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 Ecommerce 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 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 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, ordering and shipping. 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 Pool roofing Boats Home appliances Support Elovaris Applications and a network of Solution Partners provide support for the setup of the application and development of extensions, customization and individual graphic design. Shop administration and data entry Product data entry is implemented for quick learning, user- friendliness and intuitive handling. This enables staff with minimal technical background knowledge to manage the application. Page 5

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 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? In most server setups, ioncube Loader is active for any folder on your web space, but in some you need to enable it for specific folders (usually by placing a php.ini file with loading instructions in the respective folders). If so, enable ioncube Loader for these folders: / (Joomla base folder) /administrator/ /components/com_configbox/ 2.2 Installation procedure Before you install or upgrade ConfigBox you must create a backup of your website 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. Page 6

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 Plugins that you install are disabled by default. Enable them using the Plugin Manager at Extensions. Click on the red symbol next to the newly installed plugins 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). Make sure that this group has permission to login to the site at Joomla - > Site - > Global Configuration - > Permissions. What is this meant for? ConfigBox does silent registration and creates a linked Joomla user account. The group information is used to set the correct Joomla user group for this user account. Page 7

8 2.3.3 Setup of user group permissions This is not needed for Joomla 1.5 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. 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. Allow Site Login for user groups associated with customer groups If you created multiple customer groups and associated them to other Joomla groups, you need to set the same permissions 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). Page 8

9 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. Page 9

10 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) 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. 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. 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 }?> 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. 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 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). 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 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: 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. 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 > 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. 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) 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. 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 Page 23

24 Configurator page display example 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 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. 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. 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). 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. 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) 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. 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 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. 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. Setup Google Analytics Web Tracking Google Analytics Ecommerce Tracking GA Ecommerce Tracking is integrated by default. You need to enable Ecommerce Tracking in your Google Analytics profile Setting. Setup Google Analytics Ecommerce Tracking on your web property s profile Page 34

35 When does tracking take place? Since GA Ecommerce 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. 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 Ecommerce Tracking limitation), distorting statistics to some extend. Page 35

36 4.8.3 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 Ecommerce Tracking (see Google Analytics Ecommerce 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 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. Page 36

37 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: precision- city- service 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. 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 earlier versions: 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 need to be avoided because they do not work when spanning 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). Location of the original template: /components/com_cbcheckout/views/quotation/tmpl/default.php 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). Page 38

39 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? 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. Typically the keyword is the uppercase form of the phrase in English but it may be different for technical reasons. 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. 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? The files are separated between ConfigBox and Order Management and between the Frontend (aka your store) and the Backend (aka the administration panel). Phrases may be present in multiple files. 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? Page 39

40 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++ ( plus- plus.org) 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 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. Page 40