OneBB pluginy

W najnowszej wersji skryptu dodałem możliwość wgrywania własnych pluginów. Pluginy mogą korzystać z wewnętrznego API dodanego do kontrolera Plugins oraz frontowego API dostępnego w zmiennej window.$obbPlugins. Poniżej opisuję możliwości jakie daje nowa funkcjonalność.

Podstawy

Każdy plugin MUSI znajdować się wkatalogu “plugins” i folderze zgodnym z nazwą pluginu. Zalecane jest aby nazwa pluginu była zapisana CamelCase. Plik pluginu MUSI rozszerzać klasę App\Controller\Plugin\PluginController i implementować interfejs App\Controller\Plugin\PluginInterface

Wymaganymi funkcjami w każym pluginie są:

public function info() : array;
public function install() : bool;
public function active() : bool;
public function deactive() : bool;
public function uninstall() : bool;
public function getEvents(): ?array;
public function getAdminEvents(): ?array;
public function getSnippet(): ?string;

info()
Zwraca tablicę w której muszą znajdować się klucze:

[
            'name' => 'Nazwa pluginu',
            'version' => 'Wersja pluginy',
            'meta' => 'Dowolny opis max 255 znaków',
            'acp' => true, // dostęp do panelu admina bool
            'trans' => [
                [
                    'domain' => 'sl', // przedrostek pliku translacji
                    'locale' => 'pl_PL', // język translacji
                ]
            ],
        ];

install()
wywoływana podczas instalacji dodatku, tutaj zalecane jest utworzenie wszelkich kontenerów graficznych oraz pół metafield

active()
wywoływana podczas aktywacji pluginu, tutaj zalecane jest aktywowanie poszczególnych kontenerów graficznych,

deactive()
powinna wprowadzać odwrotne działanie do active, np wyłaczać kontenery graficzne.

uninstall()

analogicznie do funkcji deactive.

getEvents()
Zwraca tablicę wszystkich eventów które mogą zostać wywołane w pluginie i uruchamia odpowiednią funkcję pluginu

 public function getEvents(): ?array
    {
        return [
            'event' => 'funkcja',
        ];
    }

getAdminEvents()
tablica funkcji dostępnych do wywołania jedynie w panelu administracyjnym forum

getSnippet()
zawiera kod JS dodawany do snippetów przed zamknięciem body.

Dostępne funkcje

Rozszerzenie klasy PluginController daje dostęp do następujących funkcji:

1. createMetafield(string $namespace, string $key): Metafield
2. createMetafieldValue(Metafield $metafield, array $value): ?MetafieldValue
3. getMetafield(string $namespace, string $key): ?Metafield
4. getMetafieldValue(int $id)
5. updateMetafieldValue(int $id, array $value): bool
6. deleteMetafield(string $namespace, string $key): bool
7. deleteMetafieldValue(int $id): bool
8. createBox(string $name, string $content): ?Box
9. editBox(int $id, string $content): bool
10. setBoxOnSkin(Box $box, string $page, string $position): SkinBoxes
11. activeSkinBox($id)
12. deactiveSkinBox($id)
13. deleteBox(int $id): bool

ad 1) Pozwala na utworzenie Metafield z przypisaną przestrzenią nazw oraz kluczem w którym mogą być przechowywane dowolne wartośći przesłane przez plugin.
ad 2) Tworzy informację z danymi dla wybranego Metafield.
ad 3) Zwraca Entity Metafieldsa.
ad 4) Pobiera wartość dla danego wpisu z danymi MetafieldValue.
ad 5) Aktualizuje wybrany MetafieldValue.
ad 6) Usuwa Metafield o podanej przestrzeni nazw i kluczu.
ad 7) Usuwa dane MetafieldValue dla wybranego ID.
ad 8) Tworzy Box z kodem HTML który może być przypisany do skróki.
ad 9) Edytuje kod HTML Boxa o podanym ID,
ad 10) Przypisuje box do aktywnej skórki na podanych stronach i w podanym miejscu, dostępne parametry:
$page (string): Home, Category, Board, Plot, NewPlot, SignUp, Profile, Userlist, Validation
$position (string): top, bottom, left, right
ad 11) Aktywuje boxa o podanym ID – zostanie on wyświetlony na froncie forum,
ad 12) Deaktywuje boxa o podanym ID
ad 13) Usuwa boxa o podanym ID (operacja powoduju usunięcie przypisania boxa do skórek)

Front window.$obbPlugins

klasa window.$obbPlugins pozwala na wywołanie pluginów na froncie forum. Klasa pozwala na uruchomienie kodu w momencie wywołania danej strony za pomocą funkcji:

window.$obbPlugins.subscribe(context, func)

context: miejsce w którym ma zostać wywołana funkcja:
> Home, Category, Board, Plot, NewPlot, SignUp, Profile, Userlist, Validation
func: funkcja która ma zostać wywołana po załadowaniu wybranej strony.

window.$obbPlugins.dispatch(plugin, event, data)

uruchamia dany event pluginu, funkcja ta może również przesyłać dane w dowolnym formacie, które mogą być pobrane po stronie backendu pluginu.

Przykład snippeta który wywoła pobranie danych z pluginu “ExamplePlugin“, dla zarejestrowanego eventu “myEvent” w momencie załadowania się strony głównej. Pobrane dane zostaną przypisane do kodu HTML kontenera o ID examplePluginContent

<script>
    document.addEventListener('readystatechange', function() {
        if (document.readyState === 'complete') {
            window.$obbPlugins.subscribe('Home', function(){
            window.$obbPlugins
                .dispatch('ExamplePlugin', 'myEvent')
                .then(response => {
                    document.querySelector('#examplePluginContent').innerHTML = (response.data)
                });
            })   
        }
    }); 
</script>

Admin window.$obbPlugins

System pluginów posiada analogiczną klasę po stronie panelu administracyjnego, posiada ona dodatkowe funkcje:

routerPluginPush(plugin, temp = null, script = null, q = {})

funkcja wywołuje przekierowanie na wybraną stronę za pomocą routera VUE.
Parametry:

• plugin (string) – nazwa pluginu,
• temp (string) – nazwa funkcji odpowidzialnej za wywołanie templatki,
• script (string) – nazwa funkcji odpowidzialna za dodanie skryptu Javascript do templatki,
• q (object)- przesłanie parametrów w URL

getParam(p)

Pobiera parametr “p” z adresu URL, parametr przyjmuje wartości typu string

serializeForm(form)

zwraca formularz jako obiekt klucz: wartość dla przesłanego elementu.

dispatch(plugin, event, data = null)

działa analogicznie jak w przypadku frontu, wywołuje eventy przypisane do panelu administracyjnego.