In this blog post we will be looking at how to create a vqMod file which allows safe OpenCart customisations. First off, lets look at vqMod and why it is essential for scalable OpenCart Development.
What is OpenCart vqMod?
OpenCart is built upon a core system of template files, controllers and models which all interact with the database, shape the data and then display it in a certain way. OpenCart Developers, like myself, make a living from shaping the store to perform different tasks and enhance its abilities. However, what happens when you need to upgrade the OpenCart system or you install another module which overwrites another? Incompatibility issues and upgrading difficulties are one of the reasons that OpenCart is not as widely deployed as some other eCommerce stores.
Enter vqMod! This is a virtual file replacement system which offers a very useful “Search & Replace” which allows you to edit how files work without actually changing the original file. For example:
I have an OpenCart page which sits on the server. This file has a single line of text:
I am just a file!
Now, if OpenCart was working normally it would display the page as it was without changing anything and a developer might go into the file and change the text manually. With vqMod however, the file gets checked against any vqMod rules which sit on the store. If the filepath matches a rule in the vqMod folder then OpenCart runs the search and replace.
My example vqMod file effectively says:
- Check if this file is being displayed by OpenCart
- If it is, look for this line of code
- If you find it, change it for this replacement
- Rinse and repeat
So, the file on the server stays exactly the same but my vqMod file can change the text which is displayed safely by getting in the middle of the transfer process. So the output of the file would be:
I am a file which has been edited for the store!
This is a great system because it means that you can change the way OpenCart works but leave the core system intact which makes it much easier to upgrade and install modules without getting messy files all over! For all modules which are being installed I would recommend choosing ones which are vqMod files or modules which do not overwrite any files in OpenCart as it can cause you so many issues down the line.
How to create a vqMod file
OK, now to the good stuff. Here I’ll show you how to create a vqMod file for OpenCart, it’s dead simple as it is just an XML file and the tough bits are finding the original code samples to replace and ensuring the filepath is correct. For the purposes of making this tutorial easier, I’ll show you how it is all laid out and then go through step by step as we build one from scratch to change the “Powered By OpenCart” link at the bottom!
Right, so here is a sample vqMod file:
<modification> <id>Replace ABC with 123</id> <version>1.0</version> <vqmver>2.X</vqmver> <author>xxx</author> <file name="path/to/myfile.php"> <operation info="replace ABC with 123"> <search position="replace"><![CDATA[ $var = 'ABC'; ]]></search> <add><![CDATA[ $var = '123'; ]]></add> </operation> </file> </modification>
Right, lets go through what it all means (I got this example from the OpenCart vqMod website which is definitely worth a look at as well as this post)
<?xml version="1.0" encoding="UTF-8"?> <!--SET THE START OF THE VQMOD FILE MODIFICATION--> <modification> <!--GIVE YOUR VQMOD FILE A TITLE SO YOU KNOW WHAT IT DOES AT A GLANCE--> <id>Replace ABC with 123</id> <!--VERSION NUMBERS, LEAVE VQMOD THE SAME BUT CHANGE <VERSION> TO TRACK YOUR CHANGES--> <version>1.0</version> <vqmver>2.X</vqmver> <!--STEP INTO THE LIMELIGHT, PUT YOUR NAME HERE--> <author>xxx</author> <!-- IMPORTANT: ENSURE THIS IS DEFINITELY CORRECT! IT NEEDS TO BE A RELATIVE LINK SO DON'T PUT HTTP://WWW.[YOUR DOMAIN].COM. YOU CAN ALSO PUT A * TO DENOTE A FOLDER YOU DON'T KNOW THE NAME OF. USEFUL FOR MAKING CUSTOMISATIONS WHICH APPLY NO MATTER WHAT THE THEME IS. AN EXAMPLE IS: CATALOG/VIEW/THEME/*/TEMPLATE/COMMON/HEADER.TPL --> <file name="path/to/myfile.php"> <!--INFO ON WHAT THIS PARTICULAR FUNCTION DOES--> <operation info="replace ABC with 123"> <!--THE CODE TO LOOK FOR, WE'll TALK ABOUT THE POSITION LATER--> <search position="replace"><![CDATA[ $var = 'ABC'; ]]></search> <!--THE CODE TO REPLACE IT WITH--> <add><![CDATA[ $var = '123'; ]]></add> <!--END THE OPERATION--> </operation> <!--STATE YOU'RE FINISHED WITH THE FILE CHANGES> </file> <!--CLOSE THE VQMOD--> </modification>
OK, so now you can see the basics of how to create a vqMod file for OpenCart. These work across all versions of OpenCart because you simply need to find what to replace and choose what you want to replace it with. Now, in the next section I will go through some of the more advanced search and replace filters and you can have a crack at them if you want.
Advanced vqMod search & replace filters
In the previous example I have used the basic “replace” function which is shown with the follow line:
This line tells OpenCart to actually delete the line and then put something else in its place but with a slight change we can make it act differently. See some of the examples below:
vqMod: Add before the line
This line tells OpenCart to find the line but leave it intact, adding a line before it and then moving onto the next search term.
vqMod: Add after the line
Exact opposite of the previous example. OpenCart finds the line and adds the replacement as a line after it appears, leaving it intact.
There are more examples which can find on this page, however to keep this post relatively easy to follow I’ll just include what I have so far. If you have any questions feel free to leave me a comment below and let me know how you get on building OpenCart vqMod files.