General theme integration guide

1. Technical background. Why aren't all themes 100% compatible with MultiMerch?

There are two specific reasons why not all themes work with MultiMerch out of the box.

First, MultiMerch relies on specific lines of code in theme files to display seller data. For example, MultiMerch may look for the product name element on the product page to display seller information after it. If your theme changes or removes OpenCart's product name field from the product page, MultiMerch won't be able to display seller information.

Second, MultiMerch has its own pages that don't exist in OpenCart. For example, seller dashboard and internal seller pages don't exist in OpenCart by default, therefore custom themes don't know anything about them. Since MultiMerch uses OpenCart's default theme (just like OpenCart itself), those pages may appear broken or out of style when a custom theme is installed.

2. Theme installation. How do I install a custom theme with MultiMerch?

If you are installing a custom theme on top of an existing MultiMerch installation:

  1. Install your custom theme as usual. This process may be different for each theme, so make sure to use the installation guide that comes with your theme.
  2. Copy MultiMerch template files from to your custom theme folder at catalog/view/theme/(your theme name)/template/. You need to copy the following files and folders:
    catalog/view/theme/default/template/multiseller/ 
    catalog/view/theme/default/template/account/register-seller.tpl
  3. Modify the vqmod/pathReplaces.php file and add the following line to the end of the file replacing yourtheme with the name of your theme's folder:$replaces[] = array('~\btheme/default\b~', 'theme/yourtheme');

If you are installing MultiMerch on top of OpenCart store running a custom theme:

  1. Install MultiMerch as usual per our Installation Guide.
  2. Copy MultiMerch template files from to your custom theme folder at catalog/view/theme/(your theme name)/template/. You need to copy the following files and folders:
    catalog/view/theme/default/template/multiseller/ 
    catalog/view/theme/default/template/account/register-seller.tpl
  3. Modify the vqmod/pathReplaces.php file and add the following line to the end of the file replacing yourtheme with the name of your theme's folder:$replaces[] = array('~\btheme/default\b~', 'theme/yourtheme');
This process makes MultiMerch use your custom theme, but doesn't guarantee 100% compatibility. If at this point things don't seem to work perfectly, proceed with the integration guide below.

3. Theme integration and troubleshooting. What if my theme doesn't work out of the box?

If you've installed and enabled your custom OpenCart theme with MultiMerch, but it doesn't work as expected, you need to perform one or more of the following troubleshooting and integration steps:

  • Adjust MultiMerch vQmod files
  • Tweak stylesheets
  • Modify MultiMerch templates

Adjusting MultiMerch vQmod Files.

If you've installed and enabled your custom theme, but no MultiMerch-related information appears in your store – seller information on the product page and the MultiMerch seller menu under customer account are the most common missing parts – you need to adjust the MultiMerch vQmod files for your custom theme.

When modifying a file, vQmod looks for specific pieces of code in it and uses those to insert the new code lines. The code in the custom themes usually differs from the default one, therefore vQmod fails to find and modify it – you need to adjust the MultiMerch xml files to point vQmod to the correct code.

This is done in 4 simple steps.

1. Loading the page in question
Navigate to the page where you expect new MultiMerch information to appear. In most cases, this is the product page, customer account page and cart. Normally, you would see a new seller menu, information about the seller for a specific product or any other information that is not present in OpenCart by default.

2. Finding the vQmod error message
If the MultiMerch information is missing, open up the latest vQmod log file. Those are usually stored under vqmod/logs/ and contain information about vQmod errors. If the issue is indeed caused by vQmod not being able to find the relevant code, you'll see this described in the log message – it will include the page where the error happened, the file in question and the exact line of code that caused vQmod to fail. This is what a typical vQmod error message will look like.

---------- Date: 2014-09-08 00:20:30 ~ IP : 127.0.0.1 ----------

REQUEST URI : /opencart/
MOD DETAILS:
modFile : /var/www/opencart/vqmod/xml/multimerch_core.xml
id : MultiMerch Digital Multivendor Marketplace Core
version :
vqmver :
author : http://multimerch.com/

File Name : catalog/view/theme/yourtheme/template/common/header.tpl(0)
VQModObject::applyMod - SEARCH NOT FOUND (ABORTING MOD): <?php foreach ($scripts as $script) { ?>
----------------------------------------------------------------------

The three important parts of the message you'll need are modFile, File Name and VQModObject::applyMod. Open up the xml file in question – vqmod/xml/multimerch_core.xml – and search for the specific code that causes the error.

It could look like this.

<file name="catalog/view/theme/&themeFolder;/template/common/header.tpl">
    <operation>
        <search position="before"><![CDATA[
            <?php foreach ($scripts as $script) { ?>
        ]></search>
        <add><![CDATA[
            <script type="text/javascript"> if (!window.console) console = {log: function() {}}; var config_language = <?php echo $dt_language; ?>; </script>
        ]></add>
    </operation> 
</file>

Note the code inside the <add> tag and keep the xml file open. You'll modify it in the last step.

3. Locating the correct code for your theme
We already know what caused the error – vQmod tried to find the line <?php foreach ($scripts as $script) { ?> in the common/header.tpl template as in was specified in the vqmod/xml/multimerch_core.xml file, and failed. Now we need to point vQmod to the correct code.

Open up the corresponding template in the default theme folder – catalog/view/theme/default/template/common/header.tpl – and find the code in question – <?php foreach ($scripts as $script) { ?>. Now, open up the same template in your theme folder – catalog/view/theme/default/template/common/header.tpl – and try to find out where the code you noted in the previous step would go if inserted correctly or where it would logically belong.

In our case, it's a piece of JavaScript code that belongs inside the <head> tag. You could modify your header template to insert the missing <?php foreach ($scripts as $script) { ?> code, but an easier solution is to modify the MultiMerch xml file and point vQmod to a different code that would still be logically correct.

4. Modifying the vQmod xml file
When you know the code that causes the error and a working alternative for your theme, simply modify the relevant xml file appropriately. In our case, that would mean replacing <?php foreach ($scripts as $script) { ?> with </head> in vqmod/xml/multimerch_core.xmlThis would make vQmod insert the script tag before the closing </head> tag, which is a perfectly correct place, and amend this vQmod error.

After the error is fixed, test other pages of your store to see if there are more vQmod issues and repeat the process described above for each of them. While it may look like complicated, it's really simple to do. Fixing each vQmod error doesn't usually take more than 5 to 10 minutes and since MultiMerch uses vQmod as little as possible, the whole vQmod fixing process shouldn't take you more then half an hour or an hour at most.

Make sure to consult the official vQmod project page for the description of vQmod's inner workings and the xml file syntax – this will make the process of modifying vQmod xml files easier for you.

Tweaking Stylesheets

After the vQmod issues are amended, you will be able to view the MultiMerch information and load various seller-related pages. Depending on the styling of your theme, they will either look fine or will have various styling issues – images of incorrect sizes, wrong fonts, buttons looking differently and such.

In this case you'll need to modify the MultiMerch styles to match your theme's style. All MultiMerch style definitions are located inside the catalog/view/theme/yourtheme/stylesheet/multiseller/multiseller.css stylesheet. Feel free to modify the styling defined here to make the elements match your theme's style.

Modifying Templates

In the worst case scenario, your theme may have such a different template layout compared to the default one, that simply modifying stylesheets will not be enough. In this case, you'll need to modify MultiMerch template elements to make them suit your custom theme. This may include adding or removing classes from different elements, replacing elements with different ones or changing the element order completely.

The best approach here is to open one of your theme's templates – for example, the buyer account template if you're adjusting seller account pages – and copy the element names, classes and order into the relevant MultiMerch templates. All MultiMerch templates are located under catalog/view/theme/yourtheme/template/multiseller/.

This last step is usually the most time consuming one. However, in most cases you'll be able to achieve the desired compatibility level with stylesheet modifications only, so template modifications are rarely used.

4. Professional integration services. What do I do if this guide is too technical for me?

If you can't get your custom theme to work with MultiMerch after following this guide or if it seems too difficult for you, you may want to look for someone to help you do it. There are a few different options:

Depending on the theme, making it 100% compatible with MultiMerch may take between a few hours and a few days.