ConfigBox

Transcription

1 Shop Manager Manual ConfigBox

2 Table of Content 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 (Joomla 1.6 and above only) Setup of permissions (Joomla 1.6 and above only) Enter your business information Enter an address for notifications about reviews Integration of ConfigBox in Joomla ConfigBox Menu Item Types Configurator Basics Languages Product Listings Products Configurator Pages Elements Options and option assignments Compatibility Rules Price Calculation Calculation using Tables Calculation using Formulas One-time Prices and Recurring Prices Product Visualization Native SEF URLs How ConfigBox SEF-URLs are built ConfigBox Configuration Order Management Cart page Control what a customer can do on the cart page Set the Continue Shopping listing Customer Data Customer Groups Rovexo (formerly Elovaris Applications) Version Page 2

3 5.3.1 Associated platform group (Joomla 1.6 and above only) 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 Order Management Configuration Checkout Invoicing File Uploads for orders Others Reviews Customizing ConfigBox and Order Management Quotation PDFs Customize wording or add translatable texts Location of original and custom language files Language file format and best practices Adding a new language Managing translations after software updates: Custom programming in configuration elements Use of custom data fields CSS style overrides Customizing standard templates Custom templates for individual listings, products, pages and elements Connectors What are connectors for? What are connectors technically? How to manage connectors How to develop a connector Notification snippets Notes for ConfigBox upgrades Upgrade from ConfigBox versions prior version Rovexo (formerly Elovaris Applications) Version Page 3

4 8 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 Compatibility Installation Setup in ConfigBox and VirtueMart Rovexo (formerly Elovaris Applications) Version 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 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. Rovexo (formerly Elovaris Applications) Version 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 webspace, 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: / (the Joomla base folder) /administrator/ /components/com_configbox/ 2.2 Installation procedure If you upgrade ConfigBox you must create a backup of your website before upgrading to prevent data loss or downtimes of your store. This is a safety measure in case of an interrupted upgrade process. To install ConfigBox, have your installation packages ready, they consist of multiple files of the type.tar.gz or.zip You downloaded ConfigBox as one.zip file, you need to unzip it and use the packages in the folder Installation or Upgrade. At the Extension Manager, select your first package with the file upload element and click on Upload & Install. Rovexo (formerly Elovaris Applications) Version 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 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. After successful installation of all packages, you have to additional entries in your components menu ConfigBox and Order Management. All product setup related tasks are in ConfigBox. All tasks related to orders, payments, customer data and similar are found at Order Management. 2.3 Steps after installation Activation of Joomla plugins Joomla requires you to manually activate new plugins using the Plugin Manager at Extensions. Click on the red symbol next to the newly installed plugins Customer group setup (Joomla 1.6 and above only) Go to Order Management -> Customer Groups -> Default Group and set a Joomla user group at platform group (save once if already filled). What is this meant for? After the customer supplied his contact information on the RFQ form or order address form, a Joomla user account is created and assigned to that group. Rovexo (formerly Elovaris Applications) Version Page 7

8 2.3.3 Setup of permissions (Joomla 1.6 and above only) On the Joomla 1.6 (and above) platform Joomla group permissions are used to allow or display certain tasks or features. After installation your public group has no permissions for any of these tasks, you need to set these manually. 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 customer groups at Order Management -> Customer Groups and associate other groups, you need to set the same permissions Enter your business information At Components -> Order Management -> Shop Data 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 Components -> ConfigBox -> Configuration -> Reviews. 3 Integration of ConfigBox in Joomla To display ConfigBox pages on your website, you use menu items just as any other component. Go to Menus Your Menu and click New, then choose the menu type. ConfigBox offers multiple menu item types with parameters. The most important one is the type ConfigBox Product Listing which will show all your products or a listing of certain products (grouped by product listings). Rovexo (formerly Elovaris Applications) Version Page 8

9 3.1 ConfigBox Menu Item Types ConfigBox Configurator Page A link to a configurator page of a product. Check the section SEF Links in ConfigBox for special use of this menu item. ConfigBox Cart Link to the ConfigBox shopping cart. ConfigBox Product Details Link to a defined product details page. ConfigBox Product Listing Link to a page that shows all your products or products of a certain listing if defined. 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) Rovexo (formerly Elovaris Applications) Version Page 9

10 4 Configurator 4.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 -> Configuration -> Languages. Important: Make sure you have set the language tag correctly in the Joomla language manager. Changing a language tag would make all translations in ConfigBox disappear. Language configuration in ConfigBox: 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. Rovexo (formerly Elovaris Applications) Version Page 10

11 4.1.3 Products 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 parallel. With a custom price text, you can present a price with your own wording and insert the price value using the placeholder %s. This enables you to display your price as Starting from 100. For the Recurring base price you can do the same analogous Product Description Product descriptions are shown in the product listing and details page. You have separate product listing description and product details description. If you set Use product details description as template`, all your entered HTML will be used as-is in the product details giving you full control over the layout. You can then use placeholders for dynamic fields like price and add to cart or configure buttons. See the field s tooltip for the placeholder names Product detail panes With product detail panes you show product details segmented in a tabbed interface. You can choose to display the product details in product pages and configurator pages. Rovexo (formerly Elovaris Applications) Version 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 platform 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. Rovexo (formerly Elovaris Applications) Version Page 12

13 Detail pane entry form 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 }?> 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',KPATH_ROOT.DS.'components'.DS.'com_configbox'. DS.'views'.DS.'block_visualization'.DS.'view.html.php'); $view->display();?> Important Note: You need to set the dimensions of the product visualization. Otherwise it will not be visible. Rovexo (formerly Elovaris Applications) Version Page 13

14 Selection overview on configurator pages You can override the settings for the selection overview for each product. In this section you find the same parameters as in the global configuration itself. Set to Use Default to use the global configuration setting. Display of the selection overview in configurator pages: In Joomla you use the module called ConfigBox Selection Overview (mod_configboxprices) 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('ConfigboxViewBlockPricing,KPATH_ROOT.DS.'components'.DS.'com_configbox'.DS.'vie ws'.ds.'block_pricing.ds.'view.html.php'); $view->display();?> Rovexo (formerly Elovaris Applications) Version Page 14

15 4.1.4 Configurator Pages Note: Configurator pages were called Categories in previous versions of ConfigBox. Configuration pages enable you to create multiple steps in the configurator. If you only need one step, you just create one page Visualization View In visualization view 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 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 Elements (and their assigned options) are the components for which the customer makes his selections. An element can be a text field, checkbox, a set of radio buttons, file upload, dropdown, a set of images to Rovexo (formerly Elovaris Applications) Version Page 15

16 make a selection, a slider or a calendar. Display depends on the number of assigned options and the used widget (see Element -> settings for custom entries. Examples of elements for better understanding Car paint (with assigned options red, blue and black) Width of a brochure (no options, will be a text-field) Insurance opt-in (checkbox, one assigned option) Text Field Element To display the element as text field, add an element and assign no options to it. If you want to restrict customer entry to certain values, see the section Settings for custom entries. 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. Note: If you like the default value to be set after an element becomes active (by rule), activate the option Auto-Select Default Option or Text in the section General Element widgets for custom entries When using text fields for entries, you might want to give your customers a more appropriate way to enter their information. For this we got widgets for these kinds of entry: Regular text field with validation and minimum and maximum value Calendar for date entry Slider for number entry File upload field with file validation Popup with a custom Joomla article to pick a predefined text value (pick a Joomla article with a HTML table. In the cells you put in a text inside a <span> Element, when the customer clicks on the table cell, the value in the <span> will be entered in the text field Rovexo (formerly Elovaris Applications) Version Page 16

17 Price Calculation on elements calculation element Important note: You cannot assign options to an element with assigned price calculation models. If you disable Display element in configurator, the element will not be displayed in the configurator (and customers cannot make entries). The element will act as a calculator only and title and pricing will be displayed in overviews. Setting up calculation models is described in the manual section Calculation Models. The price multiplicator is used to multiply the result of the price calculation Checkbox Elements After you add a new element and save you will see a section called Option Assignments on the bottom of the edit screen. This allows you set up items that the customer can choose from. To display a checkbox, you assign one option to the element. See the section Options and Option Assignments for detailed information Radio-Button Field Elements Options and option assignments Options can be seen as separate products or interchangeable components of a machine and are assigned to elements. Options can be used in multiple elements across multiple products. The data of an option (e.g. price, name, SKU, ) is stored centrally, so changes affect all assignments. The data of an option assignment on the other hand (calculations, rules, picker and visualization images) are specific to each assignment. See the links Option assignment and Global option for reference. Rovexo (formerly Elovaris Applications) Version Page 17

18 Option assignment settings: Global options settings: Rovexo (formerly Elovaris Applications) Version Page 18

19 If you assign a calculation for price or recurring price, the static price of the global option will be overridden. The image for the visualization image will be displayed in 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). With the 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 are described in detail in the section Compatibility Rules. The configurator activates or disables options depending on if the conditions of the rule are met. 4.2 Compatibility Rules Compatibility rules enable you to let elements and options automatically appear and disappear (called becoming active or inactive in this manual) depending on the customer s current selections. The elements and options can be greyed out or completely hidden. Standard options can be auto-selected once the element becomes active. In the following, we refer to options all applies to elements as well. The rules are entered with a visual editor. You open the option you like to become active/inactive and click on edit at the section/field compatibility rules and the compatibility rules editor popup. Rovexo (formerly Elovaris Applications) Version Page 19

20 Rule editor since ConfigBox Rule editor: Pick an element in the grey area and you get the available conditions to be dragged into the rule. Once you click and hold on a condition, you see drop areas in the rule area where you drag and drop it. You find more info in the onscreen help at the rule editor. You can use the values of the custom fields in options and option assignments to determine your rules. Click on is to change the operator to is not or is lower etc. (where applicable). In the editor you set the conditions under which the option shall be active. If the conditions are not met the element will become inactive. If the conditions of the rule are not met anymore and the option was selected, it will be automatically deselected. You can make the option disappear by setting Hide if not applying to yes. If you like the customer to confirm automated deselection if the conditions of the display are not met anymore, set confirm deselect to yes. For compatibility rules on elements you can set that the default option (if set) will be auto-selected once the element becomes active. Rovexo (formerly Elovaris Applications) Version Page 20

21 4.3 Price Calculation With calculation models you can implement complex pricing structures with no need for programming. Depending on the pricing scheme you can use price tables or formulas to output pricing depending on customer input. Calculations can also be used for dynamic weight of options and for user input validation. Price calculations override the static prices set in options. You assign a calculation to an option assignment or an element in order to output the price calculated in the model. There are two different types of calculation models: Calculation table Calculation formula The use of these models is described in detail in the next chapters. Tables are useful for calculating a price depending on the combination of selections in two elements. For example you can calculate a price with the configured width and height of a product. Formulas are useful for calculating a price using math and any settings of elements and the settings of their selected options, especially in combination with custom fields. At ConfigBox -> Calculations you find a listing of all your calculation models. You add a model and then assign it to an option assignment or element. Calculation for an element: If you assign the calculation model to an element, it will not be displayed as a configuration element anymore, it will only be shown on overview pages (e.g. price module, cart etc.) with the price calculated in the model. This is referred to as calculation element. If you disable Display element in configurator, the element will not show up as a free entry element and the element will be displayed in overviews unless the calculation returns zero. Rovexo (formerly Elovaris Applications) Version Page 21

22 Important note: If you assign a calculation model to an element, the element needs to be a text field (no options assigned) Calculation using Tables With calculation tables, you choose 2 elements as input parameters (or another calculation). The selection of each of the elements (or the result of the calculations) is used to look up the values in the table, the cells of the table are the price output. Rovexo (formerly Elovaris Applications) Version Page 22

23 Typical workflow: 1. Add a calculation 2. Choose Table as type 3. Choose an element for columns and one for rows (or calculations) 4. Optional: If you use non-textfield elements, click save once 5. At Add rows or columns, enter a list of values you have a price for, click Add to table. Rovexo (formerly Elovaris Applications) Version Page 23

24 6. Enter the desired prices 7. Save the model and assign it to the option assignment or element of your choice Other settings: Lookup Value: Typically you won t have a price for each possible customer input, but scaled prices. For this you can change the setting Lookup Value. Use next higher or next lower to lookup the appropriate price in the table. Round Values: If you like to have the user input values rounded you can do it with this setting. Round to 1 means round to integers. Round to 10 would mean rounding to full 10s (e.g. 15 -> 20). Multiplicator: You can provide a factor to multiply the result of the calculation. This is useful to add margins to supplier prices or similar. Element Value Multiplicator: Here you can choose an element whose value (the value provided by the customer) multiplies the result of the calculation. Calculated Multiplicator: This is the same as the other multiplicators, 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 Calculation using Formulas Calculation formulas follow a similar pattern like the calculation tables, but here you can use a mathematical formula with placeholders for customer input and specific keywords to include many settings from elements and options in the formula. Rovexo (formerly Elovaris Applications) Version Page 24

25 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) 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. Rovexo (formerly Elovaris Applications) Version Page 25

26 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. 4.4 One-time Prices and Recurring Prices ConfigBox supports two parallel prices for each entity enabling you to offer products that have a one-time fee and a recurring fee (or either one of them). This enables you to offer products that for instance have a monthly price and a setup price. Typical use cases Rental offers Webhosting products Phone contracts Rovexo (formerly Elovaris Applications) Version Page 26

27 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. Rovexo (formerly Elovaris Applications) Version Page 27

28 Product page example using one-time and recurring prices Pricing is displayed according Configurator page display example Rovexo (formerly Elovaris Applications) Version Page 28

29 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 4.5 Product Visualization ConfigBox enables you to present your product visually and have real time updates of the visualization during a customer s configuration. Instead of providing images for each combination of the product, you Rovexo (formerly Elovaris Applications) Version Page 29

30 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. 4.6 Native SEF URLs ConfigBox uses the native Joomla framework to create SEF URLs. The use of third party tools that alter URLs is discouraged 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. It takes the alias of the most specific menu item and appends the aliases of the product and configurator page as needed. When two equally specific menu items are found, parent menu items of the current menu item are prioritized. Following you see a list that defines how specificity is defined for each page type. Rovexo (formerly Elovaris Applications) Version Page 30

31 Product listings: 1. Menu item of type Product Listing with a matching listing id 2. Menu item of type Product Listing with no defined listing id Product Page: 1. Menu item of type Product Page with a matching product id 2. Menu item of type Product Listing that contains the product (product alias is appended) 3. Menu item of type Product Listing with no defined listing id (product alias is appended) Configurator page: 1. Menu item of type Configurator Page with a matching page id 2. Menu item of type Configurator Page with a matching product id (page alias is appended) 3. Menu item of type Product Page with a matching product id (page alias is appended) 4. Menu item of type Product Listing that contains the product (product and page alias is appended) 5. Menu item of type Product Listing with no defined listing id (product and page alias is appended) 4.7 ConfigBox Configuration Please refer to the onscreen help on the ConfigBox configuration screen. 5 Order Management 5.1 Cart page The cart page is the interface between the configurator and the order management. Rovexo (formerly Elovaris Applications) Version Page 31

32 5.1.1 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 Order Management -> Customer Groups. Rovexo (formerly Elovaris Applications) Version Page 32

33 5.1.2 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 ConfigBox -> Configuration -> Cart. 5.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 Order Management -> User Fields you set the fields that shall be displayed or being mandatory. Rovexo (formerly Elovaris Applications) Version Page 33

34 Important Note: The billing fields First Name, Last Name, , Salutation and Country are required by the system and cannot be made optional or hidden. 5.3 Customer Groups You can manage customer groups as Order Management -> Customer Groups and set a default group for new customers at Order Management -> Configuration -> Others. 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 customer is associated with Associated platform group (Joomla 1.6 and above only) 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. Rovexo (formerly Elovaris Applications) Version Page 34

35 Benefits You can use the platform CMS ACL 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 product value and a discount rate to subtract from the product value. If a discount applies, it will be shown in order overview pages. Important note: The discount rate shall be a negative number. 5.4 Shipping Management ConfigBox automatically calculates shipping costs from the total weight of the order, shipping country and chosen shipper. Setup of zones At Order Management -> Shipping -> Zones you define zones and assign countries to these. You use these zones in shipping rates to enable you be able to use a single shipping rate for multiple countries that have the same shipping costs. Rovexo (formerly Elovaris Applications) Version Page 35

36 Setup of shipping rates 5.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) Rovexo (formerly Elovaris Applications) Version Page 36

37 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) 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 unsure about having picked the right PSP, please refer to customer support. We are striving to develop connectors to more PSPs. If you require a specific PSP, please contact customer support with the company and product name of the PSP. This helps us prioritizing PSPs Notifications You find notifications at Components -> Order Management -> 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. Rovexo (formerly Elovaris Applications) Version Page 37

38 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. 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. In most HTML editors enable this with a dropdown to choose the format of the selected text. See a screenshot below of JCE. Rovexo (formerly Elovaris Applications) Version Page 38

39 5.7 Invoices Invoice layout and content In Components -> Order Management -> Shop Data you can choose to define your custom invoice template (otherwise the default layout will be used). 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 General settings in the configuration In Order Management -> Configuration at section Invoicing you can configure the way invoices shall be handled. With Send invoice activated, your customers get their PDF invoice per as soon as the invoice is released. Invoice generation If Automatic after clearance is activated, you release the invoice in the order detail page at Order Management -> Orders. The invoice will be available and downloadable by the customer in the customer profile page. If Automatic is activated, invoices are generated automatically once the status of the order is set to paid (manual status change or status change by automatic transaction feedback). If After manual download is activated, you upload a PDF in the order detail page. Rovexo (formerly Elovaris Applications) Version Page 39

40 Example of the order detail page using `After manual download Invoice download link in customer profile page 5.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 Rovexo (formerly Elovaris Applications) Version Page 40

41 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 to track by scheduling the tracking for the next visit of the customer 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 status is set by the shop manager: 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), statistics can be distorted by time frame. Rovexo (formerly Elovaris Applications) Version Page 41

42 5.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 Rovexo (formerly Elovaris Applications) Version Page 42

43 5.9 Order Management Configuration Checkout Please refer to the onscreen help on the order management configuration screen Invoicing Here you enable invoicing of orders. Customers can download invoices in the customer profile page once the invoice has been released. Rovexo (formerly Elovaris Applications) Version Page 43

44 Invoice generation Automatic: The invoice will be generated and released once the order status was set to paid Automatic after clearance: The invoice is generated automatically and released once the shop manager clicked released in the order detail view. After manual upload: The invoice is released once the shop manager uploads a PDF in the order detail view Invoice number prefix The invoice number for automatically generated invoices will be prefixed with the entered prefix there. Invoice number start The first issued invoice will start with the number provided here File Uploads for orders File Uploads enable a customer to attach files to an order after a quote was requested, an order was saved or a purchase was made. The customer finds the upload in the order view in the customer profile. The files are visible in the shop manager order display view. Rovexo (formerly Elovaris Applications) Version Page 44

45 5.9.4 Others Preselect newsletter opt-in Activate this setting to preselect the newsletter opt-in in all customer data entry forms. Preselect alternate shipping address Activate this setting to preselect the alternate shipping address radio button in the order address form and customer profile form (the field is called Ship to same address ) Reviews Customers can write reviews and set ratings on products and options. You enable or disable reviews globally at ConfigBox -> Configuration -> Reviews or enable or disable them for specific products or options at the product or option settings. New reviews are inactive initially and need to be approved. A notification on new reviews is dispatched to alert staff. At ConfigBox -> Configuration -> Reviews you can enter an address for the notifications. At Order Management -> Reviews you have a list of all reviews where you can filter, approve and edit reviews. 6 Customizing ConfigBox and Order Management Customization of ConfigBox is straightforward, well organized, requires no modification of the base software and can go deep into the 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 Data-exchange between the configurator or order management and third party systems 6.1 Quotation PDFs To change the layout and contents of your PDF quotation you can use the Joomla Template Override System. There are 2 different quotation PDFs: The download and the attachment. Overriding the downloadable PDF: Copy the original template file from /components/com_cbcheckout/views/quotation/default.php and copy it to the custom templates folder in (/components/com_configbox/data/customization/templates/quotation/). In this location you can edit the file any way you need it. Please be aware that the HTML has to be strictly valid we recommend adhering to XHTML 1.1 strict. CSS floats are not supported by the PDF parser, use table-layouts if necessary. Rovexo (formerly Elovaris Applications) Version Page 45

46 Locale-dependent texts are found in the language file for com_cbcheckout (not com_configbox). Overriding the attachment: Copy the original from /components/com_configbox/observers/notifications/attachments/customer_11.pdf.php to the folder for custom and override attachments in /components/com_cbcheckout/data/notification_attachments/ 6.2 Customize wording or add translatable texts You can add/override wording by using standard.ini language files. The system is multilingual, you can add/override wording for all languages your platform provides using standard English in templates and add translations in.ini files Location of original and custom language files You have 2 separate locations for language files. components/com_configbox for configurator pages and cart components/com_cbcheckout for checkout and all other order and customer related pages. When in doubt where the page in question belongs to, please search for specific english texts in both locations or contact customer support for assistance. Folder for original language files /components/com_configbox/language/[language-code] /components/com_cbcheckout/language/[language-code] Folder for custom language files /components/com_configbox/data/customization/language_overrides/[language-code] /components/com_cbcheckout/data/customization/language_overrides/[language-code] Language file format and best practices The language files are regular.ini format files using a flat data structure. Example line from the German translation file: REQUEST QUOTATION= Angebot anfordern The left part is written exactly like in the original code and transformed in upper-case (called the KEY). The right part has to be in double quotes and represents the actual output of the text (called the VALUE or TRANSLATION). If you need to use double quotes in your text output, escape the character with a backslash - \ If you like to override an existing text: Identify the key in the original language file (in 95% of cases it is the english version text in uppercase) by doing a text search in the german language files Add a line in your language override file with the same key and write your own translation Rovexo (formerly Elovaris Applications) Version Page 46

47 If you like to add translatable text: This is helpful when you use custom templates and like to have multilingual text there. For example write the following in your template (Use the <?php and?> tags when appropriate) <?php echo KText::_( My multilingual text in the template );?> and add the following line in your custom language file: MY MULTILINGUAL TEXT IN THE TEMPLATE= My translation of that text Note: Texts used with KText::_() that have no translation will be shown as is. Debugging: The syntax of the.ini file is strict and if one line contains an error, all following lines in the language files are ignored and a PHP message is issued. To help you identifying if and where the syntax error occurred, you can check the ConfigBox log file for PHP messages (configbox_php_messages.php) or your webserver s error log file Adding a new language You can use the custom language file folder to add your own language. The German translation files contain a complete list of translations that you can use as a basis of your own language file. You find the language files in the following locations: components/com_configbox/language components/com_cbcheckout/language Managing translations after software updates: When texts are added or keys are modified in the original language file, we strictly append these texts to the end of the German language files. You can refer to these language files in order to keep your own translation files up to date. If an original text line is removed, an empty line is left so that translations stay same line number. Tip: Use the open-source software DiffMerge to comfortably compare language files. 6.3 Custom programming in configuration elements Using the element class API you can implement specific functionality in your configurator. For instance: Determine element pricing with your own PHP code; e.g. fetch pricing from external data sources Store configuration element values in other systems Do any modification of the standard functionality by overriding any element method (not to be confused by the template override system). How is the element class API used? 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. Rovexo (formerly Elovaris Applications) Version Page 47

48 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 subfolder, in it you put the PHP class file with the same name. Example for element class name upload : PHP class name: ConfigboxElementUpload Filesystem path: components/com_configbox/data/customization/element_classes/upload/upload.php Methods you can extend: getprice($getnetprice, $getinbasecurrency) This method returns the price in the base currency, either gross or net (depending on the 2 parameters). The method must return a number of type float. If parameter 1 is not entered, the system default has to be used (using CONFIGBOX_SHOW_NET_PRICES), if parameter 2 is missing, false is assumed. getpricerecurring($getnetprice, $getinbasecurrency) analogue to getprice(), for the recurring price. loadtemplate() This method writes the frontend HTML output of the element in the configurator. Anything written to the output buffer will be shown in the browser. 6.4 Use of custom data fields Products, elements, options and option assignments have 4 to 6 custom fields you can use to enter any additional data of your products or useful data for your order processing. You can use these fields for various tasks: Use the values in calculation formulas (see onscreen-help for detailed info) Use the values in custom templates or element classes Use the values for integrating with 3 rd party software 6.5 CSS style overrides There is an empty CSS stylesheet, where you can make change to the design of any configurator page. It is located at: components/com_configbox/data/customization/style_overrides/css/style_overrides.css This file (as any file in the customization folder) is not overwritten with ConfigBox updates and helps you keep your changes organized. 6.6 Customizing standard templates All browser output of the shop system is done using HTML templates with PHP code inserting the dynamic data into the template. All templates and so called views (PHP files that prepare the data for the templates) are unencrypted to give you insight in how the data is being displayed. Rovexo (formerly Elovaris Applications) Version Page 48

49 Location of the views and templates: There are 2 components that represent the shop system and configurator. They are located in /components/com_configbox and /components/com_cbcheckout In each of these folders you find a subfolder views containing the templates that are responsible for the browser output. In here are subfolders (like productlisting, configuratorpage etc). The folder names are the view names. In there you always have a file called view.html.php and a file called default.php in the tmpl subfolder. Overriding a template for custom design or functionality In the folder /components/com_configbox/data/customization/templates you create a folder with the view s name and copy the template file (default.php) file there. Then the system will use that template file instead of the original one. Example: Say you like to change the default template for the cart page. Go to the folder /components/com_configbox/views/cart/tmpl/ Get a copy of the default.php file in there Go to the folder /components/com_configbox/data/customization/templates Create a folder called cart Upload the default.php file there and make your changes Tips on investigating data provided in the template You see how the data is being displayed in the original templates. Usually you see snippets like $this- >products, $this->order or $this->elements. 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 in configurator page templates: dump($this->elements); 6.7 Custom templates for individual listings, products, pages and elements This section is about the template editor that basically does the same like customizing templates. In addition to that, it allows you to comfortably edit template files in the admin area and setup multiple templates and assign them to specific products, configurator pages or elements. If you like to use different designs for individual listings, products, configurator pages or elements you can set up individual templates at ConfigBox -> Templates and assign them to the respective entity in their edit form. In the edit forms of the entities you can assign the template using the field Template. Rovexo (formerly Elovaris Applications) Version Page 49

50 Note: These custom templates may need to be adapted to future major ConfigBox versions. In the release notes you find notes on which templates should be adapted. Edit form for templates You edit templates using code coloring and formatting and you can also edit these files on the file system. Rovexo (formerly Elovaris Applications) Version Page 50

51 6.8 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 (responsible for integrating the default order management) path: components/com_configbox/observers/cbcheckout.php How to manage connectors At Components -> ConfigBox -> Configuration in section Connectors: Here you can enable or disable connectors and add or remove them. Adding a connector After clicking add you enter name of the connector, the settings and provide the file. Enter the form as per installation instructions of the connector provider How to develop a connector First you pick a name for your connector. In this example we use ecomsystem. Rovexo (formerly Elovaris Applications) Version Page 51

52 Create a PHP file with a PHP class called ObserverEcomsystem. <?php class ObserverEcomsystem { } Save the file and add it as connector (see 6.8.3). Custom connectors are stored in this path: components/com_configbox/data/customization/custom_observers Connector to place a configured product in a third party ecommerce cart Add the method onconfigboxaddtocart with one parameter (passed by reference). function onconfigboxaddtocart(&$grandorderdetails) { // Code to add product to shop system } $grandorderdetails->redirecturl = 'URL TO THIRD PARTY CART'; return true; About $grandorderdetails The parameter $grandorderdetails is a PHP object containing the information about all orders. Use var_dump(), print_r() or dump() (install JDump from the JED) to see the structure of the object. About $grandorderdetails->redirecturl Set the member redirecturl to the URL of your ecommerce system s cart page. ConfigBox reads this member and redirects the customer to the given URL (can be a full 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 methods for this is called onconfigboxcheckout. function onconfigboxcheckout(&$orderdetails) { // Code to add product to shop system } $orderdetails->redirecturl = 'URL TO THIRD PARTY CHECKOUT PAGE'; return true; 6.9 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. Rovexo (formerly Elovaris Applications) Version Page 52

53 Location of the custom snippet folder components/com_cbcheckout/data/notification_elements/ Snippet and file name convention Say you call your snippet customsnippet. The file name has to be called customsnippet.html.php, the placeholder {element_customsnippet}. Data available in the snippet file $orderrecord Object holding all order data (see $orderrecord->orderaddress for order customer data) $shopdata Object holding the shop data Helpful tips See the code for the order overview for reference in /components/com_configbox/observers/notifications/elements/order_overview.html.php There is a very useful Joomla extension that lets you output the data of any variable in a tree structure in a popup. It is called JDump and can be found in the JED: Example call: dump($orderrecord); 7 Notes for ConfigBox upgrades Please check the compatibility notes at the download pages on for notes on compatibility on custom templates. 7.1 Upgrade from ConfigBox versions prior version 2.2 Calculation Formulas The placeholders A, B, C, D now need to be written with a prepended and appended space and in capital letters. So A*B is not possible anymore and has to be written A * B. This is necessary because of clashes with keywords like ElementAttribute, where the A would get replaced in case the placeholder A is defined. Please check your formulas before updating. New SEF URL routing ConfigBox has a new router for SEF links, finally removing the /configuration part from the URL and dropping the requirement to have a product listing menu item with no product listing parameter set. Also it is now possible to have different module assignments for each product or each configurator page by creating a "Configurator page" menu item with fitting parameters for product and configurator page. If you do not need this fine-grained control over your module display, you can still use a menu item with product and configurator page unset. Rovexo (formerly Elovaris Applications) Version Page 53

54 This is a one-time change of URL routing and will not be changed again in the mid-future. We found that this step was absolutely necessary to make links more flexible and easier to handle. 8 Troubleshooting Always check if you read and followed the instructions in the section Installation and the section ConfigBox upgrades. 8.1 Pricing and Product Visualization does not update Checklist: Page Caching plugins are active on configurator pages Page caching plugins like Yot-Cache or JoomlArt T3 Template Caches and others prevent ConfigBox from preparing configurations before displaying the configurator page. Solution: Deactivate the caching in general or disable it for the components com_configbox and com_cbcheckout. Links and buttons do not redirect to the intended page Third party SEF-URLs like AceSEF, SH404SEF and others manipulate URLs that can lead to incorrect redirections. Solution: Fine tune the SEF tool or disable these tools for the components com_configbox and com_cbcheckout. 8.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 8.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. 8.4 Issues with SH404SEF If you got issues with SEF URLs on ConfigBox and Order Management pages, configure SH404SEF like this: Rovexo (formerly Elovaris Applications) Version Page 54

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