Entwicklung von Visuelementen***r-3-0Quelltext

Das Grundgerüst eines Visuelements (VSE) besteht aus folgenden Abschnitten (die Reihenfolge der einzelnen Abschnitte ist unerheblich): Hinweis: Die vollständige Syntax zur Definition eines Abschnitts folgt dabei diesem Schema: z.B. ###[DEF]### ... ###[/DEF]### Wichtig:

Abschnitt [DEF]

Hier werden der Name des VSE und sämtliche Parameter bzw. Eigenschaften definiert. Die folgenden Eigenschaften repräsentieren einige Parameter in der linken Spalte des Dialogs Visuelement bearbeiten***1002 (allgemeine und spezifische Eigenschaften): Diese Eigenschaften aktivieren/deaktivieren bzw. definieren die Eigenschaften in der rechten Spalte des Dialogs Visuelement bearbeiten***1002 (Beschriftung, Designs, Kommunikationsobjekte, etc.): Die folgenden (optionalen) Eigenschaften sind erforderlich, sofern das Visuelement eine Ton- oder Sprachausgabe bereitstellt: Beispiel:
###[DEF]###
[name = Beispiel-Visuelement]

[xsize	=100]
[ysize	=50]
[text	=KO1-Wert: {#}]

[var1 = 0 #root=100] (var1 verweist auf die DB "edomiProject.editTimer")
[var2 = 123]
[var3 = 0]
[var4 = 1]
[var5 = 0]

[flagText		=1]
[flagKo1		=1]
[flagKo2		=0]
[flagPage		=1]
[flagCmd		=1]
[flagDesign		=1]
[flagDynDesign	=1]

[captionKo1		=Steuerung des Designs]
###[/DEF]###
"Whitespace" (Leerzeichen) innerhalb der Deklaration wird ignoriert: [name=(Name)] führt zum gleichen Ergebnis wie [ name = (Name) ]. Im Anschluss an eine Deklaration kann bei Bedarf ein Hilfetext angegeben werden:
###[DEF]###
...
[var1 = A] Hinweis: var1 wird auf den Defaultwert "A" gesetzt
...
###[/DEF]###
Der Hinweistext darf keine eckigen Klammern enthalten! Wichtig: Eine Deklaration darf keine eckigen Klammern oder HTML-Tags enthalten, z.B. wäre [var1 = [Test]] keine gültige Deklaration, [var1 = Test] wäre hingegen gültig. Bei Bedarf müssen HTML-Entities/Unicode-Symbole verwendet werden.

Abschnitt [PROPERTIES]

Dieser Abschnitt definiert die "spezifischen Eigenschaften" im Dialog Visuelement bearbeiten***1002 mittels einer speziellen Syntax. Der Nutzer hat hier ggf. die Möglichkeit die Parameter var1..20 entsprechend anzupassen. Wichtig: Die Syntax und die Reihenfolge ist präzise einzuhalten (wie nachfolgend beschrieben)! Beispiel:
###[PROPERTIES]###
	[columns=50,50]

	[row]
	[var1 = root,2,'Zeitschaltuhr-Auswahl',100]

	[row=Titel 1]
	[var2 = text,1,'Eingabefeld','(placeholder)']
	[var3 = select,1,'Selectbox','0#A|1#B|2#C|EDOMI#D']

	[row=Titel 2]
	[var4 = check,1,'Checkbox','Wert 0 oder 1']
	[var5 = checkmulti,1,'Checkbox mit mehreren Werten','Wert 0|Wert 1|Wert 2|Wert 3']
###[/PROPERTIES]###

Abschnitt [ACTIVATION.PHP]

In diesem (optionalen) Abschnitt kann ein PHP-Script hinterlegt werden, das bei der Projekt- oder Visuaktivierung ausgeführt wird (z.B. um bestimmte Parameter zu überprüfen oder zu modifizieren). Typischer Weise werden ausschließlich SQL-Operationen angewendet. Wichtig: In diesem Abschnitt sind keine Funktionen/Klassen/etc. erlaubt (der Code wird intern bereits in einer Funktion gekapselt)! Achtung: Es ist unbedingt zu bedenken, dass dieser Code im Kontext des Aktivierungsprozesses ausgeführt wird - ein fehlerhaftes Script kann daher EDOMI zum Absturz bringen! Beispiel: Das Steuerungs-KO der ZSU (edomiProject.editTimer.gaid) soll bei einer Aktivierung als KO1 der Visuelement-Instanz (edomiLive.visuElement.gaid) festgelegt werden. $item['var1'] repräsentiert den Parameter "var1" der Visuelement-Instanz, in dem o.g. Beispiel (siehe [DEF] bzw. [PROPERTIES]) also die ID der ausgewählten ZSU.
###[ACTIVATION.PHP]###

###[/ACTIVATION.PHP]###

Abschnitt [EDITOR.JS]

Dieser Abschnitt definiert mittels einer vorgegebenen JS-Funktion die Darstellung des Visuelements im Visueditor. Der Aufruf erfolgt nach(!) der Zuweisung von CSS-Eigenschaften ("Design" bzw. "dynamische Designs"), daher können diese Eigenschaften bei Bedarf "übersteuert" werden (siehe Beispiel). Wichtig: Die nachfolgende Funktion ist zwingend erforderlich und wird vom Visueditor beim Seitenaufbau aufgerufen: Beispiel:
###[EDITOR.JS]###
VSE_VSEID=function(elementId,obj,meta,property,isPreview,koValue) {
	var n="";
	n+="";

		//Name der ausgewählten Zeitschaltuhr (wird im Abschnitt [EDITOR.PHP] ermittelt, s.u.):
		n+="";

		//"Beschriftung" nur anzeigen, wenn var4=1 ist:
		if (obj.dataset.var4==1) {
			n+="";
		}
		
	n+="
"+property[0]+"
"+meta.itemText+"
"; //HTML-Code dem Visuelement zuweisen obj.innerHTML=n; //CSS-Anpassungen: Text immer zentrieren, kein Padding erlauben (die entsprechenden Design-Einstellungen werden hier übersteuert) obj.style.textAlign="center"; obj.style.padding="0"; //Rückgabe des ZSU-Namens zur Anzeige in der Seitenleiste return property[0]; } ###[/EDITOR.JS]###

Abschnitt [EDITOR.PHP]

In diesem (optionalen) Abschnitt kann ein PHP-Script zur Deklaration des Arrays "$property[]" angegeben werden. Dieses Array wird im Abschnitt [EDITOR.JS] als JS-Funktionsparameter "property" der Funktion "VSE_VSEID" (s.o.) übernommen. Beispielsweise kann der Name einer vom Nutzer ausgewählten Zeitschaltuhr ermittelt und übergeben werden, damit dieser innerhalb des Visuelements und/oder in der Seitenleiste angezeigt werden kann. Wichtig: In diesem Abschnitt sind keine Funktionen/Klassen/etc. erlaubt (der Code wird intern bereits in einer Funktion gekapselt)! Beispiel:
###[EDITOR.PHP]###

###[/EDITOR.PHP]###

Abschnitt [VISU.JS]

Dieser Abschnitt implementiert mittels vorgegebener JS-Funktionen die Darstellung und die Funktionalität des Visuelements in der Visualsierung auf dem Endgerät. Wichtig: Die nachfolgende Funktion ist zwingend erforderlich und wird von der Visualisierung beim Seitenaufbau aufgerufen. Der Aufruf erfolgt nur einmalig(!) beim Seitenaufbau und nach(!) der Zuweisung von CSS-Eigenschaften ("Design" bzw. "dynamische Designs"): Die nachfolgende Funktion ist zwingend erforderlich und wird von der Visualisierung beim Seitenaufbau nach der Funktion controlVSEID_constructControl() aufgerufen. Anschließend wird die Funktion bei jedem "refresh" (z.B. Änderung eines relevanten KO-Wertes) und während einer Drag-Operation (bei Nutzung der entsprechenden Funktionen) aufgerufen: Beispiel:
###[VISU.JS]###
VSE_VSEID_CONSTRUCT=function(elementId,obj) {
	var n="";

	//hier wird eine Tabelle erzeugt und (nachfolgend) mit der "Beschriftung" des Visuelements gefüllt:
	n+="";
		n+="";
	n+="
"; obj.innerHTML=n; //falls Seitensteuerung/Befehle angegeben wurden: Klick-Event auswerten if (visuElement_hasCommands(elementId)) { visuElement_onClick(obj,function(veId,objId){visuElement_doCommands(veId);}); } } VSE_VSEID_REFRESH=function(elementId,obj,isInit,isRefresh,isLive,isActive,koValue) { //falls keine Seitensteuerung/Befehle angegeben wurden: Visuelement ist "klicktranparent" if (!visuElement_hasCommands(elementId)) { obj.style.pointerEvents="none"; } //ggf. individuelle CSS-Styles festlegen (hier wurde das "Design/dynamische Design" bereits angewendet und kann nun ggf. "übersteuert" werden): if (obj.dataset.var2==1) { obj.style.background="#ff0000"; } //Visuelement beschriften (der KO-Wert wird mittels visuElement_parseString() geparsed): document.getElementById("e-"+elementId+"-text").innerHTML=visuElement_parseString(visuElement_getText(elementId),koValue); } ###[/VISU.JS]###
Die nachfolgende (optionale) Funktion wird von der Visualisierung immer dann aufgerufen, bevor ein Seitenwechsel erfolgt (auch beim Öffnen bzw. Schließen eines Popups). Das Visuelement kann somit ggf. darauf reagieren, dass es in Kürze z.B. unbedienbar wird (z.B. weil ein modales Popup geöffnet wird) bzw. nicht mehr existieren wird. Dies ist z.B. sinnvoll, wenn ein Eingabefeld den Fokus hat und während dessen ein modales Popup geöffnet wird. Bei Drag-Objekten (falls durch die Funktion "visuElement_onDrag()" definiert) ist keine individuelle Reaktion/Funktion erforderlich, da die Drag-Operation automatisch beendet wird (der aktuell durch die Drag-Operation eingestellte KO-Wert wird dann übernommen). Beispiel:
###[VISU.JS]###
VSE_VSEID_CANCEL=function(elementId) {
	//hier könnte z.B. eine Tastatureingabe in einem Input-Field abgesendet werden, bevor das Visuelement den Fokus verliert
}
###[/VISU.JS]###

Drag-Operationen

Bei Bedarf können spezielle Funktionen zur Bereitstellung einer Drag-Funktionalität genutzt werden (z.B. zur Implementierung eines Schiebereglers o.d.G.). Die Registrierung des Drag-Objekts muss dabei mittels der Funktion visuElement_onDrag() erfolgen. Die nachfolgenden Funktionen sind dann zwingend erforderlich (diese werden während einer Drag-Operation aufgerufen): Beispiel:
###[VISU.JS]###
VSE_VSEID_CONSTRUCT=function(elementId,obj) {
	var n="
(Drag-Bereich)
"; obj.innerHTML=n; //Drag-Objekt registrieren (KO2 wird per Drag absolut gesetzt, kein zyklisches Setzen): visuElement_onDrag(document.getElementById("e-"+elementId+"-drag"),0,2,-1); } ... VSE_VSEID_DRAGSTART=function(elementId,dragObj) { //keine besonderen Maßnahmen erforderlich } VSE_VSEID_DRAGMOVE=function(elementId,dragObj) { var obj=document.getElementById("e-"+elementId); if (obj) { //Mausposition ermitteln (bezogen auf dragObj) var tmp=visuElement_getMousePosition(obj,dragObj,0); //KO2-Wert auf X-Position setzen return tmp.x; } } VSE_VSEID_DRAGEND=function(elementId,dragObj,dragValue) { //keine besonderen Maßnahmen erforderlich } ###[/VISU.JS]###

Abschnitt [VISU.PHP]

In diesem (optionalen) Abschnitt können prinzipiell beliebige PHP-Funktionen/-Klassen deklariert werden. Wichtig: Mit Hilfe der JS-Funktion "visuElement_callPhp()" (im Abschnitt [VISU.JS] oder [SHARED.JS]) wird zunächst die PHP-Funktion "PHP_VSE_VSEID()" (per "Ajax") aufgerufen, diese Funktion kann dann ggf. in eigene Implementierungen verzweigen: Beispiel:
###[VISU.JS]###
VSE_VSEID_Beispiel=function(value) {
	visuElement_callPhp(VSEID,"test",{Wert:value},null);
}

...

###[/VISU.JS]###

###[VISU.PHP]###
100) {
			PHP_VSE_VSEID_eigeneFunktion($json1['Wert']);
		}
	}
}

function PHP_VSE_VSEID_eigeneFunktion(n) {
	...
}
?>
###[/VISU.PHP]###

Abschnitt [SHARED.JS]

In diesem (optionalen) Abschnitt können JS-Funktionen hinterlegt werden, die sowohl im Abschnitt [EDITOR.JS] als auch im Abschnitt [VISU.JS] zu Verfügung stehen. Wichtig: Beispiel:
###[SHARED.JS]###
VSE_VSEID_beispiel=function(obj) {
	if (obj) {
		console.log("VSE_VSEID_beispiel() von ID "+obj.id+" aufgerufen");
	}
}
###[/SHARED.JS]###
Diese Funktion kann dann sowohl im Abschnitt [EDITOR.JS] als auch im Abschnitt [VISU.JS] aufgerufen werden, beispielsweise wie folgt:
###[EDITOR.JS]###
VSE_VSEID=function(elementId,obj,meta,property,isPreview,koValue) {
	...
	VSE_VSEID_beispiel(obj);
	...	
}
###[/EDITOR.JS]###

###[VISU.JS]###
VSE_VSEID_CONSTRUCT=function(elementId,obj) {
	...
	VSE_VSEID_beispiel(obj);
	...	
}
###[/VISU.JS]###

Abschnitt [HELP]

Hier sollte das VSE kurz beschrieben werden, sowie die Bedeutungen der Parameter var1..20 erläutert werden. Der Hilfetext kann HTML-Tags enthalten (z.B. Tabellen oder Listen). Beispiel:
###[HELP]###
(Hilfetext)
###[/HELP]###