LiteMage's “config.xml” file, located under “app/code/community/Litespeed/Litemage/etc/config.xml”, is based on Magento's sample store data. If you have a customized Magento setup, you may need to add additional ESI blocks or events there.

Block Type Denoted By “T:“

In previous versions of LiteMage you needed to explicitly change or add blocks that have been re-named by installed extensions. As of version 1.0.4, most custom blocks will be detected automatically by type.

For example, the “cart” block should look something like this:

 <cart>
   <access>private</access>
   <blocks>T:Mage_Checkout_Block_Cart_Abstract</blocks>
   <purge_events>
     <sales_quote_save_after/>
   </purge_events>
 </cart>

Where instead of listing out each individual “cart” block by name in the <blocks> section, we use the type indicator prefix “T:” along with the inherited Magento class for “cart” type blocks to get “T:Mage_Checkout_Block_Cart_Abstract”. Now any blocks that inherit this type will be automatically detected and included.

Purge Tags

Also new in LiteMage 1.0.4 are the inclusion of purge tags. These changes the block into a composite block that uses the combined purge events of other existing blocks without having to redefine those purge events in the block itself.

For example:

<toplinks>
  <access>private</access>
  <blocks>top.links</blocks>
  <purge_tags>cart, wishlist</purge_tags>
</toplinks>

Here the “top.links” block is using the purge tags “cart” and “wishlist” instead of explicitly re-listing these purge events for these blocks in a <purge_events> section. This will cause the “top.links” block to be purged whenever an event would cause either the “cart” or “wishlist” blocks to be purged.

Valueonly Blocks Denoted By “$v”

Marking a block as valueonly will keep the HTML tags and comments surrounding a value in an HTML text field from being output when in debug mode. This is important in keeping behavior consistent between viewing a page normally or in debug mode. Valueonly blocks will also not appear when using the “LITEMAGE_DEBUG=SHOWHOLES” parameter to highlight injected blocks on a page.

To mark a block as valueonly, use the suffix “$v”. For example:

<welcome>
  <access>private</access>
  <blocks>welcome, litemage.jsvar,nickname$v</blocks>
</welcome>

Where the “nickname” block has been marked as valueonly.

Note: When testing, be sure to use “Enable LiteMage Cache Only for Listed IPs” (see full explanation in the Configuration Notes section below). This setting specifies certain IPs that will test caching while other IPs are served normally.

Custom ESI Block Structure

ESI blocks are grouped by common purge events. If you feel as though none of the current groupings fit what you want to accomplish, you can add your own custom grouping to LiteMage's “config.xml” file. The general structure for an ESI block is:

<Unique Group Tag>
  <access> ...  </access>
  <blocks> ... </blocks>
  <purge_events> ... </purge_events>
  <purge_tags> ... </purge_tags>
</Unique Group Tag>

Where:

• <Unique Group Tag>: The unique name you want to assign this grouping.
  
• <access>: Can be set to “public” or “private”.
  
• <blocks>: A combination of block types (where all blocks that inherit this type will automatically be included) and individual block names.
  
• <purge_events>: A combination of events present in the <frontend> → <events> section that, when triggered, will cause this grouping of blocks to be purged.
  
• <purge_tags>: A list of the “Unique Group Tags” of other ESI block groupings. The triggering of purge events for any grouping present in this list will also cause this grouping to also be purged.

Your custom grouping can either use purge events, purge tags, or both.

Custom Purge Events

If you would also like to add a new purge event for this grouping, you can do so by adding the event and its observer to the <frontend> → <events> section of LiteMage's “config.xml” file. The general structure for a purge event is:

<Unique Event Tag>
  <observers>
    <litemage_esi>
      <class>litemage/observer_esi</class>
      <method>purgeEsiCache</method>
    </litemage_esi>
  </observers>
</Unique Event Tag>

Where:

• <Unique Event Tag>: The unique name you want to assign this purge event.

This uses the predefined “purgeEsiCache” method to purge any ESI block groupings using this purge event from the cache whenever this event is triggered.

Updating LiteMage will overwrite LiteMage's “config.xml” file. Before you update, make sure to copy and save your “config.xml” file if you have made any customizations.

• LiteMage's default configuration should be suitable for testing.
• Please read the comments for each configuration option before adjusting them.
• Detailed notes on certain settings are also provided in the “Notes on Specific Configuration Settings” section below.

• Default Private Cache TTL: Should not be set higher than the Cookie Lifetime setting (System → Configuration → Web). The default Cookie Lifetime value is 3600.
• Enable Cache Warm Up: Because LiteMage is encrypted, the Magento cron.sh must use a PHP with IonCube Loader. Updating the cron.sh PHP_BIN setting to “PHP_BIN=/usr/local/lsws/fcgi-bin/lsphp5” will connect it to LSWS's PHP. (How to set up the Magento cron job: http://www.magentocommerce.com/wiki/1_-_installation_and_configuration/how_to_setup_a_cron_job )
• Enable LiteMage Cache Only for Listed IPs: This setting is used to allow administrators to test caching from certain IPs on a production server. When you are ready to use LiteMage Cache for all users, leave this setting blank. After updating this setting, flush LiteSpeed's cache (System → Cache Management). This will get rid of the cached copies made during testing (which cannot be served to normal users).
• Flush LiteMage Cache: The Flush LiteMage Cache button (under System → Cache Management) flushes all public and private caches. Cache Warm Up (if enabled) will also be started automatically after the cache is flushed.
• Each Magento installation requires a unique cache storage. If your server hosts multiple Magento installations, you must set up different cache storage paths for each installation. Follow the steps below to do so:
  • If you are using LiteSpeed-native virtual hosts, different storage paths can be set in the WebAdmin → Configuration → Virtual Hosts → your virtual host → Cache →Storage Path setting.
  • If you are using Apache configuration files, different cache storage paths can be set using the CacheRoot directive in your Apache virtual host configurations as follows (This must be put in the virtual host include file, .htaccess cannot be used.):

<IfModule Litespeed>
CacheRoot /path/to/vhost/cache/root/
</IfModule>