Shop Manager Manual ConfigBox 3.0 for Magento

Transcription

1 Shop Manager Manual ConfigBox 3.0 for Magento

2 Table of Contents 1 INTRODUCTION INSTALLATION How to check if ioncube Loader is installed What to do if ioncube Loader is not installed In which folders do I need ioncube loader to be active? Installation procedure Steps after installation Enable the languages you want to use in the settings Connect Magento products with ConfigBox products CONFIGURATOR Basics Languages Products Configurator Pages Elements Options and their assignment to elements Compatibility Rules Calculations Calculation using Matrices Calculation using Code Calculation Formulas One-time Prices and Recurring Prices Product Visualization ORDER MANAGEMENT CUSTOMIZING CONFIGBOX Custom Quotation PDFs Custom Wording and Translations Understanding the concept of language files Workflow to find and customize a phrase Custom Behavior of Elements Custom Fields ConfigBox for Magento, Rovexo - Version 3.0 Last update: Oktober 19, 2015 Page 2

3 5.5 Custom CSS styling Custom JavaScript Custom Templates Custom Templates for Products, Pages and Elements Custom Rule Conditions How to develop a custom rule condition What is Condition Data? NOTES FOR CONFIGBOX UPGRADES TROUBLESHOOTING ConfigBox for Magento, Rovexo - Version 3.0 Last update: Oktober 19, 2015 Page 3

4 1 Introduction ConfigBox is a multi-functional Product Configurator integrated in Magento. 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. ConfigBox for Magento, Rovexo - Version 3.0 Last update: Oktober 19, 2015 Page 4

5 2 Installation This section covers the installation of ConfigBox. For this you unzip the installation file you received and upload the contents to your Magento main directory. 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 You ask your hosting provider about ioncube PHP loader. If you see the line with the ioncube PHP Loader [ ], your webserver has ioncube loader installed What to do if ioncube Loader is not installed Please refer to your hosting provider in order to get ioncube Loader installed In which folders do I need ioncube loader to be active? In most server setups, ioncube Loader is active for any folder on your web space, but in some you need to enable it for specific folders (usually by placing a php.ini file with loading instructions in the respective folders). If so, enable ioncube Loader for these folders: / (Magento base folder) /app/code/local/ and all subfolders 2.2 Installation procedure Before you install or upgrade ConfigBox you must create a backup of your website to prevent data loss or downtimes of your store. This is a safety measure in case of an interrupted upgrade process. 1. You check your downloaded zip file from Rovexo 2. You unzip the file 3. You should have a folder with subfolders like app, js, media and so on 4. Upload these folders into your Magento main directory (you should see these folders and more in that directory) 5. Refresh all Magento caches. When in doubt, also delete the cache folder in /var/cache 6. Go to the admin area. You should see a menu item called ConfigBox there. ConfigBox for Magento, Rovexo - Version 3.0 Last update: Oktober 19, 2015 Page 5

6 2.3 Steps after installation Enable the languages you want to use in the settings At ConfigBox -> Settings -> Language you select the languages you want to use. Each selection in the list gives you additional text fields for translatable product data. See Languages for details Connect Magento products with ConfigBox products ConfigBox products are simply containing the configuration functionality for your Magento products. You set up any Magento product and one ConfigBox product. See Products for details. 3 Configurator 3.1 Basics Languages To use multiple languages in the configurator, you need to have set up the languages in Magento. You then choose the languages to use in the configurator at ConfigBox -> Settings -> Languages. Step by step: ConfigBox for Magento, Rovexo - Version 3.0 Last update: Oktober 19, 2015 Page 6

7 Install the language pack in the Magento configuration (See Magento documentation) Activate the language in ConfigBox (ConfigBox -> Settings -> Active Languages). Important: You need to configure Magento to have a language switch for visitors yourself. There is documentation on this on the web. ConfigBox has the translations for system texts in German and English built in. You can add translations yourself; you find detailed information on how to do it in the chapter Adding a language Products You add or edit products in the product tree view on the left hand side of the admin area. You can expand each entry and you see links to add products, pages, elements and options. You can drag pages and elements to adjust ordering Magento Product ID Here you enter the product ID of your Magento product. This is how Magento will load the right configurator when the visitor navigates to the Magento product. You find the ID of any Magento product in Catalog -> Manage Products Connect ConfigBox products with Magento products In Magento, you need to set up a single custom option. After installation of ConfigBox, there is an Input Type called ConfigBox Configuration. 1. You add one custom option of this type, 2. then enter the product ID of your Magento product in the Magento Product ID field of your product. ConfigBox for Magento, Rovexo - Version 3.0 Last update: Oktober 19, 2015 Page 7

8 Product Visualization If you like to show a product visualization in configurator pages, set up the dimensions of the visualization. Visualization images of one product should have the same dimensions. Display of the visualization in configurator pages: You have a block available for displaying the visualization. This block needs to be inserted in the right spot for your Magento theme. We cannot make this out-of-the-box as themes have no standards on positioning blocks. See the ConfigBox layout XML file in the frontend. Important Note: You need to set the dimensions of the product visualization in the product edit screen (section Product Visualization). Otherwise it will not be visible Selection overview on configurator pages The selection overview is the price module that you can show on configurator pages. It summarizes the configuration, shows pricing and taxes and can have cart and quotation request buttons. The overview is configurable. You have global settings in the settings page, and settings specific to a product in the product edit screen. Display of the selection overview in configurator pages: You have a block available for displaying the overview. This block needs to be inserted in the right spot for your Magento theme. We cannot make this out-of-the-box as themes have no standards on positioning blocks. See the ConfigBox layout XML file in the frontend. ConfigBox for Magento, Rovexo - Version 3.0 Last update: Oktober 19, 2015 Page 8

9 3.1.3 Configurator Pages Configuration pages enable you to create a configurator with multiple steps. If you only need one step, you just create one page Visualization View Keyword In Visualization View Keyword you enter a keyword, the same field is present at the option assignment and enables you to show different product visualizations on each page. Only visualization images that match the visualization view text of the configurator page are shown. If the field is empty, only the visualization images with empty fields are shown. In pages like the cart or PDF quotation, the images with an empty visualization view are used 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 Elements You set up an element for each choice the customer shall make in the configurator. If the customer should make a choice from a set of predefined options, you assign options to the element (see bottom of the edit screen for reference). If the customer is supposed to make a yes/no choice, you can assign a single option to display a checkbox or simply have 2 options with yes and no as you see fit. Otherwise you can let the customer make a free entry. You can choose a between various widgets to make customer entries more practical (see Settings for Custom Entries for details) and set validation rules to restrict entries Widgets for custom entries Settings for custom entries These settings only apply if your element has no assigned options. You can then use a widget for easier customer entry and set restrictions on what can be entered for this element. If you like to allow numbers only (e.g. for measurement entries), set Allow integer values only and optionally set a minimum and maximum value and default value. Calculated Minimum and Maximum Values allow you to make the restrictions dynamic, based on the current configuration. Calculations are described in detail in the manual section Calculations. There are multiple widgets that replace the regular text field with a more practical input, depending on your use of the element: ConfigBox for Magento, Rovexo - Version 3.0 Last update: Oktober 19, 2015 Page 9

10 Regular text field or text area Calendar for date entries Slider for number entries File upload field with file validation Popup Picker The Popup Picker is advanced You enter an HTML table and In the cells you put in a text inside a <span> Element, when the customer clicks on the table cell, the value in the <span> will be entered in the text field Price Calculation on Elements Important note: You cannot assign options to an element with assigned price calculations. If you need an element that only calculates a price without acting as a choice for the customer, then you disable Display element in configurator. The element will not be displayed as a typical choice, but it s title and price will be displayed in overviews. Setting up calculation models is described in the manual section Calculations. The price multiplicator is used to multiply the result of the price calculation. Using element price calculation is only one way to calculate pricing. You can also set price calculations for each the assigned option if it is more practical for your application Options and their assignment to elements Options are the choices that the customer has in an element. An option can be assigned to multiple elements in order to accommodate stores where options stand for specific stock items and redundant data entry should be avoided. Therefore when you assign an option to an element, you see a combined edit form for the data specific to this assignment (left side) and the option itself (right side). ConfigBox for Magento, Rovexo - Version 3.0 Last update: Oktober 19, 2015 Page 10

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

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

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

14 Typical workflow: Add a calculation Choose Matrix as type Choose an element for columns and one for rows (or calculations) Pick the values for column and rows in the grey fields Enter the desired prices Add rows or columns if needed Save the model and assign it to the option assignment or element of your choice Advanced settings: Lookup Value: Typically you won t have a price for each possible customer input, but scaled prices. For this you can change the setting Lookup Value. Use next higher or next lower to lookup the appropriate price in the table. Round Values: If you like to have the user input values rounded you can do it with this setting. Round to 1 means round to integers. Round to 10 would mean rounding to full 10s (e.g. 15 -> 20). Multiplicator: You can provide a factor to multiply the result of the calculation. This is useful to add margins to supplier prices or similar. Element Value Multiplicator: Here you can choose an element whose value (the value provided by the customer) multiplies the result of the calculation. Calculated Multiplicator: This is the same as the other multiplicator, but the result of another calculation is used. Note: If you set up text field elements meant for numbers, make sure you set up validation of the user input at the element under section Text field settings. This makes sure the price calculation won t break when customers enter non-numeric values. ConfigBox automatically deals with decimal symbols from different languages. ConfigBox for Magento, Rovexo - Version 3.0 Last update: Oktober 19, 2015 Page 14

15 3.3.2 Calculation using Code Calculation formulas follow a similar pattern like the matrices, but here you can use a PHP codewith placeholders for customer input and specific keywords to include many settings from elements and options in the code. After adding a new calculation model, select the type Code to toggle. You can add up to 4 placeholders that will be used in the formula with the letters A to D. The placeholders get replaced with the value entered by the customer for that 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. ConfigBox for Magento, Rovexo - Version 3.0 Last update: Oktober 19, 2015 Page 15

16 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 Calculation Formulas Setting up a formulas works similar to the rule editor. You have operators, numbers, element values, calculations and assorted functions to drag into the calculation area. The entries in the text fields after or (e.g. Entry in Height or..) are fall-back values that are used if no entry was provided. Make sure you use the fall-back whenever a division by zero could occur. 3.4 One-time Prices and Recurring Prices ConfigBox supports two sets of prices enabling you to offer products that have a one-time fee and a recurring fee (or either one of them). This enables you to offer products that for instance have a monthly price and a setup price. Typical use cases Rental offers Webhosting products Phone contracts ConfigBox for Magento, Rovexo - Version 3.0 Last update: Oktober 19, 2015 Page 16

17 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. Configurator page display example ConfigBox for Magento, Rovexo - Version 3.0 Last update: Oktober 19, 2015 Page 17

18 Selection overview using one-time and recurring prices and settings You can configure the selection overview for each product individually and set global defaults in the ConfigBox configuration. Cart page showing one-time and recurring prices 3.5 Product Visualization ConfigBox enables you to present your product visually and have real time updates of the visualization during a customer s configuration. Instead of providing images for each combination of the product, you ConfigBox for Magento, Rovexo - Version 3.0 Last update: Oktober 19, 2015 Page 18

19 can upload outtakes of the parts with transparent background, ConfigBox stacks those images to produce the product visualization. Display of the visualization in configurator pages: You have a block available for displaying the visualization. This block needs to be inserted in the right spot for your Magento theme. We cannot make this out-of-the-box as themes have no standards on positioning blocks. See the ConfigBox layout XML file in the frontend. Important Note: You need to set the dimensions of the product visualization in the product edit screen (section Product Visualization). Otherwise it will not be visible. 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 Order Management All processing except configuration is by Magento. Refer to Magento documentation for details. 5 Customizing ConfigBox Customization of ConfigBox is straightforward, well organized, requires no modification of the base software and enables you to make profound extensions and modifications to functionality of the software: Design of products and configurators Individual configurator designs for each product ConfigBox for Magento, Rovexo - Version 3.0 Last update: Oktober 19, 2015 Page 19

20 Output of custom, non-standard product data Modification and extension of the base functionality Customization of wording used in the application Translation in non-bundled languages Integration with third party software Important: Any customization you make or delegate needs to be checked for compatibility on software updates and revised if necessary. On minor software updates we make an effort to minimize breaking changes and if need be provide detailed information about them on our website (on the download page for each version). For major software updates (e.g. 2.6 to 2.7) you need to be prepared for a complete rewrite as worst-case scenario. 5.1 Custom Quotation PDFs Quote PDFs are a ConfigBox for Joomla feature. Check the Magento marketplace for suitable solutions. 5.2 Custom Wording and Translations Customizing wording is rather easy. You need to come prepared with knowledge on editing files on your web server and on editing plain text files with a specific encoding (UTF-8). The latter is explained later in this section Understanding the concept of language files How wording and translation is handled in ConfigBox Texts you see on the pages handled by ConfigBox are customizable. To accomplish this, the software uses plain text files called system language files to find and output the right phrase in the right language. On top of system language files, the system looks for custom language files that you can use to customize specific phrases. These files can also be used to add a new translation of ConfigBox or to translate texts that you have in custom templates. How does a language file look like? A typical line in a language file looks like this: CONTINUE="Weiter" On the left in uppercase you see the keyword of the phrase the system looks for. On the right within double quotes you see the phrase that the system will display. Typically the keyword is the uppercase form of the phrase in English but it may be different for technical reasons. Locations of system language files /app/code/local/elovaris/configbox/application/components/com_configbox/language/frontend.ini /app/code/local/elovaris/configbox/application/components/com_configbox/language/backend.ini Locations of custom language files ConfigBox for Magento, Rovexo - Version 3.0 Last update: Oktober 19, 2015 Page 20

21 /media/elovaris/configbox/customization/language_overrides/en-gb/frontend.ini /media/elovaris/configbox/customization/language_overrides/en-gb/backend.ini How to figure out which language file contains the phrase I search for? The files are separated between the frontend (aka your store) and the backend (aka the administration panel). In the backend, both files are loaded, so you search for the English translation in the frontend first, then in the backend. There are no duplicates in these. Which editor should I use to edit custom language files? Files need to be saved as plain text with UTF-8 encoding (no BOM) and only use regular double quotes (like this: ") for wrapping phrases. If you are not sure what that means, take the safe route and use one of these editors with default settings: Windows: Notepad++ ( Mac OS X: TextWrangler ( Workflow to find and customize a phrase Search for the phrase in the system language files of the right language Copy the line to the corresponding custom language file and change the phrase Notes: The keyword must remain unaltered and make sure to have your phrase wrapped in double quotes. Do not put line breaks in your phrases, if you need one, add \n or <br /> If you need double quotes in your phrase, write them as \" When changing phrases in English, you may not always find the phrase in the system language files. That is because the English language files only contain phrases if the keyword differs from the phrase. In that case you can expect the keyword to be the uppercase form of the phrase. Example: The phrase Select Product is done like this: SELECT PRODUCT="Your own wording" Phrases may change in major software updates without notice. It is up to you to check and revise your customizations if necessary. 5.3 Custom Behavior of Elements Working with custom element classes requires a seasoned PHP developer and a proper local development site is recommended. We offer workshops to get your development team up to speed. Please contact customer support for pricing and scheduling. Using the element class API you can implement specific functionality in your configurator. For instance: Determine pricing with your own PHP code; e.g. fetch pricing from external data sources Store configuration element values in other systems How is the element class API used? You add PHP files with classes that extend the original ConfigBox element class ConfigBoxElement (the source code file is located in components/com_configbox/classes/element.php). The methods of that class return pricing, the element s HTML output on configurator pages, selection overview blocks and the cart page and store selections made by the customer. ConfigBox for Magento, Rovexo - Version 3.0 Last update: Oktober 19, 2015 Page 21

22 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: /media/elovaris/configbox/customization/element_classes Each element class has a sub-folder. In it you put the PHP class file with the same name. Example for element class name upload : PHP class name: ConfigboxElementUpload File system path: /media/elovaris/configbox/customization/element_classes/upload/upload.php Methods you can extend: getprice($getnetprice, $getinbasecurrency) This method returns the price in the base currency, either gross or net (depending on the 2 parameters). The method must return a number of type float. If parameter 1 is not entered, the current system default has to be used (use the value of constant CONFIGBOX_SHOW_NET_PRICES), if parameter 2 is missing, then false is assumed. getpricerecurring($getnetprice, $getinbasecurrency) Analogue to getprice(), but used for the recurring price. loadtemplate() Use this method to output your own HTML instead of the default HTML output of the element in configurator pages. The implementation of this method writes the frontend HTML output of the element in the configurator into the output buffer. 5.4 Custom Fields Products, elements, options and option assignments have 4 to 6 custom fields you can use to enter any kind of additional. The purpose of these fields is not specific. Typical useful applications are: Usage in price calculations (see onscreen-help for detailed info) Usage in compatibility rules Usage in custom templates or element classes for output or applying custom logic Usage in connectors for integration with third party software For practical reasons, you can set your own labels of these fields in Settings -> Custom Fields. 5.5 Custom CSS styling Customizing CSS styling requires basic to moderate HTML and CSS skills. Custom styling can either be sufficient to amend styling of the shop or be used in combination with customized templates. ConfigBox comes with a style sheet specifically made for styling customizations. As all files in the customization folder, it is not overwritten during software updates. Location: /media/elovaris/configbox/customization/assets/css/style_overrides.css ConfigBox for Magento, Rovexo - Version 3.0 Last update: Oktober 19, 2015 Page 22

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

24 Some views split the content into multiple template files when it is more practical and use the output of other views within their template files when it makes sense. An example of this is the quotation view where order record information and position details come from the views record and positions. Workflow for overriding a template file 1) First you locate the view for which you want to make a customization. Take the cart as example: /app/code/local/elovaris/configbox/application/components/com_configbox/views/cart The cart view uses a single template file, named default.php (Future releases may have it split in multiple template files). Download or copy the template file, you typically want to use it as base of your customization. 2) Navigate to the folder for customized templates. The location is: /media/elovaris/configbox/customization/templates/ 3) In this folder you create a folder with the name of the view you like to override: /media/elovaris/configbox/customization/templates/cart 4) In this folder, you place the template file you like to override. Mind that you do not create the subfolder tmpl like you have it in the view folder. /media/elovaris/configbox/customization /templates/cart/default.php 5) You then make your customizations to that file as you see fit. Tips: In views with multiple template files, you can choose which ones to customize If you override only certain template files, the others will be loaded from the original view folder. This helps minimizing your efforts in case of breaking changes in software updates. Avoid CSS styling, adding images in places other than the customization folder Have a look at the chapter on custom CSS styling. You also have an image folder in your customization folder. This helps keeping your work well organized and quick to comprehend for colleagues and service providers. Make use of custom fields See section on custom fields for reference. You can access the data of these fields in the appropriate templates and use them for output, calculations or other logic. See tip on investigating template data for the best way to see where the data is stored. For multilingual sites, check the chapter on custom wording The software has an engine to make translated texts straightforward. Managing translated phrases is explained in that chapter. To make use of it for your own wording, you have a static PHP class method to output your translated phrases. Example: (Obviously, this code snippet needs to be placed within PHP tags). echo KText::_('Your phrase'); The phrase you use here must match the keyword used in your custom language file. So the line in your language file would look like this: ConfigBox for Magento, Rovexo - Version 3.0 Last update: Oktober 19, 2015 Page 24

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

26 Edit form for templates You edit templates using code coloring and formatting and you can also edit these files on the file system. 5.9 Custom Rule Conditions You can develop custom rule conditions. Developing these requires adept programming skills. Rovexo provides no free support or problem analysis for custom rule conditions How to develop a custom rule condition You develop a rule condition type and set up a list of conditions of that type. It is similar to the example conditions you see in the rule editor. These serve no actual purpose, but illustrate how it is done. ConfigBox for Magento, Rovexo - Version 3.0 Last update: Oktober 19, 2015 Page 26

27 You add a PHP class in the folder for custom rule conditions. The folder is in the customization folder in /rule_condition_types/ You pick a name for your condition type (like Example ). The PHP class needs to be called CustomCondition followed by your type name. So for type Example you got CustomConditionExample. The file name is called the same (CustomConditionExample.php). The class extends ConfigboxCondition. So you got class CustomConditionExample extends ConfigboxCondition. There are a few methods that need to be implemented. CustomConditionExample::getConditionsPanelHtml() CustomConditionExample::getConditionHtml($conditionData, $forediting = true) CustomConditionExample::getEvaluationResult($conditionData, $selections) getconditionspanelhtml() Each type gets a panel in the rule editor. This method returns the HTML to use for it. It essentially contains a list of conditions (the HTML of each condition has a certain structure, you will see more about it in the method getconditionhtml(). getconditionhtml($conditiondata, $forediting = true) This method takes the condition s data as parameter and returns the HTML for the condition. You see an example of the HTML in Example s PHP class, method CustomConditionExample::readMe(). The gist of it is that each condition is wrapped in a <span> Element with HTML 5 data attributes containing the condition s data. In the <span> is a human-readable name of the condition, the operator to choose from and a text field for the set point, the value the thing you test for should have. Those text fields have the CSS class input and a data attribute called data-condition-key that holds the key of the entry in the condition data. During saving, those text fields are stored like normal condition data, no need to have them as data in the wrapping <span> element. Whatever you add as condition data will stored when the rule is stored and will be available to you in the following method. See CustomConditionExample::readMe() for a line-by-line explanation of the HTML structure. getevaluationresult($conditiondata, $selections) ConfigBox for Magento, Rovexo - Version 3.0 Last update: Oktober 19, 2015 Page 27

28 This method is called when the condition is evaluated as part of the whole rule. $conditiondata contains everything that was set as $conditiondata in the previous method. $selections holds an array with the current configuration that is tested. The method has to return true or false. The method should be as fast as possible. Cache where you can since this method may be called multiple times each time a customer makes a selection in the configurator. See CustomConditionExample::readMe() for the concrete structure of both parameters What is Condition Data? Condition data is an array that has all the data to evaluate the condition during the configuration (via getevaluationresult()). In the rule editor each value is written as HTML 5 data attribute in the conditions HTML (in getconditionhtml()). Condition data in the Example type: Data Key Data Value Description type (required) Example The name of your condition s type name Condition 1, Condition 2, Condition 3 Only used for display fieldname field_1, field_2, field_3 Arbitrary values to use in evaluating the condition operator == The default operator for evaluating the condition shouldvalue (empty) will be populated by the user in the editor The value the thing to test for should have for the condition to be met. You can have as much condition data in your conditions as you need, the data will be available to you in the method getevaluationresult(). 6 Notes for ConfigBox upgrades Please check the compatibility notes at the download pages on for notes on compatibility on custom templates. 7 Troubleshooting Always check if you read and followed the instructions in the section Installation and the section ConfigBox upgrades. ConfigBox for Magento, Rovexo - Version 3.0 Last update: Oktober 19, 2015 Page 28

29 Pricing and Product Visualization does not update Checklist: Page Caching is active on configurator pages Remove/disable any page caching on configurator pages, since the page is dynamic and needs to be loaded fresh each visit. IonCube Loader is only active for certain directories Solution: See the chapter on Installation -> IonCube Loader on how to set up ioncube Loader correctly. Magento module conflicts Magento modules can conflict. This scenario becomes more likely if you use modules with similar purposes. Common reason is that multiple modules try to override the same Magento core model. In case you need to keep both conflicting modules you can consult a Magento developer to find a way to resolve the extension conflict. Please note that this may not be possible or prohibitively expensive and you may be forced to find an alternative for conflicting module. Please note that we cannot be held liable for module conflicts. Resolving module conflicts is the buyer s responsibility. Helpful information for developers: You can see the model rewrites that ConfigBox does in its config.xml. The amount of rewrites is not extensive and there is a good chance that conflicting modules override the same model but not the same model methods. See the module Modules Conflict Detector for help on identifying conflicts. ConfigBox for Magento, Rovexo - Version 3.0 Last update: Oktober 19, 2015 Page 29