API Dokumentation

German
- English
- German

IXM Webhelp
11.18 11.17 11.16 11.15 11.14
DOOH Webhelp
11.18 11.17 11.16 11.15 11.14

Dashboard Widgets

15 Dec 2023
19 Minuten Lesezeit

Drucken
Teilen

Dashboard Widgets

Aktualisiert am 15 Dec 2023
19 Minuten Lesezeit

Drucken
Teilen

Artikel-Zusammenfassung

Fanden Sie diese Zusammenfassung hilfreich?

Vielen Dank für Ihr Feedback

Dashboard-Widgets sind ab der globalen Version 11.0 unterstützt. Sie dienen dazu in der IXM Plattform für den Benutzer relevante Informationen im Tab Dashboard anzuzeigen. Dashboard Widgets basieren auf der gfDashboardWidgetBase, die einige Funktionen der gfWizardBase nutzt. Der Inhalt der ascData.json Datei von Dashboard Widgets ähnelt zwar der ascData.json von Wizard Spots unterscheidet sich aber bei den möglichen Elementen und Optionen die verwendet werden können. Der Grund warum sie technisch grundsätzlich auf der gfWizardBase beruhen ist, weil sie in späteren Versionen auch im HTML-Composer verwendet und auf den Player übertragen werden können.

Ein Dashboard Widget wird gezippt in die IXM Plattform hochgeladen, wobei die Dateiendung .dash.zip sein muss.

Diese ZIP-Datei muss folgende Dateien auf oberster Ebene beinhalten:

index.html: Die Datei index.html ist der Einstiegspunkt in das Widget. Von hier aus kann relativ auf weitere Ressourcen zugegriffen werden, wie es in Webseiten üblich ist. Es darf allerdings keine URL-Weiterleitung auf andere Webseiten auf Root Ebene im Zip durchgeführt werden.
ascData.json: Die Datei ascData.json beinhaltet alle Elemente, die Sie in der IXM Plattform für dieses Widget editieren können. Der Aufbau und die möglichen Bestandteile werden im folgenden Kapitel erklärt.

Fehlt eine dieser beiden Dateien, kann das Widget nicht korrekt wiedergegeben werden. Neben diesen beiden Dateien müssen auch die Dateien gfWizardBase.js und gfDashboardWidgetBase.js verwendet und im Root-Scope des Spots instanziiert werden, wobei die gfWizardBase der gfDashboardWidgetBase übergeben wird. Diese Dateien können allerdings auch in einem Unterordner abgelegt sein. Das sind die Mindestanforderungen an ein Dashboard Widget.

API-Versionen

Die API-Version stellt den direkten Bezug zur jeweiligen Grassfish IXM Plattform-Version dar. Über sie lässt sich einerseits der benötigte Funktionsumfang des Widgets festlegen und andererseits die Kompatibilität zur entsprechenden Grassfish IXM Plattform-Version sicherstellen.

Die Angabe der API-Version wird dabei im ascData.json über das Attribut ApiVersion festgelegt.

API Version	Globale Grassfish IXM Plattform Version
1	11.0.0
2	11.2.0
3	11.3.0

Versucht man beispielsweise, ein Widget mit der API Version 2 über ein IXM Plattform mit Version 11.0.0 wiederzugeben, erhält man bereits während des Uploads einen Warnhinweis, dass evtl. benötigte Funktionen nicht zur Verfügung stehen und eine korrekte Darstellung des Spots nicht gewährleistet werden kann.

ascData.json

Die ascData.json ist die Schnittstelle zwischen dem Widget und dem Editor. Hier können Elemente definiert werden, die Benutzer später im IXM Plattform editieren können. Die Datei dient aber auch dazu, allgemeine Informationen über das Widget an das Grassfish System zu liefern, wie zum Beispiel die mögliche Slotauswahl, für die das Widget vorgesehen ist.

Dokument

Document – Root-Knoten und Widget Eigenschaften
SpotIdentifier	Pflichtfeld, String, ApiVersion: 1 Dieses Identifikationsmerkmal wird vom Spotentwickler vergeben und dient dazu, bei einem Ersetzen des Widgets in der IXM Plattform zu verifizieren, ob es sich tatsächlich um den korrekten Spot handelt. Beispiel: "MyDemonstrationWidget"
SpotVersion	Pflichtfeld, String, ApiVersion: 1 Die aktuelle Version des Widgets bzw. der JSON-Struktur. Beispiel: "1.0.0"
ApiVersion	Pflichtfeld, Int, ApiVersion: 1 Gibt an, mit welchen Systemen das Widget kompatibel ist API Version 1 ist ab 11.0 gültig. Nutzt ein Widget neuere Features, die erst ab einer höheren API Version verfügbar sind, kann in es in älteren Systemen zu Fehlern in der Darstellung oder Funktionsweise des Widgets kommen. Die ApiVersion vom Dashboard Widget ist von der ApiVersion vom Wizard Spot unabhängig.
SpotType	Pflichtfeld, String, ApiVersion: 1 Der SpotType muss fix den Wert DashboardWidget haben. Er dient als Identifier für das Backend und muss mit dem dort hinterlegten Spot Type übereinstimmen. Fixer Wert für Dashboard Widgets: "SpotType": "DashboardWidget"
NumberOfSlots	Pflichtfeld, Int, ApiVersion: 1 Gibt an, wie viele Slots das Widget einnimmt. Gültige Werte sind 1 bis 3. Beispiel: "NumberOfSlots": 2
Options	Siehe Options
Elements	Siehe Elements

Optionen

Options - Features ein-/ausschalten
PossibleNumbersOfSlots	Optional, Array, ApiVersion: 1 Dabei handelt es sich um eine mögliche Slotanzahl, die ein Widget haben kann. Diese Slots sollten dann allerdings auch entsprechend programmatisch unterstützt werden. Beispiele: `"PossibleNumbersOfSlots": [ 1, 2, 3 ] "PossibleNumbersOfSlots": [ 1, 3 ]`
PossibleNumbersOfRows	Optional, Array, ApiVersion: 2 Dabei handelt es sich um eine mögliche Zeilenhöhe, die ein Widget im Dashboard einnimmt. Diese Höhen sollten dann allerdings auch entsprechend programmatisch unterstützt werden. Beispiel: `"PossibleNumbersOfRows": [ 1, 2 ]`
HasDetailView	Optional, Boolean, ApiVersion: 1 Mit dieser Option kann man in der IXM Plattform die Möglichkeit freischalten, für dieses Widget eine Detail View zu öffnen, in der mehr Informationen dargestellt werden können. Das Widget bekommt die Information, ob es seinen Inhalt in der Detailview anzeigen soll über einen URL-Parameter namens detailMode. Im Code kann dies wie folgt z.B. im dataChanged Event abgefragt werden, wo auch sonst die Slotgröße ausgelesen werden kann: Beispiel: "HasDetailView": true Beispiel-Implementierung: `var detail; // ApiVersion 1 detail = !!GFSpotBase.findUrlParam('detailMode'); // ApiVersion 2 detail = gfDashboardWidgetBase.isDetailView(); if(detail){ //do something }`
HasPrintSupport	Optional, Boolean, ApiVersion: 1 Mit dieser Option wird im IXM Plattform die Aktion für den Datenexport aktiviert. Diese Funktion muss im Widget implementiert sein. Beispiel: "HasPrintSupport": true Beispiel-Implementierung: gfDashboardWidgetBase.registerPrintRequested( function(){ var data, file; data = "Ein beliebieger Text..."; file = "export.csv"; gfDashboardWidgetBase.saveToFile(data, file); }); … function onPrintRequested() { var data = "Entity" + splitChar + "Name" + splitChar + "Id" + splitChar + "BoxId\n"; var values; var item; for(var k in multiValues) { if(multiValues.hasOwnProperty(k)) { values = multiValues[k]; if(values) { for(var i = 0; i < values.length; i++) { item = values[i]; data += k + splitChar + item.Name + splitChar + item.Id; if(item.BoxId) { data += splitChar + item.BoxId; } data += "\n"; } } } } gfDashboardExtension.saveToFile(data, "EntityData.csv"); }
UseSingleElementUpdate	Optional, Boolean, ApiVersion: 1 Mit dieser Option kann man im Spot gezielt auf Änderungen vom jeweiligen Element reagieren und muss nicht bei jeder Wertänderung eines Elements den gesamten Spot neu aufbauen. Sie müssen, wenn diese Option aktiviert ist, nicht zwangsläufig einen Eventhandler für jedes Element registrieren. Gibt es für ein Element keinen SingleElementDataChanged Handler, so wird weiterhin der globale DataChanged Handler getriggert. Ist für das Element ein SingleElementDataChanged Handler registriert, wird nur noch dieser aufgerufen, nicht mehr der globale DataChanged Handler, wenn bei diesem Element eine Änderung stattgefunden hat. Beispiel: "UseSingleElementUpdate": true Beispiel-Implementierung: `gfDashboardWidgetBase.registerSingleElementDataChangedHandler("someElementId", function(element) { // do specific view update }); ...`
DynamicResolution	Optional, Object, ApiVersion: 2 Mit dieser Option können Sie steuern, dass der Wizard-Spot eine vom Benutzer editierbare Höhe bzw. Breite hat. Diese Option kann nicht gemeinsam mit der Option PossibleResolutions eingesetzt werden. Beispiel: `"DynamicResolution": { "Active": true, "MinWidth": 400, "MaxWidth": 2000, "MinHeight": 300, "MaxHeight": 3000 }`

Elemente

Checkbox

Checkbox

Id, DisplayName

Pflichtfelder, ApiVersion: 1

Siehe Elements-Tabelle

DataType

Pflichtfeld, String, ApiVersion: 1

"DataType": "boolean"

Value

Pflichtfeld, Boolean, ApiVersion: 1

Beispiel:

"Value": false

Options -> Conditions

Optional, Object, ApiVersion: 2

Details siehe Conditional Elements.

"Operator": ["!="|"=="]

Nummernauswahl

Number

Id, DisplayName

Pflichtfelder, ApiVersion: 1

Siehe Elements-Tabelle

DataType

Pflichtfeld, String, ApiVersion: 1

"DataType": "number"

Value

Pflichtfeld, Number, ApiVersion: 1

Beispiel:

"Value": 42

Options -> Minimum

Optional, Number, ApiVersion: 1

Gibt den Minimalwert der Nummernauswahl an.

Beispiel:

"Minimum": 1.0

Options -> Maximum

Optional, Number, ApiVersion: 1

Gibt den Maximalwert der Nummernauswahl an.

Beispiel:

"Maximum": 999

Options -> StepSize

Optional, Number, ApiVersion: 1

Gibt den Rundungswert der Nummernauswahl an.

Beispiel:

"StepSize": 0.1

Options -> Conditions

Optional, Object, ApiVersion: 2

Details siehe Conditional Elements.

"Operator": ["!="|"=="|">"|">="|"<"|"<="]

Farbauswahl

Colorpicker

Id, DisplayName

Pflichtfelder, ApiVersion: 1

Siehe Elements-Tabelle

DataType

Pflichtfeld, String, ApiVersion: 1

"DataType": "color"

Value

Pflichtfeld, String, ApiVersion: 1

Das Format ist abhängig von der Option UseRGBA.

Beispiel:

UseRGBA !== true : "Value": "#FF0000"

UseRGBA === true : "Value": "rgba(72,70,189,0.64)"

Seit der globalen Version 11.0 kann auch das RGBA-Format verwendet werden, wenn UseRGBA in den Optionen aktiviert ist.

Beispiel:

"Value": "#FF0000"

Options -> UseRGBA

Optional, Boolean, ApiVersion: 1

Mit dieser Option lässt sich der erweiterte Color Picker aktivieren, der auch Alpha-Werte unterstützt. Je nach Einstellung erfolgt der Wert in einem anderen Format.

Beispiel:

"UseRGBA": true

Options -> Conditions

Optional, Object, ApiVersion: 2

Details siehe Conditional Elements.

"Operator": ["!="|"=="|"?"]

Datum

Date

Id, DisplayName

Pflichtfelder, ApiVersion: 1

Siehe Elements-Tabelle

DataType

Pflichtfeld, String, ApiVersion: 1

"DataType": "date"

Value

Pflichtfeld, String, ApiVersion: 1

Ein Datumsstring im Format YYYY-MM-DDThh:mm:ss.

Beispiel:

"Value": "2015-09-13T00:00:00"

Options -> MinDate

Optional, String, ApiVersion: 1

Mit dieser Option lässt sich das minimale Datum festlegen. Die Eingabe kann diesen Wert dabei nicht unterschreiten.

Beispiel:

"MinDate": "2015-09-11T00:00:00"

Options -> MaxDate

Optional, String, ApiVersion: 1

Mit dieser Option lässt sich das maximale Datum festlegen. Die Eingabe kann diesen Wert dabei nicht übersteigen.

Beispiel:

"MaxDate": "2015-09-15T00:00:00"

Options, Keyword ‘Today’

Optional, String, ApiVersion: 1

Für die Schwellwerte MinDate und MaxDate kann auch das Schlüsselwort Today vergeben werden. Dieses wird zur Laufzeit in das aktuelle Datum umgewandelt.

Beispiel:

"MaxDate": "Today"

Options -> Conditions

Optional, Object, ApiVersion: 2

Details siehe Conditional Elements.

"Operator": ["!="|"=="|">"|">="|"<"|"<="]

Datumsbereich

Date
Id, DisplayName	Pflichtfelder, ApiVersion: 2 Siehe Elements
DataType	Pflichtfeld, String, ApiVersion: 2 "DataType": "dateRange"
Value	Pflichtfeld, Object, ApiVersion: 2 Das Format ist abhängig von der Option TimeEnabled und TimeZoneEnabled. Beispiel: `"Value": { "From": "2015-09-13T00:00:00", "To": "2015-09-13T00:00:00" } TimeEnabled === true: "Value": { "From": "2015-09-13T11:15:00", "To": "2015-09-13T23:30:00" } TimeEnabled === true && TimeZoneEnabled === true: "Value": { "From": "2015-09-13T11:15:00Z", "To": "2015-09-13T23:30:00Z" }`
Options -> MinDate	Optional, String, ApiVersion: 2 Mit dieser Option lässt sich das minimale Datum festlegen. Die Eingabe kann diesen Wert dabei nicht unterschreiten. Beispiel: "MinDate": "2015-09-11T00:00:00"
Options -> MaxDate	Optional, String, ApiVersion: 2 Mit dieser Option lässt sich das maximale Datum festlegen. Die Eingabe kann diesen Wert dabei nicht übersteigen. Beispiel: "MaxDate": "2015-09-15T00:00:00"
Options -> TimeEnabled	Optional, String, ApiVersion: 2 Mit dieser Option lässt sich die Zeiteingabe aktivieren. Beispiel: "TimeEnabled": true
Options -> TimeZoneEnabled	Optional, String, ApiVersion: 2 Mit dieser Option lässt sich die Eingabe der Zeitzone aktivieren. Beispiel: "TimeZoneEnabled": true Achtung: Für diese Option muss zusätzlich TimeEnabled sowie die Konfiguration des IXM Plattform zur Unterstützung von Zeitzonen aktiviert sein.
Options -> Conditions	Optional, Object, ApiVersion: 2 Details siehe Conditional Elements. "Operator": "?"
Options, Schlüsselwort "Today"	Optional, String, ApiVersion: 2 Für die Schwellwerte MinDate und MaxDate kann auch das Schlüsselwort Today vergeben werden. Dieses wird zur Laufzeit in das aktuelle Datum umgewandelt. Beispiel: "MaxDate": "Today"

Date

Id, DisplayName

Pflichtfelder, ApiVersion: 2

Siehe Elements

DataType

Pflichtfeld, String, ApiVersion: 2

"DataType": "dateRange"

Value

Pflichtfeld, Object, ApiVersion: 2

Das Format ist abhängig von der Option TimeEnabled und TimeZoneEnabled.

Beispiel:

"Value": {
	"From": "2015-09-13T00:00:00",
	"To": "2015-09-13T00:00:00"
}
TimeEnabled === true:
"Value": {
	"From": "2015-09-13T11:15:00",
	"To": "2015-09-13T23:30:00"
}
TimeEnabled === true && TimeZoneEnabled === true: "Value": {
	"From": "2015-09-13T11:15:00Z",
	"To": "2015-09-13T23:30:00Z"
}

Options -> MinDate

Optional, String, ApiVersion: 2

Mit dieser Option lässt sich das minimale Datum festlegen. Die Eingabe kann diesen Wert dabei nicht unterschreiten.

Beispiel:

"MinDate": "2015-09-11T00:00:00"

Options -> MaxDate

Optional, String, ApiVersion: 2

Mit dieser Option lässt sich das maximale Datum festlegen. Die Eingabe kann diesen Wert dabei nicht übersteigen.

Beispiel:

"MaxDate": "2015-09-15T00:00:00"

Options -> TimeEnabled

Optional, String, ApiVersion: 2

Mit dieser Option lässt sich die Zeiteingabe aktivieren.

Beispiel:

"TimeEnabled": true

Options -> TimeZoneEnabled

Optional, String, ApiVersion: 2

Mit dieser Option lässt sich die Eingabe der Zeitzone aktivieren.

Beispiel:

"TimeZoneEnabled": true

Achtung: Für diese Option muss zusätzlich TimeEnabled sowie die Konfiguration des IXM Plattform zur Unterstützung von Zeitzonen aktiviert sein.

Options -> Conditions

Optional, Object, ApiVersion: 2

Details siehe Conditional Elements.

"Operator": "?"

Options, Schlüsselwort "Today"

Optional, String, ApiVersion: 2

Für die Schwellwerte MinDate und MaxDate kann auch das Schlüsselwort Today vergeben werden. Dieses wird zur Laufzeit in das aktuelle Datum umgewandelt.

Beispiel:

"MaxDate": "Today"

Zeit

Time

Id, DisplayName

Pflichtfelder, ApiVersion: 1

Siehe Elements-Tabelle

DataType

Pflichtfeld, String, ApiVersion: 1

"DataType": "time"

Value

Pflichtfeld, String, ApiVersion: 1

Das Format ist abhängig von der Option WithSeconds.

Beispiel:

WithSeconds !== true : "Value": "13:57"

WithSeconds === true : "Value": "13:59:57"

Options -> WithSeconds

Optional, Boolean, ApiVersion: 1

Mit dieser Option können für die Eingabe auch Sekunden aktiviert werden. Je nach Einstellung erfolgt der Wert in einem anderen Format.

Beispiel:

"WithSeconds": true

Options -> Conditions

Optional, Object, ApiVersion: 2

Details siehe Conditional Elements.

"Operator": ["!="|"=="|">"|">="|"<"|"<="]

Dropdowns

List
Id, DisplayName	Pflichtfelder, ApiVersion: 1 Siehe Elements-Tabelle
DataType	Pflichtfeld, String, ApiVersion: 1 "DataType": "list"
Items	Pflichtfeld, Array Beispiel: `"Items": [ "Cow", "Horse", "Sloth" ]`
Value	Pflichtfeld, String, ApiVersion: 1 Der ausgewählte Eintrag aus dem Items-Array wird unter "Value" gespeichert (in der nicht übersetzten Variante). Beispiel: "Value": "Horse"
Translations	Optional, Object, ApiVersion: 1 Bei Dropdowns können optional für jeden Wert Übersetzungen in den Translations angegeben werden. Beispiel: `"Translations": { "de": { "DisplayName": "Meine Liste", "Cow": "Kuh", "Horse": "Pferd", "Sloth": "Faultier" } }`
Options -> Conditions	Optional, Object, ApiVersion: 2 Details siehe Conditional Elements. "Operator": ["!="\|"=="\|"?"]

Radiobutton

Radio button
Id, DisplayName	Pflichtfelder, ApiVersion: 2 Siehe Elemente.
DataType	Pflichtfeld, String, ApiVersion: 2 "DataType": "radiobutton"
Items	Pflichtfeld, String[], ApiVersion: 2 Beispiel: `"Items": [ "Cow", "Horse", "Sloth" ]`
Value	Pflichtfeld, String, ApiVersion: 2 Der ausgewählte Eintrag aus dem Items-Array wird unter "Value" gespeichert (in der nicht übersetzten Variante). Beispiel: "Value": "Horse"
Translations	Optional, Object, ApiVersion: 2 Bei Dropdowns können optional für jeden Wert Übersetzungen angegeben werden. Dabei entspricht der Key dem Eintrag im Items-Array, der Value der jeweiligen Übersetzung (z.B. de, en, …). Beispiel: `"Translations": { "de": { "DisplayName": "Tierauswahl", "Cow": "Kuh", "Horse": "Pferd", "Sloth": "Faultier" } }`
Options -> Conditions	Optional, Object, ApiVersion: 2 Details siehe Conditional Elements. "Operator": ["!="\|"=="\|"?"]

Einfache Texteingabe

SimpleText

Id, DisplayName

Pflichtfelder, ApiVersion: 1

Siehe Elements-Tabelle

DataType

Pflichtfeld, String, ApiVersion: 1

"DataType": "simpleText"

Value

Pflichtfeld, Array, ApiVersion: 1

Ein Array von Objects, die jeweils ein Text-Property haben in dem ein unlayoutierter Text gespeichert wird.

Beispiel:

"Value": [
	{
		"Text": "Some text." 
	},
	{
		"Text": "Another text."
	}
]

Options -> NumberOfInstances

Optional, Int, ApiVersion: 1

Mit diesem Parameter können Sie steuern, wie viele Instanzen eines TextInputs vom Benutzer erstellt werden können. Ist der Wert nicht oder auf 0 bzw. 1 gesetzt, sieht der Benutzer nur eine Textbox und kann keine weiteren Instanzen der TextInputs anlegen.

Beispiel:

"NumberOfInstances": 1

Options -> MultilineSize

Optional, Int, ApiVersion: 1

Mit diesem Parameter können Sie steuern, wie groß das TextInput angezeigt wird (wie viele Zeilen es hat). Ist dieser Wert nicht oder auf 0 bzw. 1 gesetzt, handelt es sich um ein Single-Line TextInput ohne Zeilenumbruch.

Beispiel:

"MultilineSize": 4

Options -> MaxChars

Pflichtfelder, ApiVersion: 1

Siehe Elements-Tabelle

Options -> Required

Optional, Int, ApiVersion: 1

Mit diesem Parameter können Sie bestimmen, wie viele Zeichen der Benutzer maximal eingeben darf. Der Spot lässt sich nicht speichern, solange dieser Wert bei einem Textfeld überschritten ist. Hat das Textfeld mehrere Instanzen, gilt dieser Wert für die jeweilige Instanz.

Beispiel:

"MaxChars": 120

Options -> ValidationRegExp

Optional, Boolean, ApiVersion: 1

Mit diesem Parameter können Sie sicherstellen, dass etwas in das Textfeld eingegeben wurde.

Beispiel:

"Required": true

Options -> ValidationRegExpDescription

Optional, String, ApiVersion: 1

Mit diesem Parameter können Sie eine Regular Expression hinterlegen, die erfüllt sein muss, damit der Benutzer den Spot speichern kann. Im Fehlerfall wird die ValidationRegExpDescription angezeigt, die in den Translations übersetzt werden kann. Beachten Sie, dass Backslashes doppelt angegeben werden müssen.

Beispiel:

"ValidationRegExp": "[\\d]*"

Options -> Conditions

Optional, Object, ApiVersion: 2

Details siehe Conditional Elements.

"Operator": ["!="|"=="|"?"]

Spotgruppenauswahl

List
Id, DisplayName	Pflichtfelder, ApiVersion: 1 Siehe Elements-Tabelle
DataType	Pflichtfeld, String, ApiVersion: 1 "DataType": "spotGroup"
Value	Pflichtfeld, Array, ApiVersion: 1 Ein Array von Objekten, die jeweils die ID und den Namen (zum Zeitpunkt des Auswählens) als Eigenschaften haben. Beispiel: `"Value": [ { "Id": 123, "Name": "Meine Spotgruppe" } ]`
Options -> NumberOfInstances	Optional, Int, ApiVersion: 1 Mit diesem Parameter können Sie steuern, wie viele Instanzen einer Spotgruppe vom Benutzer hinzugefügt werden können. Ist der Wert nicht oder auf 0 bzw. 1 gesetzt, kann der Benutzer nur eine Spotgruppe auswählen und kann keine weiteren Instanzen anlegen. Beispiel: "NumberOfInstances": 1
Options -> IncludeTemplates	Optional, Boolean, ApiVersion: 1 Der Parameter legt fest ob bei der Auswahl der Spotgruppen auch Vorlagen-Spotgruppen ausgewählt werden können. Beispiel: "IncludeTemplates": true
Options -> Conditions	Optional, Object, ApiVersion: 2 Details siehe Bedingte Elemente. "Operator": ["!="\|"=="\|"?"]

Mediengruppenauswahl

List
Id, DisplayName	Pflichtfelder, ApiVersion: 1 Siehe Elements-Tabelle
DataType	Pflichtfeld, String, ApiVersion: 1 "DataType": "mediaGroup"
Value	Pflichtfeld, Array, ApiVersion: 1 Ein Array von Objekten, die jeweils die ID und den Namen (zum Zeitpunkt des Auswählens) als Eigenschaften haben. Beispiel: `"Value": [ { "Id": 123, "Name": "Meine Mediagruppe" } ]`
Options -> NumberOfInstances	Optional, Int, ApiVersion: 1 Mit diesem Parameter können Sie steuern, wie viele Instanzen einer Mediengruppe vom Benutzer hinzugefügt werden können. Ist der Wert nicht oder auf 0 bzw. 1 gesetzt, kann der Benutzer nur eine Mediengruppe auswählen und kann keine weiteren Instanzen anlegen. Beispiel: "NumberOfInstances": 1
Options -> Conditions	Optional, Object, ApiVersion: 2 Details siehe Bedingte Elemente. "Operator": ["!="\|"=="\|"?"]

Locationauswahl

List
Id, DisplayName	Pflichtfelder, ApiVersion: 1 Siehe Elements-Tabelle
DataType	Pflichtfeld, String, ApiVersion: 1 "DataType": "location"
Value	Pflichtfeld, Array, ApiVersion: 1 Ein Array von Objekten, die jeweils die ID und den Namen (zum Zeitpunkt des Auswählens) als Eigenschaften haben. Beispiel: `"Value": [ { "Id": 123, "Name": "Meine Location" } ]`
Options -> NumberOfInstances	Optional, Int, ApiVersion: 1 Mit diesem Parameter können Sie steuern, wie viele Instanzen einer Location vom Benutzer hinzugefügt werden können. Ist der Wert nicht oder auf 0 bzw. 1 gesetzt, kann der Benutzer nur eine Location auswählen und kann keine weiteren Instanzen anlegen. Beachten Sie, dass Locations hierarchisch verschachtelt sein können. Beispiel: "NumberOfInstances": 1
Options -> Conditions	Optional, Object, ApiVersion: 2 Details siehe Bedingte Elemente. "Operator": ["!="\|"=="\|"?"]

Playerauswahl

List
Id, DisplayName	Pflichtfelder, ApiVersion: 1 Siehe Elemente-Tabelle
DataType	Pflichtfeld, String, ApiVersion: 1 "DataType": "player"
Value	Pflichtfeld, Array, ApiVersion: 1 Ein Array von Objekten, die jeweils die ID und den Namen (zum Zeitpunkt des Auswählens) als Eigenschaften haben. Beispiel: `"Value": [ { "Id": 123, "Name": "Mein Player" } ]`
Options -> NumberOfInstances	Optional, Int, ApiVersion: 1 Mit diesem Parameter können Sie steuern, wie viele Instanzen eines Players vom Benutzer hinzugefügt werden können. Ist der Wert nicht oder auf 0 bzw. 1 gesetzt, kann der Benutzer nur einen Player auswählen und kann keine weiteren Instanzen anlegen. Beispiel: "NumberOfInstances": 1
Options -> Conditions	Optional, Object, ApiVersion: 2 Details siehe Bedingte Elemente. "Operator": ["!="\|"=="\|"?"]

Kategorieauswahl

List
Id, DisplayName	Pflichtfelder, ApiVersion: 1 Siehe Elemente-Tabelle
DataType	Pflichtfeld, String, ApiVersion: 1 "DataType": "category"
Value	Pflichtfeld, Array, ApiVersion: 1 Ein Array von Objekten, die jeweils die ID und den Namen (zum Zeitpunkt des Auswählens) als Eigenschaften haben. Beispiel: `"Value": [ { "Id": 123, "Name": "Meine Kategorie" } ]`
Options -> NumberOfInstances	Optional, Int, ApiVersion: 1 Mit diesem Parameter können Sie steuern, wie viele Instanzen einer Kategorie vom Benutzer hinzugefügt werden können. Ist der Wert nicht oder auf 0 bzw. 1 gesetzt, kann der Benutzer nur eine Kategorie auswählen und kann keine weiteren Instanzen anlegen. Beachten Sie, dass Kategorien hierarchisch verschachtelt sein können. Beispiel: "NumberOfInstances": 1
Options -> Conditions	Optional, Object, ApiVersion: 2 Details siehe Bedingte Elemente. "Operator": ["!="\|"=="\|"?"]

Spotauswahl

List
Id, DisplayName	Pflichtfelder, ApiVersion: 1 Siehe Elemente-Tabelle
DataType	Pflichtfeld, String, ApiVersion: 1 "DataType": "spot"
Value	Pflichtfeld, Array, ApiVersion: 1 Ein Array von Objekten, die jeweils die ID und den Namen (zum Zeitpunkt des Auswählens) als Eigenschaften haben. Beispiel: `"Value": [ { "Id": 123, "Name": "Mein Spot" } ]`
Options -> NumberOfInstances	Optional, Int, ApiVersion: 1 Mit diesem Parameter können Sie steuern, wie viele Instanzen eines Spots vom Benutzer hinzugefügt werden können. Ist der Wert nicht oder auf 0 bzw. 1 gesetzt, kann der Benutzer nur einen Spot auswählen und kann keine weiteren Instanzen anlegen. Beispiel: "NumberOfInstances": 1
Options -> Conditions	Optional, Object, ApiVersion: 2 Details siehe Bedingte Elemente. "Operator": ["!="\|"=="\|"?"]

Medienauswahl

List
Id, DisplayName	Pflichtfelder, ApiVersion: 1 Siehe Elements-Tabelle
DataType	Pflichtfeld, String, ApiVersion: 1 "DataType": "media"
Value	Pflichtfeld, Array, ApiVersion: 1 Ein Array von Objekten, die jeweils die ID und den Namen (zum Zeitpunkt des Auswählens) als Eigenschaften haben. Beispiel: `"Value": [ { "Id": 123, "Name": "Mein Spot" } ]`
Options -> NumberOfInstances	Optional, Int, ApiVersion: 1 Mit diesem Parameter können Sie steuern, wie viele Instanzen eines Mediums vom Benutzer hinzugefügt werden können. Ist der Wert nicht oder auf 0 bzw. 1 gesetzt, kann der Benutzer nur ein Medium auswählen und kann keine weiteren Instanzen anlegen. Beispiel: "NumberOfInstances": 1
Options -> Conditions	Optional, Object, ApiVersion: 2 Details siehe Bedingte Elemente. "Operator": ["!="\|"=="\|"?"]

Editionauswahl

List
Id, DisplayName	Pflichtfelder, ApiVersion: 1 Siehe Elements-Tabelle
DataType	Pflichtfeld, String, ApiVersion: 1 "DataType": "edition"
Value	Pflichtfeld, Array, ApiVersion: 1 Ein Array von Objekten, die jeweils die ID und den Namen (zum Zeitpunkt des Auswählens) als Eigenschaften haben. Beispiel: `"Value": [ { "Id": 123, "Name": "WINDOWS", "Guid": "Meine Edition", } ]`
Options -> NumberOfInstances	Optional, Int, ApiVersion: 1 Mit diesem Parameter können Sie steuern, wie viele Editionen vom Benutzer hinzugefügt werden können. Ist der Wert nicht oder auf 0 bzw. 1 gesetzt, kann der Benutzer nur eine Edition auswählen und kann keine weiteren Instanzen anlegen. Beispiel: "NumberOfInstances": 1
Options -> Conditions	Optional, Object, ApiVersion: 2 Details siehe Bedingte Elemente. "Operator": ["!="\|"=="\|"?"]

Screengruppenauswahl

List
Id, Name	Pflichtfelder, ApiVersion: 5 Siehe Elements-Tabelle
DataType	Pflichtfeld, String, ApiVersion: 5 "DataType": "screenGroup"
Value	Pflichtfeld, Array, ApiVersion: 5 Ein Array von Objekten, die jeweils die ID und den Namen (zum Zeitpunkt des Auswählens) als Eigenschaften haben. Beispiel: `"Value": [ { "Id": 123, "Name": "Meine Screeengruppe" } ]`
Options -> NumberOfInstances	Optional, Int, ApiVersion: 5 Mit diesem Parameter können Sie steuern, wie viele Editionen vom Benutzer hinzugefügt werden können. Ist der Wert nicht oder auf 0 bzw. 1 gesetzt, kann der Benutzer nur eine Edition auswählen und kann keine weiteren Instanzen anlegen. Beispiel: "NumberOfInstances": 1
Options -> Conditions	Optional, Object, ApiVersion: 2 Details siehe Bedingte Elemente. "Operator": ["!="\|"=="\|"?"]

Berechtigungsgruppenauswahl

List
Id, Name	Pflichtfelder, ApiVersion: 5 Siehe Elements-Tabelle
DataType	Pflichtfeld, String, ApiVersion: 5 "DataType": "permissionGroup"
Value	Pflichtfeld, Array, ApiVersion: 5 Ein Array von Objekten, die jeweils die ID und den Namen (zum Zeitpunkt des Auswählens) als Eigenschaften haben. Beispiel: `"Value": [ { "Id": 123, "Name": "Meine Berechtigungsgruppe" } ]`
Options -> NumberOfInstances	Optional, Int, ApiVersion: 5 Mit diesem Parameter können Sie steuern, wie viele Editionen vom Benutzer hinzugefügt werden können. Ist der Wert nicht oder auf 0 bzw. 1 gesetzt, kann der Benutzer nur eine Edition auswählen und kann keine weiteren Instanzen anlegen. Beispiel: "NumberOfInstances": 1
Options -> Conditions	Optional, Object, ApiVersion: 2 Details siehe Conditional Elements. "Operator": ["!="\|"=="\|"?"]

Bedingte Elemente – Conditions

Über Conditions lassen sich beliebig viele Bedingungen festlegen, welche über UND-Verknüpfungen verknüpft werden. Eine Condition wird über das Options-Objekt definiert und besteht aus 4 Eigenschaften:

Action: Definiert, was bei einer erfolgreichen Auswertung der Überprüfung passiert. Derzeit wird nur die Action "HIDE" zum Ausblenden von Eingabefeldern unterstützt.
TargetId: Entspricht der ID des zu testenden Elements
Operator: Legt die Art der Überprüfung fest. Die Verfügbarkeit der Operatoren ist abhängig vom jeweiligen Typ des zu testenden Elements. Details können den Eigenschaften des jeweiligen Elements entnommen werden.
Value: Der zu überprüfende Wert.

Beispiel:

{
  "Id": "boolean1",
  ...
  "Id": "radiobutton1",
  ...
  "Id": "optionalInput",
  ...
  "Options": {
    ...
    "Conditions": [
      {
        "Action": "HIDE",
        "TargetId": "boolean1",
        "Operator": "==",
        "Value": true
      },
      {
        "Action": "HIDE",
        "TargetId": "radiobutton1",
        "Operator": "==",
        "Value": "DO_NOT_SHOW"
      }
    ]
  }
}

In der oben angeführten Definition wird das Element "optionalInput" auf zwei Bedingungen überprüft.

Bedingung 1 ist erfüllt, wenn das Element "boolean1" den Wert true besitzt, d.h., die Checkbox im Editor aktiviert ist.
Bedingung 2 ist erfüllt, wenn das Element "radiobutton1" den Wert DO_NOT_SHOW besitzt.

Das Element "optionalInput" wird ausgeblendet, wenn beide Bedingungen erfüllt sind.

GFDashboardWidgetBase

Die GFDashboardWidgetBase ist die eine Erweiterung für die GFWizardBase. Es handelt sich dabei um eine JavaScript Lib, die – neben der GFWizardBase – in Dashboard Widgets integriert werden muss, damit das Widget ordnungsgemäß im Grassfish System funktioniert.

In den folgenden Unterkapiteln werden die Events beschrieben bzw. allgemeine Hinweise zu deren Verwendung dargelegt.

Verwendung

Die Datei GFDashboardWidgetBase darf in Unterordnern verschachtelt sein, sollte jedoch nicht editiert werden. Fügen Sie die Datei mittels <script>-Tag unmittelbar nach der GFWizardBase in die Webseite ein.

<script src="gfWizardBase.js"></script>

<script src="gfDashboarWidgetBase.js"></script>

Sie dürfen auf die Methoden der GFDashboardWidgetBase erst zugreifen, wenn die JavaScript-Datei auch wirklich initialisiert worden ist. Verwenden Sie hierzu die onload-Methode des <body>-Tags:

<body onload="init()">

Im Skript muss zunächst eine Instanz der GFDashboardWidgetBase erzeugt werden. Dabei nimmt der Konstruktor eine Instanz der GFWizardBase als Parameter. Im Gegensatz zur GFSpotBase ist die GFDashboardWidgetBase keine statische Klasse, sondern muss global instanziert werden.

//gfDashboardWidgetBase must be accessed globally!
var gfDashboardWidgetBase = new GFDashboardWidgetBase(new GFWizardBase());

function init()
{
//register all events
gfDashboardWidgetBase.registerDataChangedHandler(onDataChanged);
//notify the container that you are ready
gfDashboardWidgetBase.sendReady();

alert(gfDashboardWidgetBase.getVersion());
}

function onDataChanged(jsonData)
{
	
}

Initial muss der Spot ein "Ready"-Event senden, damit die Container wissen, dass sie jetzt mit dem Spot kommunizieren können. Dieser Aufruf sieht wie folgt aus:

gfDashboardWidgetBase.sendReady();

Erst nachdem der Spot sich als Ready gemeldet hat, bekommt er vom Container seine JSON-Daten. Wenn die Daten gesetzt wurden, sendet der Spot automatisch ein InitComplete-Event an den Container, dass wiederum an die IXM Plattform weitergeleitet wird. Dadurch weiß die IXM Plattform, dass das Widget angezeigt werden kann.

Optional können Sie das InitComplete verzögern, indem Sie beim sendReady einen true-Parameter mitgeben. Dadurch wird das InitComplete-Event nicht automatisch beim Setzen der Daten ausgelöst, sondern muss manuell getriggert werden.

gfDashboardWidgetBase.sendReady(true);

//do your asynchronous stuff, e.g. call a webservice

gfDashboardWidgetBase.sendInitComplete();

Hinweis

Wenn Sie InitComplete manuell triggern möchten, dies aber dann nicht triggern, kommt es beim Anzeigen des Widgets zu Fehlern. Wenn Sie in einem HTML-Wizard-Spot auch die GFSpotBase verwenden, triggern Sie bitte NUR das sendInitComplete() von der GFDashboardWidgetBase, nicht das von der GFSpotBase.

Daten empfangen

Damit das Dashboard Widget die vom Benutzer ausgefüllten Daten bekommt, muss es sich für das dataChanged-Event registrieren. Dies geschieht wie folgt:

gfDashboardWidgetBase.registerDataChangedHandler(onDataChanged);

Funktion	Registriert eine Callback-Funktion, die initial aufgerufen wird, sowie wenn sich Daten im Dashboard Widget Editor geändert haben.
Parameter	function(jsonData) jsonData die JSON-Daten, die vom Dashboard Widget Editor kommen (der modifizierte Inhalt aus der ascData.json-Datei)
Beispiele	`gfDashboardWidgetBase. registerDataChangedHandler(onDataChanged); function onDataChanged(jsonData) { var elementData = gfDashboardWidgetBase.getElementData(); document.getElementById("myElement").innerHTML = elementData["myJsonElement"].Value; }`
Minimum Version	ApiVersion: 1 Grassfish IXM Plattform: 11.0.0

Animationen Starten/Stoppen

Wenn das Dashboard Widget in der IXM Plattform geladen wird, sendet die IXM Plattform zum Starten der Animationen ein Play-Kommando via Callback.

gfDashboardWidgetBase.registerPlayHandler(onPlay);

Funktion	Startet die Animationen im Dashboard Widget. Wird vom Container aufgerufen, wenn die Animationen im Dashboard Widget beginnen sollen. Davor sollte das Dashboard Widget keine Animationen abspielen.
Parameter	Keine
Beispiele	`gfDashboardWidgetBase. registerPlayHandler(startMyAnimations);`
Minimum Version	ApiVersion: 1 Grassfish IXM Plattform: 11.0.0

gfDashboardWidgetBase.registerStopHandler(onStop);

Funktion	Diese Funktion hat derzeit keine Auswirkung.
Parameter	Keine
Beispiele	`gfDashboardWidgetBase. registerStopHandler(resetMyAnimations);`
Minimum Version	ApiVersion: 1 Grassfish IXM Plattform: 11.0.0

Detail View

Neben den drei möglichen Auflösungen im Dashboard kann das Widget noch zusätzlich in einer Detailansicht angezeigt werden. Diese Ansicht unterstützt eine Auflösung von 1024x576 Pixeln und soll dazu dienen, komplexere Darstellungen (z.B. bei Reporting) über das Widget zu ermöglichen. Über die Methode isDetailView kann abgefragt werden, ob das Widget in der Detailansicht angezeigt werden soll.

if(gfDashboardWidgetBase.isDetailView())
{
  //display Widget in detail mode.
}

Report View

Weiters lassen sich Dashboard-Addons auch im Reporting-Bereich des IXM Plattform verwenden. Für eine bessere Übersichtlichkeit wird dabei mehr Platz zur Präsentation der jeweiligen Daten reserviert. In dieser Ansicht ist die Größe nicht festgelegt, sie entspricht dem im IXM Plattform zur Verfügung stehenden Platz. Daher ist hier auf eine passende Darstellung zu achten. Über die Methode isReportView kann abgefragt werden, ob das Widget in der Report-Ansicht angezeigt werden soll.

if(gfDashboardWidgetBase.isReportView())
{
  // display widget in report mode
}

Aufforderung zum Drucken

Über die IXM Plattform kann das Dashboard-Widget aufgefordert werden, eine Druckansicht zu generieren. Das kann beispielsweise in einem neuen Tab im Browser oder in einem Aufruf zum Backend zur Generierung einer CSV-Datei resultieren. Dies geschieht mit dem Callback registerPrintHandler. In der GFDashboardWidgetBase gibt es eine Hilfsfunktion namens saveToFile, die weiter unten in diesem Kapitel beschrieben ist.

gfDashboardWidgetBase.registerPrintHandler(onPrintRequested);

Funktion	Callback function um die Printanfrage aus der IXM Plattform im Dashboard Widget zu verarbeiten.
Parameter	Keine
Beispiele	`gfDashboardWidgetBase. registerPrintHandler(onPrintRequested); function onPrintRequested() { }`
Minimum Version	ApiVersion: 1 Grassfish IXM Plattform: 11.0.0

gfDashboardWidgetBase.saveToFile(value, fileName, filetype);

Funktion	Hilfsfunktion zum Öffnen eines Dialogs, um die Implementierung des Abspeicherns von Daten zu ermöglichen.
Parameter	Value: String, die Daten fileName: String, der Dateiname filetype: String, der Typ der Datei, optional, Default: "application/octet-stream"
Beispiele	`var content; content = "ID,TEXT"\n"; content += "1,Ich"\n"; content += "2,werde"\n"; content += "3,exportiert"\n"; gfDashboardWidgetBase.saveToFile(content, "export.csv", "text/csv");`
Minimum Version	ApiVersion: 1 Grassfish IXM Plattform: 11.0.0

Logging

Es ist möglich, sich ein Onscreen-Logging ausgeben zu lassen. Nachrichten, die hier angezeigt werden sollen, müssen via sendLog an den Container gesendet werden. Mit dem Callback registerLogHandler können Sie sich dann ebenfalls an diese Logmeldungen hängen, um im Dashboard Widget noch weiter darauf zu reagieren.

gfDashboardWidgetBase.sendLog("message");

Funktion	Loggt die Nachricht im OnScreen-Log des ascInterface. Das Log muss im ascInterface mit dem URL-Parameter &debug=true aktiviert werden.
Parameter	function(message) message Nachricht, die geloggt werden soll
Beispiele	gfDashboardWidgetBase.sendLog("message");
Minimum Version	ApiVersion: 1 Grassfish IXM Plattform: 11.0.0

gfDashboardWidgetBase.registerLogHandler(onLog);

Funktion	Callback function für sendLog zur Weiterverarbeitung im Dashboard Widget.
Parameter	function(message) message Nachricht, die geloggt werden soll
Beispiele	`gfDashboardWidgetBase.registerLogHandler(onLog); function onLog(message) { }`
Minimum Version	ApiVersion: 1 Grassfish IXM Plattform: 11.0.0

Upload in die IXM Plattform

Gewisse Standard-Dashboard-Widgets werden automatisch in das System hochgeladen. Die eigenen Widgets können in der Administration unter Dashboard > Widgets in die Widgetgruppe Widgetvorlagen hochgeladen werden. Von dort aus kann man dann Varianten in die jeweiligen Widgetgruppen ziehen. Weitere Informationen dazu können Sie aus der Online Hilfe entnehmen.

Editieren in der IXM Plattform

Wenn ein Dashboard Widget aktualisiert werden soll, so ist das nur in der Administration unter Dashboard > Widgets in der Widgetgruppe Widgetvorlagen möglich. Dort muss das jeweilige Widget ausgewählt und anschließend unter Tools > Widget austauschen selektiert werden. Es öffnet sich dann der Upload Manager in dem man die neue Version des Dashboard Widgets ziehen muss, bevor man dann den Upload startet. Die ID des hochgeladenen Dashboard Widgets muss mit der ID des selektierten Dashboard-Widget übereinstimmen um es aktualisieren zu können.

What's Next

UDC Integration

In diesem Artikel

API-Versionen
ascData.json
Elemente
GFDashboardWidgetBase
Upload in die IXM Plattform
Editieren in der IXM Plattform