Util Action

Das Layout einen Addons ist in mehrere Container gegliedert. Diese können ineinandner verschaltelt sein. Durch die Verschachtelung entstehe eine Baumstruktur durch welche - mit Hilfe - der IDs die einzelnen Widgets oder Elemente angesteuert werden können. Die Knoten des Baumes werden durch Registerkarten (Tabs) und Panels repräsentiert.

Im folgenden ist ein Beispiellayout zu sehen:

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

Eine Aktion welche 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 ausgehen 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, welches die Aktion ausgelöst hat.

Um auf einen Elternknoten zuzugreifen gibt es den reservierten Ausdruck parent. (Bis v4.7) Um auf den Wurzelknoten zuzugreifen wird top genutzt. Ab v4.7 nutzen Sie root um auf den Wurzelknoten zuzugreifen 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 sehr empfehlenswert relative Pfade zu verwenden. Diese ermöglichen es das Add-On-Fenster in ein anderes Fenster einzubetten.

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 so kann das mit dem Prefix self:: erfolgen. In diesem Fall wird keine Raute (#) angegeben. Beispielsweise wird die ID das Grid bei einem Ajax-Request benötigt, welcher durch eben dieses ausgelöst wurde.

  • Beispiel:


$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";

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 ihr Add-On mehrsprachig sein, müssen Sprachdateien definiert werden. Diese werden im Add-On-XML festgelegt.

get_addon_window_action

Syntax:

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

Beschreibung:

Gibt eine Aktion zurück mit welcher ein Add-On-Fenster geöffnet wird.

  • $class - Der Pfad zur Add-On-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.

get_ajax_action

Syntax:

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

Beschreibung:

Gibt eine Aktion zurück welche einen Ajax-Request auslöst.

  • $class - Der Pfad zur Add-On-Klasse.
  • $params - Zusätzliche Parameter welche 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!


get_close_action

Syntax:

addon_util_action get_close_action()

Beschreibung:

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


get_crm_window_action

Syntax

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

Beschreibung:

Gibt eine Aktion zurück, mit welcher 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.

get_download_action

Syntax

addon_util_action get_download_action(string $url)

Beschreibung:

Gibt eine Aktion zurück, welche einen Download auslöst.


get_execute_opener_action_action

Syntax:

addon_util_action get_execute_opener_action_action(addon_util_action $action)

Beschreibung:

Gibt eine Aktion zurück, welche eine Aktion in dem öffnenden Fenster auslöst.

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

get_message_box_action

Syntax:

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

Beschreibung:

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 - Die anzuzeigende Nachricht.
  • $type - 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) Die Überschrift für eine Nachrichtenbox.
  • $buttons - (optional) Ein Array mit Buttons.

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

  • label - Der Text auf dem Button.
  • action - (optional) 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 beim drücken 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
     )
   )
);


get_print_action

Syntax:

addon_util_action get_print_action()

Beschreibung:

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


get_export_action

Syntax:

addon_util_action get_export_action()

Beschreibung:

(Ab v4.10) Gibt eine Aktion zurück, welche 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, welche der Nutzer, für den Export, selektiert hat.

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


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 Erzeugt eine Progress-Bar, die den Addon-Job $job visualisiert.

  • $params - Paramter, die an den Job übergeben werden
  • $title - Angezeigter Fenster-Titel der Progress-Bar
  • $modal - Angabe, ob das Fenster der Progress-Bar 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);

	}

}

get_protocol_window_action

Syntax

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

Beschreibung:

Gibt eine Aktion zurück mit welcher ein neues Protokoll-Fenster für einen Datensatz aus einer Addon-Tabelle.

  • $table - Die Addon-Tabelle.
  • $id - Die ID des Datensatzes. Wenn 0, wird das gesamte Protokoll angezeigt.

get_refresh_action

Syntax:

addon_util_action get_refresh_action(mixed $widget_id = false)

Beschreibung:

Gibt eine Aktion zurück, welche das angegebene Widget aktualisiert. Wenn $widget_id false ist, wird die ganze Seite neugeladen.

  • $widget_id - Die ID des Widgets, welches Aktualisiert werden soll. Die IDs werden ohne geschweifte Klammern angegeben.

get_trigger_action

Syntax:

addon_util_action get_trigger_action(string $widget_id, string $event)

Beschreibung:

Führt die Aktion $event des Widgets $widget aus.

  • $widget_id - Die ID des Widgets, welches Aktualisiert werden soll. Die IDs werden ohne geschweifte Klammern angegeben.

Beispiel:

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

get_security_window_action

Syntax

addon_util_action get_security_window_action(string $table, array $ids)

Beschreibung:

Gibt eine Aktion zurück mit welcher ein neues Sicherheitseinstellungen-Fenster für Datensätze aus einer Addon-Tabelle.

  • $table - Die Addon-Tabelle.
  • $ids - Die IDs der Datensätze.

get_validate_action

Syntax:

addon_util_action get_validate_action(array $widget_ids)

Beschreibung:

Gibt eine Aktion zurück, welche die angegebenen Widget 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.

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:

Gibt eine Aktion zurück, welche 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 der Wert welcher für die Eigenschaft gesetzt werden soll. Ein Auszug der mögliche Eigenschaften:
    • value - Der Wert welcher 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 - Die Sichtbarkeit des Widgets.
      • Gültige Werte: show, hide
  • $value - Der Wert, welcher 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'
   )
);


get_window_action

Syntax

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

Beschreibung:

Gibt eine Aktion zurück mit welcher ein neues Browser-Fenster mit einer beliebigen URL geöffnet wird.

  • $url - Die URL zu der Webseite.
  • $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.