WebsiteBaker Documentation

Diese Seite ist nicht editierbar. Sie können den Quelltext sehen, jedoch nicht verändern. Kontaktieren Sie den Administrator, wenn Sie glauben, dass hier ein Fehler vorliegt.
====== Hello Classic World - Projekt ======
FIXME
.. das klassische Beispiel Addon. Auch hier wird sich sehr vieles ändern. Grundsätzlich gilt jedoch, dass das bisherige, alte System zumindest für die 2.x-Serie noch vollständig kompatibel ist. Aus diesem Grund hier auch zuerst die Beschreibung eines Addons nach der herkömmlichen Methode, jedoch bereits mit neuen Techniken und leider auch noch vielen 'alten' Problemen.

:!: **Jede Neuentwicklung / Überarbeitung muss auf den allgemeinen [[dev:all:psr|Coding-Standards]] sowie den [[dev:284:psr|Spezifische Anpassungen der PSR-Standards an WB-2.10.0]] basieren!**

Jedes Addon benötigt eine Reihe Basis-Dateien, die **immer** vorhanden sein müssen. In den nachfolgenden Beschreibungen sind diese mit **//(erforderlich)//** gekennzeichnet. Diese Dateien müssen zwar vorhanden sein, jedoch müssen sie nicht zwangsläufig auch zusätzlichen Code enthalten. Der einfachste Weg ist es, die hier vorgestellten Musterdateien direkt herunter zu laden und zu verwenden und bei Bedarf um eigenen Code zu ergänzen.

:!: **//Achtung: Verlassen Sie sich niemals darauf, dass die Basis-Dateien eines Addons im 'Global Scope' ((mit 'Scope' wird der Sichtbarkeits- und Gültigkeitsbereich einer Variablen bezeichnet. 'Global Scope ist der Bereich, der auch durch die Superglobale $_GLOBALS[] angesprochen wird.)) geladen und ausgeführt werden!!\\
Gehen Sie grundsätzlich immer von der Annahme aus, dass diese Dateien innerhalb einer Funktion/Klassenmethode aufgerufen werden und dadurch selbstverständlich globale Variablen nicht direkt zur Verfügung stehen!//**

===== Die Dateien zu Installation aller Addons =====
Die Dateien //install.php//, //uninstall.php// und //upgrade.php// werden bei den entsprechenden Aktionen grundsätzlich vom Core automatisch aufgerufen und ausgeführt. Sie können nicht sebstständig ausgeführt werden.\\
Zusätzlich gehört zur 'Grundausstattung' die Datei //info.php// und, falls Datenbanktabellen benötigt werden, noch die Datei //install-struct.sql//.

Alle Dateien dieses Abschnittes werden grundsätzlich bei jeder Art von Addon (page / snippet / tool) benötigt.

:!: **Damit die Steuerung des Core (z.B. bei automatischer Installation) nicht unterbrochen wird, dürfen diese Dateien keinen Code enthalten, der die Ausführung des Scriptes in irgendeiner Weise abbricht.**
FIXME //(weitere Bedingungen für diese Files)//

==== info.php (deprecated) ====
Diese Datei ist zwischenzeitlich nur noch aus Gründen der Abwärtskompatibilität vorhanden und enthält ausschließlich einen Aufruf zum Import der Informationen aus der Datei //**info.ini**//. Neue oder überarbeitet Funktionen des Core greifen ab sofort vorrangig auf die Datei //**info.ini**// zu. Diese Kompatibilitäts-Funktion wird voraussichtlich Mitte 2015 endgültig deaktiviert. Bestehende Module müssen also bis zu diesem Zeitpunkt auf die neue //**info.ini**// umgestellt sein.

<code php info.php>
<?php
/**
 * The new 'info.ini' is mandatory from 2.8.4 !!!
 * This file 'info-php' is for backward compatibility only!!!!!
 * From 2.8.4 new core methods will no longer use the old vars from info.php!
 * It will be removed at least at 1th of July 2015 !!!!
 */
    if (!defined('SYSTEM_RUN')) die('illegal access!');
    $aX = UpgradeHelper::convInfoIni2InfoPhp(__DIR__);
    if ($aX) {
        $sPrefix = array_shift($aX);
        extract($aX, EXTR_PREFIX_ALL, $sPrefix);
    } else {
        $sErrMsg = 'error on converting values from \''.basename(__DIR__).'/info.ini\' '
                 . '('.UpgradeHelper::getError('convInfoIni2InfoPhp').')';
        throw new AppException($sErrMsg);
    }
</code>

==== info.ini (erforderlich) ====

Diese Datei enthält ausschließlich Informationen über das aktuelle Addon in Kurzfassung. **Ein Changelog oder sonstige 'Romane' haben in dieser Datei absolut nichts verloren.**\\
Ausführlichere Informationen müssen in verschiedenen anderen, spezialisierten Dateien im Unterverzeichnis modulverzeichnis/**//DOC/ //** zur Verfügung gestellt werden:\\
**//DOC/CHANGELOG// ->** In chronologischer Reihenfolge (neueste Einträge zuoberst) werden hier Änderungen an den Scripts eingetragen. Auch der Einstieg/Ausstieg weiterer Entwickler wird an der zeitlich richtigen Position eingetragen.\\
**//DOC/LICENSE// ->** Der Ort für ausführliche Lizenzangaben und sonstige rechtliche Angaben.\\
**//DOC/COPYING// ->** Diese Datei kann benutzt werden um z,B, eine Kopie der GPL unterzubringen.\\
**//DOC/README.EN// ->** Hier ist endlos Platz für ausführliche Beschreibungen und Anleitungen. Durch Anpassung der Dateiendung können diese Angaben in den unterschiedlichsten Sprachen geschrieben werden.

:!: **Versionsnummern müssen ausschließlich in einem Format angegeben werden, das zu der PHP-Funktion //version_compare()// kompatibel ist.**

<code ini info.ini>
<?php
;
; info file for addon 'Hello World'
; you can remove the comments below if you want.
;
; addon informations
[info]
; type of the addon (can be: page, snippet, tool, template, theme)
type            = "page"
; the directory where the addon should be located (allowed pattern: /[A-Za-z][A-Za-z0-9\-]+/)
directory       = "HelloWorld"
; readable name of the addon
name            = "The new Hello World addon"
; version of the addon
version         = "0.1.0"
; name of the author, if more then one, write as CSV list
author          = "Xaver Hinterhuber, Michaela Mustermann"
; short name of your license
license         = "GNU GPLv.2"
; short version of your terms of license
license_terms   = "--- short version of your license terms ---"
; short description of your addon. Take no more then 2 or 3 lines
; HTMl code is not allowed, but you can use \n for linefeed.
description     = "Kurzbeschreibung des Moduls"

; for whitch platform the addon is usable
[platform]
; brand name of the platform
name            = "WebsiteBaker"
; CSV list with ALL versions the addon ist testet for
versions        = "2.8.4, 2.8.4-SP1"
; minimum needed PHP version
minPhp          = "5.4"
; maximum allowed PHP version in case of code restrictions.
; set to empty string or '0' if not needed
maxPhp          = "5.6.100"

</code>
==== install-struct.sql ====
:!: **Diese Datei wird nur benötigt, wenn das Addon eigene Datenbanktabellen erhalten soll!**

[[dev:284:q_a-helloworld?&#was_ist_eine_sql-strukturdatei|{{:quest.png?32|}}]]  [[dev:284:q_a-helloworld?&#was_ist_eine_sql-strukturdatei|Was ist eine SQL-Strukturdatei?]]

Die Musterdateien für Install / Upgrade / Uninstall enthalten bereits die fertige Einbindung der SQL-Strukturdatei.\\
Sollte die Datei //install-struct.sql// nicht vorhanden sein, weil z.B. einfach keine Datenbanktabellen benötigt werden, erkennt der Code dieses und geht einfach zum Individualteil über.

<file sql install-struct.sql>
-- --------------------------------------------------------
-- SQL-Import-Struct-File
-- generated with ConvertDump Version 0.2.1
-- WebsiteBaker Edition
-- Creation time: Sat, 22 Nov 2014 08:32:00 +0100
-- --------------------------------------------------------
-- phpMyAdmin SQL Dump
-- version 3.3.2deb1ubuntu1
-- http://www.phpmyadmin.net
--
-- Host: localhost
-- Erstellungszeit: 22. November 2014 um 07:39
-- Server Version: 5.1.73
-- PHP-Version: 5.3.2-1ubuntu4.28
SET SQL_MODE="NO_AUTO_VALUE_ON_ZERO";
/*!40101 SET @OLD_CHARACTER_SET_CLIENT=@@CHARACTER_SET_CLIENT */;
/*!40101 SET @OLD_CHARACTER_SET_RESULTS=@@CHARACTER_SET_RESULTS */;
/*!40101 SET @OLD_COLLATION_CONNECTION=@@COLLATION_CONNECTION */;
/*!40101 SET NAMES utf8 */;
--
-- Datenbank: `wb284test`
--
-- --------------------------------------------------------
--
-- Tabellenstruktur für Tabelle `{TABLE_PREFIX}mod_helloworld_settings`
--
DROP TABLE IF EXISTS `{TABLE_PREFIX}mod_helloworld_settings`;
CREATE TABLE IF NOT EXISTS `{TABLE_PREFIX}mod_helloworld_settings` (
  `instance` int(11) NOT NULL DEFAULT '0',
  `name` varchar(64){FIELD_COLLATION} NOT NULL DEFAULT '',
  `value` text{FIELD_COLLATION}  NOT NULL,
  PRIMARY KEY (`section_id`, `key`)
){TABLE_ENGINE=MyISAM};
-- --------------------------------------------------------
-- END OF SQL-Import-Struct-File
-- --------------------------------------------------------
</file>
==== install.php (erforderlich) ====
Die Installation eines Addons erfolgt grundsätzlich in und durch Core-Methoden.
Erst rein addonspezifische Dinge, wie das Anlegen von neuen Datenbanktabellen werden durch diese Datei übernommen. 
<code php install.php>
<?php
if (! defined('WB_PATH')) { die('Cannot access this file directly'); }
/* -------------------------------------------------------- */
    $oReg = WbAdaptor::getInstance();
// --- process import file to create addons tables ----------------
// --- This code is needed if your addon has own tables -----------
    $oSqlStruct = new SqlImport($oReg->Db, __DIR__.'/install-struct.sql');
    if ($oSqlStruct->doImport(__FILE__)) {
// --- finish process import file ---------------------------------
// --- begin all other this addon related stuff -------------------

        /*
         * do some other stuff
         */

    } //endif
/* **** END INSTALL ********************************************************* */

</code> FIXME ergänzen um Rückgabe von Fehlermeldungen!!
==== uninstall.php (erforderlich) ====
Auch die Deinstallation eines Addons wird größtenteils durch Core-Methoden erledigt. Diese Datei muss eigentlich nur dafür sorgen, dass alles, was außerhalb des Addonverzeichnisses oder in Tabellen, die nicht zum Addon gehören (was nach den Coding-Standards eigentlich strikt verboten ist) angelegt/geändert wurde, rückgängig gemacht wird. Die Tabellen des Addons werden durch den SQL-Importer des Core anhand der //install-struct.sql// gelöscht. Nach Ausführung dieser //uninstall.php// Datei löscht der Core dann das komplette Addonverzeichnis und entfernt alle relevanten Einträge zu diesem Modul aus allen Coredateien.\\
:!: **Es ist grundsätzlich //nicht// möglich, ein Addon zu löschen, wenn es noch auf irgendeiner Seite in Benutzung ist!!**
 
<code php uninstall.php>
<?php
if (! defined('WB_PATH')) { die('Cannot access this file directly'); }
/* -------------------------------------------------------- */
    $oReg = WbAdaptor::getInstance();
    
// --- begin all other this addon related stuff -------------------

        /*
         * do some other stuff
         */

// --- end all other this addon related stuff ---------------------
    
// --- process import file to delete addons tables ----------------
// --- This code is needed if your addon has own tables -----------
    $oSqlStruct = new SqlImport($oReg->Db, __DIR__.'/install-struct.sql');
    $oSqlStruct->doImport(__FILE__);
// --- finish process import file ---------------------------------
/* **** END UNINSTALL ******************************************************* */

</code> FIXME ergänzen um Rückgabe von Fehlermeldungen!!
==== upgrade.php (erforderlich) ====
Diese Datei hat die Angewohnheit, dass sie im Laufe der Zeit immer weiter anwachsen kann. Jeder Übergang von einer Version zur nächsten kann erfordern, dass Daten des Addon an neue Bedingungen angepasst werden müssen. Eine der wichtigsten Regeln für diese Datei ist: Es muss möglich sein, von jeder beliebigen Version auf die neueste Version upzudaten.

<code php upgrade.php>
<?php
if (! defined('WB_PATH')) { die('Cannot access this file directly'); }
/* -------------------------------------------------------- */
    $oReg = WbAdaptor::getInstance();
// --- process import file to create addons tables ----------------
// --- This code is needed if your addon has own tables -----------
    $oSqlStruct = new SqlImport($oReg->Db, __DIR__.'/install-struct.sql');
    if ($oSqlStruct->doImport(__FILE__)) {
// --- finish process import file ---------------------------------
// --- begin all other this addon related stuff -------------------

        /*
         * do some other stuff
         */

    } //endif
/* **** END UPGRADE ********************************************************* */

</code> FIXME ergänzen um Rückgabe von Fehlermeldungen!!

===== Die Dateien eines Addons Type 'page' =====
Ein sogenanntes 'page'-Addon benötigt derzeit noch eine Reihe von Dateien, über die der Core das Anlegen, Löschen und Verwalten von Addon-Instanzen steuern kann. Diese '//erforderlich//'en Dateien sind nicht selbstständig lauffähig und werden ausschließlich vom Core aufgerufen.\\
Auch für diese Dateien gilt folgende Regel:\\
:!: **//Achtung: Verlassen Sie sich niemals darauf, dass die Basis-Dateien eines Addons im 'Global Scope' ((mit 'Scope' wird der Sichtbarkeits- und Gültigkeitsbereich einer Variablen bezeichnet. 'Global Scope ist der Bereich, der auch durch die Superglobale $_GLOBALS[] angesprochen wird.)) geladen und ausgeführt werden!!
Gehen Sie grundsätzlich immer von der Annahme aus, dass diese Dateien innerhalb einer Funktion/Klassenmethode aufgerufen werden und dadurch selbstverständlich globale Variablen nicht direkt zur Verfügung stehen!//**\\
[[dev:284:q_a-helloworld?&#weshalb_keine_page_id_mehr_in_addons|{{:quest.png?32|}}]]  [[dev:284:q_a-helloworld?&#weshalb_keine_page_id_mehr_in_addons|Weshalb wird die page_id in Addons nicht mehr benötigt?]]\\
Ein Page-Addon benötigt wenigstens eine Basis-Tabelle in der Datenbank. Die Tabelle muss nach dem Muster: mod_AddonName benannt werden und muss zumindest ein Integer Datenfeld für die SectionId enthalten.  Jeder Datensatz in dieser Tabelle verknüpft eine Instanz des Addons mit einer Section. Weitere Datenfelder können z.B. die Grundeinstellungen der jeweiligen Addon-Instanz aufnehmen.
==== add.php (erforderlich) ====

<file php add.php>
<?php
/**
 * add.php
 *
 * @category     Addon
 * @package      Addon_HelloWorld
 * @copyright    Manuela v.d.Decken <manuela@isteam.de>
 * @author       Manuela v.d.Decken <manuela@isteam.de>
 * @license      http://www.gnu.org/licenses/gpl.html   GPL License
 * @version      0.0.1
 * @revision     $Revision: 1 $
 * @lastmodified $Date: 2014-11-30 00:00:00 +0100 (So, 30 Nov 2014) $
 * @since        File available since 30.11.2014
 * @description  defines a new instance of this addon
 */
if (! defined('WB_PATH')) { die('Cannot access this file directly'); }
/* -------------------------------------------------------- */
// --- import needed objects ---------------------------------
    $oReg  = WbAdapter::getInstance();  // get the instance of the active registry
// --- import needed global vars -----------------------------
    
//  here you can set/get basical settings for this instance
    $oAddonReg = new AddonRegistry($oReg, basename(__DIR__), array('instance'=>$oReg->InstanceId));
    $oAddonReg->setEntry('Template', 'MyFirstOwnTemplate');

// --- end of file -------------------------------------------
</file>

==== delete.php (erforderlich) ====

<file php delete.php>
<?php
/**
 * add.php
 *
 * @category     Addon
 * @package      Addon_HelloWorld
 * @copyright    Manuela v.d.Decken <manuela@isteam.de>
 * @author       Manuela v.d.Decken <manuela@isteam.de>
 * @license      http://www.gnu.org/licenses/gpl.html   GPL License
 * @version      0.0.1
 * @revision     $Revision: 1 $
 * @lastmodified $Date: 2014-11-30 00:00:00 +0100 (So, 30 Nov 2014) $
 * @since        File available since 30.11.2014
 * @description  delete actual instance of this addon
 */
if (! defined('WB_PATH')) { die('Cannot access this file directly'); }
/* -------------------------------------------------------- */
// --- import needed objects ---------------------------------
    $oReg  = WbAdapter::getInstance();  // get the instance of the active registry
// --- import needed global vars -----------------------------
    
// -----------------------------------------------------------
/* ***********************************************************
 *                                                           *
 * put here all additional code to clean up this instance    *
 *                                                           *
 * **********************************************************/    
// --- finaly remove record from table `mod_helloworld_settings` ------
    $sql = 'DELETE FROM `'.$oReg->Db->TablePrefix.'mod_helloworld_settings` '
         . 'WHERE `instance`='.$oReg->InstanceId;
    if (! $oReg->Db->doQuery($sql)) {
        // use string var $sErrorMessage for returning of error messages!
        $sErrorMessage = $oReg->Db->getError();
    }
// --- end of file -------------------------------------------
</file>


FIXME ... und es geht noch weiter...
WebsiteBaker Documentation

Benutzer-Werkzeuge

Webseiten-Werkzeuge

Seiten-Werkzeuge
