Skip to content

Instantly share code, notes, and snippets.

@grafikchaos

grafikchaos/Magento - Add Custom Structure Blocks.md

Last active August 18, 2017 10:57
Show Gist options
  • Star 8 You must be signed in to star a gist
  • Fork 2 You must be signed in to fork a gist
  • Save grafikchaos/11148771 to your computer and use it in GitHub Desktop.
Save grafikchaos/11148771 to your computer and use it in GitHub Desktop.
Download ZIP
HowTo: Add Custom Structural Blocks to a Layout
Raw
Magento - Add Custom Structure Blocks.md

Overview

Recently had a client that wanted to customize the layout for a category landing page so that the category's title and description would be displayed above the layered navigation and product grid — essentially creating a full-width section above the left sidebar and main content areas.

NOTE: For reference, this is based off the blog post from Collaboration133.com's Magento - Add Custom Structural Block Reference.

Custom Module (My_LayoutMods)

I created a custom module to help organize and identify that there are some custom modifications to layout templates. Not saying you have to, but it may be easier for other's (or your future self) to recognize and find what customizations were done (and hopefully why).

For the purpose of this gist you should replace My or my_ with your namespace.

app/etc/modules/My_LayoutMods.xml

<!-- located at: app/etc/modules/My_LayoutMods.xml -->
<?xml version="1.0" encoding="UTF-8"?>
<!--
/**
 * Global Layout Overrides to add custom structure blocks to layout template files
 *
 * @category    My
 * @package     My_LayoutMods
 * @copyright   Copyright (c) 2013 August Ash, Inc. (http://www.augustash.com)
 * @license     http://opensource.org/licenses/osl-3.0.php  Open Software License (OSL 3.0)
 */
-->
<config>
    <modules>
        <My_LayoutMods>
            <active>true</active>
            <codePool>local</codePool>
        </My_LayoutMods>
    </modules>
</config>

app/code/local/My/LayoutMods/etc/config.xml

<!-- app/code/local/My/LayoutMods/etc.config.xml -->
<?xml version="1.0" encoding="UTF-8"?>
<!--
/**
 * Global Layout Overrides to add custom structure blocks to layout template files
 *
 * @category    My
 * @package     My_LayoutMods
 * @copyright   Copyright (c) 2013 August Ash, Inc. (http://www.augustash.com)
 * @license     http://opensource.org/licenses/osl-3.0.php  Open Software License (OSL 3.0)
 */
-->
<config>
    <modules>
        <My_LayoutMods>
            <version>1.0.0</version>
        </My_LayoutMods>
    </modules>

    <frontend>
        <layout>
            <updates>
                <my_layoutmods module="My_LayoutMods">
                    <file>my_layoutmods.xml</file>
                </my_layoutmods>
            </updates>
        </layout>
    </frontend>
</config>

app/design/frontend/base/default/layout/my_layoutmods.xml

<?xml version="1.0"?>
<!-- app/design/frontend/base/default/layout/my_layoutmods.xml -->
<?xml version="1.0" encoding="UTF-8"?>
<!--
/**
 * Global Layout Overrides to add custom structure blocks to layout template files
 *
 * @category    My
 * @package     My_LayoutMods
 * @copyright   Copyright (c) 2013 August Ash, Inc. (http://www.augustash.com)
 * @license     http://opensource.org/licenses/osl-3.0.php  Open Software License (OSL 3.0)
 */
-->
<layout version="0.1.0">
<!--==============================================
Default layout, loads most of the pages
===============================================-->
    <default>
        <reference name="root">
            <!--
            ========================================================================
            NEW BLOCK REFERENCE: custom_title
            client's custom layout for title, desc, etc. above layered navigation
            ========================================================================
            -->
            <block type="core/text_list" name="custom_title" as="custom_title" translate="label">
                <label>Custom Title</label>
            </block>
        </reference>
    </default>
<!--==============================================
END Default
===============================================-->

<!--==============================================
Catalog.xml
===============================================-->
    <catalog_custom>
        <reference name="root">
            <!-- Change category page(s) layout to 2 columns left -->
            <action method="setTemplate"><template>page/hybrid-2columns-left.phtml</template></action>
        </reference>

        <!--
        ========================================================================
        Client's custom layout for title, desc, etc. above layered navigation
        ========================================================================
        -->
        <reference name="custom_title">
            <block type="core/template" name="custom_title_block" template="catalog/category/custom_title.phtml" />
        </reference>
    </catalog_custom>

    <catalog_category_default translate="label">
        <!-- Update category default with catalog custom -->
        <update handle="catalog_custom" />
    </catalog_category_default>

    <catalog_category_layered translate="label">
        <!-- Update category default with catalog custom -->
        <update handle="catalog_custom" />
    </catalog_category_layered>
<!--==============================================
END Catalog.xml
===============================================-->


<!--==============================================
Catalogsearch.xml
===============================================-->
    <catalogsearch_custom>
        <reference name="root">
            <!-- Change category page(s) layout to 2 columns left -->
            <action method="setTemplate"><template>page/hybrid-2columns-left.phtml</template></action>
        </reference>
    </catalogsearch_custom>

    <catalogsearch_result_index translate="label">
        <!-- Update catalog search with catalogsearch custom -->
        <update handle="catalogsearch_custom" />
    </catalogsearch_result_index>

    <catalogsearch_advanced_index translate="label">
        <!-- Update catalog advanced search with catalogsearch custom -->
        <update handle="catalogsearch_custom" />
    </catalogsearch_advanced_index>
<!--==============================================
END Catalogsearch.xml
===============================================-->
</layout>

app/design/frontend/base/default/template/page/hybrid-2columns-left.phtml

You can copy this into your theme's folder structure, but it should be added into base/default because it is adding new files that should be available to all themes. I originally copied the page/2columns-left.phtml template and customized to the client's needs (i.e., adding HTML markup to wrap the content for the cutsom_title block).

<!-- located at: app/design/frontend/base/default/template/page/hybrid-2columns-left.phtml -->
<?php
/**
 * Global Layout Overrides to add custom structure blocks to layout template files
 *
 * @category    My
 * @package     My_LayoutMods
 * @copyright   Copyright (c) 2013 August Ash, Inc. (http://www.augustash.com)
 * @license     http://opensource.org/licenses/osl-3.0.php  Open Software License (OSL 3.0)
 */
?>

<?php
/**
 * Magento
 *
 * NOTICE OF LICENSE
 *
 * This source file is subject to the Academic Free License (AFL 3.0)
 * that is bundled with this package in the file LICENSE_AFL.txt.
 * It is also available through the world-wide-web at this URL:
 * http://opensource.org/licenses/afl-3.0.php
 * If you did not receive a copy of the license and are unable to
 * obtain it through the world-wide-web, please send an email
 * to license@magentocommerce.com so we can send you a copy immediately.
 *
 * DISCLAIMER
 *
 * Do not edit or add to this file if you wish to upgrade Magento to newer
 * versions in the future. If you wish to customize Magento for your
 * needs please refer to http://www.magentocommerce.com for more information.
 *
 * @category    design
 * @package     base_default
 * @copyright   Copyright (c) 2013 Magento Inc. (http://www.magentocommerce.com)
 * @license     http://opensource.org/licenses/afl-3.0.php  Academic Free License (AFL 3.0)
 */
?>
<?php
/**
 * Template for Mage_Page_Block_Html
 */
?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="<?php echo $this->getLang() ?>" lang="<?php echo $this->getLang() ?>">
<head>
<?php echo $this->getChildHtml('head') ?>
</head>
<body<?php echo $this->getBodyClass()?' class="'.$this->getBodyClass().'"':'' ?>>
<?php echo $this->getChildHtml('after_body_start') ?>
<div class="wrapper">
    <?php echo $this->getChildHtml('global_notices') ?>
    <div class="page">
        <?php echo $this->getChildHtml('header') ?>

        <!-- NEW CUSTOM STRUCTURE BLOCK -->
        <div class='custom-title-container row outer'>
            <div class='small-12 columns'>
                <?php echo $this->getChildHtml('custom_title'); ?>
            </div>
        </div>
        <!-- /NEW CUSTOM STRUCTURE BLOCK -->

        
        <div class="main-container col2-left-layout">
            <div class="main">
                <?php echo $this->getChildHtml('breadcrumbs') ?>
                <div class="col-main">
                    <?php echo $this->getChildHtml('global_messages') ?>
                    <?php echo $this->getChildHtml('content') ?>
                </div>
                <div class="col-left sidebar"><?php echo $this->getChildHtml('left') ?></div>
            </div>
        </div>
        <?php echo $this->getChildHtml('footer') ?>
        <?php echo $this->getChildHtml('global_cookie_notice') ?>
        <?php echo $this->getChildHtml('before_body_end') ?>
    </div>
</div>
<?php echo $this->getAbsoluteFooter() ?>
</body>
</html>

app/design/frontend/base/default/template/catalog/category/custom_title.phtml

You can copy this into your theme's folder structure, but it should be added into base/default because it is adding new files that should be available to all themes.

<!-- located at: app/design/frontend/base/default/template/catalog/category/custom_title.phtml -->
<?php
/**
 * Global Layout Overrides to add custom structure blocks to layout template files
 *
 * @category    My
 * @package     My_LayoutMods
 * @copyright   Copyright (c) 2013 August Ash, Inc. (http://www.augustash.com)
 * @license     http://opensource.org/licenses/osl-3.0.php  Open Software License (OSL 3.0)
 */
$category       = Mage::registry('current_category');
$categoryName   = $this->htmlEscape($category->getData('name'));
$categoryDesc   = $category->getData('description');
?>

<div class='row'>
    <div class='small-12 columns'>
        <div class="row">
            <div class="small-12 columns">
                <div class="page-title category-title">
                    <h1><?php echo $categoryName; ?></h1>
                </div>
                <div class="cat-desc">
                    <?php echo $categoryDesc; ?>
                </div>
            </div>
        </div>
    </div>
</div>
@austinpray
Copy link

Magento has got to be the most confusing software I have ever had the pleasure to deal with.

What is the deal with the casing here?

<my_layoutmods module="My_LayoutMods">
  <file>my_layoutmods.xml</file>
</my_layoutmods>

@julneb
Copy link

julneb commented Nov 9, 2015

Example Type Case Description
My_LayoutMods Module name Camel case Module class and folder name and reference
<my_layoutmods> XML element Lower case All XML elements and attribute names are lower case
my_layoutmods.xml Filename Lower case Best practice to keep filenames lower case to avoid filesystem mix-ups.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment