Podstawy tworzenia pluginów

1 Wstęp

Pluginy (pol. wtyczki) pozwalają rozszerzyć lub zmodyfikować funkcje mybb w sposób modułowy, co umożliwia nam łatwe zarządzanie nimi. Pluginy w łatwy sposób można zainstalować, odinstalować, aktywować lub dezaktywować. Tworzenie wtyczek wymaga dobrej znajomości PHP, SQL oraz znajomości działania MyBB. Pomoc w tworzeniu pluginów otrzymasz w tym dziale.

ZALECA SIĘ BY WSZYSTKIE ZMIANY NA FORUM BYŁY WYKONYWANE ZA POMOCĄ WTYCZEK, ZAMIAST MODYFIKOWANIA PLIKÓW MYBB.

2 Podstawy tworzenia pluginów

Każdy plugin musi posiadać swoją unikalną nazwę, w jednym ciągu, którą następnie użyjesz w niektórych nazwach funkcji. Na potrzeby tego poradnika użyjemy nazwy "pierwszyplugin".

Stwórz plik pluginu w folderze inc/plugins i nazwij go tak, jaką skróconą nazwę wybrałeś, np. inc/plugins/pierwszyplugin.php.

Następnie zacznij od dodania następującego kodu.

<?php

// Odebranie bezpośredniego dostępu do tego pliku bez odpowiednich upranień
if(!defined("IN_MYBB"))
{
    die("Bezpośrednie wykonanie tego pliku nie jest dozwolone.");
}


function pierwszyplugin_info()
{
    return array(
        "name"            => "",
        "description"    => "",
        "website"        => "",
        "author"        => "",
        "authorsite"    => "",
        "version"        => "1.0",
        "guid"             => "",
        "codename"        => "",
        "compatibility" => "*"
    );
}

function pierwszyplugin_install()
{

}

function pierwszyplugin_is_installed()
{

}

function pierwszyplugin_uninstall()
{

}

function pierwszyplugin_activate()
{

}

function pierwszyplugin_deactivate()
{

} 


Funkcje wymienione powyżej muszą być poprzedzone nazwą wtyczki.

W związku z tym musisz zamienić nazwę pierwszyplugin na swoją którą wybrałeś, np systemreputacji_info jeżeli Twoja wtyczka ma nazwę systemreputacji.php.

Funkcja _info() służy do podania głównych informacji o pluginie, takich jak nazwa, opis, autor, wersja lub kompatybilność z mybb. Reszta funkcji odpowiada za instalacje, aktywację, odinstalowanie i dezaktywowanie pluginu. Należy jednak pamiętać, by cofać zmiany wykonane w bazie danych (ustawienia, style, szablony, tabele itd), czyli jeżeli przy instalacji tworzysz tabelę mybb_lista, by ją potem skasować.

Teraz wypełnij treść wtyczki zgodnie z potrzebą:

_info()
Zwraca tablicę z informacją o wtyczce:

• name: nazwa wtyczki
  
• description: opis co wykonuje ta wtyczka
  
• website: adres dla jakiej strony została wykonana ta wtyczka (opcjonalne)
  
• author: autor wtyczki
  
• authorsite: strona autora wtyczki (opcjonalnie)
  
• version: numer wersji pluginu
  
• guid: unikalny identyfikator wydany przez system pluginów mybb, do sprawdzania aktualności wtyczki (przestarzałe, lepiej użyć codename)
  
• compatibility: Lista obsługiwanych wersji mybb. Np 181, 183 lub 18*.
  
• codename: unikalna nazwa kodowa w sekcji 
  

_install()
Wykonuje się kiedy plugin jest instalowany poprzez przycisk instaluj w panelu administratora. Gdy nie dodamy tej funkcji, zamiast przycisku instaluj będzie aktywuj (_activeate()).

Najlepiej tutaj stwórz potrzebne tabele, style i ustawienia.

_is_installed()
Funkcja zwraca czy plugin jest zainstalowany (TRUE), czy nie (FALSE).

Zawartość funkcji trzeba samemu uzupełnić, sprawdzając np czy dana tabela jest utworzona.

function pierwszyplugin_is_installed()
{
    global $db;
    if($db->table_exists("pierwszy_plugin"))
    {
        return true;
    }
    return false;
} 


_uninstall()
Wykonuje się gdy plugin jest odinstalowywany. Przycisk odinstaluj nie pokarze się w panelu administratora gdy nie dodamy tej funkcji.

_activeate()
Wykonuje się gdy ktoś aktywuje plugin. Poprawnie używa się go, by plugin stał się widoczny po dodaniu/edycji szablonów, plików językowych itp.

_deactivate()
Wykonuje się gdy plugin zostanie dezaktywowany. Dobre do wyłączenia jego funkcji by wprowadzić drobne zmiany. Nie powinno się tutaj kasować żadnych danych, gdyż od tego jest funkcja _uninstall().

3 Odwołanie się do funkcji mybb (Hook)

Używasz tego gdy chcesz "podpiąć" jakąś funkcję do kodu mybb. Możesz to wykonać do wielu funkcji mybb, a ich listę znajdziesz tutaj.

Podstawy

By użyć odwołania, musisz umieścić poniższy kod nad funkcją _info().

$plugins->add_hook('<hook name>', '<function name>'); 


Gdzie <hook name> jest nazwą odwołania, a <function name> nazwą funkcji którą chcesz wykonać.


Poniżej przykład użycia odwołania do funkcji index_start, przez funkcję wykonac_cos().

$plugins->add_hook('index_start', 'wykonac_cos'); 


Teraz należy zdefiniować funkcję wykonac_cos. By tego dokonać, gdzieś na dole pluginu tworzymy następujący kod:

function wykonac_cos()
{
    // Możesz tu wykonać cokolwiek
} 


By otrzymać niektóre główne dane z MyBB trzeba "przywołać" globalne zmienne, w których zawarte są informacje o naszym silniku.
np. $mybb, $db, $user
Dla przykładu możesz sprawdzić czy dany użytkownik jest administratorem:

function wykonac_cos()
{
    global $mybb;
    if($mybb->usergroup['cancp'] == 1)
    {
        // Tylko aministrator
    }
    else
    {
        // Każdy
    }
} 


Odwołania z argumentami

Niektóre odwołania mają argumenty, które podczas wykonywania funkcji możesz odczytać. Poniżej dwa przykłady takich odwołań:

$plugins->add_hook("pre_output_page", "hello_world");

$plugins->add_hook("postbit", "hello_world_postbit"); 


A teraz dwa przykłady funkcji, jeden odczytuje i wyświetla argument, natomiast drugi go edytuje.

function hello_world($page)
{
    // To doda tekst Hello World! na górze tekstu
    $page = str_replace(
        '<div id="content">',
        '<div id="content"><p>Hello World!</p>',
        $page
    );
    return $page;
}

function hello_world_postbit(&$post)
{
    // To doda tekst Hello world! na początku każdego postu
    $post['message'] = '<strong>Hello world!</strong><br />' . $post['message'];
} 


Przy tworzeniu każdego odwołania musisz sprawdzić czy nie posiada ono żadnych argumentów.

Inne opcje odowłań

Istnieją dwa dodatkowe argumenty (priorytet i plik) które mogą być podpięte do funkcji $plugins->add_hook().

$plugins->add_hook('<nazwa odwołania>', '<nazwa funkcji>', '<priorytet>', '<plik>');

// Z danymi
$plugins->add_hook('index_start', 'wykonaj_cos', 5, 'jakisplik.php'); 


Gdzie <priorytet> to priorytet w wykonaniu odwołania (domyślnie 10), a jakisplik.php dodaje zdefiniowany plik podczas wykonywania odwołania.

4 Ustawienia pluginów

Pluginy umożliwiają tworzenie ustawień w sekcji Konfiguracja w panelu administratora.

Ustawienia dodaje i usuwa się w funkcji _install() oraz _uninstall(), dzięki czemu można dezaktywować plugin, bez utraty danych.

Dodawanie ustawień

By dodać ustawienia musisz najpierw utworzyć ich grupę (wtedy otrzymasz numer grupy $gid).

global $db, $mybb;

$setting_group = array(
    'name' => 'mojagrupaustawien',
    'title' => 'Nazwa pluginu',
    'description' => 'Opis ustawien',
    'disporder' => 5, // Kolejność w której zostanie wyświetlona ta grupa
    'isdefault' => 0
);

$gid = $db->insert_query("settinggroups", $setting_group); 


Teraz możesz stworzyć trochę ustawień dla tej grupy:

$setting_array = array(
    // Tekstowe ustawienie
    'fav_colour' => array(
        'title' => 'Ulubiony kolor',
        'description' => 'Wpisz swój ulubiony kolor:',
        'optionscode' => 'text',
        'value' => 'Niebieski', // Default
        'disporder' => 1
    ),
    // Zaznaczenie pola wyboru
    'green_good' => array(
        'title' => 'Czy zielony jest fajny?',
        'description' => 'Wybierz swoją opcję z pola wyboru:',
        'optionscode' => "select\n0=Tak\n1=Może\n2=Nie",
        'value' => 2,
        'disporder' => 2
    ),
    // Pole wyboru tak/nie
    'mybbpl_good' => array(
        'title' => 'Lubisz mybboard.pl?',
        'description' => 'Czy podoba ci się mybboard.pl?',
        'optionscode' => 'yesno',
        'value' => 1,
        'disporder' => 3
    ),
);

foreach($setting_array as $name => $setting)
{
    $setting['name'] = $name;
    $setting['gid'] = $gid;

    $db->insert_query('settings', $setting);
}

// Nie zapomnij przebudować ustawień po każdej zmianie!
rebuild_settings(); 


Następujące typy ustawień są akceptowane:

• text: regularne pole tekstowe
  
• numeric: liczba
  
• textarea: pole tekstowe
  
• yesno: wybór tak lub nie
  
• onoff: wybór włączone lub wyłączone
  
• select: pole wyboru (jedno na każdą linię)
  
• forumselect: pole wyboru forów
  
• forumselectsinge: pole wyboru jednego fora
  
• groupselect: pole wyboru grup
  
• groupselectsinge: pole wyboru jednej grupy
  
• radio: pole wyboru okrągłych przycisków
  
• checkbox: pole wyboru bool
  
• language: pole wyboru języka
  
• adminlanguage: pole wyboru języka w panelu administratora
  
• cpstyle: pole wyboru stylu
  
• php: kod w języku php
  

Po utworzeniu ustawień, znajdziesz je w wybranej grupie w sekcji konfiguracja.

By odwołać się do ustawień użyj funkcji $mybb->settings['<nazwa ustawień>'], np. $mybb->settings['green_good'].


Usuwanie ustawień

Jeżeli utworzysz ustawienia w funkcji _install() musisz je potem usunąć w _uninstall().

Przykładowe usuwanie ustawień:

global $db;

$db->delete_query('settings', "name IN ('fav_colour','green_good','mybbpl_good')");
$db->delete_query('settinggroups', "name = 'mysettinggroup'");

// Nie zapomnij przebudować ustawień po każdej zmianie!
rebuild_settings(); 


Używanie ustawień dla fuckji _is_installed()

Możesz użyć ustawień by stworzyć funkcję _is_installed(), dzięki czemu w łatwy sposób będziesz mógł sprawdzać czy plugin jest zainstalowany (TRUE/FALSE).

Poniżej przykład użycia:

global $mybb;
if(isset($mybb->settings['green_good']))
{
    return true;
}

return false; 


Źródło: mybb.com