Auf dieser Seite wird das Funktionsprinzip des ControlPanel-Moduls anhand eines einfachen Zinseszins-Rechners gezeigt. Weitere Möglichkeiten zeigen die folgenden Seiten:
Die Formularfelder eines ControlPanel Objektes werden mit Properties eines Modell-Objektes verknüpft. Wenn der Anwender einen Wert in eines der Eingabefelder eingibt, verändert das ControlPanel den Wert des zugehörigen Properties automatisch. Unmittelbar danach ruft das ControlPanel eine Callback-Funktion OnModelChange auf. In dieser muss der Programmierer allenfalls die Eingabewerte auf Gültigkeit überprüfen lassen und gegebenenfalls korrigieren und danach Berechnungen im Modell anstossen, welche im Allgemeinen weitere Properties des Modells verändern. Damit diese Änderungen wiederum im Formular angezeigt werden, muss in der Callback-Funktion Update() des ControlPanel aufgerufen werden. Damit liest das ControlPanel alle aktuellen Werte der Formularfelder aus dem Modell aus und zeigt diese an.
Die Anzeigeelemente eines ControlPanel Formulares können auf vielfältige Weise über Parameter-Listen bei deren Erzeugung konfiguriert werden. Nach dem Erzeugen des Formulares und der Formularfelder wird der HTML-Code des Formulares durch Aufruf von Render() erzeugt und an dieser Stelle in die HTML-Seite eingebaut.
Die folgenden Includes werden für das Verwenden von ControlPanel Formularen benötigt:
<link rel="stylesheet" type="text/css" href="ControlPanelStyles.css" media="all"> <script src="ControlPanelX.js" type="text/javascript"></script>
Es handelt sich um Style-Sheets ControlPanelStyles.css und den Code für das ControlPanel selbst.
An einem einfachen Zinseszins-Rechner erkläre ich die Funktionsweise und Anwendung eines ControlPanel Formulares. Das Beispiel sieht folgendermassen aus:
Setze den Cursor in eines der Eingabefelder und ändere dessen Wert. Um die Eingabe abzuschliessen drücke Enter. Es wird sofort das Resultat berechnet und angezeigt. Die Eingabefelder merken sich intern den ersten Wert des Modells. Durch drücken der Esc Taste, wenn der Cursor in einem Feld steht, wird dieses auf den Startwert zurückgesetzt.
Hinweis: In diesem Beispiel findet keinerlei Überprüfung der Eingabe statt. Felder, in denen Text eingegeben werden kann, müssen überprüft werden, bevor der Text als HTML-Code irgendwo auf der Seite ausgegeben wird. Sonst besteht die Gefahr von Cross Site Scripting (eine Hacker-Methode, Websites zu missbrauchen). Solange der Text nur in Eingabefeldern wieder ausgegeben wird, kann nichts passieren.
<jscript>
function Rechner() {
this.Startkapital = 10000;
this.Zins = 0.0525;
this.Zeitraum = 10;
this.Endkapital = 0;
}
Rechner.prototype.BerechneEndkapital = function() {
this.Endkapital = this.Startkapital * Math.pow( 1 + this.Zins, this.Zeitraum );
}
var Model = new Rechner();
function Berechnung() {
Model.BerechneEndkapital();
ControlPanels.Update();
}
ControlPanels.NewPanel( {
NCols: 2,
ModelRef: 'Model',
OnModelChange: Berechnung
} ).AddHeader( {
Text: 'Zinseszins-Rechner',
ColSpan: 4
} ).AddTextField( {
Name: 'Startkapital',
Units: 'CHF'
} ).AddTextField( {
Name: 'Zins',
Format: 'std',
Digits: 8,
Units: '%',
Mult: 0.01
} ).AddTextField( {
Name: 'Zeitraum',
Format: 'std',
Digits: 8,
Units: 'Jahre'
} ).AddTextField( {
Name: 'Endkapital',
ReadOnly: true,
Units: 'CHF'
} ).Render();
xOnLoad( Berechnung );
Ein ControlPanel ist mit einem JavaScript-Objekt verknüpft. Dieses bezeichne ich als Modell. Im obigen Beispiel ist das Modell ein Zinseszins-Rechner. Der Code des Modells ist:
function Rechner() {
this.Startkapital = 10000;
this.Zins = 0.0525;
this.Zeitraum = 10;
this.Endkapital = 0;
}
Rechner.prototype.BerechneEndkapital = function() {
this.Endkapital = this.Startkapital * Math.pow( 1 + this.Zins, this.Zeitraum );
}
var Model = new Rechner();
Das Modell Rechner hat vier Properties. Die ersten drei sind die Eingabevariablen, das Property Endkapital speichert die Lösung der Berechnung der Funktion BerechneEndkapital.
In der letzten Zeile wird ein Objekt der Klasse Rechner erzeugt und der Variablen Modell zugewiesen.
Wir brauchen noch eine Funktion, die das Berechnen des Endkapitals anstösst, sobald ein Wert in einem der Textfelder des Formulars geändert wird:
function Berechnung() {
Model.BerechneEndkapital();
ControlPanels.Update();
}
Die Funktion Berechnung wird im Formular als Callback-Funktion installiert. Sie löst die Neuberechnung des Endkapitals aus. Da solche Berechnungen die Werte von Properties des Modells verändern, muss das Formular diese Werte danach auslesen und Anzeigen. Dies geschieht durch Aufruf der Funktion Update():
Damit das Modell initialisiert wird, muss nach dem Laden der Seite zum ersten mal die Funktion Berechnung aufgerufen werden. Dies wird erreicht, indem diese Funktion mit dem Event OnLoad der Seite verknüpft wird:
xOnLoad( Berechnung );
Alternativ kann auch die Funktion Berechnung einfach am Ende der Seite aufgerufen werden.
Das Formular wird in drei Schritten erzeugt:
Ein ControlPanel-Objekt, also ein Formular, wird mit der Funktion NewPanel() erzeugt. Dieses Objekt wird im Beispiel der Variablen Formular zugewiesen.
ControlPanels.NewPanel( {
NCols: 2,
ModelRef: 'Model',
OnModelChange: Berechnung
} );
Für weitere Parameter siehe NewPanel().
Die Ein- und Ausgabefelder müssen mit dem Modell verknüpft werden, dessen Werte sie anzeigen und verändern sollen. Eine solche Referenz kann über die Properties ModelRef des ControlPanel und ValueRef (bzw. Name, falls ValueRef nicht definiert wird) der ControlPanel-Felder hergestellt werden:
ControlPanels.NewPanel( {
NCols: 2,
ModelRef: 'Model',
OnModelChange: Berechnung
} ).AddTextField( {
Name: 'Startkapital', Units: 'CHF'
} ).AddTextField( {
Name: 'Zins', Format: 'std', Digits: 8, Units: '%', Mult: 0.01
} ).AddTextField( {
Name: 'Zeitraum', Format: 'std', Digits: 8, Units: 'Jahre'
} ).AddTextField( {
Name: 'Endkapital', ReadOnly: true, Units: 'CHF'
} ).Render();
Beachte, dass bei den Funktionen AddTextField() der Wert für ValueRef von Name übernommen wird, weil ValueRef nicht in der Parameterliste vorkommt. Wenn Label und ValueRef gleich sein sollen, kann man diese beiden Parameter weglassen und stattdessen die Referenz und den Label mit Name definieren.
Zunächst werden die Überschriften (Header) des Tabellen-Formulares erzeugt. Dazu dient die Funktion AddHeader():
} ).AddHeader( {
Text: 'Zinseszins-Rechner',
ColSpan: 4
} )...
Die Funktion AddHeader() muss in der Regel für jede Spalte aufgerufen werden. In unserem Beispiel hat die Tabelle 4 Spalten. Man kann jedoch auch beliebig viele Spalten zusammenfassen. Im Beispiel soll die Überschrift über alle 4 Spalten ausgedehnt werden.
Header müssen nicht nur am Anfang einer Tabelle erzeugt werden. Sie können auch mittendrin und/oder für einzelne Spalten definiert werden.
Für weitere Parameter siehe AddHeader().
Die Text-Eingabefelder werden mit der Funktion AddTextField() erzeugt. Standardmässig erzeugt jeder Aufruf zwei Tabellen-Spalten: Eine Spalte für die Label und eine Spalte für das Eingabefeld:
} ).AddTextField( {
Name: 'Startkapital',
Units: 'CHF'
} ).AddTextField( {
Name: 'Zins',
Format: 'std',
Digits: 8,
Units: '%',
Mult: 0.01
} ).AddTextField( {
Name: 'Zeitraum',
Format: 'std',
Digits: 8,
Units: 'Jahre'
} ).AddTextField( {
Name: 'Endkapital',
ReadOnly: true,
Units: 'CHF'
} ).Render();
Sobald die ganze Tabelle erzeugt worden ist, kann sie mit dem Aufruf der Funktion Render() in die Webseite eingebaut werden. Die Tabelle wird an der Stelle auf der Webseite angezeigt, an der die Funktione Render() aufgerufen wird.
} ).Render();