Injecting JavaScript and CSS Into Magento Admin Panel Page Head

The Magento Admin panel is controlled by the Adminhtml module, which does not have a strict layout mapping. This is a problem when we want to add our own JavaScript and CSS to create a new module or improve old modules.

(This post is a developer’s guide.)

For pages lacking .xml layout, the common method like the following will not work:

[codesyntax lang=”javascript” lines=”fancy”]<action method=”addJs”><script>jquery/jquery.js</script></action>[/codesyntax]

Instead, we should directly inject the JS into the ‘blocks’ given by .php files.

The Magento Onepage Checkout is quite a tricky component. For simple tasks, it is quite possible to change the PHP code with surgical precision without messing around with the JavaScript part. But unfortunately, in many complicated tasks, like adding a new step with a bunch of new functions, would inevitably involve JavaScript handling.

Here come a couple of useful tips:

Our final target is the opcheckout.js, located at: skin/frontend/default/default/js/opcheckout.js

Before we jump into hundreds of lines of JS codes, our first stop should be the template files for the Onepage Checkout. At the end of those files, you will see something like:

[codesyntax lang=”javascript” lines=”fancy”]
<script type=”text/javascript”>
//<![CDATA[
var billing = new Billing(‘co-billing-form’, …);
//]]>
</script>
[/codesyntax]

Yes, this is the critical link between our PHP part and JS part.

The Magento adminhtml (or admin panel) is quite different from other modules for the frontend. The Adminhtml module has a distinct implementation of the Model-Controller-View scheme. In fact, forms, tables, graphs and etc. are usually stereotypical and highly repetitive comparing to the large varieties in the frondend. As a result, in Adminhtml page, such elements are generalized into block ‘widgets’ to boost coding efficiency.

However, when building a new module, we often need to modify the frontend and the backend together. And in many cases, since the we already build the functions in frontend module, it’s really a waste of energy if we have to rewrite everything in terms of ‘widget’ in the backend. Simply, we would like to migrate the controller and view to the backend and reuse the code.

Here, I’m going to go through the basic steps the Mage_Adminhtml_Block_Template rather than widgets.

(This is a developer’s guide.)

Let’s begin with creating a new menu in the Admin panel. We added to the config.xml to our new module:

[codesyntax lang=”xml” lines=”fancy”]

<adminhtml>
  <menu>
    <new_module translate="title" module="new_module">
      <title>New Module Name</title>
      <sort_order>50</sort_order>
      <action>new_module/new_controller</action>
    </new_module>
  </menu>
</adminhtml>

[/codesyntax]

The Magento Admin panel is controlled by the Adminhtml module. And all Adminhtml pages require validation/authentication.

In fact, Magento has different ways treating GET and POST  admin pages, i.e.: $secretKey vs. ‘form_key’

(This is a developer’s guide.)

For GET request, we must provide http:// … /id/’secretKey’
For POST request, we must provide ‘form_key’ as a post parameter.

Example for GET:  simple attach to the end of the URL in the block .php, note that the secret key only involves the controller and the action, not the module name.

[codesyntax lang=”php” lines=”fancy”]

public function getSearchResultGetUrl(){
    //must pass on the key to maintain logged in
    $secretKey = Mage::getSingleton('adminhtml/url')->getSecretKey('adminhtml_search', 'result');
    return Mage::getUrl('pet/adminhtml_search/result/key/'.$secretKey);
}

[/codesyntax]

Magento Adminhtml, a Widget Heavy Approach

After 5  custom modules, I started to feel comfortable coding with Magento and picked up my coding speed. And then came the first project with massive modifications in the Admin panel, i.e. Adminhtml module. I had to admit that I totally underestimated the complexity of the task. The Adminhtml is, well, very different.

A common frontend module usually has an exact mapping between the actions in the controller and the views (block .php file plus template .phtml file), as defined in the layout file. Basically I can begin with the action in the controller, then use the layout .xml to look up the template .phtml files, and the outline of the code is clear.

However, such strict mapping is absent in the Adminhtml module, whose blocks are often directly controlled by the PHP code and also heavily rely on the block widgets.

I took a couple of days to investigate the source code, despite some remaining grudge against this ‘free-form’ module. I found the block widgets quite convenient.
There are many nice widgets like: Mage_Adminhtml_Block_Widget_Form, …_Grid, and etc.