General Troubleshooting Guide for LiteMage

When using the Magento Connect manager with certain browsers you may receive an “Exception during cache and session cleaning” error message in the Magento Connect output frame when attempting to either install or reinstall LiteMage. If this occurs, your Magento site will become stuck in maintenance mode and therefore be inaccessible.

The reason for this is that when Magento Connect attempts to install any new modules to your store, it first creates a “maintenance.flag” file in the root directory. The presence of this file signals that your site is now in maintenance mode and changes can be safely made. Under normal circumstances this file should be automatically deleted once the installation has completed, but certain errors (such as this one) can cause Magento Connect to halt before reaching the removal step.

To fix this simply delete the “maintenance.flag” file from the root folder of your affected Magento site.

This issue is known to occur in the following browsers: Firefox

It is recommended to enable certain IPs when troubleshooting. To enable, from the Magento Admin Panel navigate to System → Configuration and in the left side menu under “LITEMAGE CACHE” click “LiteMage Configuration”. Under “Developer Testing” add the desired IPs to the “Enable LiteMage Cache Only for Listed IPs” field.

Use your browser's developer tool to check the response header for the HTML file. This can usually be done by right clicking on the page and selecting some form of “Inspect”. Then click on the “Network” tab in the inspector and reload the page. If you see “X-LiteSpeed-Cache: hit,litemage” in the response header for the HTML file(usually listed first), then the page is being served by LiteMage Cache.

You may want to confirm whether or not an issue on a particular site is being caused by LiteMage Cache being enabled but do not want to disable LiteMage Cache for everyone. You can do this by adding the GET parameter “LITEMAGE_DEBUG=NOCACHE” to the site's URL which will cause the page to not be served by LiteMage (available since 1.0.2).

For example: Enable LiteMage cache for your store and test the following URL:

http://your-magento-domainname/home-decor/books-music/alice-in-wonderland.html

Check the HTML response header for “X-LiteSpeed-Cache: hit,litemage”, as detailed in “How to check if a page is served from LiteMage Cache” above.

Now to see the same page not being served by LiteMage, simply append “?LITEMAGE_DEBUG=NOCACHE” to the end of any URL. For example:

http://your-magento-domainname/home-decor/books-music/alice-in-wonderland.html?LITEMAGE_DEBUG=NOCACHE

When checking the HTML response header for the page, “X-LiteSpeed-Cache: hit,litemage” should no longer be listed.

This is the quickest way to debug LiteMage for specific URLs.

From LiteMage Extension 1.0.2 onwards, you can identify punched holes in a page by adding the Get parameter “LITEMAGE_DEBUG=SHOWHOLES”. Do this by appending “?LITEMAGE_DEBUG=SHOWHOLES” to the end of any LiteMage enabled URL. The injected blocks on the page will now be highlighted except for valueOnly blocks.

For example:

http://your-magento-domainname/home-decor/books-music/alice-in-wonderland.html?LITEMAGE_DEBUG=SHOWHOLES

LiteMage may not work properly with websites that have separate Mobile versions using a different skin than the default (non-responsive design).

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} "Mobi"
RewriteRule .* - [CO=ismobile:1]

Next in the Magento Admin Panel, Navigate to System → Configuration and under “LITEMAGE CACHE” click “LiteMage Configuration”. Under “General Settings” look for the “Separate Cache Copy for Customized Cookie Values” field and add “ismobile” to it.

LiteMage will work well with any responsive design without the need to perform the above steps. We recommend using a responsive design over implementing a separate mobile version of your site.

LiteMage supports this feature as of version 1.0.1.

Note: This cookie is set independent of the domain and will only be set in the request header. It is only a temporary cookie used between LSWS and LiteMage and therefore will not affect the browser cookie.

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.

Some customized themes may reference user initialized global PHP variables in injected blocks. When those ESI blocks render, null pointer errors will occur as those variables may have been initialized earlier but the injected block has no way of recognizing them.

For example, for SNS themes: the footer template may fail to output due to the variable “$var_snstheme” actually being initialized in the header block.

Solution: Make a copy of the footer.phtml file. Find the code where this variable is initialized and update the footer template to initiate this variable by adding the following 2 lines to page/html/footer.phtml after “global $var_snstheme;”. For Example:

global $var_snstheme;
if (empty($var_snstheme)) {
    include (dirname(dirname(__FILE__)).'/sns/sns.php');
}

Alternatively you can remove footer block injection. This however will slow down page loading time as well as increase cache size and is hence not recommended.

If a global variable in javascript is initialized based on user session data and saved in a public cache, then it will cause trouble for other users with differing session data.

As of version 1.0.2, a place holder block for javascript variables has been introduced. This place holder is a private block, so every user will get his/her own correct value.

Check the code:

code/community/Litespeed/Litemage/Block/Inject/Jsvar.php

You can also write your own code to customize this block. Please be sure to keep a copy of your customized code in a local directory to avoid it being overridden during LiteMage updates.

You generally do not need to modify the block code and can instead just modify the template associated with that block.

app/design/frontend/base/default/template/litemage/inject/jsvar.phtml

For example: “isLoggedIn” is used by an SNS ajax cart for wishlists. In LiteMage's config.xml file located under magento_install_directory/app/code/community/Litespeed/Litemage/etc, this block, “litemage.jsvar”, is listed under “welcome” and will be purged by logged_in/out events.

If you have any other variables based on events not already represented in LiteMage's config.xml file, you can add them in as new blocks in the “esiblock” section. (Be sure to add a LiteMage ESI observer for these events as well)

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, in litemage config.xml, you need to add in that block the attribute <valueonly/> 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.