FensterHai - Integration von eigenen Modulen - Autor: Erik Adameit Email: erik.adameit@i-tribe.de Datum: 09.04.2015 1
Inhalt 1. Übersicht... 3 2. Integration des Sourcecodes des Moduls... 3 2.1 Einschränkungen... 3 2.2 Bsp. Code... 4 3. Integration der TYPO3 Plugin Klasse... 4 4. Registrierung eines neuen Plugins... 6 5. Upload und Cache-Leerung... 7 6. Erstellung neuer Content Elemente (CE)... 7 Anhang/Beispiel... 9 2
1. Übersicht Technisch gesehen sind externe Module Teil der TYPO3 Extension fhai_external. Das Default Verzeichnis der Extension ist PATH_WEB/typo3conf/ext/fhai_external/ (PATH_WEB ist das Root-Verzeichnis der Website.). Um ein neues Modul anzulegen beachten sie den folgenden Prozess: Integration des Quellcodes/Sourcecodes des Moduls Integration der TYPO3 Plugin Klasse Registrierung eines neuen Plugins Upload und Cache-Leerung Erstellung neuer Content Elemente (CE) 2. Integration des Sourcecodes des Moduls Die Sources können jedwede PHP, JavaScript, CSS oder Bilddateien sein, die das Modul benötigt. Der Entwickler muss alle extenen Dateien in einen eigenen Unterordner des Contrib Verzeichnisses ablegen. 2.1 Einschränkungen Folgende Dinge müssen beachtet werden: Vermeiden Sie jedwede PHP Output Methoden, wie as echo, print, header, die, exit etc. Der gesamte Ooutput wird von TYPO3 geregelt und alle Daten für den Output müssen an die Hauptpluginklasse zurück gegeben werden. Vermeiden Sie die Einbindung von bekannnten JavaScript libraries, welche bereits global auf der Websdite eingebunden sind (RequireJS, jquery e.g.) Falls möglich, benutzen Sie bereits auf der Website bestehende generische Klassen und Auszeichnungen (MarkUp) 3
2.2 Bsp. Code Der PHP Code für ein externes Modul kann aus einem einzelnen oder mehreren Files mit Inclusion bestehen. Hier sehen sie ein Bsp. für ein einfaches File, welches Testdaten zurück gibt. <?php / Main content @var string / $content = "<h1>module headline</h1>"; $action =!empty($_get['action'])? trim($_get['action']) : 'unknown'; $content.= '<p>action: '. $action. '<p>'; return $content; 3. Integration der TYPO3 Plugin Klasse Das TYPO3 CMS benötigt eine exakte Struktur der Klassen und Benennungen. Zuerst muss der Entwickler dem Modul einen für einen Redakteur im TYPO3 System verständlichen entsprechenden Titel für das Plugin, sowie dem Modul einen internen Namen geben. Im Bsp. ist der Titel des Moduls Altbaurechner, während der interne Name oldbuildingcalculator ist. Beim internen Namen ist auf Folgendes zu achten: Kleinschreibung, keine Sonderzeichen, keine speziellen deutschen Umlaute oder ähnliche Zeichen, keine Striche, Unterstriche, oder Zeichen mit weiteren Punkten. Danach sollte der Entwickler die entsprechende PHP Klassen Datei im Verzeichnis Classes/Plugin/ directory anlegen. In unserem Bsp: class.tx_fhaiexternal_oldbuildingcalculator.php 4
Beim Code der Klasse müssen folgende Regeln beachtet werden: Der Klassenname ist tx_fhaiexternal_modulename (modulename wird, wie oben beschrieben definiert, tx_fhaiexternal_oldbuildingcalculator für dieses Bsp.). Die Klasse ist vererbt von \TYPO3\FhaiExternal\Plugin\AbstractPlugin class Die prefixid Variable, in der Klassendefinition muss auf den aktuellen Klassennamen gesetzt sein (tx_fhaiexternal_oldbuildingcalculator). Die Klasse enthält die Methode main(), welche benötigte Externe Ressourcen aus dem Contrib Ordner einbindet. Hier ein Bsp einer TYPO3 Plugin Modul Klasse <?php / Copyright notice (c) 2015 Anton Danilov <anton.danilov@i-tribe.de>, interactive tribe GmbH All rights reserved This script is part of the TYPO3 project. The TYPO3 project is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. The GNU General Public License can be found at http://www.gnu.org/copyleft/gpl.html. This script is distributed in the hope that it will be useful, 5
but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. This copyright notice MUST APPEAR in all copies of the script! / use \TYPO3\CMS\Core\Utility\GeneralUtility; / Plugin 'Old building calculator' for the 'fhai_external' extension. @author Anton Danilov, interactive tribe GmbH @author FensterHAI team @package TYPO3 @subpackage Plugin / class tx_fhaiexternal_oldbuildingcalculator extends \TYPO3\FhaiExternal\Plugin\AbstractPlugin { / Plugin variables prefix @var string / public $prefixid = 'tx_fhaiexternal_oldbuildingcalculator'; / The main method of the PlugIn @param string $content : The PlugIn content @param array $conf : The PlugIn configuration @return string The content that is displayed on the website / function main($content, $conf) { $this->conf = $conf; $this->pi_setpivardefaults(); //use init for calling session-start-spezial and setting shop environment $this->init(); //module content $content = require_once( \TYPO3\CMS\Core\Utility\ExtensionManagementUtility::siteRelPath($this ->extkey). 'Contrib/altbaurechner/altbaurechner.php' ); } } return $this->pi_wrapinbaseclass($content); 6
4. Registrierung eines neuen Plugins Für die Registrierung neuer Plugins werden die Dateien ext_tables.php und ext_localconf.php genutzt: <?php ext_tables.php //Old building calculator \TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addPlugin( [ 'Altbaurechner', //plugin title $_EXTKEY. '_oldbuildingcalculator', \TYPO3\CMS\Core\Utility\ExtensionManagementUtility::extRelPath($_EXTKEY). 'ext_icon. gif' ], 'list_type' ); Der Module title Altbaurechner und der Modul name oldbuildingcalculator (mit führendem Unterstrich) werden hier genutzt. <?php ext_localconf.php \TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addPItoST43($_EXTKEY, 'Classes/Plugin/class.tx_fhaiexternal_oldbuildingcalculator.php', '_oldbuildingcalculator', 'list_type', 0); Hier wird nur der Module Name benutzt. 5. Upload und Cache-Leerung Alle neuen oder geänderten Dateien müssen auf den Server hochgeladen werden. Um die Änderungen wirksam zu machen, ist ein internes TYPO3 Cache Leeren nötig. Bitte nutzen Sie dafür folgendes Commando in der Kommonandozeile: (uiserver):u79144414:~ > /usr/bin/php5.4-cli typo3cms cache:flush force Im Root Verzeichnis. Beachten Sie, dass wenn keine der folgenden Dateien geändert wurde, auch kein Cache-Leeren nötig ist. ext_localconf.php ext_localconf.php 7
6. Erstellung neuer Content Elemente (CE) Wenn alle beschriebenen Aktionen durchgeführt sind, ist das Plugin soweit konfiguriert, um es in eine TYPO3-Seite zu integrieren. Gehen Sie zu der Seite, auf der das Plugin integriert werden soll. Wählen Sie für das zu integrierende CE, Allgemeines Plugin aus. 8
Wählen Sie das benötigte Plugin aus der Liste aus und speichern Sie das Element. Anhang/Beispiel Hier sehen Sie ein Beispiel, wie Sie ein einfaches Modul erstellen, welches aus einer Überschrift und einem Copytext-Absatz besteht. Wenn der FE-User auf den Absatz klickt, verändert sich die Farbe und die Text-Auszeichnung. Module title: Example module for manual. Module name: examplemodule. Step 1: Modules sources integration (module.php, styles.css und script.js) 9
10
Step2: TYPO3 plugin class integration 11
Step 3: Register plugin (ext_localconf.php und ext_tables.php) 12
Step 4: Flushing caches and inserting to page Step 5: Frontend displaying 13