Zum Inhalt springen
Znuny Logo Znuny Community Docs

Internes Erweitern des Znuny-Kernsystems

In diesem Artikel lernst du, wie du Znuny direkt im Kern anpasst – über XML-Konfiguration, Perl-Module und Templates. Wir zeigen dir Schritt für Schritt, wie du ein eigenes „HelloWorld“-Modul ins System einbindest.

1. Verzeichnisstruktur

Abschnitt betitelt „1. Verzeichnisstruktur“

Alle Anpassungen liegen unterhalb deines Znuny-Clones im Kernel/-Verzeichnis:

Kernel/
├─ Config/Files/           # XML-Registrierungen
│  └─ XML/
├─ System/                 # Geschäftslogik-Module (Core)
├─ Modules/                # Frontend-Controller (Agent/Customer)
├─ Output/HTML/Standard/   # Template Toolkit (TT)-Templates
└─ Language/               # Übersetzungen

2. XML-Konfiguration

Abschnitt betitelt „2. XML-Konfiguration“

Neue Module und Routen werden per XML registriert. Lege in Kernel/Config/Files/XML/ eine Datei HelloWorld.xml an:

<?xml version="1.0" encoding="UTF-8"?>
<znuny_config version="2.0" init="Application">


  <!-- 1. Frontend-Modul registrieren -->
  <Setting Name="Frontend::Module###AgentHelloWorld" Required="1" Valid="1">
    <Navigation>Frontend::Agent::ModuleRegistration</Navigation>
    <Value>
      <Item ValueType="FrontendRegistration">
        <Hash>
          <Item Key="Group"><Array><Item>users</Item></Array></Item>
          <Item Key="Description" Translatable="1">HelloWorld Modul</Item>
          <Item Key="Title"       Translatable="1">HelloWorld</Item>
          <Item Key="NavBarName">HelloWorld</Item>
        </Hash>
      </Item>
    </Value>
  </Setting>


</znuny_config>

3. Core-Modul (Geschäftslogik)

Abschnitt betitelt „3. Core-Modul (Geschäftslogik)“

Erstelle in Kernel/System/HelloWorld.pm deine Logik:

package Kernel::System::HelloWorld;
use strict;
use warnings;
our @ObjectDependencies = ();


sub new {
    my ($Type, %Param) = @_;
    return bless {}, $Type;
}


sub GetHelloWorldText {
    my ($Self, %Param) = @_;
    return $Self->_FormatText(String => 'Hello World');
}


sub _FormatText {
    my ($Self, %Param) = @_;
    return uc $Param{String};
}


1;

4. Frontend-Modul (Controller)

Abschnitt betitelt „4. Frontend-Modul (Controller)“

In Kernel/Modules/AgentHelloWorld.pm bindest du deine Logik ins Agent-Frontend ein:

package Kernel::Modules::AgentHelloWorld;
use strict;
use warnings;


sub new { bless {}, shift }


sub Run {
    my ($Self, %Param) = @_;


    my $HelloObj    = $Kernel::OM->Get('Kernel::System::HelloWorld');
    my $LayoutObj   = $Kernel::OM->Get('Kernel::Output::HTML::Layout');
    my %Data;


    $Data{Text} = $HelloObj->GetHelloWorldText();


    return
        $LayoutObj->Header(Title => 'HelloWorld')
      . $LayoutObj->NavigationBar()
      . $LayoutObj->Output(
          TemplateFile => 'AgentHelloWorld',
          Data         => \%Data,
        )
      . $LayoutObj->Footer();
}


1;

5. Templates (TT)

Abschnitt betitelt „5. Templates (TT)“

Lege in Kernel/Output/HTML/Standard/AgentHelloWorld.tt folgendes Template an:

[% Data.Text %]


<p>Das ist dein selbst erstelltes HelloWorld-Modul!</p>

6. Beispiel-Workflow

Abschnitt betitelt „6. Beispiel-Workflow“

  1. Neu laden:

    Terminal-Fenster
    bin/znuny.Console.pl Maint::Config::Rebuild

  2. Cache leeren:

    Terminal-Fenster
    bin/znuny.Console.pl Maint::Cache::Delete

  3. Browser öffnen: Agent-Interface → Menü → „HelloWorld“

7. Tipps & Best Practices

Abschnitt betitelt „7. Tipps & Best Practices“
  • ObjectDependencies sauber deklarieren (z.B. DB, Layout).
  • POD-Dokumentation in Perl-Modulen nicht vergessen.
  • Übersetzungen unter Kernel/Language/de_*.pm pflegen.
  • Unit-Tests mit Mojolicious einrichten (optional).
  • Nach jeder Änderung Config rebuild & Cache löschen.

Damit hast du eine solide Vorlage, um weitere Kern-Erweiterungen in Znuny zu realisieren. Viel Spaß beim Entwickeln!

Individuelle Znuny Plugin- & Modulentwicklung

Benötigen Sie ein maßgeschneidertes Znuny-Paket oder müssen Altmodule aktualisiert werden? Softoft entwickelt release-sichere Erweiterungen.

Entwicklung anfragen

Häufig gestellte Fragen

Welche Verzeichnisstruktur ist für Kernanpassungen in Znuny relevant und wofür dienen die einzelnen Bereiche?

Für Kernanpassungen in Znuny ist das Kernel/-Verzeichnis der zentrale Ort. Es beherbergt verschiedene Unterverzeichnisse, die jeweils spezifische Funktionen erfüllen:

  • Kernel/Config/Files/XML/: Hier werden XML-Dateien abgelegt, die zur Registrierung neuer Module, Routen oder Systemkonfigurationen dienen. Sie definieren, wie das System neue Komponenten erkennt und integriert.
  • Kernel/System/: Dieses Verzeichnis enthält die Core-Module, die die eigentliche Geschäftslogik von Znuny abbilden. Hier werden Funktionen implementiert, die Daten verarbeiten, Datenbankzugriffe steuern oder komplexe Abläufe managen.
  • Kernel/Modules/: Hier sind die Frontend-Controller-Module zu finden, die für die Interaktion mit dem Benutzer im Agenten- oder Kunden-Interface zuständig sind. Sie rufen die Geschäftslogik aus Kernel/System/ auf und bereiten Daten für die Darstellung vor.
  • Kernel/Output/HTML/Standard/: In diesem Verzeichnis liegen die Template Toolkit (TT)-Templates, die für die visuelle Ausgabe im Browser verantwortlich sind. Sie definieren das Layout und die Darstellung der von den Frontend-Modulen bereitgestellten Daten.
  • Kernel/Language/: Hier werden die Sprachdateien für Übersetzungen abgelegt, um die Benutzeroberfläche und Modultexte in verschiedenen Sprachen bereitzustellen.
    Diese Struktur ermöglicht eine klare Trennung von Konfiguration, Logik, Präsentation und Internationalisierung.

Quellen

Wie wird ein neues Frontend-Modul in Znuny über XML-Konfiguration registriert und welche Einstellungen sind dabei wichtig?

Ein neues Frontend-Modul wird in Znuny durch eine XML-Datei im Verzeichnis Kernel/Config/Files/XML/ registriert. Diese XML-Datei definiert die notwendigen Einstellungen, damit das System das Modul erkennt und im Frontend verfügbar macht. Im Beispiel der Seite wird eine Datei namens HelloWorld.xml verwendet.

Die wichtigsten Einstellungen innerhalb der <Setting>-Tags sind:

  • Name="Frontend::Module###AgentHelloWorld": Dies ist der eindeutige Name der Einstellung, der das Modul identifiziert. AgentHelloWorld ist hier der Name des Perl-Moduls im Kernel/Modules/-Verzeichnis.
  • <Navigation>Frontend::Agent::ModuleRegistration</Navigation>: Dieser Wert gibt an, dass es sich um eine Registrierung für ein Frontend-Modul im Agenten-Interface handelt.
  • <Value>: Hier werden detailliertere Metadaten des Moduls definiert:
    • Group: Eine Liste von Benutzergruppen, die Zugriff auf das Modul haben sollen (z.B. users).
    • Description (Translatable): Eine kurze Beschreibung des Moduls, die übersetzbar ist.
    • Title (Translatable): Der Titel, der im Navigationsmenü angezeigt wird.
    • NavBarName: Ein optionaler, kürzerer Name für die Navigationsleiste.

Nachdem die XML-Datei erstellt wurde, muss die Systemkonfiguration neu aufgebaut und der Cache geleert werden, damit die Änderungen wirksam werden.

Quellen

Wie interagieren Core-Module und Frontend-Module in Znuny, um eine neue Funktion bereitzustellen?

In Znuny arbeiten Core-Module (Geschäftslogik) und Frontend-Module (Controller) eng zusammen, um neue Funktionen im System bereitzustellen. Das Core-Modul, wie im Beispiel Kernel::System::HelloWorld, ist für die eigentliche Datenverarbeitung und Logik zuständig. Es enthält Methoden, die spezifische Aufgaben ausführen, wie zum Beispiel das Abrufen oder Formatieren von Daten. Core-Module sind unabhängig von der Benutzeroberfläche und können von verschiedenen Stellen im System aufgerufen werden.

Das Frontend-Modul, wie Kernel::Modules::AgentHelloWorld, fungiert als Controller. Es ist die Schnittstelle zum Benutzer im Agenten- oder Kunden-Interface. Seine Hauptaufgabe ist es, Benutzeranfragen zu empfangen, die notwendigen Core-Module über den ObjectManager ($Kernel::OM->Get()) zu instanziieren und deren Methoden aufzurufen, um die benötigten Daten zu erhalten. Anschließend bereitet das Frontend-Modul diese Daten für die Darstellung vor und übergibt sie an ein Template, das die finale HTML-Ausgabe generiert. Diese Trennung ermöglicht eine saubere Architektur, bei der Logik und Präsentation entkoppelt sind.

Quellen

Welche Schritte sind nach der Entwicklung eines neuen Moduls notwendig, damit es im Znuny-System aktiv wird?

Nachdem Sie ein neues Modul (bestehend aus XML-Konfiguration, Core-Modul, Frontend-Modul und Template) entwickelt haben, sind zwei entscheidende Schritte erforderlich, damit Ihre Änderungen im Znuny-System wirksam werden und Ihr Modul im Frontend sichtbar und nutzbar ist:

  1. Konfiguration neu aufbauen (Maint::Config::Rebuild): Znuny verwendet eine gecachte Version seiner Systemkonfiguration. Neue XML-Dateien oder Änderungen an bestehenden Konfigurationen werden erst nach einem Neuaufbau der Konfiguration vom System erkannt. Dies geschieht über den Befehl bin/znuny.Console.pl Maint::Config::Rebuild. Dieser Schritt kompiliert die XML-Einstellungen in das interne Perl-Format, das Znuny zur Laufzeit verwendet.
  2. Cache leeren (Maint::Cache::Delete): Neben der Konfiguration speichert Znuny auch verschiedene andere Daten im Cache, um die Performance zu verbessern. Dazu gehören auch Template-Caches oder Modul-Caches. Um sicherzustellen, dass das System die neuesten Versionen Ihrer Module und Templates lädt, muss der Cache geleert werden. Dies erreichen Sie mit dem Befehl bin/znuny.Console.pl Maint::Cache::Delete.

Erst nach diesen beiden Schritten können Sie Ihr neues Modul im Browser über das Agenten-Interface aufrufen und testen. Es ist eine bewährte Praxis, diese Schritte nach jeder relevanten Änderung an der Kernkonfiguration oder den Modulen durchzuführen.

Quellen

Welche Best Practices sollten bei der Entwicklung von Kern-Erweiterungen in Znuny beachtet werden?

Bei der Entwicklung von Kern-Erweiterungen in Znuny gibt es mehrere Best Practices, die die Wartbarkeit, Stabilität und Zukunftsfähigkeit Ihrer Anpassungen sicherstellen:

  • ObjectDependencies sauber deklarieren: In Ihren Perl-Modulen sollten Sie alle benötigten Objekte (z.B. Kernel::System::DB, Kernel::Output::HTML::Layout) explizit in @ObjectDependencies deklarieren. Dies hilft dem ObjectManager ($Kernel::OM) bei der korrekten Instanziierung und verbessert die Testbarkeit.
  • POD-Dokumentation: Fügen Sie Ihren Perl-Modulen aussagekräftige POD-Dokumentation (Plain Old Documentation) hinzu. Dies erleichtert anderen Entwicklern und Ihnen selbst das Verständnis der Modulfunktionen und -schnittstellen.
  • Übersetzungen pflegen: Für eine mehrsprachige Unterstützung sollten alle im Frontend sichtbaren Texte in den entsprechenden Sprachdateien unter Kernel/Language/de_*.pm (oder anderen Sprachen) gepflegt werden. Verwenden Sie die Translatable="1"-Attribute in der XML-Konfiguration.
  • Unit-Tests einrichten: Obwohl optional, ist das Schreiben von Unit-Tests (z.B. mit Mojolicious) für Ihre Module eine sehr empfehlenswerte Praxis. Tests helfen, Fehler frühzeitig zu erkennen und stellen sicher, dass zukünftige Änderungen keine Regressionen verursachen.
  • Konfiguration neu aufbauen und Cache leeren: Nach jeder Änderung an der Konfiguration oder den Modulen ist es unerlässlich, die Konfiguration mit bin/znuny.Console.pl Maint::Config::Rebuild neu aufzubauen und den Cache mit bin/znuny.Console.pl Maint::Cache::Delete zu leeren, damit die Änderungen wirksam werden.

Durch die Einhaltung dieser Richtlinien schaffen Sie robuste und gut dokumentierte Erweiterungen für Ihr Znuny-System.

Quellen