From this article you’ll find out how toplinks are generated, how you can edit them easily, add new links to an existing list and create your own links list using tools offered by Magento.

Editing links – what’s difficult about it?

At first sight, the task seems to be quite trivial: we just need to modify the links list that, by default, is placed in the header. It seems that we simply have to open the template file, add or remove adequate positions, and that’s it! You couldn’t be more wrong; the links you’re trying to modify are complex objects that are based on many files. Even though they all inherit after the same class, each of them is defined in a separate file in various modules. Additionally, particular links are implemented in different ways. The task’s complexity level might give a headache to somebody who’s just starting their adventure with Magento. And we simply wanted to modify them slightly! I’ll show you everything you need to know to do the task quickly and efficiently. Let’s do it!


We will use a default Magento template and the tool called n98-magerun. If you don’t know what magerun is, you can find more information here. If you don’t have the default template configured, go to System->Configuration->Design->Package in the admin panel. Type in “default” in “current package name” and save. The rules and dependencies that we’re about to describe are global and don’t depend on the template. However, it might turn out that the files we’ll talk about won’t exist in you store’s copy or will include a different code. Therefore, we encourage you to use a clean Magento instance.

Links location

Let’s start from locating the file responsible for generating the links list. We’ll enable the development mode together with hints for templates. To do that, launch the terminal, go to the project’s folder and input the following command:
../n98-magerun.phar dev:template-hints

Next, select the store you want to activate the hints for.

I assume that your magerun file is located in the project’s root and you use the commands in
public_html or another folder with the store’s files.

Another way to turn on the hints (a slower and more boring one) is going to the System->Developer tab and changing “Current Configuration Scope” to “Main Website”. Then, in the Debug->Template Hints tab on the right, change the option to “Yes” and save.

If you want to turn the hints on again at a later time, just choose the way that’s the most convenient to you.
Now reload the site. You’ll get a view similar to:



We can see that the template file responsible for displaying the links is placed on the physical path frontend/base/default/template/page/links.phtml which in reality means that it can be found in the following folder: /app/design//frontend/base/default/template/page/template/links.phtml
At the very moment, the hint won’t be essential so you can disable them.

The links.phtml file

You will find the following code in the /app/design/frontend/base/default/template/page/template/links.phtml file:

/** * @see Mage_Page_Block_Template_Links 
getLinks(); ?> 
0): ?> 
<ul class="links"getName()): ?> id="getName() ?>"> 

toHtml() ?> 

<ligetIsFirst()||$_link->getIsLast()): ?> class="getIsFirst()): ?>firstgetIsLast()): ?> last" getLiParams() ?>>getBeforeText() ?><a href="getUrl() ?>" title="getTitle() ?>" getAParams() ?>>getLabel() ?></a>getAfterText() ?></li> 


DocComment informs us about the block that shares its methods with the template and because of the template’s content, it is the most important trail for us at the moment. The script, using the getLinks() method, downloads the list of all links stored in the Mage_Page_Block_Template_Links object and processes them in the foreach loop. Actually, if we only knew the methods of the class, we could make adequate amends in the links.phtml file by removing or editing the list. However, this way we would probably create illegible and weak code. Magento provides better tools. To understand them, let’s see the Mage_Page_Block_Template_Links class. It is placed in the /app/code/core/Mage/Page/Block/Template/Links.php file. I encourage you to browse through the file before reading on.

The Mage_Page_Block_Template_Links class

The Mage_Page_Block_Template_Links class extends the Mage_Core_Block_Template and specializes in generating blocks with links. If you had a look at the file, you must have noticed that it includes all methods that are used in the template’s file: links.phtml. The most important for us is the following function:

/** * Add link to the list * * @param string $label * @param string $url * @param string $title * @param boolean $prepare * @param array $urlParams * @param int $position * @param string|array $liParams * @param string|array $aParams * @param string $beforeText * @param string $afterText * @return Mage_Page_Block_Template_Links 
public function addLink($label, $url='', $title='', $prepare=false, $urlParams=array(), 
$position=null, $liParams=null, $aParams=null, $beforeText='', $afterText='') { 
if (is_null($label) || false===$label) { 
return $this; 
$link = new Varien_Object(array( 
'label' => $label, 
'url' => ($prepare ? $this->getUrl($url, (is_array($urlParams) ? $urlParams : array())) : $url), 
'title' => $title, 
'li_params' => $this->_prepareParams($liParams), 
'a_params' => $this->_prepareParams($aParams), 
'before_text' => $beforeText, 
'after_text' => $afterText, 

$this->_addIntoPosition($link, $position);
return $this; 

It allows you to add a link to the list of links stored in a given realization of the Mage_Page_Block_Template_Links class. You can also notice that the link is simply an object of the Varien_Obiekt class which means that it inherits all its methods. And this in turn means that it shares the interface common for all objects in Magento.

Well, this is something. We have a potentially good way for modifying the links. We’ll test it in the next article in which we’ll also take care of changing the link’s position and work on the their look.