Shop Manager Manual ConfigBox 2.5

Transcription

1 Shop Manager Manual ConfigBox 2.5

2 Table of Content 1 Introduction Installation How to check if ioncube Loader is installed What to do if ioncube Loader is not installed Installation procedure Steps after installation Automatic Database Updates ConfigBox module Price Overview Setup of permissions (Joomla 1.6 and above only) Integration of ConfigBox in Joomla ConfigBox Menu Item Types ConfigBox Overview Product Listings Setup of a product including configuration elements Product Section Configuration Page (formerly called Category ) Elements Element widgets for custom entries Compatibility Rules Price Calculation Calculation using Tables Calculation using Formulas One- time Prices and Recurring Prices Product Visualization Version 2.5 Page 2

3 4.9 How SEF URLs are built in ConfigBox Product Details Pages: Configuration Page: Configuration Page Module Assignment Trick Order Management Shipping Management Integration of Payment Systems Notifications Invoices Customizing ConfigBox and Order Management Quotation PDFs Change default system texts Custom programming in configuration elements Use of custom data fields CSS style overrides Custom templates for display Element Template default Notes for ConfigBox upgrades Upgrade of ConfigBox versions older than Upgrade to ConfigBox Troubleshooting Option description popups do not show in a box Pricing and Product Visualisation does not update Extensions VirtueMart Connector Installation Setup in ConfigBox and VirtueMart 1.1.x Setup in ConfigBox and VirtueMart 2.x Version 2.5 Page 3

4 Version 2.5 Page 4

5 1 Introduction ConfigBox is a multi- functional Product Configurator for Joomla 1.5 to Joomla 1.7 with integrated Order Management and implements the whole order process from product configuration, request for quotation (RFQ), ordering and shipping. ConfigBox can handle a wide scope of products and services and is designed for companies seeking a way to present complex products with a user- friendly and transparent experience. Configbox is a product configurator with a full featured e- commerce framework for order management. Calculate pricing from formulas and tables in real- time Manages incompatibilities for optimal experience Requests for quotation and typical order processing With a ConfigBox license you do not need any additional software for a complete ecommerce solution. There are extra packages for integration with third party systems and open interfaces to create adapters for other ERP or CRM system. ConfigBox enables you to present complex products and services in a simple and professional fashion and prevents incompatibilities and calculates intelligent pricing automatically. All this comes in full integration in the Joomla CMS. Product data entry is done with an interface that is specifically designed for user- friendliness and intuitive handling. This enables anybody with even minimal technical background knowledge to manage the product configurator, even for advanced tasks like pricing table and calculation formula entry. Version 2.5 Page 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 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. 2.2 Installation procedure If you upgrade ConfigBox you must create a backup of your website before upgrading to prevent data loss or downtimes of your store. This is a safety measure in case of an interrupted upgrade process. To install ConfigBox, have your installation packages ready, they consist of multiple files of the type.tar.gz or.zip You downloaded ConfigBox as one.zip file, you need to unzip it and use the packages in the folder Installation or Upgrade. At the Extension Manager, select your first package with the file upload element and click on Upload & Install. Version 2.5 Page 6

7 After installation of the package com_configbox.tar.gz you will be asked to enter your license key. You should have gotten this key by e- mail from Elovaris Application or your service partner. Continue installing all the packages. If any error occurs during installation check the troubleshooting section. If you find no solution please consult your service partner or Elovaris Applications. After successful installation of all packages, you have to additional entries in your components menu ConfigBox and Order Management. All product setup related tasks are in ConfigBox. All tasks related to orders, payments, customer data and similar are found at Order Management. 2.3 Steps after installation Activation of Joomla plugins Joomla requires you to manually activate new plugins using the Plugin Manager at Extensions. Click on the red symbol next to the newly installed plugins. Setup of permissions (Joomla 1.6 and above only) On the Joomla 1.6 (and above) platform Joomla group permissions are used to allow or display certain tasks or features. After installation your public group has no permissions for any of these tasks, you need to set these manually. Version 2.5 Page 7

8 Allow Site Login for the Joomla guest user group At Site - > Global Configuration - > Permissions you need to allow the guest user group (by default called Public to login to the site. This enables ConfigBox to automatically login users after a request for quotation or customer data entry. If you create customer groups and associate other groups, you need to set the same permissions. 2.4 Automatic Database Updates ConfigBox updates often include changes to the database structure. These changes are done automatically in the background. After installation or update please open a ConfigBox admin page once to let ConfigBox do all changes. 2.5 ConfigBox module Price Overview The most powerful ConfigBox module is ConfigBox Prices. This module is meant to be displayed on configuration pages and will show an outline of the current configuration and the pricing of each element and the total. It updates in real- time as soon as the customer makes selections and can be configured in fine detail to fit perfectly for each of your products. The global settings are found in the module parameters through the Joomla Module Manager. These settings can be overridden for each product at the product edit form at the section Price Module Overrides. To add the price overview module to your website, go to the Joomla Module Manager, click Add and choose the module by the name. Use it like any standard module, at the right side pane you have settings for your preferred display. See popup descriptions when hovering over the field labels. Version 2.5 Page 8

9 Figure 1 - Price Overview Module 2.6 Setup of permissions (Joomla 1.6 and above only) On the Joomla 1.6 (and above) platform Joomla group permissions are used to allow or display certain tasks or features. After installation your public group has no permissions for any of these tasks, you need to set these manually. Go to Components - > ConfigBox - > Configuration Click Permissions on the top right corner Pick the Joomla user groups you like to set permissions for Set See pricing, save order, checkout order, request quotation and request assistance to allowed (or keep these tasks denied in case you don t intend to use these features). Version 2.5 Page 9

10 3 Integration of ConfigBox in Joomla To display ConfigBox pages on your website, you use menu items just as any other component. Go to Menus Your Menu and click New, then choose the menu type. ConfigBox offers multiple menu item types with parameters. The most important one is the type ConfigBox Product Listing which will show all your products or a listing of certain products (grouped by product listings). Firgure 2 Menu Items in the Joomla Menu Manager Choose ConfigBox Product Listing and leave the parameter Product listing empty for now (since you have not added any product listings or products 3.1 ConfigBox Menu Item Types ConfigBox Configuration- Page A link to a configuration page of a product. Check the section SEF Links in ConfigBox for special use of this menu item. ConfigBox Cart Link to the ConfigBox shopping cart. ConfigBox Product Details Link to a defined product details page. ConfigBox Product Listing Link to a page that shows all your products or products of a certain listing if defined. Version 2.5 Page 10

11 Order Management Refund Policy Page Link to the RP as defined in the Shop Data of ConfigBox Order Management. Order Management Terms and Conditions Link to the TOC as defined in the Shop Data. Order Management Customer Profile Page Order Management Edit Profile Page Order Management Login Form (you can also use a standard Joomla login form) Order Management Register Form (you can also use a standard Joomla registration form) Version 2.5 Page 11

12 4 ConfigBox This section will give you step- by- step instructions on how to set up a product with configuration elements. 4.1 Overview This figure shows you how products are structured in ConfigBox. Product Structure in ConfigBox Version 2.5 Page 12

13 The customer will do the configuration on configuration- pages. If you add more than one configuration page to a product then the customer will navigate to multiple pages with next and back (step by step configuration. A customer makes his selections on elements which have assigned options (element could be Car Paint, assigned options are Red, Green and Blue. Sections simply group category- pages but do not affect the configuration process. They merely act as groupings useful for configurations that span over many pages. 4.2 Product Listings Product listings are used to display certain products together on overview pages (like household goods, power tools or accessories). You can assign products to listings and you can assign a product to multiple listings. To add a listing, go to ConfigBox - Product Listings and click Add. Set a name and save. You can then add a menu item with the Joomla Menu Manager to show the listing on your website. Overview of product listings Version 2.5 Page 13

14 4.3 Setup of a product including configuration elements Product Add a product at the products view in the admin panel (ConfigBox Products). Click on New to create a new product. At the section General you enter values for the required fields like title and assign the product to a product listing. For this example use car 1. The product alias is used for SEF URLs (see section how ConfigBox generates SEF URLs ) and has to consist of letters valid for entry in browser address bars. Also enter the VAT tax rate of the product and a base weight (which can be used to calculate shipping costs). New product screen At the section Base Price you can assign a base price on which all extras during configuration are added to. With a price label you can decorate your price, especially useful if you use setup and recurring costs parallel. With a custom price text, you can present a price with your own wording and insert the price value using the placeholder %s. This enables you to display your price as Starting from 100. For the Recurring base price you can do the same analogous. Version 2.5 Page 14

15 If you use product visualization, set up the dimensions if you dynamic visualization at the section Product Visualization. Dynamic visualization images of one product should have the same dimensions. Not setting dimensions here results in not seeing the image since the frame is set to these measures. Product descriptions are shown in the product listing and details page. You have separate product listing description and product details description. If you set Use product details description as template`, all your entered HTML will be used as- is in the product details giving you full control over the layout. You can then use placeholders for dynamic fields like price and add to cart or configure buttons. See the field s tooltip for the placeholder names. Price Module Overrides: You can override the settings for the price overview module for each product, at this section you find the same parameters as in the module itself. Set to Use Default for standard module settings Section Every configurable product needs at least one section and subsequently a configuration page with elements. A section is a grouping of configuration pages and is useful for organisation of big amounts of configuration pages of a product. Since sections are mandatory please set up one section and assign all your product s pages to it if you have no need for groupings. Click on the tab Sections and click New to add a section. Use a title and product and click Save. Section Edit Screen Configuration Page (formerly called Category ) All your configuration elements are shown on configuration pages. You can have multiple configuration pages for a product to have a step- by- step configuration, where customers click Next and Previous until the reach the last page of the configuration. We recommend to group similar elements and order them in the order of their compatibility rules. Version 2.5 Page 15

16 Configuration Page Edit Screen Click on the tab Configuration Pages and click on New to add a configuration page. Set up a title and the parent section. The visualization view is a text field, which is also found at the option assignment and deals with the product visualization. Only those images which match the image scope text of the configuration page are shown, which makes different angles or detail views possible. If you like to block the customer from going to the next step if mandatory elements have no selection, check Block continuing if missing elements. You set elements to be mandatory at the element screen later. By default, the Finish Configuration button is displayed on each page, to change that set Finish button on last page only accordingly. Version 2.5 Page 16

17 4.3.4 Elements Elements (and their assigned options) are the components on which the customer makes his selections. An element can be a text- field, checkbox or radio- button depending on the number of assigned options. Using custom element templates (some templates are bundled) you can add special functionality and display styles to them. Examples of elements for illustration Car paint (with assigned options red, blue and black) Width of brochure (no options, will be a text- field) Including insurance (checkbox, one assigned option) Text Field Element To display the element as text field, you only need to set the title and configuration page and click Apply and see it on your website. If you want to restrict possible entry values, see the section Text Field Settings. Text field settings on the element edit screen If you like to allow numbers only (e.g. for measurement entries), set Allow integer values only and optionally set a minimum and maximum value and default value (which is pre- set at the configuration start but not if the element is inactive by compatibility rules initially). If you set a minimum value, ConfigBox automatically takes care of language dependent decimal point translation (in some languages a comma is used). Version 2.5 Page 17

18 Price Calculation on elements calculation element Normally you would set price calculation on the option assignments, but you can also assign a calculation model to the element itself. Doing so will make the element disappear from the configuration page and only affect the price of the order (it will be shown with its title in order overviews like the price overview model, cart and similar pages). This is called a calculation element. Do not assign any options to an element with assigned calculation models. Price calculation settings on the edit element screen If you set Display as text field, the element will not disappear and act as a combination of a text field and calculation element (Since version 2.3.0). Setting up calculation models is described in the manual section Calculation Models. The multiplicator is used to multiply the resulting price from the calculation Checkbox Elements After you add a new element and save (or apply) you will see a section called Option Assignments on the bottom of the edit screen. This allows you set up items that the customer can choose from. One assignment makes the element display as checkbox, more assignments make it display as radio- button field. Option assignments on the element edit screen Version 2.5 Page 18

19 Option assignments: Options belong to elements and can be reused for multiple products. An option has global settings and settings (like title, price, description and others) that only apply to the specific assignments (calculation models, compatibility rules, visualization image and others). To make the element a checkbox, click on New option. A popup with the global option settings appars. New option popup at element edit screen Add the mandatory Title field and optionally SKU (inventory identification code) and a price. The option s description will be shown in a tool- tip on the website. After saving, the option will be automatically assigned to your element. You can review the assignment settings by clicking on the title of the option. Option assignment settings: For checkboxes you can set Default option to yes to make the checkbox pre- checked. Here you can assign a calculation model for price and recurring price. If set, the static price set at the global option settings are ignored. Version 2.5 Page 19

20 Here you upload the image for the dynamic product visualization. To control the stacking order of this image, enter a number at the field Layer (higher numbers make the image stacked higher up). Entering an image scope text makes the image only show if the text matches the text set at the configuration page. Compatibility rules are described in the section Compatibility Rules. Option assignment settings popup at element edit screen Radio- Button Field Elements You can setup an element just like a checkbox element, but with more than one option assignments. Clicking on the form element next to the title sets the pre- selected standard option. 4.4 Element widgets for custom entries When using text fields for entries, you might want to give your customers a more appropriate way to enter their information. For this we got widgets for these kinds of entry: Regular text field with validation and minimum and maximum value Calendar for date entry Slider for number entry File upload field with file validation Popup with a custom Joomla article to pick a predefined text value (pick a Joomla article with a HTML table. In the cells you put in a text inside a <span> Element, when the customer clicks on the table cell, the value in the <span> will be entered in the text field Version 2.5 Page 20

21 4.5 Compatibility Rules Compatibility rules enable you to let elements and options automatically appear and disappear (called becoming active or inactive in this manual) depending on the customer s current selections. The elements and options can be greyed out or completely hidden. Standard options can be auto- selected once the element becomes active. In the following, we refer to options all applies to elements as well. The rules are entered with a visual editor. You open the option you like to become active/inactive and click on edit at the section/field compatibility rules and the compatibility rules editor popup. Compatibility rules editor in ConfigBox prior to Rule editor before ConfigBox 2.4.0: You can use the filters on the top of the editor to narrow down your selection of elements. Select the involved element, an operator (equals, does not equal etc.) and the option that has to be selected. If you choose a text field element, you have additional operators (greater than etc.). Click on add to let the condition become effective. You can add multiple conditions to the rule with OR or AND to make a complex rule. Version 2.5 Page 21

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

23 default option (if set) will be auto- selected once the element becomes active. 4.6 Price Calculation With calculation models you can implement complex pricing structures with no need for programming. Depending on the pricing scheme you can use price tables or formulas to output pricing depending on customer input. In general calculation models take the number input from text field elements, but you can also use tables to make prices for combinations of 2 radio button elements. At the tab Calculation Models you find a listing of all your calculation models. Setting up a model is one step, you also have to assign your calculation model to an element or option afterwards. See descriptions at the manual section element. Assignment of a model to an element: If you assign the calculation model to an element, it will not be displayed as a configuration element anymore, it will only be shown on overview pages (e.g. price module, cart etc) with the price calculated in the model. This is referred to as calculation element. If you set Display as text field to yes, the element will show the calculated pricing and will be displayed as text field. If you assign an calculation model to an element, the element needs to be a text field (no options assigned). Price calculation section at element Version 2.5 Page 23

24 Assignment to an option assignment: You can also assign a model to an option. In that case the static price is ignored and the price from the model will be displayed instead. Price calculation at option assignment Calculation using Tables With calculation tables, you choose 2 elements as input parameters. The selection of the elements is used to look up the values in the table, the cells of the table are the price output. Version 2.5 Page 24

25 Calculation table A typical example of an calculation table is usage of 2 text field elements (e.g. for input of width and height) which is used in the table for columns and rows. At the bottom of the screen you can add your axis values ( Add in columns, Add in Rows ) you can add multiple values at once by separating with commas. After clicking go the table is created with zero values (as in the figure above). You can now enter prices for each combination of the 2 inputs. Set use next higher value to look up the next existing value in the table (e.g. customer entered 13, next axis value in the table is 20 so the value for 20 is used). Round values to makes the customer input rounded to integers, tens, hundreds etc. (only enter 1, 10, 100, etc.). Multiplicator simple multiplies the result of the calculation with the entered value. Useful when entering supplier prices and multiply it with your margin. Dynamic Multiplicator can be used to define another text- field element whose value will be used to multiply the result of the calculation. Version 2.5 Page 25

26 Note: If you set up text field elements meant for numbers, make sure you set up validation of the user input at the element under section Text field settings. This makes sure the price calculation won t break when customers enter non- numeric values. ConfigBox automatically deals with decimal symbols from different languages Calculation using Formulas Calculation formulas follow a similar pattern like the calculation tables, but here you can use a mathematical formula with placeholders for customer input. After adding a new calculation model, select the type Formula to toggle. You can add up to 4 placeholders that will be used in the formula with the letters A to D. The placeholders get replaced with the value entered by the customer for that element (or zero if no input is there). Always pad a placeholder with a space (before and after), so that the formula can be parsed properly. Example formula: ( A * B ) + C Formula Keywords You can use keywords to use values other than user input for your formula (e.g. Total for the price total of the current product). A list of keywords is found in the on- screen notes at the formula editor. With the keyword ElementAttribute you can use metadata of an element and its assigned options. E.g. use ElementAttribute(10.selectionPrice) to get the current price for the element with ID 10. You can look up element IDs at the element list screen or at the placeholder dropdowns. Since ConfigBox 2.4.0: You will see the available placeholders in the onscreen- help. You can use the custom fields in elements, options and option assignments in your formula as in the compatibility rules. You can also enter PHP code to make more complex calculations here. Also there is an element class API that lets you write your own element PHP classes that override the calculation method to make even more sophisticated price calculation. 4.7 One- time Prices and Recurring Prices ConfigBox supports 2 parallel prices for each entity enabling you to offer products that have a one time fee and a recurring fee (or either one of them). This is meant for cases like hosting contracts, phone carrier plans and similar but can be used for any kind of project. All pricing (including price calculation) can have both one- time fees and recurring fees at once. At the product settings you can label the pricing (e.g. monthly service charge ). Version 2.5 Page 26

27 Recurring pricing options at product edit screen Display on website at product listing Version 2.5 Page 27

28 Display of recurring and one- time prices during the configuration Version 2.5 Page 28

29 Price Overview Module showing recurring and setup prices The price module can be set up to display recurring pricing together with regular pricing. You can also show totals for recurring pricing only. Cart page order overview displaying recurring and normal prices Depending on the product s recurring pricing, the cart overview shows both pricing. Version 2.5 Page 29

30 4.8 Product Visualization ConfigBox enables you to present your product visually and to update it s display during configuration in real- time. Instead of having images for each combination of elements, you can upload outtakes of your options with transparent background, ConfigBox stacks those images to produce a complete product image consisting of the selected options. You display the product visualization with the supplied Joomla module ConfigBox Images which you can place in the template position of your choice. You need to set up the visualization dimensions in your product s settings (see manual section products ) and you can set a base image there as well. To add an image, go to the option assignment and upload an image at the field visualization image (see manual section elements ). The visualization stacking order` field determines how high up in the stack the image will be. Simple product visualization (without multiple layers) Version 2.5 Page 30

31 4.9 How SEF URLs are built in ConfigBox ConfigBox uses the native Joomla framework functions to create SEF URLs. There is no need for third party extensions for this. In general, ConfigBox analyses your menu item structure and determines the best URL for any page. It takes the most specific menu item (exception are configuration page items) and appends aliases defined in ConfigBox as necessary. Menu items that are currently active or being parents of the currently active menu item are prioritized. Please note that you need to enable Search Engine Friendly URLs in the Joomla Global Configuration to benefit from ConfigBox SEF URLs Product Details Pages: ConfigBox searches for a matching product menu item or a product listing menu item that shows the product. 1. A product page menu item with matching product id 2. A product listing menu item that shows the product 3. A product listing with no defined listing id Configuration Page: ConfigBox searches for a matching product menu item, then for a matching product listing, then for a matching configuration menu item. 1. A product menu item with matching product id 2. A product listing menu item where the product belongs to 3. A product listing menu item with no defined listing id 4. A configuration page menu item with matching product and category id 5. A configuration page menu item with matching product id and no category id 6. A configuration page menu item with no defined product and category Configuration Page Module Assignment Trick Even though the URL and breadcrumbs are set like described above, once the link is visited, ConfigBox will find a matching configuration page menu item and fool Joomla into thinking that this menu item is the active menu item, therefor display the modules (like the Price Module) assigned to it, while Joomla will still display the right breadcrumbs and URL. Version 2.5 Page 31

32 By setting up configuration page menu items with a product id and/or category id and assigning modules to those menu items, ConfigBox will choose the most specific matching menu item and Joomla will load the assigned modules. You can leave the category parameter or both parameters blank. ConfigBox will then use the menu item for all categories of a product or for all products respectively unless there is another more specific menu item. Please do not set a category with setting a product id. Only drawback is that the "actual" active menu item will not be displayed as such in menus in Joomla 1.5, but you can correct this manually with some JavaScript or use hidden child menu items if it is important to you. In Joomla 1.7, this problem does not exist. Version 2.5 Page 32

33 5 Order Management 5.1 Shipping Management ConfigBox automatically calculates shipping costs. Using total weight of the order, shipping country and chosen shipper, ConfigBox calculates shipping rates automatically. All shipping related data is entered in user- friendly and uncomplicated administration forms. Over the tab Order Management Shipping you can define zones and assign countries to these. Also you define shippers (like UPS, DHL etc.). When this is done you define shipping rates. You define a title that will be shown to your customer at the shipping method selection, then the shipper and the zone in which the shipper operates. With the minimum and maximum weight you set in which weight range the order weight needs to fall to apply for this rate. You can define the number days delivery will take, price and the tax rate for shipping. 5.2 Integration of Payment Systems You have various adapters for payment gateways bundled. To extend your choice of payment gateways, you can use the VirtueMart Integration Plugin (sold separately) to use VirtueMart as order management with its vast amount of payment gateway adapters. Version 2.5 Page 33

34 At Order Management Payment Options you can set up payment methods using different payment gateway providers. Enter a title that will be displayed to the customer, a price and tax rate (to be added to the order price) and a payment class. After clicking apply you see additional options at the bottom for most payment classes. After the description you can select the countries for which the payment method is available in. Following payment gateway providers is bundled with ConfigBox: PayPal Version 2.5 Page 34

35 Authorize.net MPAY24 QPAY Bank transfer (offline) Cash on delivery ConfigBox has an API to make integrations with additional gateways in a cost efficient way. We are glad to give you documentation on how to develop an adapter or give you an estimate for development. Version 2.5 Page 35

36 5.3 Notifications You can set notifications for customers and shop managers for any order status change. You find a listing of current notifications at Components - > Order Management - > s. notification edit screen Enter an internal name and choose the order status on which the should be sent. Subject and HTML is the content of your . You can use placeholders in the form {firstname} to include customer data. You find a listing of available placeholders on the right side of the edit form. You also have an to the shop manager analogous to the customer . Since ConfigBox 2.4.0: With the placeholder {element_order_overview} you can display an overview of the order. 5.4 Invoices In Components - > Order Management - > Shop Data you can define your invoice template. You can insert customer and order data analogous to the notifications. With the special placeholder {orderitems} you insert a table with the order data. Version 2.5 Page 36

37 6 Customizing ConfigBox and Order Management 6.1 Quotation PDFs To change the layout and contents of your PDF quotation you can use the Joomla Template Override System. There are 2 different quotation PDFs: The download and the attachment. Override the download: Copy the original template file from /components/com_cbcheckout/views/quotation/default.php and copy it to your template folder s override folder (/templates/[your template]/html/com_cbcheckout/quotation/). In this location you can edit the file any way you need it. Be careful to keep the HTML valid since the PDF generator is error- intolerant. CSS floats are not supported by the PDF parser, use table- layouts if necessary. Locale- dependent texts are found in the language file for com_cbcheckout (not com_configbox). Override the attachment: Copy the original from /plugins/configbox/notifications/notification_attachments/customer_11.pdf.php) to the override folder in /components/com_cbcheckout/data/notification_attachments/ and make changes there. The same implications apply as for the PDF download. 6.2 Change default system texts All text output comes from language files found in /language/[yourlanguage]/ and administrator/language/[yourlanguage]/. For ConfigBox pages you find the texts in the file called en- GB.com_configbox.ini, order management files in en- GB.com_configbox.ini. The format of these files is like this: BACK= Back Most texts are not in the English language files since the original is English, for instance if you like to change the text for Add to cart, write ADD TO CART= Go to overview You can add these changes in the language override files for ConfigBox pages found in /components/com_configbox/data/customization/language_overrides/frontend/language/[your- language]/xx.com_configbox.ini You also find overrides for the modules ConfigBox Prices and ConfigBox Currencies in the language_overrides folder. For order management pages you find the language overrides in /components/com_cbcheckout/data/customization/language_overrides/frontend/language/[your- language]/xx.com_cbcheckout.ini 6.3 Custom programming in configuration elements Using the element class API you can implement specific functionality in your configurator. For instance: Version 2.5 Page 37

38 Determine element pricing with your own PHP code; e.g. fetch pricing from external data sources Store configuration element values in other systems Do any modification of the standard functionality by overriding any element method (not to be confused by the template override system). How is the element class API used? Technically you create PHP files with classes that extend the original ConfigBox element class. There are methods that determine pricing, the element output, storing of the element s value and much more. After you created a class file, you can pick the element class in the element s edit- screen to give it the intended functionality. The element class file name and the PHP class name follows a naming convention. The files are stored in ConfigBox data folder to avoid overwriting on updates. Your element class extends the class ConfigboxElement. File folder and naming convention: Base folder: components/com_configbox/data/customization/element_classes Each element class has a subfolder, in it you have a PHP file with the same name. Example: PHP class name: ConfigboxElementUpload Subfolder name: upload Filename: upload.php Methods you can extend: getprice($getnetprice, $getinbasecurrency) This method returns the price in the base currency, either gross or net (depending on the 2 parameters). The method must return a number of type float. If parameter 1 is not entered, the system default has to be used (using CONFIGBOX_SHOW_NET_PRICES), if parameter 2 is missing, false is assumed. getpricerecurring($getnetprice, $getinbasecurrency) analogue to getprice(), for the recurring price. loadtemplate() This method writes the frontend HTML output of the element in the configurator. Anything written to the output buffer will be shown in the browser. Version 2.5 Page 38

39 6.4 Use of custom data fields Elements, options and option assignments have 4 custom fields you can use to enter any additional data of your products or useful data for your order processing. You can use these fields for various tasks: Use the values in calculation formulas (see onscreen- help for detailed info) Use the values in custom templates or element classes Use the values for integrating with 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 Custom templates for display If you want to make design changes that are not possible using CSS overrides or even want certain pages or individual elements have a different look and feel you can use the ConfigBox template system. At Components - > ConfigBox - > Templates you can see the original templates for Product listings Product detail pages Configuration pages Elements You can copy the template markup of any of these templates, create a new template, make your changes and then you can assign the template to your element, page etc. There is a drop- down item called Template for elements and all other corresponding items. Note: These custom templates may need to be modified for new ConfigBox versions in case we have to make changes to the original templates Element Template default This is the standard display of a checkbox element. Version 2.5 Page 39

40 Using more than one option assignment makes the element look like this. Text fields with widget text look like this: 7 Notes for ConfigBox upgrades 7.1 Upgrade of ConfigBox versions older than 2.2 Templates Custom Templates from ConfigBox 2.x are still compatible with ConfigBox although the new features and improvements in the cart, product listing and product details page are only available if you adapt your cart template. Calculation Formulas The placeholders A, B, C, D now need to be written with a prepended and appended space and in capital letters. So A*B is not possible anymore and has to be written A * B. This is necessary because of clashes with keywords like ElementAttribute, where the A would get replaced in case the placeholder A is defined. Please check your formulas before updating. New SEF URL routing ConfigBox has a new router for SEF links, finally removing the /configuration part from the URL and dropping the requirement to have a product listing menu item with no product listing parameter set. Also it is now possible to have different module assignments for each product or each category by creating a "Configuration Page" menu item with fitting parameters for product and category. If you do not need this fine- grained control over your module display, you can still use a menu item with product and category unset. Version 2.5 Page 40

41 This is a one- time change of URL routing and will not be changed again in the mid- future. We found that this step was absolutely necessary to make links more flexible and easier to handle. 7.2 Upgrade to ConfigBox Setup of permissions when using Joomla 1.6 or above When using Joomla 1.6 or above please open up the permission screen at ConfigBox - > Configuration - > Permissions (top right corner) and set the price display and other permissions for public groups. Otherwise none of your users (except super users) will be able to see pricing and cart buttons. Uninstall Plugin ConfigBox Request Handler When upgrading to version (any Joomla version) you need to uninstall the plugin Configbox Request Handler it is not needed anymore. You find the plugin in the group configbox. Rename E- Mail notification placeholder {order_id} In the E- Mail Templates at Order Management - > s you need to rename the placeholder {order_id} with {cb_order_id}. The new features in the notification- system made this necessary. 8 Troubleshooting Always check if you read and followed the instructions in the section Installation and the section ConfigBox upgrades. 8.1 Option description popups do not show in a box Joomla templates normally include CSS styles that define the display of your popups in harmony of your template s overall design. That is why ConfigBox does not interfere by setting it s own styles. If your Joomla template lacks styling for popups (also called tool tips or just tips), you need to add the CSS styling yourself in your template s stylesheet. The typical tool- tip styling CSS for Joomla 1.5 is:.tool-tip { float: left; border: 1px solid #D4D5AA; padding: 5px; background: #FFFFCC; max-width: 200px; }.tool-title { padding: 0; margin: 0; margin-top: -15px; padding-top: 15px; Version 2.5 Page 41

42 } padding-bottom: 5px; background: url(../../system/images/selector-arrow.png) no-repeat; font-size: 100%; font-weight: bold;.tool-text { margin: 0; font-size: 100%; } For Joomla 1.6 and above it is:.tip { } float: left; background: #ffc; border: 1px solid #D4D5AA; padding: 5px; max-width: 400px; z-index: 50;.tip-title { padding: 0; margin: 0; font-size: 1em; font-weight: bold; margin-top: -15px; padding-top: 15px; padding-bottom: 5px; background: url(../images/selector-arrow.png) no-repeat; }.tip-text { font-size: 1em; margin: 0; } These CSS styles are from the Joomla supplied template stylesheets and probably GPL licensed. 8.2 Pricing and Product Visualisation does not update In most cases this happens when, - the jquery JavaScript library (integrated with the Plugin jquery Includer) is overwritten by another Joomla extension. Most YooTheme Modules load jquery and have module parameters to disable loading it themselves. Navigate to the Module Manager, open the regarding module(s) and search for a parameter allowing you to disable loading jquery. These modules should work fine with the jquery library loaded by our plugin. Version 2.5 Page 42

43 - The jquery Includer plugin is not installed or activated. Navigate to Plugin Manager - > Filter for group system. Check if the plugin System jquery Includer exists and is activated. If not, install and/or activate it. See section Installation. - Your Joomla template removes all JavaScript files loaded via the Joomla framework. This is a rather rare case nowadays and happens on some free templates or bargain- templates. Open the file index.php in your Joomla template folder and search for regarding code in the <head> section of the file. ConfigBox cannot guarantee proper functionality if the template tampers with files loaded via the Joomla framework. - Page Caching plugins are active on configuration pages Page caching plugins like Yot- Cache or JoomlArt T3 Template Caches prevent ConfigBox from preparing orders before displaying the configuration page. Deactivate the caching in general or disable it for the components com_configbox and com_cbcheckout. 8.3 The installation failed and uninstallation, reinstallation is not possible If the installation failed there is a known issue with Joomla 2.5 leaving database table rows about the extension behind, making uninstallation, launch and reinstallations impossible. Solution Launch phpmyadmin in your server hosting panel Go to the table jos_assets Search for rows with name com_configbox and remove the rows Search for rows with name com_cbcheckout and remove the rows Go to the table jos_extensions Search for rows with name com_configbox and remove the rows Search for rows with name com_cbcheckout and remove the rows 9 Extensions 9.1 VirtueMart Connector Please note that we discontinue sale of the VirtueMart Connector until further notice. Customers that already have purchased the connector get support and technical assistance on incompatibilities Installation You install the VM connector as Joomla plugin. You find the plugin in the group configbox by the name ConfigBox VirtueMart Integration. Important note: You need to activate the plugin in the Plugin Manager. Version 2.5 Page 43

44 9.1.2 Setup in ConfigBox and VirtueMart 1.1.x Setup in VirtueMart configuration: At Components - > VirtueMart - > Configuration - > Security activate Allow the inclusion of extended classes from the theme- directory. VM connector plugin parameters You find the plugin in the group configbox by the name ConfigBox VirtueMart Integration. Ignore the settings for VirtueMart 2.x. VM category ID: Set the ID of the product category Version 2.5 Page 44

45 VM vendor ID: Set your vendor ID (default is 1) VM manufacturer ID: Set the manufacturer ID of the ConfigBox products (default is 1) VM shopper group ID: Set the shopper group ID for the ConfigBox products (default is 1) VM theme name: Set the VM theme name (default is default, set another name if you use a custom VM theme). VM table prefix: If your VM installation uses a different table prefix, enter it here Setup in ConfigBox and VirtueMart 2.x Setup in VirtueMart configuration: Set up a tax calculation that calculates the tax amount for the ConfigBox products added to VM. You enter the calculation ID in the VM connector plugin settings (described below). The ID is found on the far right side of the calculations table). The tax calculations are found at Components - > VirtueMart - > Products - > Tax & Calculation Rules. VM Connector plugin settings: You find the plugin in the group configbox by the name ConfigBox VirtueMart Integration. Ignore the settings for VirtueMart 1.1.x. VM Calculation ID: Enter the calculation ID set in the step before. Version 2.5 Page 45