Rozwój wtyczek z użyciem pakietów OPM

W tej sekcji dowiesz się, jak tworzyć własne wtyczki jako pakiety OPM dla OTOBO, instalować i dystrybuować je.

---

1. Budowa pliku .sopm

Plik SOPM (*.sopm) zawiera wszystkie metadane pakietu:

<?xml version="1.0" encoding="utf-8"?>
<otobo_package version="1.0">
  <Name>MojaRozszerzenie</Name>
  <Version>1.0.0</Version>
  <Framework>10.0.x</Framework>   <!-- Minimalna wersja OTOBO -->
  <Vendor>NazwaTwojejFirmy Sp. z o.o.</Vendor>
  <URL>https://github.com/twój-użytykownik/otobo-mojapakiet</URL>
  <License>GPL-3.0</License>
  <Description Lang="pl">Rozszerzenie dla specjalnych funkcji</Description>
  <ChangeLog Version="1.0.0" Date="13.06.2025 12:00:00">Pierwsze wydanie</ChangeLog>
  <Filelist>
    <File Location="Kernel/Config/Files/XML/MojaRozszerzenie.xml" Permission="644"></File>
    <File Location="Kernel/System/MojaRozszerzenie.pm"            Permission="644"></File>
    <File Location="Kernel/Modules/AgentMojaStrona.pm"           Permission="644"></File>
    <File Location="Kernel/Output/HTML/Standard/AgentMojaStrona.tt" Permission="644"></File>
    <File Location="Kernel/Language/pl_MojaRozszerzenie.pm"       Permission="644"></File>
  </Filelist>
</otobo_package>

• Name/Version/Framework: Unikalna identyfikacja pakietu i zgodna wersja OTOBO.
• Filelist: Wszystkie pliki, które są kopiowane podczas instalacji.

---

2. Pliki i struktura katalogów

Umieść swój pakiet w osobnym katalogu, np. MojaRozszerzenie/:

MojaRozszerzenie/
├─ MojaRozszerzenie.sopm
├─ Kernel/
│  ├─ Config/Files/XML/MojaRozszerzenie.xml
│  ├─ System/MojaRozszerzenie.pm
│  ├─ Modules/AgentMojaStrona.pm
│  ├─ Output/HTML/Standard/AgentMojaStrona.tt
│  └─ Language/pl_MojaRozszerzenie.pm
└─ sql/
   └─ create_tables.sql      # opcjonalnie, dla migracji bazy danych

• Kernel/Config/Files/XML/: Rejestruje moduły, menu lub pola dynamiczne.
• Kernel/System/: Klasa logiki biznesowej.
• Kernel/Modules/: Kontroler frontendu.
• Szablony i język: Pliki TT + pliki tłumaczeń.pm.

---

3. Budowanie i instalowanie pakietu

3.1 Tworzenie OPM

Użyj narzędzia CLI, aby utworzyć OPM z pliku SOPM:

cd /ścieżka/do/MojaRozszerzenie
bin/otobo.Console.pl Dev::Package::Build \
  --sopm-file MojaRozszerzenie.sopm \
  --output /tmp/MojaRozszerzenie.opm

3.2 Instalacja

Interfejs administracyjny: Prześlij pakiet w Admin → Ustawienia → Zarządzanie pakietami. Konsola:

bin/otobo.Console.pl Admin::Package::Install /tmp/MojaRozszerzenie.opm

Aby odinstalować lub zaktualizować:

bin/otobo.Console.pl Admin::Package::Uninstall /tmp/MojaRozszerzenie.opm
bin/otobo.Console.pl Admin::Package::Upgrade   /tmp/MojaRozszerzenie.opm

---

4. Punkty rozszerzeń

4.1 Pola dynamiczne

W Kernel/Config/Files/XML/MojaRozszerzenie.xml zarejestruj nowy sterownik pola dynamicznego:

<Setting Name="DynamicFields::Driver###MojePole" Required="0" Valid="1">
  <Navigation>DynamicFields::Driver</Navigation>
  <Value>
    <Array>
      <Item><Hash>
        <Item Key="DriverName">MojePole</Item>
        <Item Key="Module">Kernel::System::DynamicField::Driver::MojePole</Item>
      </Hash></Item>
    </Array>
  </Value>
</Setting>

Zaimplementuj sterownik w Kernel/System/DynamicField/Driver/MojePole.pm.

4.2 Obsługa zdarzeń

Zarejestruj swój obsłuchiwacz zdarzeń:

<Setting Name="Event::EventHandler###MójObsłuchiwacz" Required="0" Valid="1">
  <Navigation>Event::EventHandler</Navigation>
  <Value>
    <Array>
      <Item><Hash>
        <Item Key="Module">Kernel::System::Event::Handler::MójObsłuchiwacz</Item>
      </Hash></Item>
    </Array>
  </Value>
</Setting>

Zaimplementuj obsłuchiwacz w Kernel/System/Event/Handler/MójObsłuchiwacz.pm (Run()-metoda).

4.3 Filtrowanie wyjścia

<Setting Name="Output::Filter###MójFiltr" Required="0" Valid="1">
  <Navigation>Output::Filter</Navigation>
  <Value>
    <Array>
      <Item><Hash>
        <Item Key="Module">Kernel::System::Output::Filter::MójFiltr</Item>
      </Hash></Item>
    </Array>
  </Value>
</Setting>

Zaimplementuj filtr w Kernel/System/Output/Filter/MójFiltr.pm.

---

5. Wdrożenie i OTOpar

• Indeks repozytorium: Utwórz Packages.xml dla własnego repozytorium:

  bin/otobo.Console.pl Dev::Package::RepositoryIndex \
    --directory /var/www/otobo-pakiety

• Dodaj adres URL repozytorium w SysConfig Package::RepositoryList.

• OTOpar: Prześlij swój OPM na https://otopar.perl-services.de, aby inni mogli go zainstalować bezpośrednio.

---

6. Przykład: Pakiet MyCalendar

1. SOPM utwórz z nazwą MyCalendar.
2. Skrypt bazy danych sql/create_calendar.sql dla tabeli calendar_events.
3. Konfiguracja XML definiuje nowe pole biletu „Termin”.
4. Moduł jądra Kernel/System/CalendarEvent.pm z metodami CRUD.
5. Moduł frontendu Kernel/Modules/AgentCalendar.pm, szablon AgentCalendar.tt.
6. Pakiet zbuduj i prześlij go do OTOpar.

---

7. Porady i najlepsze praktyki

• Numer wersji w sopm dostosuj (SemVer).
• Migracje bazy danych w sql/ wersjonuj czysto.
• Testy jednostkowe dla klas systemowych i modułów.
• Dokumentacja w pliku README oraz POD w modułach Perl.
• Tłumaczenia w Language/pl_*.pm i en_*.pm.

Dzięki temu masz solidną podstawę, aby tworzyć własne wtyczki OTOBO, dystrybuować je i używać w projektach klientów. Powodzenia!