Tworzenie wtyczek za pomocą pakietów OPM

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

---

1. Struktura pliku .sopm

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

<?xml version="1.0" encoding="utf-8"?>
<otobo_package version="1.0">
  <Name>MyExtension</Name>
  <Version>1.0.0</Version>
  <Framework>10.0.x</Framework>   <!-- Minimalna wersja OTOBO -->
  <Vendor>TwojaNazwa Sp. z o.o.</Vendor>
  <URL>https://github.com/twoj-user/otobo-mypackage</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/MyExtension.xml" Permission="644"></File>
    <File Location="Kernel/System/MyExtension.pm"            Permission="644"></File>
    <File Location="Kernel/Modules/AgentMyPage.pm"           Permission="644"></File>
    <File Location="Kernel/Output/HTML/Standard/AgentMyPage.tt" Permission="644"></File>
    <File Location="Kernel/Language/pl_MyExtension.pm"       Permission="644"></File>
  </Filelist>
</otobo_package>

• Name/Version/Framework: Unikalny identyfikator pakietu i kompatybilna wersja OTOBO.
• Filelist: Wszystkie pliki, które zostaną skopiowane podczas instalacji.

---

2. Pliki i struktura katalogów

Utwórz swój pakiet we własnym katalogu, np. MyExtension/:

MyExtension/
├─ MyExtension.sopm
├─ Kernel/
│  ├─ Config/Files/XML/MyExtension.xml
│  ├─ System/MyExtension.pm
│  ├─ Modules/AgentMyPage.pm
│  ├─ Output/HTML/Standard/AgentMyPage.tt
│  └─ Language/pl_MyExtension.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 frontendowy.
• Szablony i język: Pliki TT + plik tłumaczenia .pm.

---

3. Budowanie i instalacja pakietu

3.1 Tworzenie OPM

Użyj narzędzia CLI, aby zbudować OPM z Twojego SOPM:

cd /sciezka/do/MyExtension
bin/otobo.Console.pl Dev::Package::Build \
  --sopm-file MyExtension.sopm \
  --output /tmp/MyExtension.opm

3.2 Instalacja

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

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

Aby odinstalować lub zaktualizować:

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

---

4. Punkty rozszerzeń

4.1 Pola dynamiczne

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

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

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

4.2 Handler zdarzeń

Zarejestruj swój handler zdarzeń:

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

Zaimplementuj handler w Kernel/System/Event/Handler/MyHandler.pm (metoda Run()).

4.3 Filtr wyjściowy

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

Filtr w Kernel/System/Output/Filter/MyFilter.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-packages

• Dodaj adres URL swojego repozytorium w SysConfig pod 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. Utwórz SOPM z nazwą MyCalendar.
2. Skrypt bazy danych sql/create_calendar.sql dla tabeli calendar_events.
3. XML konfiguracyjny definiuje nowe pole biletu „Termin”.
4. Moduł rdzenia Kernel/System/CalendarEvent.pm z metodami CRUD.
5. Moduły frontendowe Kernel/Modules/AgentCalendar.pm, szablon AgentCalendar.tt.
6. Zbuduj pakiet i prześlij go do OTOpar.

---

7. Wskazówki i najlepsze praktyki

• Dostosuj numer wersji w sopm (SemVer).
• Czysto wersjonuj migracje bazy danych w sql/.
• Utwórz testy jednostkowe dla klas systemowych i modułowych.
• Dokumentacja w README plus POD w modułach Perla.
• Tłumaczenia w Language/pl_*.pm i en_*.pm.

Dzięki temu masz solidną podstawę do tworzenia, dystrybucji i utrzymywania własnych wtyczek OTOBO w projektach klientów. Miłej zabawy!