Page tree
Skip to end of metadata
Go to start of metadata

1. Einrichtung der Entwicklungsumgebung

Eine Anleitung zur Einrichtung zu Ihrer Entwicklungsumgebung finden Sie im Tutorial Einrichtung.

Nachdem Sie das CRM-System und Ihre Entwicklungsumgebung eingerichtet haben, können Sie das erste Add-On entwickeln. Erstellen Sie dazu das Projekt "helloworld" in Ihrem Arbeitsverzeichnis über Ihre Entwicklungsumgebung.

Um die Autovervollständigung Ihrer Entwicklungsumgebung nutzen zu können, stehen Ihnen unsere Klassenbibliotheken zur Verfügung. Erstellen Sie dazu in Ihrem Projekt das Verzeichnis "ressources" und kopieren beide php-Dateien dorthin.

2. addon.xml

Grundlage des Add-Ons bildet die addon.xml. Diese erstellen Sie im Verzeichnis Ihres Add-Ons.

<?xml version="1.0" encoding="UTF-8"?>
<tecart_addon>
  <author>TecArt GmbH</author>
     <version>1.0</version>
     <prefix>helloworld</prefix>
     <name>helloworld</name>
</tecart_addon>


Beachten Sie, dass das Prefix nur aus Zahlen und Kleinbuchstaben bestehen darf.

Anschließend sollten Sie das Add-On unter Administration → System → Add-Ons bereits aufgelistet sehen. Zum Installieren wählen Sie das Add-On aus und klicken auf den Button "Installieren".


3. Felder hinzufügen

Aufgabe dieses Beispiel-Add-Ons soll es sein, den Text "Hello World" in verschiedene Felder eines Tickets zu schreiben. Dazu müssen erst Felder in den Tickets angelegt werden. Diese können Sie in der addon.xml definieren und so bei der Installation des Add-Ons anlegen lassen.


<?xml version="1.0" encoding="UTF-8"?>
<tecart_addon>
  <author>TecArt GmbH</author>
     <version>1.0</version>
     <prefix>helloworld</prefix>
     <name>helloworld</name>
 
   <fields>
       <field module="MODULE_TICKETS" name="text" type="FIELDTYPE_TEXT" size="20" width="150" position="max" />
       <field module="MODULE_TICKETS" name="text_ajax" type="FIELDTYPE_TEXT" size="20" width="150" position="max" />
       <field module="MODULE_TICKETS" name="button" type="FIELDTYPE_BUTTON" target="windows/tickets" size="20" width="150" window_open="true" position="max" label="helloworld">
           <param name="oid" value="$id" />
       </field>
   </fields>
 
</tecart_addon>

Änderungen an der addon.xml werden nicht sofort in das System übernommen. Um die Änderungen wirksam werden zu lassen, wählen Sie das Add-On unter Administration → System → Add-Ons aus und klicken "Update". Anschließend werden die Änderungen im CRM-System durchgeführt. In der Feldverwaltung (Administration → Felder) im Bereich "Tickets" sehen Sie nun drei neue Felder.

Folgendes Bildschirmfoto aus der CRM Feldverwaltung entspricht nicht mehr der neuesten Version und wird demnächst durch ein aktuelles ersetzt.


4. Aktion beim Speichern eines Tickets

Nun soll das Add-On in das Feld text den Text "Hello World" schreiben, wenn ein Ticket gespeichert wird. Dazu benutzen Sie die Web-Hooks "Ticket ⇒ Nach dem Anlegen" und "Ticket ⇒ Nach dem Speichern". Diese werden ebenfalls in der addon.xml definiert, um mit der Installation des Add-Ons zur Verfügung zu stehen.

<?xml version="1.0" encoding="UTF-8"?>
<tecart_addon>
  <author>TecArt GmbH</author>
     <version>1.0</version>
     <prefix>helloworld</prefix>
     <name>helloworld</name>
 
   <fields>
       <field module="MODULE_TICKETS" name="text" type="FIELDTYPE_TEXT" size="20" width="150" position="max" />
       <field module="MODULE_TICKETS" name="text_ajax" type="FIELDTYPE_TEXT" size="20" width="150" position="max" />
       <field module="MODULE_TICKETS" name="button" type="FIELDTYPE_BUTTON" target="windows/tickets" size="20" width="150" window_open="true" position="max" label="helloworld">
           <param name="oid" value="$id" />
       </field>
   </fields>
 
   <webhooks>
       <webhook hook="ticket_after_save_existing" target="webhooks/tickets">
           <param name="oid" value="$oid" />
       </webhook>
       <webhook hook="ticket_after_save_new" target="webhooks/tickets">
           <param name="oid" value="$oid" />
       </webhook>
   </webhooks>
 
</tecart_addon>


Nachdem Sie das Add-On im System aktualisiert haben, können Sie die Web-Hooks unter Administration → System → Web-Hooks sehen.

Beide Web-Hooks verweisen auf eine Aktion, die im Add-On noch definiert werden muss. Wenn Sie jetzt ein Ticket neu anlegen oder speichern, sehen Sie nur eine Fehlermeldung in der Ereignisanzeige.

5. Web-Hooks

Diese Fehlermeldung sagt aus, dass die Klasse "webhooks/tickets" nicht existiert. In der Definition der Web-Hooks wurde diese als Ziel (target) angegeben. In diesem Schritt erstellen Sie diese Klasse. Dazu legen Sie in Ihrem Add-On das Verzeichnis "webhooks" an und erstellen darin die Datei tickets.class.php.

Ihr Add-On hat jetzt folgende Struktur

In die Datei tickets.class.php schreiben Sie folgenden Inhalt:

<?php
 
namespace addon;
 
class tickets extends addon_webhook
{
   public function perform()
   {
       // Read id of the ticket
       $oid = $this->request['oid'];
 
       // The text to write
       $text = 'Hello World';
 
       // Save change to the ticket
       \crmapi::tickets()->changeTicket($oid, array($this->add_prefix('text') => $text));
 
       // Return successfull result
       return array(
           'success' => true,
           'stop'    => false,
           'error'   => ''
       );
   }
}


Wie Sie sehen, können Sie in einem Add-On über die API auf das CRM-System zugreifen. Anders als Änderungen an der addon.xml stehen Änderungen am Code sofort zur Verfügung. Wenn Sie also nun ein Ticket speichern, wird in das Add-On-Feld "text" der Wert "Hello World" geschrieben.

6. Fenster

Eine weitere Möglichkeit, die das Add-On-Framework bietet, sind eigene Fenster. Um ein eigenes Fenster zu öffnen, benötigen Sie einen Button. Dieser wurde für die Tickets bereits oben über die Felder eingerichtet. Wenn Sie auf diesen Button klicken, erhalten Sie aktuell ein leeres Fenster und eine Fehlermeldung in der Ereignisanzeige.

Um das Fenster mit Inhalt zu füllen, legen Sie im Add-On das Verzeichnis "windows" an. Darin erstellen Sie die Dateien "tickets.xml" und "tickets.class.php".

Ihr Add-On hat jetzt folgende Struktur

In die Datei tickets.class.php schreiben Sie folgenden Inhalt:

<?php
 
namespace addon;
 
final class tickets extends addon_view
{
   public function get_template()
   {
       return 'windows/tickets.xml';
   }
 
   public function get_actions()
   {
       return array(
           'write'        => addon_util_action::get_ajax_action('ajax/write', array('oid' => $this->request['oid'])),
           'close_window' => addon_util_action::get_close_action()
       );
   }
 
   public function get_title()
   {
       return 'window_title';
   }
 
   public function get_assignments()
   {
       return array();
   }
}


Damit haben Sie den Controller definiert. In die Datei tickets.xml schreiben Sie folgenden Inhalt:

<?xml version="1.0" encoding="UTF-8"?>
<layout type="fluid-full">
 
<row min-size="3"></row>
<row min-size="5">
 
   <col size="12" align="center">
     <button text="button_write" on-press="write" />
     <button text="button_cancel" on-press="close_window" />
   </col>
 
</row>
 
</layout>


Damit haben Sie das Template definiert. Wenn Sie nun auf den Button im Ticket klicken, erhalten Sie ein Fenster mit zwei Buttons.

Beim Klick auf "button_cancel" schließt sich das Fenster. Ein Klick auf "button_write" erzeugt wieder eine Fehlermeldung.

7. Ajax

Die Fehlermeldung entsteht dadurch, dass an den Button button_write eine Ajax-Aktion gebunden ist, die noch nicht existiert. Diese legen Sie nun an. Dazu erstellen Sie das Verzeichnis "ajax" und darin die Datei "write.class.php".

Ihr Add-On hat jetzt folgende Struktur

In die Datei write.class.php schreiben Sie folgenden Inhalt:

<?php
 
namespace addon;
 
class write extends addon_ajax
{
 
   public function perform()
   {
       $oid = $this->request['oid'];
 
       $text = 'helloworld ajax';
       $test = \crmapi::tickets()->changeTicket($oid, array($this->add_prefix('text_ajax') => $text));
 
       return array(
           addon_util_action::get_close_action()
       );
   }
}


Damit haben Sie die Ajax-Aktion definiert. Wenn Sie nun auf den Button button_write klicken und das Ticket-Fenster aktualisieren, sehen Sie den Text "helloworld ajax" im Feld text_ajax.

8. Sprache

Die Texte im Add-On müssen jetzt noch sprachspezifisch angezeigt werden. Dazu definieren Sie die verfügbaren Sprachen des Add-Ons und legen die dazugehörigen Sprachdateien an.

Zuerst erstellen Sie das Verzeichnis "lang" mit der Datei de.inc.php im Add-On.

Ihr Add-On hat jetzt folgende Struktur:

In die Datei de.inc.php schreiben Sie folgenden Inhalt:

<?php
 
$lang['text']       = 'Hello World';
$lang['text_ajax']  = 'Hello World Ajax';
$lang['button']     = 'Hello World Button';
$lang['helloworld'] = 'Hello World Button';
 
$lang['button_write']  = 'Schreiben';
$lang['button_cancel'] = 'Schließen';
$lang['window_title']  = 'Hello World Beispiel';


In der addon.xml definieren Sie nun noch die Sprache:


<?xml version="1.0" encoding="UTF-8"?>
<tecart_addon>
  <author>TecArt GmbH</author>
     <version>1.0</version>
     <licence_file>license.txt</licence_file>
     <help_file>https://wiki.tecart.de/Addon_Implementierung</help_file>
     <prefix>helloworld</prefix>
     <name>helloworld</name>
 
   <fields>
       <field module="MODULE_TICKETS" name="text" type="FIELDTYPE_TEXT" size="20" width="150" position="17" />
       <field module="MODULE_TICKETS" name="text_ajax" type="FIELDTYPE_TEXT" size="20" width="150" position="18" />
       <field module="MODULE_TICKETS" name="button" type="FIELDTYPE_BUTTON" target="windows/tickets" size="20" width="150" window_open="true" position="19" label="helloworld">
         <param name="oid" value="$id" />
       </field>
   </fields>
 
   <webhooks>
       <webhook hook="ticket_after_save_existing" target="webhooks/tickets">
           <param name="oid" value="$oid" />
       </webhook>
       <webhook hook="ticket_after_save_new" target="webhooks/tickets">
           <param name="oid" value="$oid" />
       </webhook>
   </webhooks>
 
   <languages>
       <lang src="lang/de">de</lang>
   </languages>
 
</tecart_addon>


Nachdem Sie das Add-On im System aktualisiert haben, haben die Buttons im Fenster neue Beschriftungen.


  • No labels