WaBis

walter.bislins.ch

CP: ControlPanel-Felder

CpField ist die Basis-Klasse für alle ControlPanel-Felder. Sie definiert ein paar Properties und Funktionen, die allen abgeleiteten Felder gemeinsam sind.

Von CpField abgeleitete Klassen sind:

CpField Klasse

CpField = {
Panel: ControlPanel; ReadOnly; Init = Parent ControlPanel
Name: String; ReadOnly; Init = 'Field' + FieldCounter
Label: String; ReadOnly; Init = Name
ValueRef: CpObjectRef; Private; Init = [ModelRef + '.' +] Name
ReadOnly: Boolean; ReadOnly; Init = ControlPanel.ReadOnly
Enabled: Boolean; Private; Init = ControlPanel.Enabled
EnabledRef: CpObjectRef or function(); Private; Init = ControlPanel.EnabledRef
Description: String; ReadOnly; Init = ''
Link: String; ReadOnly; Init = ''
ColSpan: Integer(>0); ReadOnly; Init = 1
Attr: String; ReadOnly; Init = ''
}

CpField Properties

Panel Verweis auf das übergeordnete ControlPanel Objekt. Das CpField Objekt wird in der Liste ControlPanel.Fields verlinkt.
Name Standardwert für Label und ValueRef
Label Label für das ControlPanel-Feld. Label dürfen HTML-Tags enthalten.
ValueRef Referenz auf eine globale Variable oder ein Objekt-Property.
ReadOnly true → Feld kann nicht verändert werden
Enabled false → Feld ist deaktiviert. Dieses Property kann nur mit der Funktion IsEnabled() abgefragt werden
EnabledRef Referenz auf ein Modell-Property, welches den Enabled-Zustand fernsteuert oder eine function, welche den enabled Zusatand berechnet.
Description wird eingeblendet, wenn die Maus über dem Label oder dem HelpImage steht
Link HTML- oder Wiki-Link zu einer Help-Seite mit der Beschreibung des Ein-/Ausgabefeldes.
ColSpan Anzahl Tabellen-Spalten, welche das Werte-Feld überspannen soll
Attr Zusätzliche HTML-Attribute für das Werte-Feld

Hinweis: Diese Properties werden an die abgeleiteten Klassen vererbt.

CpField Funktionen

GetType() Fragt den Typ des Feldes ab
GetValueRef() Gibt den String-Wert des ValueRef Properties zurück. Auf ValueRef darf nicht direkt zugegriffen werden.
IsEnabled() Gibt den Enabled-Zustand des Feldes zurück. Auf Enabled darf nicht direkt zugegriffen werden.
SetEnabled() Setzt den Enabled-Zustand des Feldes.
GetHtmlID() Gibt die HTML-ID eines ControlPanel-Feldes oder Items zurück
GetDomObj() Gibt eine Referenz auf das DOM-Element eines ControlPanel-Feldes oder Items zurück

CpObjectRef Klasse

Einige Ref-Properties wie ValueRef, EnabledRef usw. verweisen auf eine globale Variable oder ein Model-Property. Dieser Verweis wird intern in Form eines CpObjectRef Objektes dargestellt. Die Verweise werden jedoch mit einem String-Parameter definiert.

Auf die Properties vom Typ CpObjectRef darf nicht zugegriffen werden. Einzig für das Abfragen des ursprünglichen ValueRef Strings gibt es die Funktion GetValueRef().

CSS-Klassen

Das ControlPanel-Modul erzeugt zur Darstellung der Panels HTML-Tabellen. Für die Formatierung der Tabellen mit CSS werden den Tabellen und deren Zeilen und Zellen diverse CSS-Klassen zugewiesen. Damit ist es möglich, einzelne Tabellen, Zeilen, Spalten oder Zellen über CSS zu adressieren und zu formatieren. Zusätzliche Klassen können den Tabellen und Zellen beim Erzeugen mit PanelFormat und Attr zugewiesen werden.

Folgende Klassen kommen standardmässig zur Anwendung:

CSS-Klasse Objekt Beschreibung
ControlPanel ControlPanel Alle ControlPanel-Tabellen erhalten diese Klasse
Slider ControlPanel Mit ControlPanels.NewSliderPanel() erzeugte Tabellen erhalten diese Klasse zusätzlich
Left, Right ControlPanel Mit ControlPanels.NewSliderPanel() erzeugte Tabellen erhalten diese Klasse zusätzlich, je nachdem auf welcher Seite des Sliders das Wertefeld steht, siehe ValuePos
NCols<N> ControlPanel Diese Klassen geben an, wieviele Kolonnen einen Tabelle hat. NCols1 bedeutet, die Tabelle hat 2 Kolonnen, je eine für Labels und eine für die Eingabefelder, Splider usw.
PanelFormat ControlPanel Dem Property PanelFormat zugewiesene Klassen werden ebenfalls der Tabelle zugewiesen.
HdRow Header-Zeile Jede Titelzeile einer Tabelle erhält diese Klasse.
Row<N> Tabellen-Zeilen Jede Zeile einer Tabelle erhält diese Klasse. Row1 ist die erste nicht-Header Zeile der Tabelle.
Label Label-Spalten Jede Zelle in der Spalte mit Labels erhält diese Klasse.
Value Value/Slider-Spalten Jede Zelle in der Spalte mit Eingabefeldern oder Slidern erhält diese Klasse.
Slider Slider-Spalten Jede Zelle in der Spalte mit Slidern erhält diese Klasse.
SliderValue Value-Spalten Jede Zelle in der Spalte mit Slider-Wertefeldern erhält diese Klasse, siehe AddValueSliderField().
Col<N> Zellen derselben Spalte Jede Zelle einer bestimmten Spalte erhält diese Klasse. Allen Zellen der ersten Spalte wird die Klasse Col1 zugewiesen usw.
TextField Texte, Label Alle Texte wie Label und Einheiten werden in ein DIV mit dieser Klasse verpackt.
FieldGrid Checkbox, Radiobuttons Checkboxen und Radiobuttons werden in eine Tabelle mit dieser Klasse verpackt.
Field Text-Feld Eingabefelder erhalten diese Klasse
ReadOnly alle Felder Eingabefelder mit dem Property ReadOnly = true erhalten diese Klasse

HTML-IDs

Die verschiedenen HTML-Elemente eines ControlPanels erhalten jeweils eindeutige HTML-IDs. Diese leiten sich aus den Name Properties und den Feld-Typen ab:

ID Objekt Beschreibung
ControlPanel<N> ControlPanel-Tabelle Standard-ID für ControlPanel-Tabellen. Kann über ControlPanel.Name geändern werden. Die erste Tabelle erhält die ID ControlPanel1 usw. Die Nummer wird vom ControlPanels.Counter übernommen.
ControlPanel<N>-<FieldName> Eingabefelder
ControlPanel<N>-<FieldName>-Unit Einheiten Einheiten hinter Eingabefeldern wernden in ein DIV der Klasse FieldText verpackt, welche diese ID erhält
ControlPanel<N>-<FieldName>-Slider Slider-Objekte
ControlPanel<N>-<FieldName>-Slider-Handle Slider-Schieberegler Über diese ID lassen sich die Schieberegler von Slidern einzeln ansprechen, um zum Beispiel deren Hintergrundfarbe zu ändern

CpField.Panel

CpField.Panel: ControlPanel; ReadOnly 

Panel ist ein Link auf das ControlPanel, in welchem das Feld enthalten ist. Das Feld wird im Array Fields des ControlPanels verlinkt. Panel wird automatisch beim Hinzufügen eines Feldes zu einem ControlPanel zum Beispiel mit AddTextField() gesetzt.

Hinweis: Wenn ein ControlPanel mit Delete() oder ControlPanels.DeletePanels() gelöscht wird, werden die gegenseitigen Links gekappt, damit der Speicher der Objekte von der Garbage Collection freigegeben werden kann.

CpField.Name

CpField.Name: String; ReadOnly; Init = 'Field' + FieldCounter 

Jedes ControlPanel-Feld hat einen Parameter Name, welcher bei der entsprechenden Funktion zum Erzeugen des Feldes angegeben werden kann (z.B. AddTextField()). Bei CpCheckboxField Objekten hat zudem jedes Checkbox-Item einen eigenen Namen.

Name dient als Standardwert für Label und ValueRef, wenn diese nicht spezifiziert werden.

Wird der Parameter Name nicht definiert, bekommt er den Standardwert 'Field' + FieldCounter. FieldCounter ist eine fortlaufende Zahl 1..N. Jedes ControlPanel hat seinen eigenen FieldCounter. Der Name des ersten Feldes des ersten ControlPanel der Webseite lautet standardmässig 'ControlPanel1-Field1'.

Der Name eines Feldes bildet zusammen mit dem ControlPanel.Name, und eventuellen weiteren Zusätzen, die HTML-ID- und Name-Attribute von Ein- und Ausgabe-Elementen:

Text-Input-ID    = ControlPanel.Name + '-' + TextField.Name
TextFieldUnit-ID = ControlPanel.Name + '-' + TextField.Name + '-Unit'
HtmlField-ID     = ControlPanel.Name + '-' + HtmlField.Name
Slider-ID        = ControlPanel.Name + '-' + SliderField.Name + '-Slider'
Radiobutton-Name = ControlPanel.Name + '-' + RadiobuttonField.Name
Radiobutton-ID   = ControlPanel.Name + '-' + RadiobuttonField.Name + '-' + i
Checkbox-Name    = ControlPanel.Name + '-' + CheckboxField.Items[i].Name
Checkbox-ID      = ControlPanel.Name + '-' + CheckboxField.Items[i].Name

CpField.Label

CpField.Label: String; ReadOnly; Init = Name 

Label für das ControlPanel-Feld. Ein Label ist die Beschriftung des Feldes. Label dürfen HTML-Tags enthalten.

Wenn ein Label nicht angezeigt werden soll, also auch nicht Name (Standardwert) angezeigt werden soll, so kann Label = '-' gesetzt werden.

Standardmässig werden pro Feld zwei Tabellen-Spalten verwendet. In der ersten Spalte (Label-Spalte) wird das Label angezeigt, in der zweiten (Werte-Spalte) das Input-/Output-Element, der Slider oder HTML-Text. Mit dem Parameter ColSpan kann erreicht werden, dass sich ein Feld über mehrere Tabellen-Spalten spannt. Wenn ein Feld eine gerade Anzahl von Tabellen-Spalten überspannt, so gibt es nur eine Werte-Spalte und das Label wird nicht angezeigt.

Wenn Description definiert ist, wird diese eingeblendet, wenn der Mauszeiger über dem Label steht.

CpField.ValueRef

CpField.ValueRef: CpObjectRef; Private; Init = [ModelRef + '.' +] Name 

Referenz auf eine globale Variable oder ein Objekt-Property. ValueRef wird nur bei Feldern verwendet, welche Werte manipulieren oder anzeigen:

Hinweis: Bei einem CpCheckboxField hat jedes Checkbox-Item einen eigenen CpCheckboxItem.ValueRef.

Der Wert von ValueRef kann nicht direkt ausgelesen werden. Verwende dazu die Funktion GetValueRef(). Beim Erzeugen eines Feldes zum Beispiel mit AddTextField() wird dieses Property als String vorgegeben. Intern wird dieser String in ein CpObjectRef umgewandelt.

Standardwert für ValueRef ist CpField.Name, welches immer einen definierten Wert hat. Wenn ModelRef definiert ist, ist der Standardwert ModelRef + '.' + CpField.Name.

Wenn ModelRef nicht definiert ist, verweist ValueRef entweder auf eine globale Variable oder direkt auf ein Modell-Property. Wenn ModelRef eine globale Variable referenziert, verweist ValueRef auf ein Property des Modells, das dieser Variablen zugewiesen ist. Wenn jedoch ValueRef einen Punkt enthält, wird ModelRef ignoriert:

ModelRef = '';         ValueRef = 'Variable'          → Variable
ModelRef = 'Objekt';   ValueRef = 'Property'          → Objekt.Property
ModelRef = <beliebig>  ValueRef = 'Objekt.Property'   → Objekt.Property

Es sind auch Referenzen auf Objekt-Properties eines Modells möglich. Zum Beispiel:

ModelRef = 'Model.Child'; ValueRef = 'Prop';          → Model.Child.Prop

Hinweis: Sobald ValueRef einen Punkt enthält, wird ModelRef ignoriert!

Das referenzierte Property kann auch eine Funktion sein, welche einen anderen Propery-Wert liest oder setzt. Dies kann dazu verwendet werden, um spezielle Formatierungen zu implementieren. Die dem Property zugewiesene Funktion muss wiefolgt definiert sein:

MyObject.MyProperty = function AccessMyValue( aValueRef, value ) {
  if (xDef(value)) {
    // set a property value
  } else {
    // return a property value
  }
}

Wenn das TextField einen Wert im Modell setzen will, wird diese Funktion mit entsprechendem Wert in value aufgerufen. Wenn der Modell-Wert gelesen werden soll, ist value undefiniert. Aufgrund dieser Eigenschaft kann die Funktion unterscheiden, ob ein Wert gesetzt oder gelesen werden soll.

CpField.ReadOnly

CpField.ReadOnly: Boolean; Private; Init = ControlPanel.ReadOnly or false 

true → Eingabe-Elemente können nicht editiert oder verändert werden, sondern dienen als blosse Anzeigen.

Wenn alle Text-Felder eines ControlPanel nicht editierbar sein sollen (ReadOnly sind), kann dies mit dem Parameter ReadOnly = true des ControlPanel erreicht werden. Bei Schiebereglern, Checkbox- und Radiobutton-Feldern, wird das ReadOnly Property nicht automatisch vom ControlPanel vererbt, sondern es muss explizit bei diesen Feldern gesetzt werden, siehe AddSliderField(), AddValueSliderField(), AddCheckboxField() und AddRadiobuttonField().

Der globale Wert ControlPanel.ReadOnly kann beim Erzeugen jedes Text-Feldes überschrieben werden.

ReadOnly-Felder werden anders dargestellt, als Elemente, die geändert werden können. Diese Darstellung kann teilweise durch Umdefinieren der Klasse ReadOnly geändert werden, z.B. für Text-Felder:

<style>
table.ControlPanel input.ReadOnly { /* styles */ }
</style>

Der Unterschied zwischen ReadOnly und Enabled Feldern ist der, dass ReadOnly statisch ist, während der Enabled Zustand dynamisch per Javascript geändert werden kann. Ein ReadOnly Feld kann auch dann nicht verändert werden, wenn Enabled = true ist.

CpField.Enabled

CpField.Enabled: Boolean; Private; Init = ControlPanel.Enabled 

Gibt an, ob ein Feld aktiviert (enabled) oder deaktiviert ist. Felder können dynamisch aktiviert und deaktiviert werden, nicht zu verwechseln mit statischen ReadOnly Feldern.

Hinweis: Dieses Property kann nicht direkt verändert oder ausgelesen werden. Verwende dazu die Funktionen IsEnabled() und SetEnabled().

Der Zustand Enabled kann auch indirekt automatisch über ein Modell-Property oder eine Funktion gesteuert werden, indem in EnabledRef eine Referenz auf ein entsprechendes Modell-Property oder eine Funktion definiert wird. Die Funktion muss true oder false zurück geben.

Hinweis: Bei einem CpCheckboxField hat jedes Checkbox-Item einen eigenen CpCheckboxItem.Enabled Wert.

Der Unterschied zwischen ReadOnly und Enabled Feldern ist der, dass ReadOnly statisch ist, während der Enabled Zustand dynamisch per Javascript geändert werden kann. Ein ReadOnly Feld kann auch dann nicht verändert werden, wenn Enabled = true ist.

CpField.EnabledRef

CpField.EnabledRef: CpObjectRef or function(); Private; Init = ControlPanel.EnabledRef 

Wird hier ein Property-Name eines Modells angegeben, welches vom Typ Boolean sein muss, so steuert dieses Property den Enabled-Zustand. Dieser Zustand kann auch mit IsEnabled() abgefragt werden. Es kann auch eine Funktion ohne Parameter zugewiesen werden, welche den Enabled-Zustand berechnet und true oder false zurück gibt.

Hinweis: Bei einem CpCheckboxField hat jedes Checkbox-Item einen eigenen CpCheckboxItem.EnabledRef Wert.

CpField.Description

CpField.Description: String; ReadOnly; Init = '' 

Description wird eingeblendet, wenn die Maus über dem Label oder dem HelpImage steht. Die Beschreibung darf keine HTML-Tags enthalten. Description wird in einem HTML-Attribut title platziert, d.h. spezielle HTML-Zeichen müssen in ihrer Namen-Form codiert werden (z.B. < → &lt;, & → &amp; usw.). Die Beschreibung sollte möglichst kurz sein. Weitere Informationen können über das Property Link auf einer separaten Seite verlinkt werden.

CpField.Link: String; ReadOnly; Init = '' 

HTML- oder Wiki-Link zu einer Seite mit mehr Informationen zu einem Feld.

Wenn Link definiert ist, wird das Help-Symbol HelpImage hinter dem Eingabefeld angezeigt. Ein Klick darauf ruft die verlinkte Seite auf.

Wenn Link ein Wiki-Link in der Wabis-Wiki Syntax ist, wird dieser Link automatisch in einen entsprechenden HTML-Link zu der Wiki-Seite umgewandelt.

http://walter.bislins.ch/doku/ControlPanel
./javascript/ControlPanel/demo.html
[[Wiki:Seitenname#Header]]

CpField.ColSpan

CpField.ColSpan: Integer(>0); ReadOnly; Init = 1 

Anzahl Tabellen-Spalten, welche das Werte-Feld überspannen soll.

Jedes ControlPanel-Feld besteht aus zwei Teilen: einem Label-Feld und einem Werte-Feld mit dem Ein-/Ausgabe-Element. Mit ColSpan kann definiert werden, über wie viele Tabellen-Spalten sich das Werte-Feld erstrecken soll.

Ist ColSpan eine gerade Zahl, so wird das Label-Feld nicht angezeigt und das Werte-Feld erstreckt sich über ColSpan Tabellen-Spalten. Ist ColSpan eine ungerade Zahl, wird das Label-Feld angezeigt. Insgesamt erstreckt sich ein ControlPanel-Feld also immer über eine gerade Anzahl von Tabellen-Spalten.

ColSpan ist nützlich, wenn sich bei mehrspaltigem Layout ein Werte-Feld über mehr als eine Layout-Spalte erstrecken soll.

CpField.Attr

CpField.Attr: String; ReadOnly; Init = '' 

Zusätzliche HTML-Attribute für das Werte-Feld. Attr muss im Format von HTML-Tag-Attributen definiert werden. Inline-Styles z.B. werden wiefolgt definiert:

Attr: 'style=\"color: green; font-weight: bold;\"'

Hinweis: Für Label-Felder können keine zusätzlichen Attribute definiert werden.

CpField.GetType()

CpField.GetType( )

Return: String

Gibt den Typ des Feldes zurück. Mögliche Return-Werte sind:

  • 'HtmlField' (Note: ein EmptyField ist ein CpHtmlField)
  • 'TextField'
  • 'SliderField'
  • 'CheckboxField'
  • 'RadiobuttonField'

CpField.GetValueRef()

CpField.GetValueRef( ItemName )

ItemName: String; Optional; Default = ''
muss nur bei Checkbox-Felder angegeben werden
Return: String

Gibt den String-Wert des Properties ValueRef zurück, welches vom Typ CpObjectRef ist.

Da ein CpCheckboxField für jedes CpCheckboxItem eine eigene ValueRef hat, muss bei Checkbox-Felder ItemName angegeben werden. Bei allen anderen Felder wird ItemName ignoriert.

CpField.IsEnabled()

CpField.IsEnabled( ItemName )

ItemName: String; Optional; Default = ''
muss nur bei Checkbox-Felder angegeben werden
Return: Boolean

Gibt den Enabled-Zustand des Feldes zurück.

Da ein CpCheckboxField für jedes CpCheckboxItem einen eigenen Enabled-Zustand hat, mus bei Checkbox-Feldern ItemName angegeben werden. Bei allen anderen Feldern wird ItemName ignoriert.

Der Enabled-Zustand kann auch über ControlPanel.IsEnabled() oder ControlPanels.IsEnabled() erfragt werden.

CpField.SetEnabled()

CpField.SetEnabled( ItemName, Enabled )

ItemName: String; Optional; Default = ''
wird nur bei Checkbox-Felder verwendet
Enabled: Boolean; Optional; Default = true

Setzt den Enabled-Zustand des Feldes.

Da ein CpCheckboxField für jedes CpCheckboxItem einen eigenen Enabled-Zustand hat, mus bei Checkbox-Feldern ItemName angegeben werden. Bei allen anderen Feldern wird ItemName ignoriert. Wenn bei Checkbox-Felder ItemName = '' ist, werden alle Items des Feldes auf Enabled gesetzt.

Über die Referenzen EnabledRef kann erreicht werden, dass sich Panel-Felder automatisch aufgrund von Modell-Properties aktivieren/deaktivieren. Wenn EnabledRef definiert ist, hat SetEnabled() keine Wirkung. Der Enabled-Zustand wird dann allein durch das referenzierte Modell-Property oder eine zugewiesene Funktion gesteuert.

Der Enabled-Zustand kann auch über ControlPanel.SetEnabled() oder ControlPanels.SetEnabled() für einzelne Felder oder mehrere Felder auf einmal gesetzt werden.

CpField.GetHtmlID()

CpField.GetHtmlID( ItemRef )

ItemRef: String | Integer
Name bzw. Index eines Checkbox- bzw. Radiobutton-Items
Return: String

Gibt die HTML-ID des Feldes oder Items zurück. Die HTML-ID wird aus dem ControlPanel.Name und dem Name des Feldes bzw. Items gebildet. Eine Referenz auf das Feld bzw. Item kann per GetDomObj() erfragt werden.

ItemRef hat nur eine Bedeutung, wenn das Feld ein CpCheckboxField oder CpRadiobuttonField ist. Diese beiden Felder haben mehrere Kontroll-Elemente, d.h. mehrere zugehörige Items. Bei CpCheckboxField können diese Item über ihren Namen angesprochen werden, bei CpRadiobuttonField über den Index in die Item-Liste. Bei allen anderen Feldern wird ItemRef ignoriert.

Wird ein Item nicht gefunden, gibt die Funktion einen Leerstring zurück.

Die HTML-ID von ControlPanels kann mit ControlPanel.GetHtmlID() abgefragt werden.

CpField.GetDomObj()

CpField.GetDomObj( ItemRef )

ItemRef: String | Integer
Name bzw. Index eines Checkbox- bzw. Radiobutton-Items
Return: DOM-Input-Element

Gibt eine Referenz auf das DOM-Element des Feldes (DOM-Input-Element) zurück. Die HTML-ID dieses Elementes kann mit GetHtmlID() abgefragt werden.

ItemRef hat nur eine Bedeutung, wenn das Feld ein CpCheckboxField oder CpRadiobuttonField ist. Diese beiden Felder haben mehrere Kontroll-Elemente, d.h. mehrere zugehörige Items. Bei CpCheckboxField können diese Item über ihren Namen angesprochen werden, bei CpRadiobuttonField über den Index in die Item-Liste. Bei allen anderen Feldern wird ItemRef ignoriert.

Wird ein Item nicht gefunden, gibt die Funktion null zurück.

Das DOM-Element von ControlPanels kann mit ControlPanel.GetDomObj() abgefragt werden.

Hinweis: Wenn das DOM-Element noch nicht erzeugt ist, d.h. Render() wurde noch nicht aufgerufen, gibt die Funktion null zurück.

Weitere Infos zur Seite
Erzeugt Montag, 8. August 2016
von wabis
Zum Seitenanfang
Geändert Mittwoch, 16. Januar 2019
von wabis