ControlPanel werden z.B. mit der Funktion ControlPanels.NewPanel() erzeugt. Mit Feld-Funktionen werden die verschiedenen Ein-/Ausgabe-Elemente in den Zellen eines ControlPanel Objektes erzeugt.
Ein ControlPanel-Objekt verwaltet ein mehrspaltiges Tabellen-Layout mit Labeln und Ein-/Ausgabe-Elementen. ö
}
Ein ControlPanel-Objekt wird mit der Funktion ControlPanels.NewPanel() erzeugt. Mit AddHeader() können Überschriften definiert werden und mit diversen Funktionen wie AddTextField(), AddSliderField() usw. können verschiedenen Ein- und Ausgabefelder erzeugt werden. Der zugehörige HTML-Code wird mit der Funktionen Render() in die Webseite eingebaut, nachdem die Tabelle vollständig aufgebaut ist.
Ein ControlPanel-Objekt enthält einige Properties, welche an bestimmte ControlPanel-Felder vererbt werden oder mit Properties von Feldern kombiniert werden.
Die Properties eines ControlPanel Objektes dürfen nur gelesen werden. Ihre Werte werden beim Erzeugen des Objektes mit ControlPanels.NewPanel() festgelegt.
| Name | Teil der HTML-ID der Tabelle und der Tabellen-Felder |
| ModelRef | Name einer globalen Variablen, welcher das Modell zugewiesen ist |
| OnModelChange | wird aufgerufen, nachdem das Modell durch Userinteraktion geändert wurde |
| NCols | Anzahl Layout-Spalten. Eine Layout-Spalte entspricht 2 Tabellen-Spalten |
| Format | Format der Zahlendarstellung. Standardwert für CpTextFields |
| FormatTab | Bestimmt die Zahlengruppierung bei nur 4 Stelligen Zahlen |
| Digits | Anzahl dargestellte Ziffern, abhängig vom Format. Standardwert für CpTextFields |
| Attr | Zusätzliche Attribute für die Tabelle |
| PanelFormat | Zusätzliche Klassen zur Formatierung der ControlPanel-Tabelle bzw. deren Felder |
| PanelClass | Klasse, welche der Tabelle zugewiesen wird (default ControlPanel) |
| ReadOnly | true → Wert im Eingabefeld kann nicht verändert werden. Standardwert für CpTextFields |
| Enabled | false → Felder sind deaktiviert. Enabled wird als Standardwert an die Felder des Panels verwendet. |
| EnabledRef | Referenz auf ein Modell-Property, welches den Enabled-Zustand fernsteuert. Dieser Wert dient als Standardwert für die Felder des Panels |
| HelpImage | Pictogramm, welches hinter einem Feld angezeigt wird, wenn Link definiert ist |
| Fields | Liste der ControlPanel-Felder |
| FieldCounter | Zählt die Felder der Tabelle. Teil von Standard-Feld-Namen |
| ValuePos | Gibt an, ob die Funktion AddValueSliderField() das Werte-Feld links oder rechts des Sliders platzieren soll |
ControlPanel Konstruktoren | |
|---|---|
| NewPanel() | Erzeugt ein ControlPanel |
| NewSliderPanel() | Erzeugt ein spezielles Panel nur für Slider-Felder |
Feld-Funktionen | |
| AddHeader() | Erzeugt eine Überschrift in einem ControlPanel Objekt |
| AddEmptyField() | Erzeugt ein CpHtmlField ohne Text in einem ControlPanel Objekt |
| AddHtmlField() | Erzeugt ein CpHtmlField in einem ControlPanel Objekt |
| AddTextField() | Erzeugt ein CpTextField in einem ControlPanel Objekt |
| AddSliderField() | Erzeugt ein CpSliderField in einem ControlPanel Objekt |
| AddCheckboxField() | Erzeugt ein CpCheckboxField in einem ControlPanel Objekt |
| AddRadiobuttonField() | Erzeugt ein CpRadiobuttonField in einem ControlPanel Objekt |
| GetField() | Sucht ein bestimmtes Feld in der Fields Liste des ControlPanel |
Verwaltungs-Funktionen | |
| Render() | Schreibt den HTML-Code des ControlPanel in die Webseite |
| GetHtml() | Erzeugt den HTML-Code des ControlPanel und gibt ihn als String zurück |
| Init() | Initialsiert das Panel und liest die aktuellen Model-Werte als Standardwerte für die ControlPanel-Felder |
| SetDefaults() | Liest die aktuellen Model-Werte als Standardwerte für die ControlPanel-Felder |
| Update() | Liest die aktuellen Modell-Werte und zeigt sie in den ControlPanel-Feldern an |
| UpdateLayout() | Veranlasst die Neuberechnung der Grössen der ControlPanel-Felder. Diese Funktion wird automatisch gerufen, wenn die Fenstergrösse oder das Layout der Webseite geändert wurde. |
| IsDisplayed() | gibt true zurück, wenn das ControlPanel und alle übergeordneten Dom-Elemente sichtbar sind. |
| Invalidate() | Erzwingt ein Update aller ControlPanel-Felder beim nächsten Aufruf von Update() |
| Reset() | Setzt alle Modell-Properties auf die Standardwerte zurück |
| IsEnabled() | Gibt true zurück, wenn ein bestimmtes Feld aktiviert ist |
| SetEnabled() | Setzt den Zustand Enabled eines oder mehrerer Felder |
| Delete() | Löscht das ControlPanel und gibt den Speicher Frei |
| GetHtmlID() | Gibt die HTML-ID eines ControlPanel zurück |
| GetDomObj() | Gibt eine Referenz auf das DOM-Element (eine HTML-Tabelle) eines ControlPanel zurück |
ControlPanels.NewPanel( Parameter )
Beachte, dass NewPanel() eine Memberfunktion der Klasse ControlPanels ist und nicht der Klasse ControlPanel (ohne s am Ende)!
Erzeugt ein ControlPanel Objekt und initialisiert es entsprechend den Angaben in Parameter.
Alle Funktionen zum Erzeugen von ControlPanel-Feldern geben dieses ControlPanel Objekt zurück. Damit lassen sich die Funktionsaufrufe verknüpfen. Wenn nur ein einziges ControlPanel Objekt pro Seite benötigt wird, muss man das ControlPanel Objekt nicht einmal einer Variablen zuweise. Die Funktion Update() kann für alle ControlPanels einer Seite über ControlPanels.Update() aufgerufen werden.
}
ControlPanels.NewSliderPanel( Parameter )
Beachte, dass NewSliderPanel() eine Memberfunktion der Klasse ControlPanels ist und nicht der Klasse ControlPanel (ohne s am Ende)!
Erzeugt ein ControlPanel über die Funktion NewPanel(). Dieses ControlPanel ist speziell für ein Formular mit Slidern und zugehörigen Werte-Feldern gemacht. Ein entsprechender Slider mit Werte-Feld kann mit der Funktion AddValueSliderField() erzeugt werden.
Wenn NCols in Parameter nicht definiert ist, wird NCols = 1 gesetzt, was einer Tabelle mit 4 Spalten entspricht. Diese sind wiefolgt aufgeteilt:
| ValuePos | Spalte1 | Spalte2 | Spalte3 | Spalte4 |
|---|---|---|---|---|
| 'left' | Label | Wertefeld | Slider | |
| 'right' | Label | Slider | Wertefeld | |
Wenn NCols = 2 gesetzt wird, hat die Tabelle entsprechend 8 Kolonnen.
Dem Property PanelFormat werden die Klassen Slider Left oder Slider Right je nach Wert von ValuePos hinzugefügt. Die Spalten-Zellen der Tabelle erhalten die Klassen Label, Value und Slider. Über Standard-CSS werden die Spaltenbreiten passend formatiert (siehe ControlPanel.inc).
ControlPanel.Name: String; ReadOnly; Init = 'ControlPanel' + ControlPanels.Counter
Counter ist eine fortlaufende Nummer 1..N. Jede ControlPanel-Tabelle bekommt eine HTML-ID. Über die HTML-ID kann die Tabelle per JavaScript oder Stylesheet referenziert werden.
Der ControlPanel.Name wird Bestandteil der id und name Attribute von Feld-Elementen:
Input-ID = ControlPanel.Name + '-' + CpField.Name TextFieldUnit-ID = ControlPanel.Name + '-' + CpField.Name + '-Unit' HtmlField-ID = ControlPanel.Name + '-' + CpField.Name Slider-ID = ControlPanel.Name + '-' + CpField.Name + '-Slider' Radiobutton-Name = ControlPanel.Name + '-' + CpRadiobuttonItem.Name Radiobutton-ID = ControlPanel.Name + '-' + CpRadiobuttonItem.Name + '-' + i Checkbox-Name = ControlPanel.Name + '-' + CpCheckboxItem.Name Checkbox-ID = ControlPanel.Name + '-' + CpCheckboxItem.Name
ControlPanel.ModelRef: String; ReadOnly; Init = ''
Optionaler Name einer globalen Variablen, welcher das Modell zugewiesen ist.
Die Verknüpfung eines Ein-/Ausgabe-Elementes mit einem Objekt-Property kann entweder ganz mit dem Parameter ValueRef eines Feldes erfolgen, oder über die Kombination ModelRef und ValueRef. Wenn alle Felder mit Properties des selben Modells verknüpft werden sollen, bietet es sich an, in ModelRef auf das Modell zu verweisen und in ValueRef jeweils nur das entsprechende Modell-Property anzugeben. Es sind folgende Kombinationen möglich:
ModelRef = ''; ValueRef = 'Variable' → Variable ModelRef = 'Variable'; ValueRef = 'Property' → Objekt.Property ModelRef = ?; ValueRef = 'Variable.Property' → Objekt.Property
Es sind auch Referenzen auf Objekt-Properties eines Modells möglich. Zum Beispiel:
ModelRef = 'Model.Child'; ValueRef = 'Prop' → 'Model.Child.Prop'
Achtung: Sobald ValueRef einen Punkt enthält, wird ModelRef ignoriert!
ControlPanel.OnModelChange: Function(CpField,Value:Any); ReadOnly; Init = null
OnModelChange() wird aufgerufen, nachdem der User über ein Eingabe-Element einen Wert des Modells geändert hat. Eine übliche Implementation einer solchen Funktion ist z.B:
var tabform = ControlPanels.NewPanel( { OnModelChange: Compute, ...} );
:
function Compute( ) {
model.ComputeAllProperties();
tabform.Update();
}
ControlPanel.NCols: Integer(>0); ReadOnly; Init = 1
Anzahl Layout-Spalten. Eine Layout-Spalte entspricht 2 Tabellen-Spalten.
Jedes ControlPanel-Feld besteht aus zwei Teilen: einem Label-Feld und einem Werte-Feld mit dem Ein-/Ausgabe-Element. Mit NCols kann spezifiziert werden, wie viele ControlPanel-Felder nebeneinander angezeigt werden sollen.
Wenn bei mehrspaltigem Layout nicht genügend ControlPanel-Felder definiert werden, um auch die letzte Tabellen-Zeile zu füllen, werden automatisch entsprechend viele leere Felder erzeugt, um die Zeile zu füllen.
Beachte, dass für jedes ControlPanel-Feld zwei Header-Zellen erzeugt werden. Wenn nicht 2 x NCols Header mit der Funktion AddHeader() definiert werden, muss mindestens einer der Header mehrere Tabellen-Spalten überspannen. Dies wird mit dem Parameter ColSpan der Funktion AddHeader() erreicht.
ControlPanel.Format: String; ReadOnly; Init = 'fix'
ControlPanel.FormatTab: Boolean; ReadOnly; Init = true
ControlPanel.Digits: Integer(0..16); ReadOnly; Init = 2
Format und Digits können global für alle Text-Felder eines ControlPanel oder für jedes CpTextField separat gesetzt werden.
Wenn beim CpTextField Format oder Digits nicht definiert sind, werden Format bzw. Digits des ControlPanel übernommen.
Die Formatierung der Zahlen eines Text-Feldes übernimmt der NumFormatter. Einige Grundeinstellungen können direkt am NumFormatter eingestellt werden. Zahlenformat und Genauigkeit können für jedes Text-Feld separat eingestellt werden. Folgende Formate stehen zur Verfügung:
Mit FormatTab kann gesteuert werden, ob bei vierstelligen Zahlen die erste, bzw. bei Nachkommastellen die letzte Zahl durch die Zahlengruppierung alleine stehen darf oder nicht:
| FormatTab = true | FormatTab = false |
|---|---|
| 1234 → 1 234 | 1234 → 1234 |
| 12345 → 12 345 | 12345 → 12 345 |
| 0,1234 → 0,123 4 | 0,1234 → 0,1234 |
| 0,12345 → 0,123 45 | 0,12345 → 0,123 45 |
FormatTab kann pro Tabelle eingestellt werden. Der Entsprechende Parameter des NumFormatters heisst TableLike. Dieser Parameter wird vom ControlPanel nach der Ausgabe wieder auf den alten Wert zurückgesetzt.
ControlPanel.Attr: String; ReadOnly; Init = ''
Zusätzliche Attribute für die ControlPanel-Tabelle. Attr muss im Format von Tag-Attributen definiert werden. Inline-Styles z.B. werden wiefolgt definiert:
Attr: 'style=\"color: green; font-weight: bold;\"'
Styles werden jedoch besser über Stylesheets definiert. Dabei kann auf die ID eines ControlPanels zugegriffen werden. So kann z.B. ein Style für das erste ControlPanel einer Seite mit dem Standardnamen 'ControlPanel1' definiert werden:
<style>
#ControlPanel1 { font-weight: bold; color: #444; }
</style>
ControlPanel.PanelFormat: String; ReadOnly; Init = ''
Zusätzliche Klassen zur Formatierung der ControlPanel-Tabelle. Mit zusätzlichen Klassen, welche einem ControlPanel zugewiesen werden können, kann die Formatierung beeinflusst werden. Es können mehrere Klassennamen mit einem Leerzeichen dazwischen angegeben werden.
Folgende Klassen sind in ControlPanelStyles.css vordefiniert:
Um z.B. alle Label linksbündig statt rechtsbündig anzuzeigen und kürzere Eingabefelder zu erzeugen, gibt man die Klasen LabelLeft und InputShortWidth an:
ControlPanels.NewPanel( {
PanelFormat: 'LabelLeft InputShortWidth', ...
} );
Es können natürlich beliebige weitere Klassen selbst in einem Stylesheet definiert und verwendet werden. Tabellen und Felder können darin über ihre Klassen und Id's referenziert werden.
ControlPanel.PanelClass: String; ReadOnly; Init = 'ControlPanel'
Diese Klasse wird der Panel-Tabellen zugewiesen. Über diese Klasse können die Tabellen individuell per CSS gestyled werden.
ControlPanel.ReadOnly: Boolean; ReadOnly; Init = false
Standardwert des Properties ReadOnly für CpTextField.
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>
ControlPanel.Enabled: Boolean; Private; Init = true
Standardwert die Properties Enabled der ControlPanel-Felder.
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 verändert oder ausgelesen werden. Für das Auslesen und Verändern des enstprechenden Feld-Properties verwende die Funktionen IsEnabled() und SetEnabled().
Der Zustand Enabled kann auch indirekt automatisch über ein Modell-Property gesteuert werden, indem in EnabledRef eine Referenz auf ein entsprechendes Modell-Property definiert wird.
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.
ControlPanel.EnabledRef: CpObjectRef; Private; Init = ''
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.
Der EnabledRef Wert des Panels kann nicht abgefragt oder geändert werden. Er wird lediglich als Standardwert für die Felder des Panels verwendet. Zum Abfragen und Ändern des Enabled Zustandes eines Feldes verwende die Funktionen IsEnabled() und SetEnabled(), welche sowohl auf Ebene alles ControlPanels, als auch auf Ebene ControlPanel und auf Ebene CpField existieren.
ControlPanel.HelpImage: String; ReadOnly; Init = 'q.gif'
Pictogramm, welches hinter einem Feld angezeigt wird, wenn der Parameter Link definiert ist.
Wenn für ein ControlPanel-Feld der Parameter Link definiert ist, wird standardmässig ein Pictogramm hinter dem Feld angezeigt. Ein Klick darauf bringt die verlinkte Seite zur Anzeige. Wenn HelpImage = '' gesetzt wird, wird kein Pictogramm angezeigt. Es kann auch der Filename eines beliebigen anderen Pictogrammes definiert werden.
Das Pictogramm wird relativ zum Verzeichnis von ControlPanelX.js gesucht. Dieses Verzeichnis kann über die folgende Variable abgefragt werden:
ControlPanel.prototype.ScriptPath
ControlPanels.NewPanel( {
:
HelpImage = ControlPanel.prototype.ScriptPath + 'myHelpPic.gif'
} );
ControlPanel.Fields: Array of CpField; ReadOnly; Init = [ ]
Alle ControlPanel-Felder werden in der Liste Fields des ControlPanel gespeichert.
ControlPanel.FieldCounter: Integer(>=0); ReadOnly; Init = 0
FieldCounter ist ein interner Zähler. Er wird bei jedem erzeugten ControlPanel-Feld um 1 erhöht und dient der automatischen Namensgebung der Felder → CpField.Name.
ControlPanel.ValuePos: String('left', 'right'); ReadOnly; Init = 'left'
ValuePos hat nur eine Bedeutung, wenn das ControlPanel Objekt mit der Funktion NewSliderPanel() erzeugt wird. Es bestimmt die Position des Werte-Feldes neben einem Slider, welcher mit der Funktion AddValueSliderField() erzeugt wird.
ControlPanel.AddHeader( Parameter )
}
Fügt ein Titel-Feld in das ControlPanel ein.
Panels werden als Table-Elemente auf der Webseite implementiert. Jedes ControlPanel-Feld benötigt mindestens 2 Tabellen-Spalten: eine für Labels und eine für Werte-Felder. Wenn z.B. ein ControlPanel mit NCols = 2 definiert wird, hat die zugrundeliegende Tabelle 4 Spalten. Es müssen dann entweder 4 Header-Zellen durch 4-maliges Aufrufen von AddHeader definiert werden, oder eine oder mehrere Header-Zellen müssen durch Angabe von ColSpan mehrere Spalten überspannen.
Header müssen am Anfang einer Tabelle erzeugt werden! Alle erzeugten Header werden in der ersten Zeile der Tabelle angezeigt. Jedes Panel kann nur eine Titelzeile haben!
Diese Funktion gibt das ControlPanel Objekt als Returnwert zurück. Dadurch lassen sich ControlPanel Funktionen verketten.
Attr muss im Format von Tag-Attributen definiert werden. Inline-Styles z.B. werden wiefolgt definiert:
Attr: 'style=\"color: green; font-style: italic;\"'
ControlPanels.NewPanel( {
NCols: 2,
:
} ).AddHeader( {
Text: 'Titel 1',
ColSpan: 2
} ).AddHeader( {
Text: 'Titel 2',
ColSpan: 2
} )....
ControlPanel.GetField( FieldName )
Sucht im Panel ein Feld mit dem Name FieldName und gibt eine Referenz darauf zurück. Bei Checkbox-Feldern wird FieldName auch mit den Namen der CpCheckboxItems verglichen. Passt ein solcher Name, wird die Referenz auf das CpCheckboxField zurückgegeben.
Wird FieldName in diesem Panel nicht gefunden, wird null zurückgegeben.
Liegt noch kein ControlPanel vor, kann ein Feld über die Funktion ControlPanels.GetField() gesucht werden.
Jedes Feld hat zum Teil unterschiedliche Properties. Um auf diese zugreifen zu können, muss der Feld-Typ bekannt sein. Dieser kann mit der Funktion GetType() abgefragt werden.
ControlPanel.Render( )
Erzeugt den HTML-Code für das fertig definierte ControlPanel und fügt diesen an der Stelle des Aufrufes von Render() in die Webseite ein. Weitere Manipulationen am ControlPanel Objekt haben keine Auswirkungen mehr.
Die Verbindung zwischen ControlPanel und Dom-Elementen wird in der automatisch aufgerufenen Funktion Init() hergestellt. Die Funktion Init() wird nach dem vollständigen Laden der Webseite gerufen.
Dadurch, dass Render() das ControlPanel-Objekt this zurückgibt, können alle Feld-erzeugenden Funktionen aneinandergereiht werden:
var myPanel = ControlPanels.NewPanel( {
:
} ).AddTextField( {
:
} ).Render();
Dank dem Returnwert von Render() wird am Ende das ControlPanel der Variablen myPanel zugewiesen.
ControlPanel.GetHtml( )
Erzeugt den HTML-Code für das fertig definierte ControlPanel und gibt diesen in String-Form zurück. Diese Funktion wird intern von Render() gerufen.
Der mit GetHtml() erzeugte String kann zum Beisiel mit der Funktion xInnerHtml() in ein Div-Element geschrieben werden. Danach müssen allerding die Links zwischen Panel- und Dom-Elementen explizit über Init() (für ein Panel) oder ControlPanels.ConnectDom() (für mehrere Panels) hergestellt werden.
ControlPanel.Init( GetDefault )
Init veranlasst, dass die aktuellen Modell-Werte ausgelesen werden und bei den ControlPanel-Feldern als Startwert gespeichert werden (nur beim ersten Aufruf oder wenn GetDefault true ist). Mit Reset() kann das Modell auf diese Startwerte zurückgesetzt werden. Init() ruft zudem die Funktion Update(), um die Anzeige der Felder zu initialisieren, sodass sie die Startwerte anzeigen. Init() verbinden schliesslich das Panel mit den zugehörigen Dom-Elementen der Webseite.
Init() wird automatisch nach dem vollständigen Laden der Webseite ausgeführt und muss daher in den meisten Fällen nicht explizit aufgerufen werden. Das automatische Aufrufen von Init() kann aber wenn nötig bei der Funktion NewPanel() mit dem Argument AutoInit: false unterdrückt werden.
Die Startwerte werden nur beim ersten Aufruf von Init() oder wenn GetDefault true ist eingelesen.
Für mehrere Panels gemeinsam kann Init mit der Funktion ControlPanels.Init() ausgeführt werden. Vergleiche auch mit der Funktion ControlPanels.ConnectDom(), welche ihrerseits Init() aufruft.
ControlPanel.SetDefaults( Panels, updateGui )
SetDefaults liesst alle aktuellen Modell-Werte als Defaultwerte der entsprechenden Felder ein. Wenn der Cursor in ein Feld gesetzt wird und Esc gedrückt wird, wird der Defaultwert in das entsprechende Feld gesetzt.
Wenn updateGui = true ist, wird danach noch die Funktion ControlPanel.Update() gerufen um die Defaultwerte jetzt in die Felder zu schreiben.
ControlPanel.Update( )
Update liest für jedes ControlPanel-Feld den zugehörigen Modell-Wert aus und zeigt ihn an. Update muss gerufen werden, nachdem externe Funktionen die Modell-Werte geändert haben, um die aktuellen Werte in den Panels anzuzeigen.
Update ist so optimiert, dass nur Felder nachgeführt werden, deren Modell-Wert nicht mehr mit der Anzeige übereinstimmen.
Für mehrere Panels gemeinsam kann Update mit der Funktion ControlPanels.Update() ausgeführt werden.
var model = new MyModel();
var myPanel = ControlPanels.NewPanel( { OnModelChange: Compute, ... } );
:
function Compute() {
// Modell-Werte werden geändert
model.Update();
// Anzeigen des ControlPanels myPanel werden nachgeführt
myPanel.Update();
}
oder Variante ohne Variable myPanel:
var model = new MyModel();
ControlPanels.NewPanel( {
Name: 'myPanelName',
OnModelChange: Compute,
:
} )...
function Compute() {
// Modell-Werte werden geändert
model.Update();
// Anzeigen des ControlPanels myPanelName werden nachgeführt
ControlPanels.Update( 'myPanelName' );
}
oder ohne Panel-Name:
var model = new MyModel();
ControlPanels.NewPanel( {
OnModelChange: Compute,
:
} )...
function Compute() {
// Modell-Werte werden geändert
model.Update();
// Anzeigen aller ControlPanels werden nachgeführt
ControlPanels.Update();
}
Wenn sich zwar nicht der Wert eines Modell-Properties ändert, aber dessen Darstellungsformat, so funktioniert Update() wegen der Optimierung nicht richtig. Um zu erzwingen, dass der gleiche Wert im neuen Format dargestellt wird, muss vor Update() die Funktion Invalidate() gerufen werden. Für eine Anwendung siehe Demo-Code.
ControlPanel.UpdateLayout( VisiState )
Diese Funktion kann gerufen werden, wenn ein ControlPanel unsichtbar/sichtbar gemacht wurde, um die Geometrie der Elemente neu berechnen zu lassen.
Hinweis: Bei Verwendung Moduls Tabs zum Ein-/Ausblenden von Panels mittels Tabulator-Zeilen werden automatisch UpdateLayout-Funktionen im Modul Tabs installiert. Diese Funktion muss nicht explizit gerufen werden!
Für mehrere Panels gemeinsam kann UpdateLayout mit der Funktion ControlPanels.UpdateLayout() ausgeführt werden.
ControlPanel.IsDisplayed( )
Gibt true zurück, wenn das ControlPanel und alle übergeordneten Dom-Elemente sichtbar sind.
Hinweis: Dom-Elemente werden mit dem Style display: none unsichtbar gemacht. Diese Funktion funktioniert auch, wenn dieser Style nicht direkt im Dom-Element, sondern per CSS gesetzt wird.
ControlPanel.Invalidate( )
Invalidate erzwingt ein Neuzeichnen aller ControlPanel-Felder beim nächsten Aufruf von Update(), auch wenn sich der dargestellte Wert nicht geändert hat.
Anwendung: Wenn FormatRef, DigitsRef oder UnitsRef definiert sind und sich die so referenzierten Modell-Werte (Format, Digits, Units) ändern, werden die Anzeigen durch den Aufruf von Update() wegen der Optimierung nicht automatisch nachgeführt, da sich nur die Formatierung, nicht aber der Modell-Wert geändert hat. Um einen Update zu erzwingen kann vor dem Update() die Funktion Invalidate gerufen werden.
Eine Anwendung der Funktion Invalidate() findest du auf der Seite CP-Anwendung: UnitRef, MultRef.
Für mehrere Panels gemeinsam kann Invalidate mit der Funktion ControlPanels.Invalidate() ausgeführt werden.
ControlPanel.Reset( CallModelChangeCB, Update )
Reset setzt alle Modell-Werte auf ihre Startwerte zurück. Die Startwerte werden in der Funktion Init() vom Modell abgefragt und bei den Feldern gespeichert. Init() wird automatisch nach dem Laden der Seite gerufen.
Falls man dem User eine Funktion zum Zurücksetzen des Formulares zur Verfügung stellen will, erzeugt man auf der Webseite am besten einen Button (z.B. mit der Funktion ControlPanels.ResetButton()), welcher als Aktion Reset ruft:
function MyModel() {
// model properties are defined here
this.Update();
}
MyModel.prototype.Update = function() {
// compute some stuff that changes some properties
}
var model = new MyModel();
ControlPanels.NewPanel( {
OnModelChange: UpdateAll,
:
} ).AddHeader( {
Text: 'Titel' + ControlPanels.ResetButtonR(),
:
} ).Render()
function Reset() {
ControlPanels.Reset();
UpdateAll();
}
function UpdateAll() {
model.Update();
ControlPanels.Update();
}
Beachte, dass durch den Aufruf von ControlPanels.Reset() die Funktion UpdateAll() standardmässig nicht automatisch aufgerufen wird, nachdem alle Modellwerte zurückgesetzt wurden. So können Reset() Aufrufe für mehrere Panels zusammengefasst werden, ohne dass nach jedem Aufruf UpdateAll() ausgeführt wird. Wenn jedoch nur ein ControlPanel existiert, kann der Parameter CallModelChangeCB bei ControlPanels.Reset() true gesetzt werden und UpdateAll() muss dann dort nicht aufgerufen werden.
Beim Anklicken des Reset Buttons passiert im obigen Beispiel folgendes:
Für mehrere Panels gemeinsam kann Reset mit der Funktion ControlPanels.Reset() ausgeführt werden.
ControlPanel.IsEnabled( FieldName )
Überprüft, ob ein Feld bedienbar ist oder nicht. Dies kann beim Ereugen des Feldes mit dem Parameter Enabled oder später mit der Funktion SetEnabled() gesteuert werden. Auch eine indirekte Steuerung über ein Modell-Property kann mit dem Parameter EnabledRef einiger Felder veranlasst werden.
Hinweis: Da CpCheckboxField Objekte mehrere unabhängige Kontrol-Elemente (Checkbox-Items) haben, gibt FieldName den Namen eines dieser Items an, nicht den Namen des Checkbox-Feldes selbst.
Liegt kein ControlPanel vor, kann der Enabled-Zustand auch mit ControlPanels.IsEnabled() abgefragt werden.
ControlPanel.SetEnabled( FieldName, Enabled )
Aktiviert/Deaktiviert ein ControlPanel-Feld. Deaktivierte Felder werden grau angezeigt und nehmen keinen Eingaben entgegen. Sie zeigen jedoch die aktuellen Modellwerte weiterhin an.
Der aktuelle Zustand wird im Property Enabled festgehalten, welches über IsEnabled() abgefragt werden kann. Der Zustand Enabled kann auch automatisch über eine EnabledRef auf ein Modell-Property gesteuert werden. Wenn EnabledRef definiert ist, hat SetEnabled() keine Wirkung. Der Enabled-Zustand wird dann allein durch das referenzierte Modell-Property gesteuert.
Wenn FieldName nicht definiert oder '' ist, werden alle Felder des ControlPanel auf Enabled gesetzt. Wenn Enabled nicht definiert ist, wird true angenommen.
Hinweis: Da CpCheckboxField Objekte mehrere unabhängige Kontrol-Elemente (Checkbox-Items) haben, gibt FieldName den Namen eines dieser Items an, nicht den Namen des Checkbox-Feldes selbst.
Liegt kein ControlPanel vor, kann der Enabled-Zustand mit der Funktion ControlPanels.SetEnabled() falls erwünscht gleich für mehrere Panels gemeinsam gesetzt werden.
ControlPanel.Delete( DeleteDom )
Delete() löst die Verbindungen zwischen dem Panel und seinen ControlPanel-Feldern und entfernt den Eintrag in der ControlPanels.PanelList für dieses Panel.
Wenn DeleteDom true gesetzt wird, Default ist false, werden auch die Dom-Elemente des Panels gelöscht.
Mehrere Panels gemeinsam kann man über die Funktion ControlPanels.DeletePanels() löschen.
ControlPanel.GetHtmlID( )
Gibt die HTML-ID des Panels zurück. Die HTML-ID ist die ID des Tabellen-Elementes, welches ein Panel darstellt. Die HTML-ID wird aus dem Name des Panels gebildet. Eine Referenz auf das Tabellen-Element kann per GetDomObj() erfragt werden.
Die HTML-ID von Feldern kann mit CpField.GetHtmlID() abgefragt werden.
ControlPanel.GetDomObj( )
Gibt eine Referenz auf das DOM-Element (Tabelle) zurück, welches das Panel enthält. Die HTML-ID dieses Elementes kann mit GetHtmlID() abgefragt werden.
Referenzen auf die DOM-Feldelemente können mit CpField.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.