Top-Links von Magento anpassen

Update 11.02.2012: Der Code ist auch mit Magento 1.6.2.0 verwendbar.

Heute beschäftigen wir uns mit einer häufig auftretenden Aufgabe: dem Hinzufügen, Verändern und Entfernen von Links der Header-Navigation in Magento. Vielleicht gebraucht ihr auch den intern verwendeten Namen „Top-Links“ oder bezeichnet es als „oberes Menü“. Es geht jedenfalls um die Links zu Benutzerkonto, Wunschzettel, Warenkorb, Kasse, Anmeldung und Abmeldung, welche im Screenshot zu sehen sind. Ich verwende für dieses Posting Magento 1.4.1.1. Der Code funktioniert bis zumindest Magento 1.6.2.0. Das Prinzip ist jedoch genauso auf ältere Versionen anwendbar.

Wo werden die Links gesetzt?

Wenn man wissen möchte, wo die Links herkommen, wird man sich vermutlich zuerst auf die Suche nach dem entsprechenden .phtml-File und der dazugehörigen Block-Klasse machen. Dabei hilft die Debugging-Funktion „Template hints“ (zu finden unter System > Konfiguration > Erweitert > Entwickleroptionen > Debug). Achtung: die Auswahl erscheint erst, wenn man links oben im Konfigurationsbereich eine „Store View“ ausgewählt hat.

Wir sehen, dass der Inhalts-Block durch die Klasse Mage_Page_Block_Template_Links repräsentiert und die Darstellung in frontend/base/default/template/page/template/links.phtml erzeugt wird. Dann ist doch alles klar, oder?

Nicht so ganz, denn der Code in links.phtml sieht wie folgt aus:

<?php $_links = $this->getLinks(); ?>
<?php if(count($_links)>0): ?>
    <ul<?php if($this->getName()): ?> id="<?php echo $this->getName() ?>"<?php endif;?>>
    <?php foreach($_links as $_link): ?>
        <li<?php if($_link->getIsFirst()||$_link->getIsLast()): ?><?php endif; ?> <?php echo $_link->getLiParams() ?>><?php echo $_link->getBeforeText() ?><a href="<?php echo $_link->getUrl() ?>" title="<?php echo $_link->getTitle() ?>" <?php echo $_link->getAParams() ?>><?php echo $_link->getLabel() ?></a><?php echo $_link->getAfterText() ?></li>
    <?php endforeach; ?>
    </ul>
<?php endif; ?>

Die .phtml-Datei holt sich die Links also von der Block-Klasse. Wir öffnen die Datei app/code/core/Mage/Page/Block/Template/Links.php und stellen fest, dass die Links mittels der Methode addLink() hinzugefügt werden:

public function addLink($label, $url='', $title='', $prepare=false, $urlParams=array(), $position=null, $liParams=null, $aParams=null, $beforeText='', $afterText='')
{
    // Code zum Hinzufügen des Links
}

Top-Links können somit überall hinzugefügt werden, wo man Zugriff auf die Instanz der Block-Klasse hat. Der Core-Code verwendet dazu die Layout-XML-Dateien. Der Block für die Header-Navigation trägt im Layout den Namen „top.links„. Mit einer Suche nach der Methode „addLink“ innerhalb des Tags <reference name=“top.links“> findet man somit recht schnell die Links. Anbei eine Tabelle, welche Links an welcher Stelle hinzugefügt werden:

Link	XML-Datei und Handle	Code
Abmelden (Log Out)	customer.xml (customer_logged_in)	<action method="addLink" translate="label title" module="customer">   <label>Log Out</label>   <url helper="customer/getLogoutUrl"/>   <title>Log Out</title>   <prepare/>   <urlParams/>   <position>100</position> </action>
Anmelden (Log In)	customer.xml (customer_logged_out)	<action method="addLink" translate="label title" module="customer">   <label>Log In</label>   <url helper="customer/getLoginUrl"/>   <title>Log In</title>   <prepare/>   <urlParams/>   <position>100</position> </action>
Mein Benutzerkonto (My Account)	customer.xml (default)	<action method="addLink" translate="label title" module="customer">   <label>My Account</label>   <url helper="customer/getAccountUrl"/>   <title>My Account</title>   <prepare/>   <urlParams/>   <position>10</position> </action>
Mein Warenkorb (My Cart)	checkout.xml (default)	<block type="checkout/links" name="checkout_cart_link">   <action method="addCartLink"></action> </block>
Mein Wunschzettel (My Wishlist)	wishlist.xml (default)	<block type="wishlist/links" name="wishlist_link">   <action method="addWishlistLink"></action> </block>
Zur Kasse (Checkout)	checkout.xml (default)	<block type="checkout/links" name="checkout_cart_link">   <action method="addCheckoutLink"></action> </block>

Mit diesem Wissen ausgestattet können wir die Navigation bearbeiten.

Wie man die Links bearbeitet

Um die bestehenden Links auszublenden oder abzuändern, kann man auf drei Wegen vorgehen:

1. Man kopiert die betroffenen Layout-XML-Dateien (checkout.xml, customer.xml und/oder wishlist.xml) in das eigene Theme und modifiziert die Zeilen entsprechend der Erfordernisse.
2. Man nimmt die Änderungen in der Datei local.xmldes Themes vor.
3. Man legt im Theme eine eigene XML-Datei an, welche die Top-Links bearbeitet.

Wir wählen den dritten Weg, da es sich dabei um eine übersichtliche, wiederverwendbare Lösung handelt und wir gleich noch einen eigenen Link hinzufügen werden.

Eine eigene Layout-Datei einbinden

Zuerst erstellen wir das Grundgerüst für unsere Extension (app/etc/modules/Emzee_HeaderNavigation.xml):

<?xml version="1.0"?>
<config>
    <modules>
        <Emzee_HeaderNavigation>
            <active>true</active>
            <codePool>local</codePool>
            <depends>
                <Mage_Checkout />
                <Mage_Customer />
                <Mage_Wishlist />
            </depends>
        </Emzee_HeaderNavigation>
    </modules>
</config>

Durch die <depends>-Anweisungen stellen wir sicher, dass die XML-Dateien der Core-Module vor unserer XML-Datei eingebunden werden. Damit existieren die Links bereits, wenn wir an der Reihe sind und wir können sie somit wieder entfernen.

Im nächsten Schritt erstellen wir das Verzeichnis app/code/local/Emzee/HeaderNavigation/ und legen im Unterverzeichnis etc/ die obligatorische config.xml an (insgesamt also app/code/local/Emzee/HeaderNavigation/etc/config.xml):

<?xml version="1.0"?>
<config>
    <modules>
        <Emzee_HeaderNavigation>
            <version>0.1.0</version>
        </Emzee_HeaderNavigation>
    </modules>
    <frontend>
        <layout>
            <updates>
                <Emzee_HeaderNavigation>
                    <file>emzee_headernavigation.xml</file>
                </Emzee_HeaderNavigation>
            </updates>
        </layout>
    </frontend>
</config>

Durch das Frontend-Layout-Update geben wir Magento zu verstehen, dass diese Layout-Datei ebenfalls geladen werden soll. Das Tag unterhalb von <updates> muss nicht den Namen der Extension tragen. Wichtig ist nur, dass der Name von keiner Core-Klasse und keiner anderen Extension verwendet wird. Statt „Emzee_HeaderNavigation“ wäre „MeinTotalEinzigartigerLayoutUpdateTag“ genauso zulässig.

Nun kommt die Layout-XML-Datei emzee_headernavigation.xml dran. Wir kreieren unser eigenes Theme „emzee“, damit die Core-Verzeichnisse auch hier nicht verändert werden, und legen die Datei darin ab (app/design/frontend/default/emzee/layout/emzee_headernavigation.xml):

<?xml version="1.0"?>
<layout version="0.1.0" />

Jetzt müssen wir Magento noch dazu bringen, die XML-Datei in unserem Theme zu berücksichtigen. Wenn Sie bereits etwas im Shop angepasst haben, sollten Sie das Theme bereits eingerichtet haben und diesen Schritt nicht mehr umsetzen müssen. Da ich von einer frischen Magento-Installation ausgehe und für das Beispiel keine eigene View anlegen möchte, mache ich es mir einfach und passe die Konfiguration des default-Themes etwas an. Dazu gehe ich in das Backend und trage unter System > Konfiguration > General > Design Folgendes ein:

Somit sucht Magento im Theme „emzee“ des Packages „default“ (/app/design/frontend/default/emzee) nach Layout-Dateien und greift auf das Fallback-Verzeichnis (/app/design/frontend/default/default) zurück, falls es keine Layout-Datei findet. Bisher haben wir noch keine Layout-Anpassungen vorgenommen, doch sobald wir eine Anweisung in die XML-Datei pflanzen, sollten wir Auswirkungen sehen.

Existierende Links entfernen

Knöpfen wir uns zu Beginn den Link „Mein Benutzerkonto“ vor. Wie in der obigen Tabelle zu sehen ist, wird der Link über einen Helper hinzugefügt. Das erleichtert uns die Arbeit: die Top-Links-Block-Klasse besitzt nämlich eine Methode removeLinkByUrl(), über die wir die Links entfernen müssen. Wenn wir denselben Helper verwenden, bekommen wir dieselbe URL zurück und können somit dem Link den Garaus machen.

Hier kommt der Code für die Datei emzee_headernavigation.xml. Was genau passiert, erkläre ich gleich.

<?xml version="1.0"?>
<layout version="0.1.0">
    <default>
        <reference name="top.links">
            <action method="removeLinkByUrl">
                <url helper="customer/getAccountUrl" />
            </action>
        </reference>
    </default>
</layout>

• <default>: Der Link wird innerhalb des default-Handles hinzugefügt. Deswegen nehmen wir auch das Entfernen innerhalb des default-Handles vor.
• <reference name="top.links">: Wir hängen uns beim Top-Links-Block ein, der den Layout-Namen „top.links“ hat.
• <action method="removeLinkByUrl">: wir rufen die Methode removeLinkByUrl() der Block-Klasse auf (Mage_Page_Block_Template_Links::removeLinkyByUrl()).
• <url helper="customer/getAccountUrl" />: wir übermitteln der Methode als 1. Parameter den Rückgabewert des Helpers.

Und siehe da: der Link ist weg!

Wir können nun auch die anderen Links entfernen. „Mein Benutzerkonto„, „Anmelden„, und „Abmelden“ werden direkt im XML eingefügt und lassen sich mittels der Informationen löschen, die wir dort vorfinden. Die drei anderen Links „Mein Warenkorb„, „Mein Wunschzettel“ und „Zur Kasse“ hingegen werden mittels eigener Blöcke integriert. Am Einfachsten ist es hier, den gesamten Block zu löschen:

<remove name="checkout_cart_link"/>

Hier der Code, um alle Links verschwinden zu lassen:

<?xml version="1.0"?>
<layout version="0.1.0">
    <default>
        <reference name="top.links">
            <action method="removeLinkByUrl">
                <url helper="customer/getAccountUrl" />
            </action>
            <remove name="checkout_cart_link" />
            <!-- nur für Magento < 1.4.2 -->
            <!-- <remove name="wishlist_link" />-->
        </reference>
        <!-- ab Magento 1.4.2 -->
        <reference name="wishlist_link">
            <action method="setTemplate">
                <template>not-existing-file.phtml</template>
            </action>
        </reference>
    </default>
    <customer_logged_in>
        <reference name="top.links">
            <action method="removeLinkByUrl">
                <url helper="customer/getLoginUrl" />
            </action>
        </reference>
    </customer_logged_in>
    <customer_logged_out>
        <reference name="top.links">
            <action method="removeLinkByUrl">
                <url helper="customer/getLoginUrl" />
            </action>
        </reference>
    </customer_logged_out>
</layout>

Danke an Hans-Christian für seinen Hinweis, dass die Wunschliste ab Version 1.4.2 anders entfernt werden muss!

Magic, Ladies and Gentlemen!

Eigene Links hinzufügen

Natürlich können wir die Methode addLink() verwenden, um eigene Links in die Top-Navigation aufzunehmen. Wie wir oben gesehen haben, stehen uns beim Methoden-Aufruf einige Parameter zur Verfügung. Zuerst zeige ich den Beispiel-XML-Code, dann das Resultat auf der Seite und im HTML-Code. Anschließend erkläre ich in der Tabelle, was wir mit den einzelnen Parametern bewirkt haben.

<?xml version="1.0"?>
<layout version="0.1.0">
    <default>
        <reference name="top.links">
            <!-- ... -->
            <action method="addLink" translate="label title">
                <label>matthias-zeis.com</label>
                <url>http://www.matthias-zeis.com/ </url>
                <title>Matthias Zeis von LimeSoda</title>
                <prepare />
                <urlParams />
                <position>100</position>
                <liParams>id="matthias-zeis-link"</liParams>
                <aParams>
                    <class>li-css-klasse-1 li-css-klasse-2</class>
                    <id>li-id-klasse</id>
                    <target>_blank</target>
                </aParams>
                <beforeText>Besuche </beforeText>
                <afterText> (externer Link)</afterText>
            </action>
        </reference>
    </default>
    <!-- ... -->
</layout>

Wichtig: wenn man einen der späteren Parameter verwenden möchte (zum Beispiel, um dem Listeneintrag eine Id zu verpassen), dann muss man die vorhergehenden Parameter zwingend angeben.

Fazit

Am Anfang ist die Handhabung der Top-Links bzw. Header-Navigation für viele Entwickler sehr verwirrend. Wenn man das Prinzip verstanden hat, kann man jedoch erkennen, dass es sich um eine sehr flexible Lösung handelt, mit der man abhängig von der aufgerufenen Seite, der Backend-Konfiguration etc. allerlei Dinge anstellen kann. Übersetzungen werden ebenso berücksichtigt. Zu diesen Funktionen sind wir noch gar nicht gekommen, doch das Thema bietet sich natürlich für ein zukünftiges Posting an. 😉