How to Create A vQmod
Note: As of LiteCart 2.5.0+ vQmod has been replaced with vMod. Go to Admin → vMods to edit or create your vMods. The vMod system is backwards compatible with vQmod. But relying on vQmod is discouraged as it will eventually be removed completely.
The official vQmod wiki is available at https://github.com/vqmod/vqmod/wiki/.
Creating a vQMod has many benefits. It lets you disable it with a click if isn't working properly. It's not lost between version upgrades. It's easy to share with others. And it gives you great confidence when you master it.
A vQmod is an XML file containing instructions of what core file to modify in the platform and what changes to do to it. The elements of the file speak their names and is pretty much straight forward. File is to define a file, and Operations is to define something to do with it.
Lightweight Example
This is a minimal example of how to virtually modify pages/index.inc.php
and output Hello World before the content.
CDATA is being used to encapsulate the code blocks, so you don't need to escape special characters.
- ~/vqmods/xml/hello_world.xml
<?xml version="1.0" encoding="utf-8"?>
<modification>
<id>Hello World</id>
<version>1.0</version>
<vqmver required="true">2.4.0</vqmver>
<author>ACME Corp.</author>
<file name="pages/index.inc.php">
<operation error="log">
<search position="before"><![CDATA[
echo $page->stitch('views/index');
]]></search>
<add><![CDATA[
echo 'Hello World';
]]></add>
</operation>
</file>
</modification>
Cheat Sheet
This is a cheat sheet when making a new vqmod, showing all possible values for parameters. Use can it as your base for creating new vqmods.
- ~/vqmods/xml/sample.xml
<?xml version="1.0" encoding="utf-8"?>
<modification>
<id>Prototype</id>
<version>1.0</version>
<vqmver required="true">2.5.2</vqmver>
<author>ACME Corp.</author>
<file name="relative/path/to/file.php">
<operation error="skip|log|abort">
<search position="replace|before|after|top|bottom|ibefore|iafter" index="0" offset="0"><![CDATA[
... (single line matching only) ...
]]></search>
<add><![CDATA[
...
]]></add>
</operation>
<!-- Another operation ... -->
</file>
<!-- Another file ... -->
</modification>
Syntax
vQmod supports a number of parameters:
modification
modification / id
modification / version
modification / author
modification / file
This is the name of the file to modify
Requires attribute “name” as relative filename to the location of the main index.php file (e.g. catalog/controller/product/product.php). Can be delimited with commas to apply to multiple files at once (2.3.0 +) Name attribute supports a wildcard (*) character for dynamic path building. Each wildcard is limited to a single directory level.
catalog/view/theme/*/template/product/product.tpl
catalog/view/theme/*/*/product/product.tpl
etc
There can be multiple file tags in a single xml file. Each file can have its own set of operations
Optional attribute “path” can be used to prefix file name's to avoid repetition. This is simply prepended to the file names and _no_ validation is attempted (2.3.0 +)
Optional attribute “error” set to log|skip|abort
_skip_ means it will simply ignore this file.
_log_ is the same as skip, but logs the error. *(default)*
_abort_ means to log the error and cancel the remaining operations in that particular xml script. It does not revert changes to other files already made in that script and doesn't stop other xml files.
*Wildcard paths will ignore the “error” attribute completely*
modification / file / operation
This is the wrapper of the actual operation occurring.
There can be multiple operations to the same _file_ tag.
Optional attribute “error” set to skip|log|abort
_skip_ means all other operations will be applied even if one cannot. There will be no error in the log.
_log_ is the same as skip, but logs the error.
_abort_ means to log the error and revert to the original source. *(default)*
modification / file / operation / ignoreif
modification / file / operation / search
This is the first required step of the operation.
<font color=”#ff0000“><b>Can only search single lines</b></font>, both fully and partially. But _offset_ and _index_ attributes will assist.
Automatically trims whitespace and linebreaks
One `<search>` tag per `<operation>` tag
Use CDATA tags to wrap code.
Required attribute “position” set to before|after|replace|top|bottom|~~all~~|ibefore|iafter.
_replace_ will replace the data in the _search_ tag with the data in the _add_ tag. (default)
_before_ will insert the _add_ data before the _search_ data
_after_ will insert the _add_ data after the _search_ data
_top_ will insert the _add_ data at the top of the file. The _search_ data is ignored.
_bottom_ will insert the _add_ data at the bottom of the file. The _search_ data is ignored.
~~_all_ will completely replace all the code in the file with the _add_ data. The _search_ data is ignored.~~ Deprecated as of 2.4.0
_ibefore_ will insert the code before the search inline instead of the line before
_iafter_ will insert the code afterthe search inline instead of the line before
Optional attribute “offset” to work with the position
if the search position is before and offset 3 it will put the _add_ data before the line, 3 lines above the searched line
if the search position is after and offset 3 it will put the _add_ data after the line, 3 lines below the searched line
if the search position is replace and offset 3 it will remove the code from the search line and the next 3 lines and replace it with the _add_ data
if the search position is top and offset 3 it will put the code before the line, 3 lines below the top of the file
if the search position is bottom and offset 3 it will put the code after the line, 3 lines above the bottom of the file
Optional attribute “index” for specifying which instances of a search tag should be acted on
If the search string is “echo” and there are 5 echos in the file, but only want to replace the 1st and 3rd, use index=“1,3”
Comma delimited for multiple instances starting with “1”
Leave out or set to FALSE to replace all instances. (default)
Optional attribute “regex” for specifying whether or not to search a regex pattern.
If true, the _search_ data should be a valid regex pattern
Leave out or set to FALSE to use normal string search (default)
Does not apply to `ibefore` and `iafter`
Optional attribute “trim” set to true|false
modification / file / operation / add
This is the second required step of the operation.
Can be multiple lines
One `<add>` tag per `<operation>` tag.
Location of added data depends on the position attribute of the search command.
Use CDATA tags to wrap code.
*NEW IN 2.6.0*: `<add>` tag now supports all the search attributes.
*Attributes in the `<add>` tag will override attributes in the `<search>` tag.*
Optional attribute “position” set to before|after|replace|top|bottom|ibefore|iafter.
replace will replace the data in the search tag with the data in the add tag. (default)
before will insert the add data before the search data
after will insert the add data after the search data
top will insert the add data at the top of the file. The search data is ignored.
bottom will insert the add data at the bottom of the file. The search data is ignored.
ibefore will insert the code before the search inline instead of the line before
iafter will insert the code afterthe search inline instead of the line before
Optional attribute “offset” to work with the position
if the search position is before and offset 3 it will put the add data before the line, 3 lines above the searched line
if the search position is after and offset 3 it will put the add data after the line, 3 lines below the searched line
if the search position is replace and offset 3 it will remove the code from the search line and the next 3 lines and replace it with the add data
if the search position is top and offset 3 it will put the code before the line, 3 lines below the top of the file
if the search position is bottom and offset 3 it will put the code after the line, 3 lines above the bottom of the file
Optional attribute “index” for specifying which instances of a search tag should be acted on
If the search string is “echo” and there are 5 echos in the file, but only want to replace the 1st and 3rd, use index=“1,3”
Comma delimited for multiple instances starting with “1”
Leave out or set to FALSE to replace all instances. (default)
Optional attribute “regex” for specifying whether or not to search a regex pattern.
If true, the search data should be a valid regex pattern
Leave out or set to FALSE to use normal string search (default)
Does not apply to `ibefore` and `iafter`
Optional attribute “trim” set to true|false
<![CDATA[ ]]>
See Also