WaBis

walter.bislins.ch

CP: Anwendungen

Auf dieser Seite wird das Funktionsprinzip des ControlPanel-Moduls anhand eines einfachen Zinseszins-Rechners gezeigt. Weitere Möglichkeiten zeigen die folgenden Seiten:

Funktionsprinzip

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.

Inlcudes

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.

Beispiel Zinseszins-Rechner

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.

JavaScript-Code des Zinseszins-Rechners

<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 );

Das Modell

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

Das Formular wird in drei Schritten erzeugt:

  1. Erzeugen einer Formular-Instanz
  2. Erzeugen des Headers (optional) und der Ein- und Ausgabe-Felder (oder anderer Formular-Elemente)
  3. Generieren des HTML-Codes für das Formular

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 
} );

NCols
Gibt an, wie viele Layout-Spalten mit Eingabefeldern das Formlar haben soll. Die Tabelle selbst hat dann doppelt so viele Spalten, weil Label und Eingabefeld je eine Spalte benötigen.
ModelRef
Über diesen Parameter wird das Formular mit dem Modell verknüpft, welches der globalen Variablen Model zugewiesen ist. Siehe Modell-Referenz.
OnModelChange
Damit wird eine Callback-Funktion installiert, welche gerufen wird, nachdem durch Ändern eines Wertes über ein Eingabefeld das Modell verändert worden ist. In dieser Funktion wird im Allgemeinen die Berechnung weiterer Modell-Properties ausgelöst und danach ein Update der ControlPanel-Felder angestossen, damit diese Änderungen auch angezeigt werden.

Für weitere Parameter siehe NewPanel().

Modell-Referenz

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.

Header erzeugen

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.

Text
Dies ist der Text, der in einer Spaltenüberschrift erscheinen soll. Es sind HTML-Tags in der Überschrift erlaubt.
ColSpan
Gibt an, wie viele Spalten zu einer einzigen Zelle zusammengefasst werden sollen. Achtung: Eine Tabelle mit NCols Spalten von Label-/Eingabefelder-Paaren hat 2 x NCols Spalten.

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().

Ein-/Ausgabefelder erzeugen

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();

Name
Der Name des Eingabefeldes bestimmt die HTML-ID des Feldes, den Label und die Verknüpfung ValueRef zu einem Modell-Property. Der Zugriff auf das Modell-Property geschieht über die Kombination des Tabellen-Parameters ModelRef und/oder des Feld-Parameters Name bzw. ValueRef.
Format und Digits
Definieren das Anzeigeformat dieses Feldes, falls es vom Standardformat der Tabelle abweichen soll.
Units
Für ein Eingabefeld kann eine Einheit (%, m, kg usw.) definiert werden, welche hinter dem Eingabefeld angezeigt wird.
Mult
Wenn das Eingabefeld nicht direkt den Wert eines Modell-Properties anzeigen soll, kann ein Multiplikationsfaktor definiert werden. Eine Zahl im Eingabefeld wird mit diesem Faktor multipliziert, bevor sie im Modell gespeichert wird. Die Zahl im Modell wird durch diesen Faktor dividiert, bevor sie im Eingabefeld angezeigt wird. Beispiel: damit Eingaben in % erfolgen können, wird der Eingabewert mit dem Faktor 0.01 multipliziert, bevor er im Modell gespeichert wird.
ReadOnly=CpTextField.*
Resultate von Modell-Berechnungen werden in Ausgabefeldern, das sind schreibgeschützte Felder, angezeigt. Schreibgeschützte Felder können durch den User nicht direkt verändert werden. Die Werte können jedoch markiert und kopiert werden. Es kann auch ein ganzes ControlPanel schreibgeschützt werden, indem der Parameter ReadOnly des Panels entsprechend gesetzt wird. Einzelne Felder können diesen Wert überschreiben.

Generieren des HTML-Codes

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();

Weitere Infos zur Seite
Erzeugt Sonntag, 7. August 2016
von wabis
Zum Seitenanfang
Geändert Montag, 22. August 2016
von wabis