Custom Templates

Customising templates requires moderate PHP programming skills and related skills like HTML/JS/CSS depending on the extend of your customisations.

ConfigBox output is organised in views as part of ConfigBox' MVC pattern (e.g. product listing, cart, checkout, admin order page etc.). Each view has a template file (or multiple ones) responsible for output in the browser and these template files can be customised.

Important: As with any customisation, custom templates may need to be checked and changed for compatibility on software updates. In the ConfigBox client center you find detailed information on breaking changes for each software update.

Base folder locations in Joomla and Wordpress

In the following we refer to the appDir, which is this on each platform:

Joomla: /components/com_configbox/
Wordpress: /wp-content/plugins/configbox/app/
Magento 2: /vendor/rovexo/configbox-php/src/Rovexo/Configbox/

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

In appDir/views you find sub-folders for each view that ConfigBox uses for displaying pages. This is called a view folder. Each view folder contains a PHP file called view.html.php that handles preparation of the data in the template.

Each view folder also contains a sub-folder called tmpl that contains a template file that is typically named default.php. The HTML produced in this template file is what you are going to see as content on your page.

Some views split the content into multiple template files when it is more practical and use the output of other views within their template files when it makes sense. An example of this is the quotation view where order record information and position details come from the views ‘record’ and ‘positions’.

Workflow for overriding a template file

1. First you locate the view for which you want to make a customisation. Take the cart as example:

/appDir/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 template overrides.

Mind where is your customization directory, this differs between Joomla, Wordpress and Magento. The location is in {customizationDir}/templates/

3. In this folder you create a folder with the 

name of the view you like to override: {customizationDir}/templates/cart

4. In this folder, you place the 

template file you like to override. Mind that you do not create the sub-folder tmpl like you have it in the view folder.

{customizationDir}/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 a 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 

See the chapter on custom CSS styling and custom JavaScript. 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 straight-forward. Managing translated phrases is explained in the chapter custom Wording and Translations. To make use of it for your own wording, you have a static PHP class method to output your translated phrases.

Example:

Then add this to your custom language file

Investigating data provided in the template files (Joomla only)

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:

http://extensions.joomla.org/extensions/miscellaneous/development/1509

Example (Obviously the variable used here must exist and the call be placed in PHP tags):

Use an IDE like PHPStorm to get code completion, code jumping and help texts

We have made great efforts to code documentation and when editing templates you get auto-completion and help texts for most data you work with.

Make use of the log files for debugging

ConfigBox logs errors, warnings, notices and other diagnostic information extensively. The log files can be useful in case you work directly on a remote server and do not have access to the server’s error log files. On Joomla, you find a sub folder called 'configbox' in your Joomla log folder, on Wordpress you find a folder called /logs in your WP site's main folder.

Mind that CB logs all PHP messages encountered during the runtime, which includes messages triggered by other extensions. Check the file path mentioned in the log messages to see what triggered the message.