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 Properties

Hinweis: Diese Properties werden an die abgeleiteten Klassen vererbt.

CpField Funktionen

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:

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:

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!

Es können auch Array Elemente referenziert werden. Dabei muss allerdings beachtet werden, dass das Modell nie den referenzierten Array ersetzt, sondern nur die Array Elemente ändert. Dies kann leicht vergessen werden, wenn ein Modell Property z.B. ein Vektor ist, der über Vektor Funktionen berechnet wird.

ValueRef = 'Property[0]'

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

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.

Beispiele für Links

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.