Introducing FLEXIcontent labs - Yireo

Jdoc-tags in Magento PHTML

A feature - that was added a couple of months ago in MageBridge, but not given any attention yet - gives template-developers a very powerful tool to extend Magento. With MageBridge, the Magento frontend is largely replaced with the Joomla! templating framework, but there are weird cross-configurations available - and this is one of them: Adding jdoc-tags to PHTML-templates, so you can assign Joomla! module-positions to Magento content.

The jdoc-tags in Joomla!

A Joomla! template is built up using various files, but the PHP-file index.php is the main entry-point. While various other templating frameworks (Morph, RocketTheme Gantry, YOOtheme WARP, etcetera) exist that overwrite or modify the default Joomla! templating behaviour, for this blogpost it's best to focus on the Joomla! core: Within the PHP-file index.php, you can add so-called jdoc-tags to add module-positions, a component-area and a header.

<jdoc:include type="modules" name="top" />

These jdoc-tags are then replaced by the Joomla! Framework with the actual dynamic content. In the code above, all module-instances that are assigned to the template-position top will replace this tag.

Magento PHTML-templates

Similar to the Joomla! template, the Magento theme is also made up by PHP-files that contain a mix of PHP-code and HTML-code. But instead of using just one single file (index.php), Magento uses numerous templating-files that not only give the website a general HTML-structure, but also generate the HTML for any other extension in the system.

All these templating files end with the file-suffic phtml, so they are generally referred to as PHTML-templates. Each PHTML-template is actually generated through some kind of mystical XML-code (the XML-layout) and underlying PHP-classes. The total of this is called a block. So a block is a combination of an XML-definition, a PHP block-class and a PHTML-template ... in general.

MageBridge combined theming

Without knowing too much about the Magento theming layer, you need to understand that the Magento theming layer outputs data through blocks (chunks of HTML-code) and that each one of these blocks can be forwarded to Joomla! using MageBridge. MageBridge uses, for instance, the Magento block named content to place content in the Joomla! component-area (in other words, the Magento content-block equals the Joomla! component-area).

But any other Magento block can be inserted into Joomla! using the MageBridge Custom Block module. While the positioning of Magento blocks in the Magento theme is done through complex XML-code, you can change positioning of Magento blocks in the Joomla! system by using the Joomla! Module Manager. A great benefit.

Modifying a PHTML-template ... still in Magento

But if you want to modify the Magento block itself, you still need to dive into the Magento theme. For instance, if you add Magento block with the shopping cart to a Joomla! module-position, but you want to change the HTML-code of that shopping cart, you will need to modify the Magento theme: You configure a specific Magento child-theme based on the default parent-theme, you then copy the original PHTML-template to your own child-theme, and modify things from there.

jdoc-tags in Magento PHTML-templates

And now, comes the point of this blogpost: With MageBridge, every Magento block that is brought to Joomla!, can be parsed using Joomla! plugins. Thanks to this, MageBridge offers a feature that allows a Magento block to contain jdoc-tags, that are then replaced with dynamic Joomla! content. You can therefor assign Joomla! modules to a specific area in Magento.

Example: Adding a custom text to the Thank You page

An example: When you complete the checkout-process in Magento, you end up on a page that thanks you for your purchase. This page is built up through various elements, but the Magento content-block (that is displayed in the Joomla! component-area) is based on the PHTML-template checkout/success.phtml (by default, located in the Magento folder app/design/frontend/base/default/template).

This PHTML-template contains the following Magento code:

<?php echo $this->getMessagesBlock()->getGroupedHtml() ?>
<h2 class="sub-title"><?php echo $this->__('Thank you for your purchase!') ?></h2>

Now you can simply add a Joomla! jdoc-tag to this:

<?php echo $this->getMessagesBlock()->getGroupedHtml() ?>
<h2><?php echo $this->__('Thank you for your purchase!') ?></h2>
<jdoc:include type="modules" name="magebridge-checkout-success" /> 

When you now create a new Joomla! module - for instance a Custom HTML module with an extra text or images - and assign it to the position magebridge-checkout-success. Now the Joomla! text magically appears within the Magento content-area.

Example: Use a default Short Description for all Magento products

Let's say that you want to add some general text for all Magento products, that don't have a short description yet. While you can add this also to the Magento PHTML-template directly, using a CMS to easily change the text afterwards is always better. The product-page is composed of various blocks, but the Magento PHTML-template catalog/product/view.phtml contains most elements.

For instance, the short description is placed like this:

<?php if ($_product->getShortDescription()):?>
...
<?php endif; ?> 

Again, you can just add a jdoc-tag, but this time it is conditional so it only appears when there is no short description yet:

<?php if ($_product->getShortDescription()):?>
...
<?php else: ?>
<jdoc:include type="modules" name="mb-product-shortdescription" />
<?php endif; ?>

Hope you have fun with this.