Custom Layout Handles Magento Extension

version 1.0.0

This extensions has the ability to add various XML Layout handles or body classes which can then be used in the customized themes. It can for example add XML Layout handles for various category related information or the currently loaded module.

Disclaimer

This is the installation and user manual for the Custom Layout Handles extension created by Solide Webservices. Although great care has been taken to ensure the accuracy and completeness of this manual, Solide Webservices is unable to accept any legal responsibility concerning errors or ommisions in this document.

You are not allowed to copy or edit the content or the layout of this document. If you would like to redistribute the content of this document please contact Solide Webservices through email: contact@solidewebservices.com

Installation, Upgrade and Deinstallation

This extension is freely available through the Magento Connect marketplace. Installation follows the normal procedure for installing Magento extensions.

System Requirements

Installation through Magento Connect

With these steps you will be able to install the Custom Layout Handles extension in your webshop.

  1. If you dont already have a Magento Connect Marketplace account, create one now. Log in at http://www.magentocommerce.com/magento-connect/ with your account.
  2. Go to the Magento Connect product page of this extension which can be found here:
  3. Click on the button "Install Now", select Magento Connect 2, check the extension license agreement checkbox and click the button "Get Extension Key".
  4. Copy the extension key which is now shown to your clipboard.
  5. Go to http://www.yourdomain.com/downloader/ where yourdomain.com is the URL where your Magento installation is located and log into your Magento Connect Manager with your admin credentials.
  6. Paste the content of your clipboard in the field highlighted in the screenshot below and hit the install button.
  7. Wait until the installation process is finished and click the refresh button below the command line textarea afterwards.
  8. Go the http://www.yourdomain.com/admin/ where yourdomain.com is the URL where your
    Magento installation is located. If you are already logged in to the backend please log out and login
    again as this will prevent you from getting a 404 error on the extension pages due to permissions that have not been set for the logged in user. After logging in again please refresh your cache settings under "System > Cache Management". This is necessary to avoid any caching problems after the installation of an extension. The installation or upgrade is now completed.

Upgrade through Magento Connect

With these steps you will be able to upgrade the Custom Layout Handles extension in case you have it already installed and a new version has been released.

  1. Go to http://www.yourdomain.com/downloader/ where yourdomain.com is the URL where your Magento installation is located and log into your Magento Connect Manager with your admin credentials.
  2. Click on the button "Check For Upgrades".
  3. Locate the Custom Layout Handles extension in the package list, in case it's highlighted there is an update available. Select the "Upgrade to x.x.x" action option where x.x.x is the new version number as shown below. Then click the "Commit Changes" button at the end of the list.

Deinstallation through Magento Connect

With these steps you will be able to remove the Custom Layout Handles extension from your webshop.

  1. Disable the extension under "System > Configuration > Advanced". On this page you will find the Custom Layout Handles extension and you can disable it.
  2. Go to http://www.yourdomain.com/downloader/ where yourdomain.com is the URL where your Magento installation is located and log into your Magento Connect Manager with your admin credentials.
  3. Scroll down to the list of existing extensions and select the "Uninstall" option next to the Custom Layout Handles extension as shown below. Then click the "Commit Changes" button at the end of the list.
  4. Click the refresh button after the de-installation process has finished. The Custom Layout Handles extension is now uninstalled.

Settings

The settings for the Custom Layout Handles extension can be found through the Magento backend configuration menu under "System > Configuration > Custom Layout Handles".

Setting Value Description
Enable Extension Yes / No This allows you to enable or disable the extension on a global level. If "No" is selected here all custom layout handles will not be available.
XML Layout Handles
Add Module Layout Handle Yes / No If enabled XML handles for modules are added and can then be used in XML Layout updates. For instance on all customer pages the layout handle <module_customer> is available.
Add CMS Title Layout Handle Yes / No If enabled XML handles for the CMS title are added and can then be used in XML Layout updates. For instance on the about page a layout handle <cms_about> is available.
Add Category Name Layout Handle Yes / No If enabled XML handles for the category names are added and can then be used in XML Layout updates. For instance on a category named Mens Clothes a layout handle <catalog-category-mens-clothes> is available.
Add Category Level Layout Handle Yes / No If enabled XML handles for the category level are added and can then be used in XML Layout updates. For instance on a category which is a sub-sub-category a handle <catalog_category_level_3> is available.
Add Category Fertility Handle Yes / No If enabled XML handles for the fertility (parent child relations) are added for categories and can then be used in XML Layout updates. For instance on a category which has no childeren a handle <catalog_category_nochilderen> is available.
Body Classes
Add Module To Body Classes Yes / No If enabled a CSS class is added to the body based on the loaded module and can then be used in CSS stylesheets. For instance on all customer pages the body class .module-customer is available.

 

Working With Layout Handles

This module is capable of adding various Custom XML Layout Handles which can then be used in layout XML files for customizing the look and feel of a Magento webshop. It can however be quite hard to figure out the exact name of the layout handle that has been added through this extension. Below is information on how you can view the available XML layout handles on the page you are viewing. It uses a module which is written by Alan Storm, a Magento guru.

Download and install the LayoutViewer by extracting the content and uploading the 'app' directory to the root of your Magento installation. Once installed you can add the parameter "?showLayout=handles" behind every URL to view the available layout handles for this page. For instance:

http://www.example.com/about/?showLayout=handles

This will show you something similar to the following screenshot. Here the custom layout handles for the CMS title and the current module have been highlighted.

The custom layout handles <module_cms> and <cms_about> are available for this page to use in your XML layout files.

Troubleshooting

In this section you will find answer to common issues.

I recieve a 404 error after installing the extension and going to the settings page

This is a common issue when installing Magento extensions. It is caused because the permission for using the new extension havent been set for the currently logged in admin user. The solution is to logout and login again in the admin backend.