Yireo tutorials

Learn more about Joomla!TM and Magento
You are here: Home Tutorials MageBridge MageBridge theming MageBridge and module chromes

MageBridge and module chromes

If you are familiar with Joomla!TM templating, you may have heard of module chromes. Every module within a template can be styled in different manners - using different chromes. The chrome adds extra HTML to the module. But how to deal with modules chromes with MageBridgeTM?

Common chromes are:

  • xhtml
  • rounded
  • raw

A module can be decorated with a chrome by adding a <jdoc>-statement to the template-code with a specific style-argument, and then linking the module to that <jdoc>-tag by assigning the proper position.

 
<jdoc:include type="modules" name="left" style="xhtml" />
 

MagentoTM and page assignment

As soon as you start adding Magento blocks to the Joomla! template, things start to get weird. The reason for this is the way that Magento deals with page assignment. Let's take for example the MageBridge Shopping Cart module.

If the cart-module is configured on the module-position "left", it behaves just like any other module. The module is shown on the position "left" and how this position is actually visualized is determined by the Joomla! template.

For every Joomla! module you can also configure the Page Assignment - you can determine that the MageBridge cart-module should be visible on the Joomla! homepage and all MageBridge pages, but not on the FAQ-page. So far, so good. But if you start browsing inside the MageBridge pages and you end up in the checkout, suddenly the cart-module is empty. The reason for this is the Magento theme.

The shopping cart displayed in the MageBridge cart-module is actually nothing more than a Magento block, and therefor part of the Magento theming system. If you would browse Magento stand-alone, you will notice that in the checkout the shopping-cart disappears together with the entire left-column. The reason for this lies with the Magento XML layout.

Page assignment on both sides

The Magento theme - just like Joomla! - also uses a thing like page assignment - it uses so-called handles to determine which page is displayed and in Magento XML layouts a handle can be instructed to use a specific page-layout (for instance "1column.phtml", "2columns-left.phtml" or "2columns-right.phtml"). The Magento default is to use a three-column layout for all pages, but other page handles (referring to specific pages) might use a different layout.

In fact, the page handle belonging to the checkout-procedure ("checkout.xml") refers to the one-column layout. So, as soon as you're reaching the checkout-pages, not only the left-column but also the right-column disappears. Because MageBridge reuses the Magento theme inside Joomla!, this means that the Magento theme removes the shopping-cart module from the page, even when Joomla! is set to display it. In fact, Joomla! is still displaying the MageBridge module, but the content (the Magento block) is just empty.

So here's the challenge: How can we keep both theming systems in sync? There are two approaches we can take here: Or we remove the page assignment from Magento and manage things completely in Joomla!. Or we detect the page assignment set in Magento and reuse it in Joomla!.

Magento XML layouts

Let's take the approach of removing the Magento page assignment. As we have already told you, the page assignment in Magento is managed inside the Magento XML layout files. These files are located inside Magento in "/app/design/frontend/INTERFACE/THEME/layout", where INTERFACE stands for the theming interface and THEME stands for your theme. When using a standard Magento installation, both are set to "default", so the layout-files are located in "/app/design/frontend/default/default/layout".

If we want to remove the page assignment, we want to reset everything to the default - we remove all layout-updates, and reset all non-default page handles to the default page handle. The first downside here is that this will take a lot of work - really a lot of work! We need to rewrite most of the XML layout. While the default page layout is set in "page.xml", other XML layout-files contain new block-definitions as well as alteration of existing defintions (so-called layout updates). For each block, we have determine if it should be shown on all pages or not.

Showing the Magento blocks on all pages

Though we only recommend using this approach if you're fit enough for it, we're just going to explain the steps. Let's take the checkout-page and the shopping-cart-module as example. Both are defined in the file "checkout.xml". The cart-module displays a block with name "cart_sidebar" and its definition can be located in the default page handle (<default>). The good thing here is that its added to the block "right", so if we can make the block "right" appear again, the shopping-module is available again on the checkout-page.

<default>
    <reference name="right">
        <block type="checkout/cart_sidebar" name="cart_sidebar" ....
        ....

The checkout-pages are accessed through the page-handle "checkout_cart_index". Its definition looks a bit like the following:

<checkout_cart_index>
    <remove name="right"/>
    <remove name="left"/>
    <reference name="root">
        <action method="setTemplate">
            <template>page/1column.phtml</template>
        </action>
    </reference>
    <reference name="content">
    ....

What you can see here is that for the page "checkout_cart_index", the blocks "left" and "right" (and all the child-blocks inside it) are removed. Also the default page layout "3column.phtml" is rewritten to "1column.phtml". We can fix both alterations by deleting the responsible <remove> tags:

<checkout_cart_index>
    <reference name="content">
    ....

One warning is in place here: It could be that certain blocks were removed by a page-handle on purpose! Some Magento blocks contain PHP-logic that conflicts with the logic of other blocks. There is no other way for finding out about this than testing, testing, testing. If you find such a conflict (most likely because a PHP Fatal Error occurs) the fun stops. You could start hacking the responsible PHP-code, but the best advice we can give you is: Don't use this approach.

Disabling the MageBridge module when empty

So let's focus on the other approach: Detect the page assignment from within Joomla!. This is a cleaner and faster way to accomplish things. But, before we dive into ways for making our Joomla! template more compatible with MageBridge, first we tackle another small problem: Let's say we have a <jdoc>-tag with position "left" and a style "xhtml". The position "left" is filled with our MageBridge cart-module but also a Joomla! menu-module.

<div id="left-column">
    <jdoc:include type="modules" name="left" style="xhtml" />
</div>

Adding a style-argument to a <jdoc>-tag allows for adding a specific chrome to every module in it. A chrome-style adds extra HTML to the module-content and thus allows for easier styling of modules. When the chrome is set to "xhtml" or "rounded", extra <div>-tags are added to the module-HTML. When the chrome is set to "raw", no extra HTML-tags are added and even the module title is omitted.

Now, imagine that the chrome is set to "xhtml". For the Joomla! module this works out perfectly. Joomla! assigns the module to each page and the module-title is added to the module correctly. But the MageBridge cart-module acts differently: If we are on the checkout-page, the module-content is empty (because the Magento block is empty) but because of the chrome, the module-title is still added. It looks strange to have a module-title with no content below it, doesn't it?

Using the chrome "raw"

We want to alter the behavior for MageBridge-modules to display the chrome (including the module-title) if the module has content, but display nothing at all if the content is empty. This is done easily by choosing a different chrome - instead of "xhtml" we could choose "raw" which does the job perfectly. But within one <jdoc>-tag we can only define one chrome. The easy solution would be to include two <jdoc>-tags, one for regular Joomla! modules and one for MageBridge-modules:

<div id="left-column">
    <jdoc:include type="modules" name="left" style="xhtml" />
    <jdoc:include type="modules" name="left-magebridge" style="raw" />
</div>

Again this is not the way we recommend things. Having a seperate <jdoc>-tag for MageBridge-modules is not flexible.

Overriding html/modules.php

Using Joomla! template overrides you could create your own chrome in "html/modules.php" to add or remove   HTML to MageBridge-modules only. You can create a file "templates/TEMPLATE/html/modules.php" in your own template, open up the existing "templates/system/html/modules.php" and copy the chrome-function to your own file. Next, change the name of the function to something else (for instance rename "modChrome_rounded" to "modChrome_myrounded").

Within the PHP/HTML code you can see a logic to display the module-title or not:

if($module->showtitle != 0)

We want to change this logic to ignore the "showtitle" parameter if the module being displayed is a MageBridge module. For this we add some extra PHP to this logic:

if($module->showtitle != 0 && !preg_match('/^mod_magebridge_/', $module->module)

This kind of logic will not only allow you to remove the module-title but also create a completely different HTML-layout for just MageBridge modules. In this case the <jdoc>-tag has to be altered to use the style "myrounded" instead of "rounded", while the module-position (the name-attribute) stays the same.

Removing a Joomla! column when the Magento theme tells you so

Now we have seen how to remove the shopping-cart module from the Joomla! template if it's empty. But if the Magento theme is telling us to remove the left-column, we also need to remove all the other Joomla! modules on the position "left". Normally you would remove the left-column on a specific page by disabling all modules through page assignment, and then use PHP-logic in your template to the left-column:

<?php if($this->countModules('left') > 0): ?>
<div id="left">

The problem here is that the countModules()-function doesn't know about the Magento theming system at all. What we want to do is check for the current Magento page-layout and act accordingly. MageBridge offers a helper-class that allows you to determine the current page layouts: MageBridgeTemplateHelper.

<?php if($this->countModules('left') > 0 
    && MageBridgeTemplateHelper::hasLeftColumn()): ?>
<div id="left">

This involves extra work in your Joomla! template but is the cleanest way of handling page assignments. If you are using templates from professional Joomla!-template builders like JoomlArt or RocketThemes, you will need to modify the code in a different place. For instance, with JoomlArt themes the column-logic is placed in a file called ja_vars_1.5.php. Change the line starting with "$ja_right = " to the following:

$ja_right = ($this->countModules('right') 
    && MageBridgeTemplateHelper::hasRightColumn());

That should work.

Tutorials on MageBridge theming

Tutorials on MageBridge development

 

Payments Methods

Payment Methods