Tworzenie rozszerzeń

System rozszerzeń pozwala na roszerzenie funkcjonalności FluxBB bez dotykania kodu źródłowego. FluxBB używa haków i pliku manifest, który opisuje jak je używać. Ten dokument opisuje informacje o podstawowym używaniu haków, format pliku manifest, i jak rozmieścić pliki potrzebne do wydania roszerzenia.

Haki są specjalnymi „tagami” w kodzie FluxBB, które zostają zamieniane na każdy kawałek kodu przypisanego w pliku manifest. Typowy hak wygląda tak:

($hook = get_hook('vf_start')) ? eval($hook) : null;

Powinienieś zwrócić uwagę na to czym jest „vf_start”. Jest to bowiem nazwa haka. W tym przypadku, hak znajduje się na początku pliku viewforum.php (co sugeruje prefiks „vf_”). Jeśli będziesz chciał przypisać temu hakowi kod, musisz przypisać jemu tą nazwę w pliku manifest.

Wszystkie rozszerzenia zawierają plik manifest, manifest.xml. Plik manifest jest podstawą dla każdego rozszerzenia. Jest to normalny plik XML, który zawiera informacje o rozszerzeniu, takie jak nick autora, krótki opis co dane rozszerzenie robi i wersję FluxBB, która jest wymagana do uruchomienia roszerzenia.¹⁾ Dodatkowo manifest zawiera informacje o hakach, i o tym kiedy FluxBB powinien je używać.

Typowy manifest wygląda tak:

<?xml version="1.0" encoding="UTF-8"?>
 
<extension engine="1.0">
  <id>przykladowe_rozszerzenie</id>
  <title>Przykładowe rozszerzenie</title>
  <version>0.1</version>
  <description>To jest krótki opis rozszerzenia.</description>
  <author>John Doe</author>
  <minversion>1.3 Beta</minversion>
  <maxtestedon>1.3 Beta</maxtestedon>
 
  <hooks>
    <hook id="vf_start"><![CDATA[
	// Dołącz plik z katalogu extensions
	require $ext_info['path'].'/foobar.php';
    ]]></hook>
    <hook id="vf_pre_header_load"><![CDATA[
	// Wywołaj funkcję z pliku foobar.php
	foobar_function();
    ]]></hook>
  </hooks>
</extension>

A teraz krótki opis:

<?xml version="1.0" encoding="UTF-8"?>

To jest podstawowa deklaracja XML, z która wersja języka XML jest potrzebna i jakie kodowanie ma zostać użyte. FluxBB od wersji 1.3 w pełni obsługuje kodowanie UTF-8, więc powinieneś użyć właśnie tego kodowania znaków.

<extension engine="1.0">

Powyższe określa dla której wersji silnika zostało zaprojektowane rozszerzenie. Określenie wersji silnika będzie wymagane gdy system rozszerzeń FluxBB zostanie gruntownie przepisany (stare rozszerzenia będą wtedy niekompatybilne). Aktualną wersją silnika rozszerzeń jest 1.0.

<id>przykladowe_rozszerzenie</id>

Identyfikator rozszerzenia. FluxBB używa go do rozróżniania każdego rozszerzenia, więc identyfikator powinien być unikalny. Folder, w którym znajduje się rozszerzenie musi mieć taką samą nazwę jak ID rozszerzenia. Najlepszym wyjściem jest używanie małych liter i znaku podkreślenia „_”. ID nie może być dłuższe niż 50 znaków.

<title>Przykładowe rozszerzenie</title>

Tytuł rozszerzenia. Użyj swojej wyobraźni.

<version>0.1</version>

Wersja twojego rozszerzenia. Także od ciebie zależy jakiego schematu użyjesz do określania poszczególnych wersji, ale spróbuj utrzymać numery wersji dostosowane logicznie do zmian w rozszerzeniu.

<author>John Doe</author>

Twoje imię i nazwisko.

<minversion>1.3 Beta</minversion>
<maxtestedon>1.3 Beta</maxtestedon>

Minimalna wersja FluxBB którą rozszerzenie wymaga do uruchomienia i maksymalna na której zostało przetestowane. Jeśli wersja twojego FluxBB nie jest w zakresie pomiędy wersją minimalna a wersją, na której zostało ono przetestowane, FluxBB pokaże ostrzeżenie podczas instalacji rozszerzenia.

  <hooks>
    <hook id="vf_start"><![CDATA[
	// Dołącz plik z katalogu extensions
	require $ext_info['path'].'/foobar.php';
    ]]></hook>
    <hook id="vf_pre_header_load"><![CDATA[
	// Wywołaj funkcję z pliku foobar.php
	foobar_function();
    ]]></hook>
  </hooks>

Sekcja hooks (haki) mówi FluxBB co powinien z nimi zrobić. Ta sekcja posiada podsekcje dla każdego haka użytego w rozszerzeniu, przypisanego do jego nazwy. The PHP code with which the hook is replaced with resides in the CDATA section (identified by the <![CDATA[ and ]]> tags). That is, the hooks vf_start and vf_pre_header_load will be replaced with anything you enter in their respective CDATA sections.²⁾

This example uses two hooks, both in viewforum.php.³⁾ The first hook (vf_start) simply includes a PHP file from the extension directory. As you can see, the extension has access to all the functionality of FluxBB that is available, such as the global variable FORUM_ROOT in this case. The second hook simply calls a function called defined in foobar.php.

In addition to „merely” adding functions through external files, hooks allow you to circumvent FluxBB's core functionality, and replace them with your own. For example, you can use temporary variables to get around the BBCode parser, and replace it with a completely different parser.⁴⁾

In order to make the extension easily installable for users, it needs to have a specific directory structure. Mind you, the layout is extremely simple. All you need is a directory that has the same name as the ID from your manifest. You put the manifest in that directory. Language files are put in a folder called lang and given the name Language.php e.g. myextension/lang/English.php. Everything else can be laid out as you wish.