http://www.developer.com/xml/e-commerce-platform-customization-tweaking-the-magento-admin-interface.html

Back to article

E-commerce Platform Customization: Tweaking the Magento Admin Interface


November 22, 2011

I've spent the past several months working on a non-trivial Magento-driven e-commerce project for a local client. The project involved more than 14,000 products segmented into more than 50 categories and they were further broken down into those which are purchasable, rentable, and available only via special quote. It goes without saying that we encounter some pretty interesting challenges on a daily basis. Other trying factors include a fairly sophisticated custom theme and integration of a sophisticated order-fulfillment pipeline.

Throughout it all, Magento has repeatedly proved itself up to even the most demanding configuration tasks. The level of thought and effort put into all aspects of the platform is in a word, striking. Much of my praise stems from Magento's extensibility. The fact is, there have been numerous instances where Magento does not meet the exacting requirements of a particular project, necessitating modifying or adding new features to the software. Magento's architecture is such that it's possible to deeply integrate new features into the existing design and capabilities by way of custom extensions. These extensions never touch the core files, meaning that the Magento upgrade process is seamless and easy rather than a nightmare fraught with mistakes and errors.

But the project documentation falls well short of expectations in terms of properly documenting exactly how one goes about extending the platform. The community wiki, though voluminous and in places rather well-written, tends to focus on specific aspects of integration rather than presenting a general introduction to the topic.

In fact, my own frustrations regarding the lack of substantial documentation have been such that I've recently started work on a new book titled Easy Magento, which introduces effective extension development and layout management alongside a host of other indispensable topics. In the meantime, I thought it would be useful to provide those of you who are just getting started modifying developing your own extensions with a simple but practical example involving modifying the default Magento administration interface, which you can use as the basis for making your own forays into enhancing Magento's capabilities.

How the Magento E-commerce Platform Builds Pages

Perhaps more than any other factor, the key to truly mastering Magento's approach to extensibility lies in understanding the important role XML has to play in both page layouts and functional extensions. In fact, every single page you encounter when navigating a Magento-driven website is in some manner defined within an XML file! Consider for instance the Magento administration console's interface for viewing orders (Figure 1).

Magento Admin Interface
Figure 1.
Viewing an Order in the Magento Admin Interface

This interface is actually defined within an XML file named sales.xml, which resides in app/design/adminhtml/default/default/layout/sales.xml. A very small part of sales.xml is presented here (formatted for improved readability):

....
<reference name="left">
<block type="adminhtml/sales_order_view_tabs"
name="sales_order_tabs">
<block type="adminhtml/sales_order_view_tab_info"
name="order_tab_info"
template="sales/order/view/tab/info.phtml">
<block type="adminhtml/sales_order_view_messages"
name="order_messages"></block>
<block type="adminhtml/sales_order_view_info"
name="order_info"
template="sales/order/view/info.phtml"></block>

...

The bolded lines identify just one of many blocks which comprise any given Magento page. This particular block is responsible for generating the two sections titled Order # 100000041 (the order confirmation email is not sent) and Account Information, in addition to two other address-related sections not presented in Figure 1.

The type attribute refers to the block responsible for retrieving the dynamic order information which is retrieved from the database and inserted into the view template, which is identified by the template attribute. Therefore the block is adminhtml/sales_order_view_info and the template is sales/order/view/info.phtml. Taking Magento's autoloading approach into account, this means the block is found at app/code/core/Mage/Adminhtml/Block/Sales/Order/View/Info.php and the template is found at app/design/adminhtml/default/default/template/sales/order/view/info.phtml.

Take a few moments to review in particular the template, as we'll be overriding its layout in order to produce the updated version found in Figure 2.

Magento Admin Interface
Figure 2.
The Revised Order Review Page in the Magento Admin Interface

Creating a New Extension for the Magento Admin Interface

Remember that the goal is to revise what the Magento administrator sees when viewing the order review page while not actually touching the default app/design/adminhtml/default/default/template/sales/order/view/info.phtml file. In order to accomplish this, we need to extend Magento using a custom extension.

In order to prevent namespace collisions, extensions are typically identified by a unique string associated with the developer, in addition to a name which identifies the specific extension. For the purpose of this example I'll use the namespace Gilmore and the extension name Backend.

Begin by creating a file named Gilmore_Backend.xml and placing it within the directory app/etc/modules/. Add the following contents to the file:

<?xml version="1.0"?>
<config>
<modules>
<Gilmore_Backend>
<active>true</active>
<codePool>local</codePool>
</Gilmore_Backend>
</modules>
</config>

After saving this file, log in to the Magento administration console and navigate to System &gt Configuration > Advanced and make sure the extension is enabled (Figure 3).

Magento Admin Interface
Figure 3.
Ensuring the Gilmore_Backend Extension Is Recognized

Configuring the Magento Extension

Next, you'll need to configure the extension. This is done by creating a--you guessed it -- configuration file. This file should be named config.xml and placed in a directory app/code/local/Gilmore/Backend/etc/. Of course, this directory tree doesn't yet exist, so you have to create it. Within config.xml, place the following contents:

<?xml version="1.0"?>
<config>
<modules>
<Gilmore_Backend>
<version>0.1</version>
</Gilmore_Backend>
</modules>
<adminhtml>
<layout>
<updates>
<backend>
<file>gilmore.xml</file>
</backend>
</updates>
</layout>
</adminhtml>

</config>

The bolded <layout> section is the particularly important part, as it tells Magento that we want to update the Magento administration HTML (known as adminhtml), and the update instructions are found in a file named gilmore.xml. Because gilmore.xml doesn't exist, you'll need to create it too, placing it in the directory app/design/adminhtml/default/default/layout/gilmore.xml. Within this file add the following:

<?xml version="1.0"?>
<layout>
<adminhtml_sales_order_view>
<reference name="order_info">
<action method="setTemplate">
<template>gilmore/backend/info.phtml</template>
</action>
</reference>
</adminhtml_sales_order_view>
</layout>

This file is where many beginners tend to stumble, precisely because the XML syntax is so confusing. However, when broken down into the various parts it is actually quite easy to understand. The adminhtml_sales_order_view enclosure refers to the very same enclosure found in sales.xml. The reference element associated with the order_info attribute tells Magento that we want to update the block identified by order_info (identified within sales.xml) with whatever is found within the reference enclosure. In this particular instance, we are using the setTemplate method to identify a new template, which is found in app/design/adminhtml/default/default/template/gilmore/backend/info.phtml.

Updating the Sales Order View Template in Magento

The only remaining step is to actually update the page HTML to reflect the new layout. To do so, copy the contents of app/design/adminhtml/default/default/template/sales/order/view/info.phtml into app/design/adminhtml/default/default/template/gilmore/backend/info.phtml, change as desired, save the changes, and reload the order review page!

Where To From Here?

Admittedly, the update sequence seems rather lengthy, particularly because we're interested in updating only a small part of a page. However, after working through the process a few times, you'll find that it takes only a few quick moments to configure. Additionally, this is but the most simple of changes; when creating much more complex changes you'll find this approach to be incredibly convenient. And as always, if you have any questions, be sure to get in touch!

About the Author

Jason Gilmore is founder of the publishing, training, and consulting firm WJGilmore.com. He is the author of several popular books, including "Easy PHP Websites with the Zend Framework", "Easy PayPal with PHP", and "Beginning PHP and MySQL, Fourth Edition". He is currently writing a new book titled Easy Magento. Follow him on Twitter at @wjgilmore.

Sitemap | Contact Us