LiteMage Cache Customization

This page is dedicated to covering common methods of customizing LiteMage Cache for different use cases.

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.

Hole-punching Dynamically Created Blocks From A Template

As of LiteMage 1.0.6, you can now hole-punch dynamically created blocks from a template. LiteMage injects after the layout files are loaded and all blocks are generated. This works for most cases, but when a template block is rendering, it can dynamically create a block that is not defined in the layout file.

For example, in a customized template, the “customer/form_login” block can be overridden with a local implementation. This local implementation will be displayed in the block header, such as:

default/ma_pisces_sport/template/page/html/header.phtml:

<?php echo
$this->getLayout()->createBlock('customer/form_login')->setTemplate('customer/form/mini.login.phtml')->toHtml(); ?>

This block contains private information for the logged in customer, and so a hole must be punched here. Unfortunately LiteMage would have no knowledge of this new block. In order to notify LiteaMage to inject here, you must add a special attribute to the block. You need to change the above code to conatain two new parameters, “litemage_dyn1” and “$litemage_attr”:

<?php
  $litemage_attr = array('litemage_dynamic' =>
                      array('tag' => 'welcome', 'access' => 'private', 'type' => 'customer/form_login',
                            'template' => 'customer/form/mini.login.phtml'));
echo $this->getLayout()->createBlock('customer/form_login', 'litemage_dyn1',
$litemage_attr)->setTemplate('customer/form/mini.login.phtml')->toHtml(); ?>

“litemage_dyn1” is any unique block name. For example, if you have a second dynamic block, you need to name it something like “litemage_dny2” to keep it unique.

“$litemage_attr” contains the following injection information:

• “litemage_dynamic”: A fixed key string that LiteMage uses to detect this special block attribute.
• 'tag': (Optional) The default value is 'welcome' which will purge by log in/log out events. You can also set this to any tag previously defined in “config.xml”. If you need to define a new purge event or combination of purge events for this block, create a new tag in “config.xml” with the desired purge events and use that tag value here.
• 'access': Can be set to either “public” or “private”.
• 'type': The first parameter in the createBlock() function.
• 'template': (Optional) If the block has a template set, as in the above case, you must provide that template here.

LiteMage will detect this special block attribute by the fixed key string “litemage_dynamic”, which you can also see above.

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 the <frontend> → <litemage> → <esiblock> section of 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. Can contain letters, digits, and the following special characters: '.','_',and '-'. Do not use any spaces.
  
• <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 like to add additional purge events not currently present in LiteMage's “config.xml” file, you can do so by adding the event and its observer to the <frontend> → <events> section. The general structure for a purge event is:

<magento_event_name>
  <observers>
    <litemage_esi>
      <class>litemage/observer_esi</class>
      <method>purgeEsiCache</method>
    </litemage_esi>
  </observers>
</magento_event_name>

Where:

• <magento_event_name>: The name of a new existing Magento event not currently present in the <events> section.

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

LiteMage's “config.xml” file contains a rewrite for Magento's translate line to fix a bug. If you intend to only use a single language for your store, you may remove this rewrite for a possible performance improvement. The rewrite is located near the start of “config.xml” in <config> → <global> → <models> and will look like the following:

<core>
  <rewrite>
    <translate>Litespeed_Litemage_Model_Translate</translate>
  </rewrite>
</core>

As of LiteMage 1.0.8, we have introduced two new fields to LiteMage's “User-Defined Cache Rules” under System » Configuration » LITEMAGE CACHE » LiteMage Configuration in the Magento Admin Panel. These fields are “Customized Block Names for 'welcome' Tag ” and “Customized Block Names for 'toplinks' Tag”, which are input as comma separated lists.

Both the “welcome” and “toplinks” tags are predefined in LiteMage's “config.xml” file, with “welcome” blocks being purged by log in/out events and “toplinks” blocks being a composite grouping of both the “cart” and “wishlist” tags, which will be purged by cart and wishlist changes respectively.

While these changes can still be made within LiteMage's “config.xml” file, it is more convenient to do so through these fields. The reason for this is that when LiteMage is updated, it's “config.xml” file is overwritten, requiring you to re-add these changes to the new file with every update. But, if these changes are made through LiteMage's configuration settings in the Magento Admin Panel, the changes are saved to the Magento database and will remain persistent through updates; no need to re-add!

(It is not necessary to have other predefined tags configurable from within the Magento Admin Panel as they are already intelligently detected by class type, which would cover most use cases.)

LiteMage may not work properly with websites that have separate Mobile versions using a different skin than the main site.

In such cases, you can tell LiteMage to cache the website's Mobile version differently than the main version so they are not mixed up. Do this by adding the following to the .htaccess file:

RewriteCond %{HTTP_USER_AGENT} android|avantgo|blackberry|blazer|compal|elaine|fennec|hiptop|iemobile|ip(hone|od)|iris|kindle|lge\ |maemo|midp|mmp|opera\ m(ob|in)i|palm(\ os)?|phone|p(ixi|re)\/|plucker|pocket|psp|symbian|treo|up\.(browser|link)|vodafone|wap|windows\ (ce|phone)|xda|xiino [NC,OR]
RewriteRule .* - [E=Cache-Control:vary=ismobile]

LiteMage supports this feature as of LSWS version 5.0.7.

Important: Your rewrite rules must exactly match your backend's mobile detection. If these do not match, you may run into the issue where your rewrite rules think that a device is mobile while the backend does not and visa-versa. This can cause, for example, the desktop version of a page to be cached and flagged as the mobile version which will then be wrongly served to all mobile viewers.

This is a feature as of version 1.0.1. To enable it, you should add the customized cookie name in the configuration. Do this from the Magento Admin Panel by navigating to System → Configuration and under “LITEMAGE CACHE” click on “LiteMage Configuration”. Then under “General Settings” look for “Separate Cache Copy for Customized Cookie Values” and add the customized cookie name to the list.

Private holes can only be punched at the block level. If a piece of private information does not have its own block, we have to add a block in order to inject the ESI process.

For example, a user review input form is integrated into a product page by a customized theme. The form can be varied according to each product, and the default nickname is varied by each logged in user. You cannot simply configure the whole page/block to be private.

As of version 1.0.2, sample code has been added to demonstrate how to handle private information inside of a public block. There are a few steps to be followed.

• In the corresponding layout file, add a block. For example: customized_theme/layout/catalog.xml

old:

              <block as="review_form" name="product.review.form" template="review/form.phtml" type="review/form"/>

new:

               <block as="review_form" name="product.review.form" template="review/form.phtml" type="review/form">
                  <block type="litemage/inject_nickname" name="nickname" as="nickname"/>
              </block>

The sample code is shipped by default under Litemage/Block/Inject/Nickname.php.

• Modify the template to use the newly injected block for the value.

old:

<input type="text" name="nickname" id="nickname_field" class="input-text required-entry" value="php echo $this->htmlEscape($data->getNickname()) ?>" required/>

new:

 <input type="text" name="nickname" id="nickname_field" class="input-text required-entry" value="<?php echo $this->getChildHtml('nickname') ?>" required/>

• Since this is inside the value quote, you must add $v after the block name or block type in LiteMage's config.xml to avoid extra info/debug info from being output to browser.

Again, if you have any customizations, please make these changes in your local directory or create a backup as they will otherwise be overridden by future LiteMage updates.

If you are using customized messages blocks not derived from “Mage_Core_Block_Messages”, such as what is talked about in inchoo's Fancy Magento Global Messages article, LiteMage may have trouble detecting these message blocks automatically.

As of LiteMage 1.0.9, we have added both support and a convenient new customization field in the Magento Admin Panel under System » Configuration » LITEMAGE_CACHE » LiteMage Configuration called “Customized Block Names for 'message' Tag” that can be used to define customized message blocks that render from a template.

All you have to do is add the name field from the same XML tag you used to define your block type to the the comma separated list “Customized Block Names for 'message' Tag”. If we use the previously mentioned inchoo article as an example, this tag would look like:

<block type="core/template" name="inchoo_global_messages" template="core/inchoo_global_messages.phtml" before="-" />

Where we would add “inchoo_global_messages” to the “Customized Block Names for 'message' Tag” list. This also has the added benefit of being saved to the Magento database, meaning you will not be required to re-apply these changes when updating as you would in LiteMage's “config.xml” file.