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

1. IDs

Das Layout einen Add-ons ist in mehrere Container gegliedert. Diese können ineinander verschachtelt sein. Durch die Verschachtelung entsteht eine Baumstruktur, durch die mithilfe der IDs die einzelnen Widgets oder Elemente angesteuert werden können. Die Knoten des Baums werden durch Registerkarten (Tabs) und Panels repräsentiert.

Im folgenden ist ein Beispiellayout zu sehen:

root ------ Panel1
        |-- Tab1
        |-- Tab2------ Panel2
        |          |-- Panel3
        |-- Tab3

Eine Aktion, die aus von einem Widget in Panel3 gestartet wird und ein Widget aus Panel1 nutzen will, muss sich dazu durch den Baum bewegen. Dazu werden vor der eigentlichen ID des Widgets die ID der Knoten mit zwei Doppelpunkten getrennt angegeben. Es gibt zwei Möglichkeiten dieses Problem anzugehen: Einerseits kann die ID ausgehend vom Wurzelknoten (root) angeben werden. Es wird also ein absoluter Pfad genutzt. Andererseits kann von Panel3 ausgegangen werden; in diesem Fall ist es ein relativer Pfad.

Der relative Pfad geht immer von dem Knoten aus, in dem sich das Widget befindet, das die Aktion ausgelöst hat.

Um auf einen Elternknoten zuzugreifen, gibt es den reservierten Ausdruck parent. (Bis v4.7) Auf den Wurzelknoten wird mit top zugegriffen. Ab v4.7 wird root genutzt, um auf den Wurzelknoten und top, um auf die Template-Wurzel zuzugreifen.

In den folgenden Beispielen wird davon ausgegangen, dass das Widget die ID my-Text-Field hat.

  • Beispiel für einen relativen Pfad:

$id = "parent::parent::Panel1::my-Text-Field";
  • (Bis v4.7) Beispiel für den absoluten Pfad:

$id = "top::Panel1::my-Text-Field";
  • (Ab v4.7) Beispiel für den absoluten Pfad:

$id = "root::Panel1::my-Text-Field";

Es ist empfehlenswert, relative Pfade zu verwenden. Diese ermöglichen es, das Add-on-Fenster in ein anderes Fenster einzubetten.

1.1. Suffixe

Wenn die ID des Widgets benötigt wird, kann diese mit dem Suffix #full_id erlangt werden. Ebenso kann explizit der Wert, der im Widget eingetragen ist, mit #value geholt werden. Das passiert aber auch implizit, wenn das Suffix nicht angegeben wurde.

Die ID zu erlangen ist insbesondere nötig, wenn die Add-on-Seite in unterschiedliche Add-on-Seiten eingebettet werden soll.

  • Beispiel für das Holen einer ID:

$id = "parent::parent::Panel1::my-Text-Field#full_id";

(Bis v4.7) Wenn es nötig ist, einen Wert aus dem auslösenden Widget zu bekommen, kann das mit dem Präfix self:: erfolgen. In diesem Fall wird keine Raute (#) angegeben. Wird beispielsweise die ID des Grids bei einem Ajax-Request benötigt, welcher durch eben dieses ausgelöst wurde:

$id = "self::full_id";

(Ab v4.7) Werte des aufrufenden Widgets können mit self# angegeben werden. self:: ist deprecated und sollte durch self# ersetzt werden.

  • Beispiel:

$id = "self#full_id";

2. Sprachvariablen

Bei sämtlichen Bezeichnern (Labels) und Texten können die Namen von Sprachvariablen angegeben werden. Diese werden, sofern sie in den Add-on-Sprachvariablen oder in den CRM-Sprachvariablen eingetragen sind, ersetzt. Es bedarf keiner expliziten Kennzeichnung und es ist empfehlenswert, Sprachvariablen statt statischer Texte zu verwenden.

Soll das Add-on mehrsprachig sein, müssen Sprachdateien definiert werden. Diese werden im Add-on-XML festgelegt.

3. Methoden

3.1. get_addon_window_action

Syntax:

addon_util_action get_addon_window_action(string $class, int $width, int $height, array $params = array())

Beschreibung:

Diese Methode gibt eine Aktion zurück, mit der ein Add-on-Fenster geöffnet wird.

  • $class - ist der Pfad zur Add-on-Klasse.

  • $width - ist die Breite des Fensters.

  • $height - ist die Höhe des Fensters.

  • $params - ist ein GET-Parameter in Form eines assoziativen Arrays. Wenn Werte aus den Widgets benötigt werden, können deren IDs mit geschweiften Klammern umschlossen als Wert des Schlüssel-Wert-Paares des assoziativen Arrays vermerkt werden. Feste Werte haben keine geschweiften Klammern.

3.2. get_ajax_action

Syntax:

addon_util_action get_ajax_action(string $class, array $params = array(), boolean $spinner = true)

Beschreibung:

Diese Methode gibt eine Aktion zurück, die einen Ajax-Request auslöst.

  • $class - ist der Pfad zur Add-on-Klasse.

  • $params - sind zusätzliche Parameter, die dem Request mitgegeben werden. Wenn Werte aus den Widgets benötigt werden, können deren IDs mit geschweiften Klammern umschlossen als Wert des Schlüssel-Wert-Paares des assoziativen Arrays vermerkt werden. Feste Werte haben keine geschweiften Klammern.

  • $spinner - gibt an, ob auf dem auslösenden Widget ein Ladesymbol (Spinner) angezeigt werden soll.

Achtung: Wenn das Argument $spinner auf TRUE gesetzt ist, dann wird über dem betreffenden Container, sei es ein Button oder ein Grid, ein Ladekreisel eingeblendet. Dieser unterbindet die Funktionalität des Doppelklicks!

3.3. get_close_action

Syntax:

addon_util_action get_close_action()

Beschreibung:

Diese Methode gibt eine Aktion zurück, welche das Fenster schließt, in dem die Aktion ausgelöst wurde.

3.4. get_crm_window_action

Syntax:

addon_util_action get_crm_window_action(string $op, int $width, int $height, array $params = array())

Beschreibung:

Diese Methode gibt eine Aktion zurück, mit der ein CRM-Fenster geöffnet wird.

  • $op - Die CRM-Klasse.

  • $width - Die Breite des Fensters.

  • $height - Die Höhe des Fensters.

  • $params - GET-Parameter in Form eines assoziativen Arrays. Wenn Werte aus den Widgets benötigt werden, können deren IDs mit geschweiften Klammern umschlossen als Wert des Schlüssel-Wert-Paares des assoziativen Arrays vermerkt werden. Feste Werte haben keine geschweiften Klammern.

3.5. get_download_action

Syntax:

addon_util_action get_download_action(string $url)

Beschreibung:

Diese Methode gibt eine Aktion zurück, die einen Download auslöst.

3.6. get_execute_opener_action_action

Syntax:

addon_util_action get_execute_opener_action_action(addon_util_action $action)

Beschreibung:

Diese Methode gibt eine Aktion zurück, die eine Aktion in dem öffnenden Fenster auslöst.

  • $action - Die im öffnenden Fenster auszulösende Aktion.

3.7. get_export_action

Syntax:

addon_util_action get_export_action()

Beschreibung:

(Ab v4.10) Diese Methode gibt eine Aktion zurück, die die Inhalte eines Grids zum Export anbietet. Diese Aktion ist nur für das Kontextmenü des Grids zulässig.

Sobald der Nutzer Datensätze selektiert hat, erscheint automatisch eine Abfrage, ob der Nutzer alle Datensätze oder lediglich die ausgewählten exportieren möchte.

Um die Daten im Grid zu filtern, wird beim Export im Request der Schlüssel 'items' übermittelt. Dieser enthält die IDs der Datensätze, die der Nutzer für den Export selektiert hat.

Der Name der Export-Datei wird mithilfe der Methode get_name im Grid ermittelt.

3.8. get_external_window_action

Syntax:

addon_util_action get_external_window_action(string $url, array $params = array())

Beschreibung:

Diese Methode gibt eine Aktion zurück, die ein Fenster im Standard-Webbrowser öffnet, sofern der TecArt-Starter verwendet wird. Das kann sinnvoll sein, wenn eine Webapplikation nicht vom TecArt-Starter unterstützt wird.

  • $url - die Ziel-URL für das neue Fenster

  • $params - optionale Get-Parameter. Die Angabe erfolgt als Map.

3.9. get_message_box_action

Syntax:

addon_util_action get_message_box_action(string $message, string $type, string $title, array $buttons = array())

Beschreibung:

Diese Methode gibt eine Aktion zurück, die entweder eine modale (alles überdeckende) Nachrichtenbox -- bei Auslösung -- anzeigt oder, wenn keine Buttons angegeben sind, eine kleine Hinweisbox. Der Titel wird im Falle der Hinweisbox nicht mit ausgegeben.

  • $message - ist die anzuzeigende Nachricht.

  • $type - ist der Typ der Nachricht. Dieser hat Einfluss auf die farbliche Gestaltung. Die folgenden Typen stehen zur Verfügung:

    • info

    • success

    • warning

    • danger

    • primary - nur für Nachrichtenboxen

    • secondary - nur für Nachrichtenboxen

  • $title - (optional) Überschrift für eine Nachrichtenbox.

  • $buttons - (optional) Array mit Buttons.

Es können beliebig viele Buttons angegeben werden. Ein einzelner Button ist ein assoziatives Array, in dem folgende Schlüssel zur Verfügung stehen:

  • label - ist der Text auf dem Button.

  • action - (optional) ist eine einzelne Aktion oder ein Array von Aktionen, welche ausgeführt werden sollen, wenn der Button gedrückt wurde.

  • focus - (optional) kann nur für einen Button angegeben werden. Dieser Button ist initial fokussiert und wird bei Betätigung der Enter-Taste gedrückt.

  • cancelation - (optional) kann nur bei einem Button angegeben werden. Führt die Aktion des Buttons aus, wenn der Nutzer die Escape-Taste drückt.

Beispiel für eine Hinweisbox:

$action = addon_util_action::get_message_box_action('Ihre Buchung wurde gespeichert.', 'success');

Beispiel für eine Nachrichtenbox:

$action = addon_util_action::get_message_box_action(
  'Ihre Buchung konnte nicht gespeichert werden, wollen sie das Fenster trotzdem schließen?', 
   'danger', 
   'Fehler', 
   array(
     array(
       'label' => 'Ja',
       'action' => addon_util_action::get_close_action()
       )
     ),
     array(
       'label' => 'Nein',
       'focus' => true,
       'cancelation' => true
     )
   )
);

3.10. get_print_action

Syntax:

addon_util_action get_print_action()

Beschreibung:

Diese Methode gibt eine Aktion zurück, welche die Inhalte eines Grids zum Druck anbietet. Diese Aktion ist nur für das Kontextmenü des Grids zulässig

3.11. get_progress_action

Ab V4.6 Syntax:

addon_util_action get_progress_action(Addon_Job $job, array $params, string $title, $boolean $modal = false, array $on_success = array(), array $on_error = array())

Beschreibung:

Diese Methode erzeugt eine Fortschrittsanzeige, die den Addon-Job $job visualisiert.

  • $params - Paramter, die an den Job übergeben werden

  • $title - Fenster-Titel der Fortschrittsanzeige

  • $modal - Angabe, ob das Fenster der Fortschrittsanzeige modal sein soll oder nicht

  • $on_success - Actions, die nach erfolgreichem Abschluss des Hintergrund-Prozesses ausgeführt werden sollen

  • $on_error - Actions, die ausgeführt werden sollen, wenn der Prozess fehlerhaft ausgeführt wurde

Beispiel:

final class export extends addon_ajax
{
 
  public function perform()
  {
    $action = addon_util_action::get_progress_action('job/export', $this->request, $this->get_lang('export'), true,
            array(addon_util_action::get_execute_opener_action_action(
                addon_util_action::get_download_action(\crmapi::docs()->getTempFileDownloadLink($this->request['zipfile'], 'datev.zip'))
            )),
            array(addon_util_action::get_execute_opener_action_action(addon_util_action::get_message_box_action('ASDF', 'danger')))
        );
 
    $this->add_response_action($action);
 
  }
 
}

3.12. get_protocol_window_action

Syntax:

addon_util_action get_protocol_window_action(string $table, int $id = 0)

Beschreibung:

Diese Methode gibt eine Aktion zurück, mit der ein neues Protokoll-Fenster für einen Datensatz aus einer Add-on-Tabelle geöffnet werden kann.

  • $table - ist die Add-on-Tabelle.

  • $id - ist die ID des Datensatzes. Wenn 0, wird das gesamte Protokoll angezeigt.

3.13. get_refresh_action

Syntax:

addon_util_action get_refresh_action(mixed $widget_id = false)

Beschreibung:

Diese Methode gibt eine Aktion zurück, die das angegebene Widget aktualisiert. Wenn $widget_id false ist, wird die ganze Seite neu geladen.

  • $widget_id - ist die ID des Widgets, das aktualisiert werden soll. Die IDs werden ohne geschweifte Klammern angegeben.

3.14. get_trigger_action

Syntax:

addon_util_action get_trigger_action(string $widget_id, string $event)

Beschreibung:

Diese Methode führt die Aktion $event des Widgets $widget aus.

  • $widget_id - ist die ID des Widgets, das aktualisiert werden soll. Die IDs werden ohne geschweifte Klammern angegeben.

Beispiel:

$action = addon_utils_action::get_trigger_action('button1', 'on-press');

3.15. get_security_window_action

Syntax:

addon_util_action get_security_window_action(string $table, array $ids)

Beschreibung:

Diese Methode gibt eine Aktion zurück, mit der ein neues Sicherheitseinstellungen-Fenster für Datensätze aus einer Add-on-Tabelle geöffnet werden kann.

  • $table - ist die Add-on-Tabelle.

  • $ids - sind die IDs der Datensätze.

3.16. get_validate_action

Syntax:

addon_util_action get_validate_action(array $widget_ids)

Beschreibung:

Diese Methode gibt eine Aktion zurück, die die angegebenen Widgets validiert. Schlägt eine Validierung fehl, werden die folgenden Aktionen nicht ausgeführt und dem Nutzer angezeigt, welche Felder noch ausgefüllt werden müssen oder falsch ausgefüllt sind. Folgende Widgets können validiert werden:

Parameter:

  • $widget_ids Ein Array mit IDs. Die IDs werden ohne geschweifte Klammern angegeben.

3.17. get_widget_set_action

Syntax:

addon_util_action get_widget_set_action(mixed $widget_ids_or_widget_id, mixed $property_name_or_properties, mixed $value = null)

Beschreibung:

Diese Methode gibt eine Aktion zurück, die eine einzelne oder mehrere Eigenschaften für ein oder mehrere Widgets setzt

  • $widget_ids_or_widget_id - kann eine ID oder ein Array von IDs sein. Die IDs werden ohne geschweifte Klammern angegeben.

  • $property_name_or_properties - kann eine einzelne Eigenschaft oder ein assoziatives Array sein. In dem assoziativen Array ist der Schlüssel, die Eigenschaft und der Wert, welcher für die Eigenschaft gesetzt werden soll. Ein Auszug der möglichen Eigenschaften:

    • value - ist der Wert, der in dem Widget eingetragen ist (In einem Textfeld ist das der Text.)

      • Gültige Werte: die, die durch das jeweilige Widget angenommen werden können

    • spinner - bestimmt, ob ein Ladehinweis angezeigt wird

      • Gültige Werte: show, hide und toggle

    • visibility - ist die Sichtbarkeit des Widgets.

      • Gültige Werte: show, hide

  • $value - ist der Wert, der für die angegebene Eigenschaft gesetzt werden soll. Wird ignoriert, wenn $property_name_or_properties ein assoziatives Array ist.

Desweiteren können viele der im Template angegebenen Attribute mit der widget_set-Methode manipuliert werden.

Beispiele:

  • In einem einzelnen Widget wird eine Eigenschaft gesetzt.

$action = addon_util_action::get_widget_set_action('my-Text-Field', 'value', 'ich bin der neue Text im Textfeld');
  • In mehreren Widgets werden mehrere Eigenschaften auf einmal gesetzt.
$action = addon_util_action::get_widget_set_action(
  array('my-Text-Field', 'my-Button'),
   array(
     'visiblity' => 'show',
     'spinner' => 'show'
   )
);

3.18. get_window_action

Syntax:

addon_util_action get_window_action(string $url, int $width, int $height, array $params = array())

Beschreibung:

Diese Methode gibt eine Aktion zurück, mit der ein neues Browser-Fenster mit einer beliebigen URL geöffnet wird.

  • $url - ist die URL zu der Webseite.

  • $width - ist die die Breite des Fensters.

  • $height - ist die Höhe des Fensters.

  • $params - sind GET-Parameter in Form eines assoziativen Arrays. Wenn Werte aus den Widgets benötigt werden, können deren IDs mit geschweiften Klammern umschlossen als Wert des Schlüssel-Wert-Paares des assoziativen Arrays vermerkt werden. Feste Werte haben keine geschweiften Klammern.

  • No labels