Hello World

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 erstellen. Erstellen Sie dazu das Projekt "helloworld" in Ihrem Arbeitsverzeichnis über Ihre Entwicklungsumgebung.

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

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 können Sie das Add-On unter Administration → System → Add-Ons bereits sehen und installieren. Zum Installieren wählen Sie das Add-On aus und klicken auf den Button "Installieren".

Aufgabe des 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.

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.

Diese Fehlermeldung sagt aus, dass die Klasse "webhooks/tickets" nicht existiert. In der Definition der Web-Hooks wurde diese als 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.

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.

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 Addon 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.

Die Texte im Add-On müssen jetzt noch sprachspezifisch angezeigt werden. Dazu legen Sie die verfügbaren Sprachen des Add-Ons fest und legen 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.