Hooks system: Difference between revisions

Jump to navigation Jump to search

Hooks system (view source)

Revision as of 08:29, 20 September 2022

3,622 bytes removed ,  4 years ago
no edit summary
VisualWikitext
Tag: 2017 source edit
No edit summary
Tag: 2017 source edit
Line 10: Line 10:
{{TemplateDocDevEn}}
{{TemplateDocDevEn}}


=Einführung=
=Introduction=
Hooks sind eine Funktion für Entwickler, mit der sie benutzerdefinierten Code zu den Standardseiten von Dolibarr hinzufügen können, ohne die Kerndateien von Dolibarr ändern zu müssen. Im Gegensatz zum Trigger-System (eine andere Möglichkeit, mit dem Code von Dolibarr zu interagieren), das an Ereignisse in Dolibarr gebunden ist, können Hooks überall und jederzeit ausgeführt werden, wenn sie im Kern von Dolibarr vorgesehen sind. Sie sind Einfügungsstellen im Programm.  
Every business always requires something "extra" or different to the Dolibarr core functionality.
While all improvements and extensions to the Dolibarr code should be contributed back via Github to be included in a future version, some modifications will be too specific to be of interest to all.
Hence the Hooks system was introduced in Dolibarr. This allows developers to add custom code/features to the Dolibarr core files without the need to modify the core files.
This greatly simplifies the upgrading process by keeping modifications separate from the core code.


*Hooks sind abhängig von einem Kontext aktiv oder nicht (häufig ein Kontext pro Modul: zum Beispiel „productcard“ für Produkte, „invoicecard“ für Rechnungen...). Um vorhandene Hooks zu finden, suchen Sie nach  '''" initHooks( "'''
As opposed to [[triggers]] (actions linked to a business event) − hooks are entry points into the program and can modify any part of the program functions.
*Hooks sind Funktionen, die Standardcode einfügen oder ersetzen. Um Code zu finden, der überschrieben werden kann, suchen Sie nach '''" executeHooks("'''
There are many hooks already built into the code and you may add more. They can be considered a point where the code execution is diverted "out" of the current page and runs your code, then returns back.
Your custom code may add something or modify an object or completely replace an existing code block, depending on the implementation of the hook in that specific instance.


==Einen Hook hinzufügen, um das Einfügen von Code zu ermöglichen==
Every hook has a name, eg. "doActions" found in this code: $reshook=$hookmanager->executeHooks('doActions',$parameters,$object,$action);
However the hook name is often not unique (may be repeated in various code modules), so to identify the location accurately, code modules have a "context" name that will be referred to by all hooks in that code module location.
So to use a hook, you need to know its context name (its location) and the hook name.


Um einen Hook in Ihrem eigenen Modul zu implementieren (damit Ihr Modul von anderen "gehooked" werden kann), müssen Sie zwei Schritte durchführen.
*The Hook Context Name (e.g.: "productcard" for products, "invoicecard" for invoices, etc..). can be found by searching for "'''initHooks('''" in the php files.


Diese Schritte müssen für jedes php-Skript in Ihrem Modul, in dem Sie Hooks implementieren wollen, wiederholt werden.
This will find results such as "$hookmanager->initHooks(array('thirdpartycomm','globalcard'));" where "thirdpartycomm" is the context.


1- Initialisieren Sie das HookManager-Objekt (platzieren Sie diesen Code am Anfang Ihres php-Skripts, direkt nach oder vor den Includes):
*The Hook Name can be found by searching for "'''executeHooks('''" in the block of code you are interest in modifying...possibly there may be no hook defined so you may add your own (and submit a corresponding pull-request in Github so it gets included in a future version).


<source lang=php>
This will find results such as "$reshook = $hookmanager->executeHooks('addMoreBoxStatsCustomer', $parameters, $object, $action);" where "addMoreBoxStatsCustomer" is the Hook name.
// Initialize technical object to manage hooks of thirdparties. Note that conf->hooks_modules contains array array
include_once(DOL_DOCUMENT_ROOT.'/core/class/hookmanager.class.php');
$hookmanager=new HookManager($db);
$hookmanager->initHooks(array('context'));
</source>
 
$hookmanager->initHooks() akzeptiert 1 Parameter (ein Array von Kontexten) und aktiviert die Hook-Unterstützung für dieses Skript:
 
- ''''context'''' ist der String, der den Ausführungskontext enthält. Dies ist ein einfacher Indikator, der von Hook-Funktionen verwendet werden kann, um zu erkennen, in welchem Kontext sie aufgerufen werden (mehrere Seiten/Module können denselben Hook an verschiedenen Stellen aufrufen, und eine Hook-Funktion kann nur für einen bestimmten Kontext ausgeführt werden wollen und nicht für alle anderen).
 
Hinweis: Sie können mehrere Kontexte gleichzeitig setzen (z. B. wenn Sie einen gemeinsamen Kontext für mehrere Seiten benötigen, aber auch einen eigenen Kontext für eine bestimmte Seite haben möchten).
 
2- Platzieren Sie dann den Aufruf der Hooks dort, wo das Hinzufügen von Code erlaubt ist:
 
<source lang=php>
$parameters=array();
$reshook=$hookmanager->executeHooks('hookname',$parameters,$object,$action); // See description below
// Note that $action and $object may have been modified by hook
if (empty($reshook))
{
  ... // standard code that can be disabled/replaced by hook if return code > 0.
}
</source>
 
''''hookmanager->executeHooks()'''' akzeptiert 4 Parameter und fügt einen Hook hinzu (das ist ein Einstiegspunkt in Ihr Skript für Funktionen, die außerhalb Ihres Skripts und Moduls liegen):
 
- ''''Hookname'''' ist der Name der Methode, die aufgerufen wird. Zum Beispiel: 'formObjectOptions'.
 
- ''''$parameters'''' ist ein benutzerdefiniertes Array, um mehr benutzerdefinierte Daten an den Hook zu übermitteln (die Funktion im Hook kann diese Daten verarbeiten). Platzieren Sie hier, was Sie wollen, es kann eine Datei, ein Array mit Zeichenketten oder etwas anderes sein. Zum Beispiel:
 
<source lang=php>
$parameters=array('file'=>'my/path/to/a/file', 'customnames'=>array('henry','david','john'));
</source>
 
- '''$object''' ist das Objekt, das Sie der Hook-Funktion übergeben wollen, sicherlich die Daten des aktuellen Moduls (z. B. das Rechnungsobjekt, wenn Sie sich in einem Rechnungsmodul befinden, usw.). Es kann alles Mögliche sein, aber denken Sie daran, dass es die Hauptkomponente ist, die von den Hook-Funktionen verwendet wird.
 
- '''$action''' ist ein String, der die aktuelle Aktion angibt (kann null sein oder etwas, das wie "create" oder "edit" aussieht).
 
Hinweis: Sie müssen diesen Schritt mehrmals wiederholen, wenn Sie mehrere Hooks an verschiedenen Stellen Ihres Skripts einfügen wollen.
 
Nun sollte Ihr Modul gehookt werden können. Sie können die unten unter '''Hook implementieren''' beschriebene Vorgehensweise befolgen, um eine Hook-Funktion zu implementieren, die den Vorteil dieser Funktion nutzt (Sie können auch testen, ob es funktioniert). 
 
==Einen Hook implementieren==
Um einen Hook zu verwenden (also einen Teil des Codes hinzuzufügen oder zu überschreiben), müssen Sie zunächst einen Moduldeskriptor definiert haben (siehe [[Développement module|Modul_Entwicklung#Modul_Deskriptor_erstellen_(erforderlich)]] dafür).
Anschließend müssen Sie die folgenden Schritte durchführen:
 
1. Fügen Sie Ihr Modul dem Kontext hinzu, in dem der Hook ausgeführt werden soll. Das heißt, wenn man sich in dem gegebenen Kontext befindet, wird Ihr Code aufgerufen. Bearbeiten Sie dazu den Deskriptor Ihres Moduls ('''/htdocs/yourmodulename/core/modules/modYourModuleName.class.php''') und füllen Sie die Variable '''$this->module_parts''' wie im Beispiel :
 
<source lang=php>
$this->module_parts = array(
'hooks' => array('hookcontext1','hookcontext2')  // Set here all hooks context you want to support
);
</source>
 
Anmerkung: Sie können den Kontext eines Moduls auch finden, indem Sie Folgendes hinzufügen
 
<source lang=php>
print('Module context: '.$object->context);
</source>
(Fügen Sie diesen Code in die php-Datei ein, in der die Hooks aufgerufen werden, und löschen Sie ihn wieder, sobald der Wert des Kontexts ermittelt wurde).
 
[File:warning.png]] Achtung: Vergessen Sie nicht, Ihr Modul in der Modulverwaltung zu deaktivieren und dann wieder zu aktivieren, damit die Änderung wirksam wird, denn die Speicherung der zu verwaltenden "Modul-Hooks"-Paare erfolgt in der Datenbank, die erst bei der Aktivierung des Moduls aktualisiert wird.


=Adding a hook point into code=
=Adding a hook point into code=
Line 240: Line 184:
Just search for "'''executeHooks('''" through the whole sourcecode (generally called "find in files") and you should easily find all the hooked methods calls.
Just search for "'''executeHooks('''" through the whole sourcecode (generally called "find in files") and you should easily find all the hooked methods calls.
There are many, and more are added in each version update.
There are many, and more are added in each version update.
This is small list of some example hooks (not up to date/complete): [[:Category:Hooks]]
This is small list of some example hooks (not up to date/complete): [[Hooks]]


Note: please note that this list changes continually as hooks and contexts are added into Dolibarr, so if you really need to find a specific hooks, please search directly in the sourcecode.
Note: please note that this list changes continually as hooks and contexts are added into Dolibarr, so if you really need to find a specific hooks, please search directly in the sourcecode.
Gschratzer
265

edits

Retrieved from "https://wiki.dolibarr.org/index.php/Special:MobileDiff/54662"

Navigation menu