ConfigBox 3.1 for Joomla

Transcription

1 Shop Manager Manual ConfigBox 3.1 for Joomla

2 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 Questions Predefined Answers and their assignment to questions Compatibility Rules Calculations Calculation using Matrices Calculation using Code Calculations using the Formula 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 Customer Data Customer Groups Associated platform group Version Rovexo Last update: January 28, 2018 Page 2

3 4.3.2 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 Settings 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 Fields Custom CSS styling Custom JavaScript Custom Templates Custom Templates for Specific Listings, Products, Pages and Questions Custom Connectors Custom Notification snippets Custom Rule Conditions How to develop a custom rule condition What is Condition Data? NOTES FOR CONFIGBOX UPGRADES Version Rovexo Last update: January 28, 2018 Page 3

4 6.1 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 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 Rovexo 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. Version Rovexo Last update: January 28, 2018 Page 4

5 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 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. Version Rovexo Last update: January 28, 2018 Page 5

6 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 from Rovexo. 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 Rovexo. 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 Setup of user group permissions Joomla group permissions are used to allow or display certain tasks or features. After installation, your public group has no permissions for any of these tasks, you need to set these manually. Version Rovexo Last update: January 28, 2018 Page 6

7 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, Germany is assumed to be the store s country. VAT is charged for customers in Germany 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. For EU VAT rules on Electronic Goods and Services be sure to make tax classes in Settings, assign your electronic goods and services products to that group and set the right tax class in the individual countries. 2.4 Integration of ConfigBox in Joomla To display ConfigBox pages on your website, you use menu items just as any other component. Version Rovexo Last update: January 28, 2018 Page 7

8 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) 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. Version Rovexo Last update: January 28, 2018 Page 8

9 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) Version Rovexo Last update: January 28, 2018 Page 9

10 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, questions and answers. You can drag pages and questions to adjust ordering. Version Rovexo Last update: January 28, 2018 Page 10

11 Others -> Product SEF Segment The product SEF segment (prev. called 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. When you use recurring payments, then with the 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. Version Rovexo Last update: January 28, 2018 Page 11

12 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 }?> Version Rovexo Last update: January 28, 2018 Page 12

13 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 Questions You set up a question for each choice the customer shall make in the configurator. You can choose if the customer needs to answer and set rules for each question and answers to control what questions the customer will see and which answers will be available to him. Version Rovexo Last update: January 28, 2018 Page 13

14 3.1.6 Predefined Answers and their assignment to questions Typically you assign answers that are specific to a question. But in case you have a larger catalogue and some answers repeat themselves you can reuse answers across questions and across products. Mind the dropdown on the top left at Answer. When you add an answer to a question you can here pick an existing answer and when you do, all data on the left-hand side of the form will be shared across the catalogue. A change in one of these answers will be reflected in all of them. Version Rovexo Last update: January 28, 2018 Page 14

15 About using price calculations in answers Without a price calculation, the static price (see field in the left-hand side) is used. If you assign a price calculation, that static price will be ignored and the calculation result will be used instead. About Visualization Mind that you don t see visualization settings in the answers if you haven t enabled Visualization in your product. The image you upload at Visualization -> Visualization Image will be added to the product visualization if the customer selects the answer. 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 Rules Compatibility rules enable you to set conditions that must be met to show the answer. See section Compatibility Rules for reference. 3.2 Compatibility Rules Compatibility rules enable you to set conditions in questions and answers that must be fulfilled before the question/answer becomes visible to the customer. The system evaluates the conditions each time the customer answers a question or changes an answer. You set or edit a rule in each question and answer edit screen and choose behavior for various situations. For questions and answers you choose if the question (or answer) shall be hidden or greyed out while not applying. In the question edit screen you can choose what shall happen when the customer s current selection becomes impossible (deselect, find alternative, alert the customer or not). You set the conditions of your rule with a visual drag and drop editor. Version Rovexo Last update: January 28, 2018 Page 15

16 Rule editor: 1) Pick a question 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 on precedence in processing the logic). 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 answer prices or a combination of all of them is most suitable. Calculations are also used for dynamic weight calculation of answers and for dynamic validation of customer entries in questions. You can add and set calculation for each question or answer 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 Code Matrix is a classic price table and useful for calculating a price that depends on the combination of two customer choices. Version Rovexo Last update: January 28, 2018 Page 16

17 The Formula enables you to create formulas with customer entries custom field data of selected answers. It also enables you to incorporate results of other calculations. Code 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 questions or calculations as the axis parameters. The customer s selection for each of the questions (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. Typical workflow: Add a calculation Choose Matrix as type Choose a question for columns and a question 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 answer or question of your choice Advanced settings: Version Rovexo Last update: January 28, 2018 Page 17

18 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 to: 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). Multiplier: You can provide a factor to multiply the result of the calculation. This is useful to add margins to supplier prices or similar. Question Value Multiplier: Here you can choose an question whose value (the value provided by the customer) multiplies the result of the calculation. Calculated Multiplier: This is the same as the other multiplier, but the result of another calculation is used. Note: Be sure to set validation on the questions you use in calculations. ConfigBox automatically deals with decimal symbols from different languages Calculation using Code 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 questions and answers in the formula. Version Rovexo Last update: January 28, 2018 Page 18

19 After adding a new calculation, select the type Code 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 question (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) 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 question and its assigned aswers. E.g. use ElementAttribute(10.selectionPrice) to get the current price for the question with ID 10. You can look up question IDs at the question list screen or at the placeholder dropdowns. You can also enter PHP code to make more complex calculations here Calculations using the Formula Editor The formula editor lets you create easy and complex formulas using drag and drop. You have operators, numbers, question 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 Version Rovexo Last update: January 28, 2018 Page 19

20 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. Enable recurring pricing in a product at Others Typical use cases Rental offers Webhosting products Phone contracts Settings recurring pricing You can label each price type individually on a per-product basis and define an interval for the recurring payments. Version Rovexo Last update: January 28, 2018 Page 20

21 Product list item example using one-time and recurring prices Configurator page display example with recurring pricing Version Rovexo Last update: January 28, 2018 Page 21

22 Selection overview settings with recurring payment (in product edit screen) Example selections overview (with recurring pricing part in full details and one-time price just total): You can configure the selection overview for each product individually and set global defaults in the ConfigBox configuration. Version Rovexo Last update: January 28, 2018 Page 22

23 Cart page showing one-time and recurring prices Detail modal window: 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 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 in your answers at Visualization Image (see manual section Questions). With Visualization Stacking Order you define the position of the image in the stack. Version Rovexo Last update: January 28, 2018 Page 23

24 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 Version Rovexo Last update: January 28, 2018 Page 24

25 Save an order Checkout an order 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. 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. Version Rovexo Last update: January 28, 2018 Page 25

26 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) Associated platform group 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. Version Rovexo Last update: January 28, 2018 Page 26

27 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. Version Rovexo Last update: January 28, 2018 Page 27

28 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) Version Rovexo Last update: January 28, 2018 Page 28

29 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. Note: Below to Customer` there is another section ` to Shop Manager` Enter an internal name and choose the order status on which the should be sent. 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. With the placeholder {element_order_overview} you can display an overview of the order. Version Rovexo Last update: January 28, 2018 Page 29

30 4.6.1 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. See the manual section con custom Notification Snippets on how to make your own! 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 Settings There are various ways on how CB handles invoicing. See the settings page in the CB backend at Invoicing. Version Rovexo Last update: January 28, 2018 Page 30

31 With Send invoice via activated, your customers get their PDF invoice per as soon as the invoice is released. Invoice generation If Automatic after clearance is activated, the invoice will be auto-generated but you choose the moment manually(in the order detail page Orders). The invoice will be available and downloadable by the customer in the customer profile page. If Automatic is activated, invoices are auto-generated and sent automatically once the status of the order is set to paid (either from the PSP during checkout or manually by you changing the order status). If After manual download is activated, you upload your own PDF in the order detail page. Example of the order detail page using `After manual download 4.8 Google Analytics Tracking and Reporting Prerequisites To use the Google Analytics integration features of ConfigBox, you need to have Google Universal Analytics tracking code integrated in your website. Setup Google Analytics Web Tracking Google Analytics E-commerce Tracking Google Analytics 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 Version Rovexo Last update: January 28, 2018 Page 31

32 When does tracking take place? Since Google Analytics 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. 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). Version Rovexo Last update: January 28, 2018 Page 32

33 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 4.9 Reviews Customers can write reviews and set ratings on products. You enable or disable reviews globally at ConfigBox -> Configuration -> Reviews or enable or disable them for specific products at the product edit screen. 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. Version Rovexo Last update: January 28, 2018 Page 33

34 4.10 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. 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 Version Rovexo Last update: January 28, 2018 Page 34

35 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. Customization folder: /components/com_configbox/data/customization/ 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 (<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-pdforderslip). Do margin styling on these classes to avoid changing <body> styling on normal website pages. Location of the original template: /components/com_configbox/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 Version Rovexo Last update: January 28, 2018 Page 35

36 The template uses the output of other views (namely record and positions. 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? 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/ frontend.ini /components/com_configbox/language/en-gb/ 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/overrides.ini Note: Overrides affect both frontend and backend. How to figure out which language file contains the phrase I search for? Any phase that is used in both backend and frontend is in frontend.ini backend only phrases are in backend. Best simply search first in in frontend, then in backend. 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. Version Rovexo Last update: January 28, 2018 Page 36

37 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 Fields Products, questions and answers 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 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.4 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. 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 with x standing for the view s name. While barely avoidable anyways, we recommend you Version Rovexo Last update: January 28, 2018 Page 37

38 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.5 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/custom.js Tips: We use AMD modules using requirejs. We use our own context ( CB ). You got cbrequire available in the global scope to get modules. We register cbj as jquery module (which is independent from whatever jquery you may have in the global scope). 5.6 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 that handles preparation of the data that is used for displaying content. 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: Version Rovexo Last update: January 28, 2018 Page 38

39 /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: 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. 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: Version Rovexo Last update: January 28, 2018 Page 39

40 Example (Obviously the variable used here must exist and the call be placed in PHP tags): dump($this->questions); 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.7 Custom Templates for Specific Listings, Products, Pages and Questions 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 questions. In the edit forms of the corresponding types you can assign the template using the field Template. Version Rovexo Last update: January 28, 2018 Page 40

41 Edit form for templates You edit templates using code coloring and formatting and you can also edit these files on the file system. 5.8 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/orders.php How to manage connectors ConfigBox -> Settings -> Connectors: Version Rovexo Last update: January 28, 2018 Page 41

42 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). Version Rovexo Last update: January 28, 2018 Page 42

43 function onconfigboxaddtocart(&$cartdetails) { // Code to add product to shop system } $grandorderdetails->redirecturl = 'URL TO THIRD PARTY CART'; return true; About $cartdetails The parameter $cartdetails 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 $cartdetails->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(&$cartdetails) { // Code to add product to shop system } $orderdetails->redirecturl = 'URL TO THIRD PARTY CHECKOUT PAGE'; return true; 5.9 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 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 Version Rovexo Last update: January 28, 2018 Page 43

44 /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: dump($orderrecord); 5.10 Custom Rule Conditions You can develop custom rule conditions. Developing these requires adept programming skills. Rovexo provides no free support or problem analysis for custom rule conditions How to develop a custom rule condition You develop a rule condition type and set up a list of conditions of that type. It is similar to the example conditions you see in the rule editor. These serve no actual purpose, but illustrate how it is done. You add a PHP class in the folder for custom rule conditions. The folder is in the customization folder in /rule_condition_types/ You pick a name for your condition type (like Example ). The PHP class needs to be called CustomCondition followed by your type name. So for type Example you got CustomConditionExample. The file name is called the same (CustomConditionExample.php). The class extends ConfigboxCondition. So you got class CustomConditionExample extends ConfigboxCondition. There are a few methods that need to be implemented. CustomConditionExample::getConditionsPanelHtml() CustomConditionExample::getConditionHtml($conditionData, $forediting = true) CustomConditionExample::getEvaluationResult($conditionData, $selections) getconditionspanelhtml() Each type gets a panel in the rule editor. This method returns the HTML to use for it. It essentially contains a list of conditions (the HTML of each condition has a certain structure, you will see more about it in the method getconditionhtml(). Version Rovexo Last update: January 28, 2018 Page 44

45 getconditionhtml($conditiondata, $forediting = true) This method takes the condition s data as parameter and returns the HTML for the condition. You see an example of the HTML in Example s PHP class, method CustomConditionExample::readMe(). The gist of it is that each condition is wrapped in a <span> Element with HTML 5 data attributes containing the condition s data. In the <span> is a human-readable name of the condition, the operator to choose from and a text field for the set point, the value the thing you test for should have. Those text fields have the CSS class input and a data attribute called data-condition-key that holds the key of the entry in the condition data. During saving, those text fields are stored like normal condition data, no need to have them as data in the wrapping <span> element. Whatever you add as condition data will stored when the rule is stored and will be available to you in the following method. See CustomConditionExample::readMe() for a line-by-line explanation of the HTML structure. getevaluationresult($conditiondata, $selections) This method is called when the condition is evaluated as part of the whole rule. $conditiondata contains everything that was set as $conditiondata in the previous method. $selections holds an array with the current configuration that is tested. The method has to return true or false. The method should be as fast as possible. Cache where you can since this method may be called multiple times each time a customer makes a selection in the configurator. See CustomConditionExample::readMe() for the concrete structure of both parameters What is Condition Data? Condition data is an array that has all the data to evaluate the condition during the configuration (via getevaluationresult()). In the rule editor each value is written as HTML 5 data attribute in the conditions HTML (in getconditionhtml()). Condition data in the Example type: Data Key Data Value Description type (required) Example The name of your condition s type name Condition 1, Condition 2, Condition 3 Only used for display fieldname field_1, field_2, field_3 Arbitrary values to use in evaluating the condition operator == The default operator for evaluating the condition shouldvalue (empty) will be populated by the user in the editor The value the thing to test for should have for the condition to be met. You can have as much condition data in your conditions as you need, the data will be available to you in the method getevaluationresult(). Version Rovexo Last update: January 28, 2018 Page 45

46 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 is a major release and underwent a rewrite of almost all code. You best take any customizations you have and compare it with the built-in counterpart and rewrite. 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 component com_configbox. 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 component com_configbox. 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. Version Rovexo Last update: January 28, 2018 Page 46

47 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 For configbox, use the settings Use Joomla router, Translate URL, Insert language code, Use Joomla router, Disable shurl (see screenshot for reference) Version Rovexo Last update: January 28, 2018 Page 47

48 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 files larger than 32MB (see php.ini settings post_max_size and upload_max_filesize). Check the size of your update package and make sure both settings are high enough. Check for any warnings on the Joomla extension manager page. 8 Extensions 8.1 VirtueMart Connector Please note that we discontinued the sale and support of the VirtueMart Connector. See the manual of previous versions. Version Rovexo Last update: January 28, 2018 Page 48