How To Create a vMod

As of LiteCart 2.5.0+ there is a vMod editor included in the platform that simplifies the process of creating a vMod. Go to Admin -> vMods and click "Create New vMod".

vMod is a virtual modification technology developed by the author of LiteCart and launched with LiteCart version 2.5.0. It replaces the previously included third party technology called vQmod. The vMod system is backwards compatible with vQmod. But relying on vQmod is discouraged as it is scheduled to be removed completely in LiteCart 3.0.

vMod focuses on simplicity and being lightweight. It also introduces features previously not seen in vQmod. Some of the noteworthy differences are:

Super optimized and simple. A little over half the footprint of vQmod (16 kb instead of 26kb).
String aliases allow you to define one value for all occurrences in the file.
Configurable with user defined settings
Multi-line matching supported
Allowing line offsets both before AND after.
Cache serializing to JSON instead of PHP serialize() allowing up to 300% faster performance in fetching cache.
Regular expression path aliases

Basic Example

vmods/my_fancy_addon.xml:


<?xml version="1.0" encoding="UTF-8"?>
<vmod>
  <name>My Fancy Add-on</name>
  <description>This is an example modification</description>
  <version>1.0</version>
  <author>acme.com</author>

  <file name="path/to/file.php">
    <operation method="replace" type="multiline">
      <find><![CDATA[
        I like green tomatoes.
      ]]></find>
      <insert><![CDATA[
        I like green apples.
      ]]></insert>
    </operation>
  </file>
</vmod>

Full Cheat Sheet

<?xml version="1.0" encoding="UTF-8"?>
<vmod>
  <name>Sample</name>
  <description>This is a sample modification</description>
  <version>1.0</version>
  <author>acme.com</author>
  <priority>0</priority>

  <alias key="foo" value="bar" />

  <setting>
    <title>Foo</title>
    <description>Description of foo.</description>
    <key>foo</key>
    <function>text()</function>
    <default_value>bar</default_value>
  </setting>

  <install><![CDATA[
  ...PHP code that runs during install...
  ]]></install>

  <uninstall><![CDATA[
  ...PHP code that runs during uninstall...
  ]]></uninstall>

  <upgrade version="1.1"><![CDATA[
  ...PHP code that runs after installing an update...
  ]]></upgrade>

  <file name="path/or/glob*/to/{file1,file2}.php">
    <operation method="top|bottom|before|after|replace|all" type="multiline|inline|regex" onerror="warning|ignore|cancel">
      <find indexes="1,3" offset-before="0" offset-after="0"><![CDATA[
        ...
      ]]></find>

      <insert><![CDATA[
        ...
      ]]></insert>
    </operation>
  </file>
</vmod>

Examples

Inline Matching

    <operation method="replace" type="inline">
      <find><![CDATA[oranges]]></find>
      <insert><![CDATA[apples]]></insert>
    </operation>

Multiline Matching

    <operation>
      <find method="replace" type="multiline"><![CDATA[
        I like apples.
        I like oranges.
      ]]></find>
      <insert><![CDATA[
        I like apples and oranges.
      ]]></insert>
    </operation>

Regular Expression Matching

    <operation method="replace" type="regex">
      <find><![CDATA[#^I like (apples)\.$#m]]></find>
      <insert><![CDATA[I don't like $1.]]></insert>
    </operation>

Full Page Replacement

    <operation method="all" type="multiline">
      <find />
      <insert><![CDATA[
        <?php full_page_code(); ?>
      ]]></insert>
    </operation>

Or using regular expressions:

    <operation method="replace" type="regex">
      <find><![CDATA[#^.*$#s]]></find>
      <insert><![CDATA[<?php full_page_code(); ?>]]></insert>
    </operation>

Alias

Alias is a way to define a repetitive value or content.

  <alias key="foo" value="bar" />

A defined alias will be substituted for all occurences of {alias:keyname} in the code with the defined value. It could be used for repetitive blocks of code or single values. Whatever is convenient to replace with an alias.

      <insert><![CDATA[
        echo '{alias:keyname}';
      ]]></insert>

Settings

Settings will allow the merchant to configure the vMod by collecting user defined settings. The settings will be output in the code by the use of a snippet tag {setting:keyname}.

  <setting>
    <title>Foo</title>
    <description>Description of foo.</description>
    <key>foo</key>
    <function>text()</function>
    <default_value>bar</default_value>
  </setting>

The example above will produce an alias {setting:foo} that is substituted in the code with the actual value configured by the merchant. Example $foo = '{setting:foo}';

For a list of helper functions that can be used for setting values see form_draw_function() in includes/functions/func_form.inc.php. Commonly used functions are text(), textarea(), password(), number(), decimal(), date(), toggle("y/n"), select("a","b").