[Announce] BETA: Modul: HookModules 0.0.2 + Mini-Handbuch

darkside · Post by **darkside** » 13 Mar 2008, 11:00

Ein kleiner Fehler hat sich eingeschlichen, den ich nun korrigiert habe.

Download: HookModules-0.0.2.opm

Für alle die wissen möchten, worum es geht, sei der Thread Funktion der Standard Module durch eigene Module erweitern ans Herz gelegt.

Da ich momentan kein umfangreiches Howto schreiben kann, werde ich hier erst mal die grundsätzliche Verfahrensweise darlegen, wie ein "Hook"-Modul auszusehen hat. Es wird von mir aber keine große Erklärung über den Aufbau von OTRS und seinen Modulen geben. Dies kann im Entwicklerhandbuch oder in den vorhandenen Modulen direkt nachgelesen werden.

Das Hookmodul stellt zugleich ein Frontend-Modul dar, muss aber nicht als Frontendmodul registriert werden. Es wird demzufolge vom Hook-Hack unter Kernel/Modules gesucht (und nur da)
unabhängig davon können natürlich zusätzliche Backendmodule erstellt und verwendet werden
Das Hook-Modul muss mindestens die Routine "new" beinhalten, welche zur Initialisierung des Moduls verwendet wird.
Es werden dem Hook-Modul dabei die gleichen Parameter übergeben, wie jedem Frontend-Modul (bspw. Objekte wie "DBObject" oder "LogObject" etc.). Zusätzlich gibt es hier einen Parameter "ModuleObject" welches Zugriff auf das OTRS-Standard-Modul, welches gerade abgearbeitet werden soll, ermöglicht.

Empfohlener Aufbau:
Code: Select all
```
sub new {
  my $Type = shift;
  my %Param = @_;

  my $Self = {};
  bless ($Self, $Type);

  foreach (keys %Param) {
    $Self->{$_} = $Param{$_};
  }

  foreach (qw(ParamObject DBObject LayoutObject ConfigObject LogObject)) {
    if (!$Self->{$_}) {
      $Self->{LayoutObject}->FatalError(Message => "Got no $_!");
    }
  }

  <own Code>
  </own Code>

  return $Self;
}
```
Je nach Konfiguration muss es dann die Routinen "PreRun", "LayoutData", "MailSendData" und/oder "AfterRun" geben.
PreRun: Diese Routine wird nach der Initialisierung des Standard-Moduls aber noch vor Ausführung dieses Standard-Moduls aufgerufen. Der "PreRun" Routine werden keine Parameter übergeben; es gibt hier auch keinerlei Rückgabewerte die ausgewertet werden.

Empfohlener Aufbau:
Code: Select all
```
sub PreRun {
  my $Self = shift;
  my %Param = @_;

  <own Code>
  </own Code>
}
```

LayoutData: Die vom Standard-Modul aufbereiteten Ausgabedaten werden dieser Routine noch vor der Ausgabe zwecks Manipulation (hinzufügen, löschen, verändern) übergeben. Die manipulierten Daten sind von der Routine zurück zu geben.

Mindestaufbau der Routine:

Code: Select all

sub LayoutData {
  my $Self = shift;
  my %Param = @_; # in $Param{Data} befinden sich dann die zu manipulierenden Daten

  <own Code>
    <example add>
      $Param{Data}->{newValue} = "New Value"; # kann dann im Template über $Data{"NewValue"} ausgegeben werden
    </example add>

    <example edit>
      $Param{Data}->{existingValue} = "New Value";
    </example edit>

    <example delete>
      delete $Param{Data}->{existingValue};
    </example delete>
  </own Code>

  return $Param{Data};

MailSendData: Einige Module (bspw. AgentTicketCompose) senden eMails. Die vom Standard-Modul aufbereiteten eMail-Daten werden dieser Routine noch vor dem Absenden der eMail zwecks Manipulation (hinzufügen, löschen, verändern) übergeben. Die manipulierten Daten sind von der Routine zurück zu geben.

Mindestaufbau der Routine:

Code: Select all

sub MailSendData {
  my $Self = shift;
  my %Param = @_; # in $Param{Data} befinden sich dann die zu manipulierenden Daten

  <own Code>
    <example add>
      $Param{Data}->{newValue} = "New Value";
    </example add>

    <example edit>
      $Param{Data}->{existingValue} = "New Value";
    </example edit>

    <example delete>
      delete $Param{Data}->{existingValue};
    </example delete>
  </own Code>

  return $Param{Data};

AfterRun: Nachdem die HTML Ausgabe generiert wurde, aber noch bevor diese auch an den Browser gesendet wird, wird die Routine "AfterRun" ausgeführt. Als Parameter wird dieser Routine die komplett generierte Ausgabe zwecks Manipulation übergeben. Die manipulierten Daten sind von der Routine zurück zu geben.

Mindestaufbau der Routine:
Code: Select all
```
sub AfterRun {
  my $Self = shift;
  my %Param = @_; # in $Param{Output} befindet sich dann die zu manipulierende HTML Ausgabe

  <own Code>
  </own Code>

  return $Param{Output};
}
```
Die "Manipulation" der Daten in den einzelnen Routinen ist natürlich kein muss. Man kann dort auch nur bspw. Datenbanken-Aktion machen ... bspw. Daten für eine erweiterte Statistik erheben. In jedem Falle MUSS aber eine Rückgabe der übergebenen Daten erfolgen!!
Die Routinen "PreRun", "LayoutData", "MailSendData" und/oder "AfterRun" brauchen nur dann jeweils definiert werden, wenn diese Funktion mit dem Hook-Modul auch genutzt werden soll. Welche man benutzen will, wird in der Konfiguration zu dem Hookmodul festgehalten.
Die Konfiguration ist am besten in einer zum Hook mitgelieferten Konfigurationsdatei unterhalb "Kernel/Config/Files" aufgehoben. Der Aufbau muss dann so aussehen:
push (@{$Self->{HookModule}->{Name des Standardmoduls}}, [('Name des Hookmoduls', 0|1, 0|1, 0|1, 0|1)]);
Die letzten 4 Stellen sind jeweils mit einer 1 (aktiviert) ODER 0 (deaktiviert) zu versehen. Die Stellen bedeuten dabei:
1. Stelle: Ausführen von "PreRun",
2. Stelle: Ausführen von "LayoutData",
3. Stelle: Ausführen von "MailSendData",
4. Stelle: Ausführen von "AfterRun"
Beispiel aus dem Modul "ExtendedResponses":
Code: Select all
```
# registriere das Hookmodul "ExtendedResponses" für das Standardmodul "AdminResponse". Führe dabei die Routinen "PreRun", "LayoutData" und "AfterRun" aus
push (@{$Self->{HookModule}->{AdminResponse}}, [('ExtendedResponses', 1, 1, 0, 1)]);

# registriere das Hookmodul "ExtendedResponses" für das Standardmodul "AgentTicketCompose". Führe dabei die Routinen "PreRun", "LayoutData" und "MailSendData" aus
push (@{$Self->{HookModule}->{AgentTicketCompose}}, [('ExtendedResponses', 1, 1, 1, 0)]);
```

Ich hoffe diese Ausführung ist soweit verständlich.
Wenn nicht, einfach mal fragen

Andreas