1.1.3. Datenobjekte
Einige Komponenten stellen Daten dar, die aus mehr als einem Merkmal bestehen, z.B. die tabellarische Auflistung von E-Mails nach Betreff, Absender und Datum. Diese Komponenten greifen auf Datenobjekte oder Arrays zu. In Datenobjekten stehen die einzelnen Daten als Werte von Objekteigenschaften ("Properties"), in Arrays sind die einzelnen Daten als Werte von Array-Schlüsseln ("Keys") hinterlegt. In den Komponenten lässt sich einstellen, welche Objekteigenschaften bzw. Array-Schlüssel für den Wert des Formularfelds, die Beschriftung usw. herangezogen werden.
Das folgende Beispiel zeigt ein Objekt und einen Array, die Daten enthalten, die beispielsweise in einer Tabelle (Komponente GhGuiDataGrid), einer Liste (Komponente GhGuiList) oder einem Baum (Komponente GhGuiTree) ausgegeben werden können:
Beispiel für ein Datenobjekt und einen Daten-Array:
1
2
3
4
5
6
7
8
9
10
11
12
13
2
3
4
5
6
7
8
9
10
11
12
13
<?php
$dataObject = new stdClass();
$dataObject->itemId = 'item01';
$dataObject->itemLabel = 'Testeintrag 1';
$dataObject->itemDate = '2011-09-25 12:34:56';
$dataObject->itemFrom = 'K. Kunde';
$dataArray = array(
'itemId' => 'item01',
'itemLabel' => 'Testeintrag 1',
'itemDate' => '2011-09-25 12:34:56',
'itemFrom' => 'K. Kunde'
);
In Bezug auf die PHP GUI sind dieses Datenobjekt und der Array gleichwertig, da sie unter der gleichen Eigenschaft bzw. dem gleichen Schlüssel jeweils den gleichen Wert enthalten. Die Unterstützung von sowohl Objekten als auch Arrays dient dazu, möglichst flexibel Daten verschiedener Quellen verarbeiten zu können.
In den Komponenten wird in der Regel eine Liste solcher Datenobjekte oder Arrays übergeben, also ein Array von Objekten oder ein Array von Arrays:
Beispiel mehrerer Datensätze in Arrays:
1
2
3
4
5
6
2
3
4
5
6
<?php
$items = array(
array('itemId' => 'item01', 'itemLabel' => 'Testeintrag 1', 'itemDate' => '2011-09-25 12:34:56'),
array('itemId' => 'item02', 'itemLabel' => 'Testeintrag 2', 'itemDate' => '2011-10-01 09:21:33'),
array('itemId' => 'weitereId1', 'itemLabel' => 'Noch ein Testeintrag', 'itemDate' => '2011-09-28 18:57:58')
);
Damit die Komponente, zu der solche Datensätze hinzugefügt werden, weiß, welche Daten wofür verwendet werden sollen, gibt es Methoden, um dies einzustellen. Die Methode, mit der die Dateneigenschaft festgelegt wird, deren Wert bei Auswahl des Datensatzes im Formular beim Absenden enthalten ist, wird in der Regel mit der Methode setValueProperty() angegeben. Je nach Komponente gibt es unterschiedliche Möglichkeiten, weitere Dateneigenschaften z.B. für die Beschriftung zu verwenden. Auch hier wird jeweils über eine Methode der Name einer Objekteigenschaft der Datenobjekte oder der Name eines Schlüssels der Daten-Arrays angegeben.
Im folgenden Beispiel wird eine Auswahlliste erstellt, die als Formularwerte den Schlüssel 'itemId' und als Beschriftung der einzelnen Listeneinträge den Schlüssel 'itemLabel' der Daten-Arrays verwendet:
Beispiel einer Auswahlliste mit Einträgen aus Daten-Arrays:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
<?php
// Liste der Daten-Arrays:
$items = array(
array('itemId' => 'item01', 'itemLabel' => 'Testeintrag 1', 'itemDate' => '2011-09-25 12:34:56'),
array('itemId' => 'item02', 'itemLabel' => 'Testeintrag 2', 'itemDate' => '2011-10-01 09:21:33'),
array('itemId' => 'weitereId1', 'itemLabel' => 'Noch ein Testeintrag', 'itemDate' => '2011-09-28 18:57:58')
);
// Auswahlliste erstellen (mit 'listSelection' als Formularfeldname):
$list = new GhGuiList('listSelection');
// Festlegen, dass die Dateneigenschaft 'itemId' für den Formularwert verwendet wird:
$list->setValueProperty('itemId');
// Festlegen, dass die Dateneigenschaft 'itemLabel' die Beschriftung der Listeneinträge enthält:
$list->setCaptionProperty('itemLabel');
// Daten der Liste hinzufügen:
$list->addItems($items);
In der Komponente GhGuiList lassen sich nur simple Auswahllisten darstellen, bei denen eine Eigenschaft der Daten als Beschriftung und eine andere als Wert für das Formularfeld verwendet wird. Komplexere Darstellungen ermöglicht unter anderem die Komponente GhGuiDataGrid (im Folgenden kurz als "Data-Grid" bezeichnet), die eine tabellarische Auflistung der Datensätze darstellt. Wie auch bei der Auswahlliste wird hier über die Methode setValueProperty die Dateneigenschaft festgelegt, die bei Auswahl eines Datensatzes in der Tabelle, den Wert für das Formularfeld bestimmt. Zusätzlich können dem Data-Grid mehrere Spalten hinzugefügt werden, die den Titel der Tabellenspalte, die Dateneigenschaft für den Inhalt der Zellen dieser Spalte und optional auch das Format, in dem Werte dieser Spalte dargestellt werden, bestimmen. Ist die Dateneigenschaft, die als Wert für das Formularfeld verwendet werden soll, nicht bereits in einer der Spalten enthalten, so muss eine unsichtbare Spalte für diese Dateneigenschaft hinzugefügt werden. Das folgende Beispiel veranschaulicht, wie ein Data-Grid zur Darstellung derselben Daten wie im vorigen Beispiel erstellt wird:
Beispiel eines Data-Grid mit Einträgen aus Daten-Arrays:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
<?php
// Liste der Daten-Arrays:
$items = array(
array('itemId' => 'item01', 'itemLabel' => 'Testeintrag 1', 'itemDate' => '2011-09-25 12:34:56'),
array('itemId' => 'item02', 'itemLabel' => 'Testeintrag 2', 'itemDate' => '2011-10-01 09:21:33'),
array('itemId' => 'weitereId1', 'itemLabel' => 'Noch ein Testeintrag', 'itemDate' => '2011-09-28 18:57:58')
);
// Data-Grid erstellen (mit 'gridSelection' als Formularfeldname):
$grid = new GhGuiDataGrid('gridSelection');
// Festlegen, dass die Dateneigenschaft 'itemId' für den Formularwert verwendet wird:
$grid->setValueProperty('itemId');
// Versteckte Spalte für 'itemId' hinzufügen:
$grid->addColumn('itemId');
// Sichtbare Spalte für 'itemLabel' hinzufügen:
$grid->addColumn('itemLabel', 'Betreff');
// Sichtbare Spalte für 'itemDate' hinzufügen und als Datum formatieren:
$grid->addColumn('itemDate', 'Datum', null, GhGuiFormatter::DATETIME_GERMAN);
// Daten dem Data-Grid hinzufügen:
$grid->addRows($items);
Die Methode addColumn() des GhGuiDataGrid fügt dem Data-Grid eine Spalte hinzu und nimmt als ersten Parameter den Namen der Dateneigenschaft für die Spalte auf. Werden keine weiteren Parameter angegeben, so wird eine versteckte Spalte angelegt, die nur Daten enthält, aber nicht angezeigt wird. Als zweiter Parameter wird die Beschriftung der Spalte (der Spaltentitel in der Tabelle) angegeben. Als dritter Parameter kann die Breite der Spalte festgelegt werden. Wird dieser nicht angegeben, so wird der Platz entsprechend auf die Spalten verteilt. Als vierter Parameter schließlich kann eine Formatierung für die Spalte angegeben werden. Dies ist insbesondere dann nützlich, wenn es sich um Daten wie Datumsangaben oder Preise handelt. Die Kernklasse [clssses]GhGuiFormatter[/classes] bietet unterschiedliche Formatierungsmöglichkeiten für Daten an, in diesem Beispiel wurde als Formatierung das deutsche Datums- und Zeitformat gewählt (GhGuiFormatter::DATETIME_GERMAN).
Für Bäume (Komponenten GhGuiTree und GhGuiComboTree) muss eine hierarchische Struktur der Daten aufgebaut werden. Hierzu dient die Hilfsklasse GhCoreTree. Einem solchen Baum können Elemente ("Knoten") und untergeordnete Elemente hinzugefügt werden, indem den Elementen eine ID vergeben wird, die innerhalb des Baums eindeutig ist. Beim Hinzufügen eines untergeordneten Elements wird die ID des Elements, zu dem hinzugefügt werden soll, angegeben. Zusätzlich zur ID und Beschriftung können einem Element beliebige Daten zugeordnet werden. In der Regel ist dies ein Objekt oder Array, wie sie auch, wie oben beschrieben, für Listen und Data-Grids verwendet werden. Entsprechend kann der Baum-Komponente über die Methode setValueProperty() die Dateneigenschaft angegeben werden, die den Wert für das Formularfeld des Baums enthält.
Das folgende Beispiel demonstriert den Aufbau eines Baums und die Anzeige in einer GhGuiTree Komponente:
Beispiel eines Baums mit Einträgen aus Daten-Arrays:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
<?php
// GREYHOUND PHP GUI laden:
require_once 'ghgui/ghgui.php';
// Webseite erstellen:
$page = new GhGuiExtensionPage('PHP GUI Beispiel');
// Formular zur Webseite hinzufügen:
$form = new GhGuiForm();
$page->addComponent($form);
// Baum mit Daten aus Arrays aufbauen:
$treeData = new GhCoreTree();
// Element zur ersten Ebene hinzufügen (mit ID 100):
$treeData->add(100, 'Buchhaltung', array('itemId' => 'item01'));
// Untergeordnete Elemente zuordnen (zum Element mit der ID 100):
$treeData->addChild(101, 100, 'Einkauf', array('itemId' => 'item02'));
$treeData->addChild(102, 100, 'Verkauf', array('itemId' => 'item03'));
// Weiteres Element zur ersten Ebene hinzufügen (mit ID 200):
$treeData->add(200, 'Kundenservice', array('itemId' => 'item04'));
// Untergeordnetes Element zum Element mit ID 200 zuordnen:
$treeData->addChild(201, 200, 'Produktanfragen', array('itemId' => 'item05'));
// Baum-Komponente erzeugen und Baum zuordnen (Formularfeld 'treeSelection' nennen):
$tree = new GhGuiComboTree('treeSelection', $treeData);
// Dateneigenschaft 'itemId' für den Wert des Formularfelds verwenden:
$tree->setValueProperty('itemId');
// Baum ins Formular einfügen:
$form->addComponent($tree);
// Button zum Absenden des Formulars einfügen:
$form->addComponent(new GhGuiButton('Absenden'));
// Falls das Formular abgeschickt wurde wird die Auswahl im Baum angezeigt:
$selection = GhCoreGlobals::getValue('treeSelection');
if(!$selection !== null)
$form->addComponent(new GhGuiText('Folgendes Baumelement wurde ausgewählt: ' . $selection));
// Webseite anzeigen:
$page->show();
Die Komponenten verwenden in der Regel als Voreinstellung für die Dateneigenschaft, die den Wert des Formularfelds angibt, die Eigenschaft ID und für die Beschriftung die Eigenschaft Name. Die Objekte im GREYHOUND Server (z.B. Themen und Gruppen) enthalten in diesen Eigenschaften die Server-interne Objekt-ID bzw. die Bezeichnung des Objekts, sodass in der Voreinstellung Objekte aus dem GREYHOUND Server ohne besondere Einstellungen als Datenobjekte genutzt werden können, z.B. um die Themen und Gruppen zur Auswahl in einem GhGuiComboTree darzustellen. Da die Listenelemente im GREYHOUND Server (E-Mails, Telefonnotizen, Faxe, Briefe, Notizen, etc.) die Eigenschaft Subject statt Name für die Bezeichnung verwenden, muss bei der Verwendung dieser Elemente entsprechend die Dateneigenschaft für die Beschriftung auf Subject gesetzt werden.
| Themen dieser Ebene |
|---|
| 1.1.1. Webseitenaufbau |
| 1.1.2. Formulare |
| 1.1.3. Datenobjekte |
| 1.1.4. Icons |