How to Modulentwicklung [Teil 2]

Wie schreibe ich ein OXID eShop Modul?

Die metadata.php Datei

Die wichtigste Datei bei der Modulentwicklung ist die metadata.php Datei.

In der metadata.php Datei werden alle technischen Modulinformationen hinterlegt, die das OXID Framework benötigt um die eigenen Anpassungen zu adoptieren.

Zuerst legt man ein eigenes Modulverzeichnis an. Der Name des Modulverzeichnisses beginnt mit dem Entwicklerkürzel und dann folgt der Modulname.

 

Nachdem man das eigene Modulverzeichnis angelegt hat, legt man die metadata.php Datei innerhalb des eigenen Modulverzeichnisses an.

Die metadata.php Datei enthält zwei Variablen. Diese sind die Metadata Version Variable $sMetadataVersion = '1.1' und die Modul Array Variable $aModule = array(...).

Die Metadata Version Variable enthält die Metadata Versionsnummer und die Modul Array Variable enthält Pflichtfelder und optionale Felder.

Pflichtfelder metadata.php Datei

<?php

$sMetadataVersion = '1.1';

$aModule = array(
    'id'           => 'bisQuestionAnswer',
    'title'        => 'Modul f&uuml;r Fragen und Antworten zum Artikel',
    'extend'       => array(),
    'files'        => array(),
    'blocks'       => array(),
    'settings'     => array()
);

Erklärungen zu den Pflichtfeldern

id
Eindeutige Modul ID mit Entwicklerkürzel bis und Modulname QuestionAnswer
title
Modulbezeichnung Modul für Fragen und Antworten zum Artikel
extend
Das extend Array zeigt alle überladeten OXID Framework Klassen an
files
Das files Array zeigt alle eigene Klassen an die dem OXID Framework bekannt gemacht werden sollen
blocks
Das blocks Array zeigt alle erweiterten oder überschriebenen OXID Blocks an
settings
Das settings Array zeigt die Modulkonfigurationen und -einstellungen an

Admin Tab um eigenes Feld erweitern

Zu allerest möchten wir eine Checkbox ergänzen. Wir haben festgelegt, dass wir gerne eine Checkbox mit der Bezeichnung Produkt erklärungsbedürftig? bei der Artikelverwaltung im Tab Erweitert ergänzen möchten.

Ziel ist es bei jedem Artikel individuell festlegen zu können ob im Frontend der Tab Fragen & Antworten angezeigt wird.

Das OXID Framework bietet dort die Möglichkeit dies über eine Block Überladung zu bewerkstelligen.

Jetzt ist die große Frage was ist ein Block?

Ein Block ist ein definierter Codeabschnitt, diesen Codeabschnitt kann man über eine Blocküberladung ändern oder erweitern.

In unserem Fall möchten wir den Block gerne erweitern. Beim Erweitern eines Blocks kann man vor oder nach dem Codeabschnitt des Blocks seinen Code platzieren.

Wir entscheiden uns dafür unseren Codeabschnitt nach dem Codeabschnitt des Blocks zu platzieren.

An zweiter Stelle fragen wir uns wie ist ein Block als solcher im Quellcode zu erkennen?

Ein Block steht wie folgt in der Smarty Template Datei:

[{block name="Blockname"}]
...
Template Code
...
[{/block}]

An dritter Stelle fragen wir uns wie finde ich nun den Blocknamen aus dem Erweitert Tab um diesen Block zu überladen?

Daumenregel um Admin Controller, Model und View zu identifizieren

Wenn man sich in den Adminbereich einloggt und über die linken Adminmenüpunkte drüber hovern, dann sieht man unten Links den Link eingeblendet wohin die Reise geht.

Innerhalb dieses Links ist über den Parameter cl der Controller definiert. Hinter dem Parameter cl folgt der Controllername.

Den Controllername findet man im OXID Framewort unter dem Verzeichnis /application/controllers/admin/ wieder.

Öffnet man den entsprechenden Controller article.php findet man die Template Variable protected $_sThisTemplate = 'article.tpl', welche den Namen des verwendeten Templates enthält.

Die Template Datei article.tpl findet man im Verzeichnis /application/views/admin/tpl/ wieder.

Schaut man sich die Template Datei an findet man ein HTML Dokument mit Frames vor. Im Frameset Tag sind 2 Frames enthalten:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">

<html>
<head>
    <title>[{ oxmultilang ident="GENERAL_ADMIN_TITLE" }]</title>
</head>

<!-- frames -->
<frameset  rows="40%,*" border="0" onload="top.loadEditFrame('[{$oViewConf->getSelfLink()}]&[{ $editurl }][{ if $oxid }]&oxid=[{$oxid}][{/if}]');">
    <frame src="[{$oViewConf->getSelfLink()}]&[{ $listurl }][{ if $oxid }]&oxid=[{$oxid}][{/if}]" name="list" id="list" frameborder="0" scrolling="Auto" noresize marginwidth="0" marginheight="0">
    <frame src="" name="edit" id="edit" frameborder="0" scrolling="Auto" noresize marginwidth="0" marginheight="0">
</frameset>


</html>

Die 2 Frames enthalten die Listen- und Detailansicht:

  • die Liste article_list.tpl
  • die Detailansicht article_main.tpl

Die Listenansicht und Detailansicht Templates besitzen im OXID Framework immer die gleichen Suffixes. Die Suffixes lauten _list und _main.

Wenn es sich nun im Admin um einen Tab handelt. Findet man den zugehörigen Controller, Model und View anhand des Namens welcher sich hinter der Route beim drüber hovern des Tabs unten links angezeigt wird.

In unseren Fall wäre dies für den Erweitert Tab #article_extend, das Template heißt also article_extend.tpl.

Unser Block den wir gerne erweitern möchten heißt admin_article_extend_form.

Block Überladung in metadata.php bekannt machen

Da wir nun das Admin Template und den Namen des Blocks kennen den wir gerne erweitern möchten, können wir den Block in der metadata.php im Blocks Array bekannt machen:

'blocks' => array(
  array(
    'template' => 'article_extend.tpl',
    'block' => 'admin_article_extend_form',
    'file' => '/views/blocks/article_extend.tpl'
  ),
),

Der Wert template gibt an in welchen Tempalte sich der Block befindet.

Der Wert block gibt an in welchen Codeabschnitt bzw. Block sich die Überladung befindet.

Der Wert file gibt an wo sich unsere Block Template Datei im Modulverzeichnis befindet.

Für unsere Überladung legen wir das Verzeichnis views mit dem Unterverzeichnis blocks an. In dem Unterverzeichnis blocks legen wir folgende Blocküberladungsdatei article_extend.tpl an:

[{$smarty.block.parent}]
<tr>
    <td class="edittext" width="120">
        Produkt erkl&auml;rungsbed&uuml;rftig?
    </td>
    <td class="edittext">
        <input class="edittext" type="hidden" name="editval[oxarticles__bisinneedofexplanation]" value='0'>
        <input class="edittext" type="checkbox" name="editval[oxarticles__bisinneedofexplanation]" value='1' [{if $edit->oxarticles__bisinneedofexplanation->value == 1}]checked[{/if}] [{ $readonly }]>
    </td>
</tr>

Der Smarty Tag [{$smarty.block.parent}] sorgt dafür, dass vor unser Checkbox der Original Code innerhalb des definierten Blocks angezeigt wird.

Die Blocküberladung Informationen werden beim erstmaligen Aktivieren des Modul in der Tabelle oxtplblocks gespeichert.

Aktivieren wir unser Modul im Admin unter Erweiterungen -> Module und gucken uns den Erweitert Tab im Admin erneut an wurde unsere Checkbox Produkt erklärungsbedürftig? ergänzt.

Datenbankfeld anlegen

Das Speichern unser Checkbox übernimmt das OXID Framework automatisch. Allerdings ist dafür die Voraussetzung, dass unser Artikelfeld in der Datenbanktabelle oxarticles bekannt ist.

Damit wir sicherstellen, dass unser neues Datenbankfeld immer vorhanden ist nutzen wir in der metadata.php das Events Array.

Genauer wir benutzen die Event Methode onActivate um festzulegen welche Routine ausgeführt werden soll wenn das Modul aktiviert wird.

Zusätzlich müssen mir noch eine eigene Klasse dem OXID Framework bekannt machen.

In unser eigenen Klassen können wir dann unsere onActivate definieren und das SQL hinterlegen welches beim Aktivieren des Moduls abgesetzt werden soll.

<?php

$sMetadataVersion = '1.1';

$aModule = array(
    'id'           => 'bisQuestionAnswer',
    'title'        => 'Modul f&uuml;r Fragen und Antworten zum Artikel',
    'extend'       => array(),
    'files'        => array(
        'bisQuestionAnswerEvents' => 'bisQuestionAnswer/core/bisquestionanswerevents.php',
    ),
    'blocks'       => array(
        array(
            'template' => 'article_extend.tpl',
            'block' => 'admin_article_extend_form',
            'file' => '/views/blocks/article_extend.tpl'
        ),
    ),
    'settings'     => array(),
    'events'       => array(
        'onActivate'   => 'bisQuestionAnswerEvents::onActivate',
    ),
);

Der Wert onActivate enthält den Klassennamen + Methodennamen der statisch definierten Methode in unserem Modul welche in unserem Modul bei Modulaktivierung ausgeführt wird.

Neben dem hinzufügen des Events wurde noch unsere eigene Klasse bisQuestionAnswerEvents mit der Methode onActivate über das files Array ergänzt.

Für unsere eigene Klasse haben wir das Verzeichnis core mit der Datei bisquestionanswerevents.php angelegt.

<?php

class bisQuestionAnswerEvents
{

    public static function onActivate()
    {
        $sSql = "ALTER TABLE `oxarticles`
                  ADD `BISINNEEDOFEXPLANATION` tinyint(1) unsigned NOT NULL DEFAULT '0'
                  COMMENT 'Enable in need of explanation tab';";

        oxDb::getDb()->execute( $sSql );
    }

}

Über ein Alter Statement erweitern wir die Tabelle oxarticles um das Feld bisinneedofexplanation.

Nachdem wir unser Modul um die statische Methode onActivate ergänzt haben deaktivieren und aktivieren wir unser Modul erneut.

Jetzt wurde im Hintergrund unser Alter Statement ausgeführt.

Nun ist unser Tabellenfeld bekannt und wir können die Checkbox anklicken und unsere Änderung speichern.

Herzlichen Glückwunsch du hast erfolgreich über ein Modul im OXID Admin ein neues Tabellenfeld hinterlegt und bekannt gemacht!

Fortsetzung

Im 3. Teil der Modulentwicklung geht es nächste Woche weiter mit:
Wie lege ich im Admin einen eigenen Menüpunkt “Fragen & Antworten” an?

Key Learnings

  • Aufbau der metadata.php Datei kennen gelernt
  • Eigenes Admin Feld über Blocküberladung definiert
  • Eigenes Datenbanktabellenfeld über Modul Event angelegt


3 Kommentare

Dein Kommentar

An Diskussion beteiligen?
Hinterlasse uns Deinen Kommentar!

Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert.