WebsiteBaker Documentation

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Hello Classic World - Project ======
.. The classic example addon. Here, too, very much will change. In principle, however the previous, old system is is still fully compatible at least for 2.8.4. For this reason also the first description of an addon to the conventional method, however, already with new techniques and, unfortunately, still with many 'old' problems.

:!: ** Each new development / revision must be based on the general  [[dev:all:psr|Coding-Standards]] and [[en:dev:284:psr|Specific Adaption of the PSR-Standards to WB-2.8.4]]!**

Each Addon requires a series of basic files that must be available **always**. In the following descriptions, these are marked with **//(required)//**. Although these files must be present, they do not necessarily need to contain additional code. The easiest way is to directly download the sample files presented here and to use and complete them with your own code if desired.

:!: **//Note: Never rely on an execution of these basic files files of Addons in the 'Global Scope' (( 'Scope' denotes the visibility and scope of a variable.  'Global Scope' is the area which is also addressed by the superglobal $_GLOBALS [].)) \\
Always assume that these files will be called within a function / class method and thus are not, of course, global variables directly available!//**


===== The files to install all addons =====
The files //install.php//, //uninstall.php//, and //upgrade.php// are in principle called and executed automatically  at the appropriate actions by the core. You can execute them manually on your own.\\
In addition, part of the 'basic set' the file //info.php// and, if database tables are needed, yet the file //install-struct.sql//.

All files in this section are generally required for any type of Addon (page / snippet / tool).

:!: **In order that the control of the core (e.g. automatic installation) will not be interrupted, these files may not contain code that aborts the execution of the script in any way.**
FIXME (further conditions for these files)

==== info.php (currently still needed) ====
In the meantime this file is available only for backward compatibility and only contains a call to import the information from the //**info.ini**// file. New or revised features of the core grab immediate priority on the //**info.ini**// file. This compatibility feature is expected to be disabled permanently  in the future. Existing modules must therefore be changed up to this point to use the new //**info.ini**//.

<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 (required) ====

This file contains only information about the current Addon in a nutshell. **A changelog or other 'novels' have absolutely no place in this file.**\\
For more detailed information must be provided in various other specialized files in the subdirectory module directory/**//DOC/ //**:\\
**//DOC/CHANGELOG// ->** In chronological order (newest entries at the top) changes to the scripts are entered here. Also, the entry / exit of other developers will be entered at the correct time position.
**//DOC/LICENSE// ->** The place for detailed license information and other legal information.
**//DOC/COPYING// ->** This file can be used to e.g., to accommodate a copy of the GPL.
**//DOC/README.EN// ->** Here is unlimited space for detailed descriptions and instructions. By adapting the file extension, such information may be written in different languages.

:!: **Version numbers must only be given in a format that is compatible with the PHP function //version_compare()//.**

<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"

</code>
==== install-struct.sql ====
:!: **This file is only needed if the addon is to get their own database tables!**

[[dev:284:q_a-helloworld?&#was_ist_eine_sql-strukturdatei|{{:quest.png?32|}}]]  [[dev:284:q_a-helloworld?&#was_ist_eine_sql-strukturdatei|What is a SQL file structure?]]

The sample files for Install / Upgrade / Uninstall included the final integration of the SQL file structure.\\
If the file //install-struct.sql// is not present, for example, because simply no database tables are required, the code automatically recognizes this and simply proceeds with the individual part.

<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 (required) ====
The installation of an Addon basically is done by core methods. Only pure Addon specific things, such as creating new database tables are created by this file.
<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 complement by return error messages !!
==== uninstall.php (required) ====
The uninstall of an Addon is mostly done by core methods, too. This file must actually only ensure that everything outside the addon directory was created/modified (which is actually strictly forbidden according to the coding standards) or in tables that do not belong to the addon, is reverted. The tables of the addon will be deleted by the SQL-based Core Importer of the //install-struct.sql//. After executing this file //uninstall.php// the Core will delete the entire addon folder and removes all relevant entries to this module from all core files.
:!: **It is generally //not// possible to delete an addon, if it is still on in use on any page!!**

<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 accomplish by the return of error messages!!
==== upgrade.php (required) ====
This file has a habit that they can always continue to grow over time. Each transition from one version to another may require that the information about the addon must be adapted to new conditions. One of the most important rules for this file is: It must be possible to update from any version to the latest version.

<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 complement by return error messages !!

===== The files of addons of type 'page' =====
A so-called 'Page'-Addon currently needs a set of files so that the core can control the creating, deleting and managing of addon instances. These '//required//' files can not be run stand alone, but the can only be called from the core.\\
For these files, the following rule applies:
:!: **//Warning: Never assume that the base files of addons are loaded and run in the 'Global Scope' (( 'Scope' denotes the visibility and scope of a variable.  'Global Scope' is the area which is also addressed by the superglobal $_GLOBALS [].))

Always assume that the files are called from inside a function/class method and of course, global variables are not available!//**\\
[[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|Why is page_id no longer needed in addons?]]\\
A Page addon requires at least one base table in the database. The table must be according to the pattern: it must be named mod_AddonName and have at least an integer data field included for SectionId. Each record in this table associates an instance of the addon with a Section. More fields can contain standard settings of the addon instance, for example.
==== 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 (required) ====

<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 ... and many more things to be added...
WebsiteBaker Documentation

User Tools

Site Tools

Page Tools
