Writing a Plugin

From EQdkp Plus
Jump to navigation Jump to search


API Level

With EQdkp Plus 2.0, we introduced an API Level for the Plugin Class. This ensures, that old Plugins cannot produce fatal errors if they use removed methods of the Plugin Class. If we want to remove or rename Plugin Class Methods, we set them as deprecated (can be viewn if Debug-Mode is enabled). After two Increasements of the API Level, we will remove the method. That means that Plugins will not work anymore and loaded by the EQDkp Plus if their API-Level is Recent API level minus three.

That means that an Plugin author has to update it's Plugin regularly to make sure his Plugin is working with the latest API.

Example

We want to remove a method in API Level 19. We set this method as deprecated and increase the API Level to 20. With API Level 22, this method will be removed. All Plugin with an API Level lower 20 will not be loaded anymore and have to be adjusted to the new API Level.

API Levels

API-Level EQdkp Plus Version
20 2.0.0
23 2.1.0

Sample Plugin

As a sample Plugin, we use our Shoutbox Plugin. 

<?php
/*
 * Project:     EQdkp Shoutbox
 * License:     Creative Commons - Attribution-Noncommercial-Share Alike 3.0 Unported
 * Link:        http://creativecommons.org/licenses/by-nc-sa/3.0/
 * -----------------------------------------------------------------------
 * Began:       2008
 * Date:        $Date: 2012-11-11 13:32:45 +0100 (So, 11. Nov 2012) $
 * -----------------------------------------------------------------------
 * @author      $Author: godmod $
 * @copyright   2008-2011 Aderyn
 * @link        http://eqdkp-plus.com
 * @package     shoutbox
 * @version     $Rev: 12426 $
 *
 * $Id: shoutbox_plugin_class.php 12426 2012-11-11 12:32:45Z godmod $
 */

if (!defined('EQDKP_INC'))
{
  header('HTTP/1.0 404 Not Found');
  exit;
}


/*+----------------------------------------------------------------------------
  | shoutbox
  +--------------------------------------------------------------------------*/
class shoutbox extends plugin_generic
{

  public $version    = '0.3.4';
  public $build      = '11404';
  public $copyright  = 'Aderyn';
  public $vstatus    = 'Beta';
  
  protected static $apiLevel = 23;

  /**
    * Constructor
    * Initialize all informations for installing/uninstalling plugin
    */
  public function __construct()
  {
    parent::__construct();

    $this->add_data(array (
      'name'              => 'Shoutbox',
      'code'              => 'shoutbox',
      'path'              => 'shoutbox',
      'contact'           => 'Aderyn@gmx.net',
      'template_path'     => 'plugins/shoutbox/templates/',
      'icon'              => 'fa-bullhorn',
      'version'           => $this->version,
      'author'            => $this->copyright,
      'description'       => $this->user->lang('sb_short_desc'),
      'long_description'  => $this->user->lang('sb_long_desc'),
      'homepage'          => EQDKP_PROJECT_URL,
      'manuallink'        => false,
      'plus_version'      => '1.0',
      'build'             => $this->build,
    ));

    $this->add_dependency(array(
      'plus_version'      => '0.7'
    ));

    // -- Register our permissions ------------------------
    // permissions: 'a'=admins, 'u'=user
    // ('a'/'u', Permission-Name, Enable? 'Y'/'N', Language string, array of user-group-ids that should have this permission)
    // Groups: 2 = Super-Admin, 3 = Admin, 4 = Member
    $this->add_permission('a', 'delete', 'N', $this->user->lang('delete'), array(2,3));
	$this->add_permission('u', 'view',    'Y', $this->user->lang('view'),    array(1,2,3,4));
    $this->add_permission('u', 'add',    'Y', $this->user->lang('add'),    array(2,3,4));

    // -- Menu --------------------------------------------
    $this->add_menu('admin', $this->gen_admin_menu());

    // -- Portal Module -----------------------------------
    $this->add_portal_module('shoutbox');

    // -- PDH Modules -------------------------------------
    $this->add_pdh_read_module('shoutbox');
    $this->add_pdh_write_module('shoutbox');

    // -- Exchange Modules --------------------------------
    $this->add_exchange_module('shoutbox_add');
    $this->add_exchange_module('shoutbox_list');


    // -- Hooks -------------------------------------------
    $this->add_hook('search', 'shoutbox_search_hook', 'search');
  }

  /**
    * pre_install
    * Define Installation
    */
  public function pre_install()
  {
    // include SQL and default configuration data for installation
    include($this->root_path.'plugins/shoutbox/includes/data/sql.php');
    include($this->root_path.'plugins/shoutbox/includes/data/config.php');

    // define installation
    for ($i = 1; $i <= count($shoutboxSQL['install']); $i++)
      $this->add_sql(SQL_INSTALL, $shoutboxSQL['install'][$i]);

    // insert configuration
    if (is_array($config_vars))
      $this->config->set($config_vars, '', 'shoutbox');
  }

  /**
    * pre_uninstall
    * Define uninstallation
    */
  public function pre_uninstall()
  {
    // include SQL data for uninstallation
    include($this->root_path.'plugins/shoutbox/includes/data/sql.php');

    for ($i = 1; $i <= count($shoutboxSQL['uninstall']); $i++)
      $this->add_sql(SQL_UNINSTALL, $shoutboxSQL['uninstall'][$i]);
  }

  /**
    * post_uninstall
    * Define Post Uninstall
    */
  public function post_uninstall()
  {
    // clear cache
    $this->pdc->del('pdh_shoutbox_table');
  }

  /**
    * gen_admin_menu
    * Generate the Admin Menu
    */
  private function gen_admin_menu()
  {
    $admin_menu = array (array(
        'name' => $this->user->lang('shoutbox'),
        'icon' => 'fa-comment',
        1 => array (
          'link'  => 'plugins/shoutbox/admin/settings.php'.$this->SID,
          'text'  => $this->user->lang('settings'),
          'check' => 'a_shoutbox_',
          'icon'  => 'fa-wrench'
        ),
        2 => array (
          'link'  => 'plugins/shoutbox/admin/manage.php'.$this->SID,
          'text'  => $this->user->lang('sb_manage_archive'),
          'check' => 'a_shoutbox_delete',
          'icon'  => 'fa-archive'
        )

    ));

    return $admin_menu;
  }

}

?>

Possibilities

Here are some possibilities that you can do with our Plugin Class.

Add Dependencies

$this->add_dependency(array(
  'plus_version'      => '2.0'
 ));

Available Dependencies:

  • plus_version : string; The needed EQdkp Plus Core Version
  • games : array(string, string, ...); String-Array for all supported games; Remove if all games should be supported
  • php_functions : array(string, string, ...); String-Array with required php functions

Add Permissions

$this->add_permission('a', 'delete', 'N', $this->user->lang('delete'), array(2,3));
  • permissions: 'a'=admins, 'u'=user
  • ('a'/'u', Permission-Name, Enable? 'Y'/'N', Language string, array of user-group-ids that should have this permission)
  • Groups: 2 = Super-Admin, 3 = Admin, 4 = Member

You can check the permission with the user methods. 

$this->user->check_auth('a_shoutbox_delete');

The Plugin Name will automatically added to the Permission name.

Add Menu

$this->add_menu($menu_name, $menu_array);
//Example:
$this->add_menu('admin', $this->gen_admin_menu());

Available Menu name:

  • admin (The Admin Menu, Submenu in Extensions Section)
  • main (The Mainmenu)
  • settings (The Usersettings)

Example Admin Menu: 

  private function gen_admin_menu()
  {
    $admin_menu = array (array(
        'name' => $this->user->lang('shoutbox'),
        'icon' => 'fa-comment',
        1 => array (
          'link'  => 'plugins/shoutbox/admin/settings.php'.$this->SID,
          'text'  => $this->user->lang('settings'),
          'check' => 'a_shoutbox_',
          'icon'  => 'fa-wrench'
        ),
        2 => array (
          'link'  => 'plugins/shoutbox/admin/manage.php'.$this->SID,
          'text'  => $this->user->lang('sb_manage_archive'),
          'check' => 'a_shoutbox_delete',
          'icon'  => 'fa-archive'
        )

    ));

    return $admin_menu;
  }

Add Portal Module

$this->add_portal_module($portalmodule_name);

Portal Module has to be in Subfolder "portal".

Add PDH Modules

    $this->add_pdh_read_module('shoutbox');
    $this->add_pdh_write_module('shoutbox');

PDH Modules have to be in Subfolder "pdh". For more information about PDH see Plus Data Handler.

Add Exchange Module

    $this->add_exchange_module('shoutbox_add');

Exchange modules have to be in subfolder "exchange". For more information about Exchange modules see Plus Exchange.

Add Hook

    $this->add_hook('search', 'shoutbox_search_hook', 'search');

Hooks have to be in subfolder "hooks". For more information about Hooks see Hooks/en.

Add Notifications

You should add the notification type at the post_install method. 

//public function addNotificationType($strID, $strLanguageVar, $strCategory, $intPrio=0, $blnDefault=0, $blnGroup=false, $strGroupLangVar="", $intGroupAt=3, $strIcon="")
$this->ntfy->addNotificationType('mediacenter_media_unpublished', 'mc_notify_unpublished_media', 'mediacenter', 1, 1);

Also, you should delete the type at the pre_uninstall method 

//public function deleteNotificationType($strID){
$this->ntfy->deleteNotificationType('mediacenter_media_unpublished');

Creating a new notifications works like this: 

//public function add($strType, $strDatasetID, $strFromUsername, $strLink, $intUserID=false, $strAdditionalData="", $intCategoryID=false, $mixPermission=false)
$this->ntfy->add('mediacenter_media_new', $intRealCategoryID, $this->pdh->get('user', 'name', array($intUserID)), $strLink, false, $strCategoryName);

Routing

Register your Pageobjects in the constructur. 

$this->routing->addRoute('WriteApplication', 'addrequest', 'plugins/guildrequest/page_objects');

Pageobjects should be in subfolder "pageobjects". For more information about Routing see Routing.

Install

  • pre_install()
  • post_install()

Uninstall

  • pre_uninstall()
  • post_uninstall()

Language

Language files are located in subfolder "language".

Templates

Templates should be located in subfolder "templates". Admin Templates should be located in subfolder "templates/admin".

Changes

Changes with 2.1

  • Increased API Level to 23
  • New way to add own language vars
$this->user->objLanguage->add_lang($this->user->lang_name, $lang);

Changes with 2.3

  • Cronjobs now handled by cronjobs-class, instead of timekeeper. The Methods stay the same.
  • HTML Elements now use the output method.
    'MY_DROPDOWN' => (new hdropdown(.....))->output(),
  • For Captchas, there is a new captcha class with handles all captchas. The direct use of Recaptcha is deprecated
  • Breadcrumbs are now handled with PHP (page_path variable at core->set_vars() method), no breadcrumbs in template files needed anymore
Retrieved from "https://wiki.eqdkp-plus.eu/w/index.php?title=Writing_a_Plugin&oldid=1732"