Das globale Objekt und Klasse ControlPanels führt eine Liste aller ControlPanel Objekte auf einer Webseite. Es stellt Funktionen zum Erzeugen und Verwalten der ControlPanel zur Verfügung.
Das ControlPanel-Modul legt eine globale Variable ControlPanels von der Klasse ControlPanels an. In diesem Objekt wird im Property PanelList ein Array mit allen erzeugten ControlPanel Objekten gespeichert. Über ControlPanels Funktionen lassen sich neue ControlPanel Objekte erzeugen suchen und gruppenweise ansprechen.
}
Die ControlPanel in der PanelList können über ihren Namen mit der Funktion Get() gesucht werden. Mit Hilfe der Funktion ForEachPanel() können Anwenderfunktionen auf alle oder eine Auswahl von ControlPanel der Liste ausgeführt werden. Die Meisten ControlPanels Funktionen verwenden diese Funktion ebenfalls.
Achtung: Es gibt die zwei unterschiedlichen Klassen:
| Counter | Zählt die Anzahl ControlPanel Objekte einer Seite. Wird an Default-Namen der ControlPanel Objekt angehängt, siehe HTML-IDs. |
| PanelList | Array mit allen ControlPanel Objekten der Webseite |
| AddBeforeInitHandler() | Installiert eine Funktion, welche vor der automatischen Initialisierung der Controlpanel gerufen wird. |
| NewPanel() | Erzeugt ein ControlPanel Objekt |
| NewSliderPanel() | Erzeugt ControlPanel speziell für CpSliderField |
| Button() | Erzeugt den HTML-Code für einen universellen Button |
| SimpleButton() | Erzeugt den HTML-Code für einen universellen Button |
| ResetButton() | Erzeugt den HTML-Code für einen Reset-Button |
| ResetButtonR() | Erzeugt den HTML-Code für einen Reset-Button und platziert ihn rechts |
| SmallButton() | Erzeugt den HTML-Code für einen kleinen-Button z.B. für Titelzeilen |
| SmallButtonR() | Erzeugt den HTML-Code für einen kleinen-Button z.B. für Titelzeilen rechtsbündig |
| Update() | Ruft die Update() Funktion aller oder einer Auswahl von ControlPanels auf. |
| UpdateLayout() | Ruft die UpdateLayout() Funktion aller oder einer Auswahl von ControlPanels auf. |
| Invalidate() | Ruft die Invalidate() Funktion aller oder einer Auswahl von ControlPanels auf. |
| Reset() | Ruft die Reset() Funktion aller oder einer Auswahl von ControlPanels auf. |
| ConnectDom() | Ruft die Init() Funktion aller oder einer Auswahl von ControlPanels auf, um die ControlPanels erneut mit ihren DOM-Elementen der Webseite zu verlinken. |
| Init() | Ruft die Init() Funktion aller oder einer Auswahl von ControlPanels auf. |
| SetDefaults() | Ruft die SetDefaults() Funktion aller oder einer Auswahl von ControlPanels auf. |
| IsDisplayed() | Ruft die IsDisplayed() Funktion eines bestimmten ControlPanels auf. |
| IsEnabled() | Ruft die IsEnabled() Funktion eines bestimmten ControlPanel-Feldes auf. |
| SetEnabled() | Ruft die SetEnabled() Funktion aller oder einer Auswahl von ControlPanels auf. |
| DeletePanels() | Ruft die Delete() Funktion aller oder einer Auswahl von ControlPanels auf. |
| Get() | Sucht das ControlPanel über seinen Namen in der PanelList des globalen ControlPanels Objektes. |
| GetField() | Sucht ein ControlPanel über seinen Namen in der PanelList des globalen ControlPanels Objektes und sucht darin ein bestimmtes ControlPanel-Feld. |
| GetIx() | Sucht ein ControlPanel über seinen Namen in der PanelList des globalen ControlPanels Objektes und gibt seinen Index in die Liste zurück. |
| ForEachPanel() | Führt eine Funktion auf alle oder eine Auswahl von ControlPanel aus. |
Über die Funktion Update() können die Update-Funktionen aller ControlPanel einer Seite gerufen werden, auch wenn die individuellen ControlPanels keiner Variablen zugewiesen sind.
ControlPanels.NewPanel( {
ModelRef: Model,
OnModelChange: UpdateAll
}
).AddTextField( {
Name: 'ModelField1',
}
).AddTextField( {
Name: 'ModelField2',
}
).Render();
function UpdateAll() {
Model.Update();
ControlPanels.Update();
ModelGraph.Redraw();
}
ControlPanels.Counter: Integer(>=0); ReadOnly; Init = 0
Counter ist ein Zähler, der mit jedem Aufruf von NewPanel() oder NewSliderPanel() um 1 erhöht wird. Startwert ist 0. Counter wird zum Definieren von ControlPanel.Name verwendet, wenn dieser bei NewPanel() bzw. NewSliderPanel() nicht definiert wird:
ControlPanel.Name = 'ControlPanel' + ControlPanels.Counter;
Das erste ControlPanel erhält die Nummer 1. Der Counter wird auch erhöht, wenn dem ControlPanel explizit ein Name zugewiesen wird. Der Counter reflektiert die bis anhin erzeugten ControlPanel Objekte. Der Counter wird beim Löschen eines ControlPanel Objektes nicht verändert.
ControlPanels.PanelList: Array of ControlPanel; ReadOnly; Init = [ ]
Jedes neu erzeugte ControlPanel Objekt wird in dieses Array aufgenommen. Mit Delete() oder DeletePanels() gelöschte Objekte werden aus dieser Liste entfernt.
Mit Hilfe dieser Liste können individuelle Objekte oder ganze Gruppen von ControlPanel Objekten über entsprechende ControlPanels Funktionen manipuliert werden.
ControlPanels.Button( Params )
}
ControlPanel.Button gibt den HTML-String eines Buttons zurück. Dieser String kann in einem CpHtmlField oder in einem Panel-Header verwendet werden.
var model = new MyModel();
ControlPanels.NewPanel( {
:
} ).AddHtmlField( {
Html:
ControlPanels.Button( {
Text: 'Preset 1',
Code: 'Preset1()'
},
:
} )...
function Preset1() {
myModel.SetPreset1();
ControlPanels.Update();
}
Hinweis: Für das schnelle Erzeugen von einfachen und kleinen Buttons oder von Reset-Buttons gibt es spezielle Funktionen:
ControlPanels.ResetButton( )
ControlPanels.ResetButtonR( )
Erzeugt den HTML-Code (String) für einen Reset-Button, der mit Reset beschriftet ist und die globale Funktion Reset() aufruft, wenn er angeklickt wird. Die Variante ohne R erzeugt den Button linksbündig, die Variante R rechtsbündig.
:
} ).AddHeader( {
Text: 'Überschrift' + ControlPanels.ResetButtonR(),
:
} )...
ControlPanels.SmallButton( Text, Code, Color )
ControlPanels.SmallButtonR( Text, Code, Color )
Erzeugt den HTML-Code (String) für einen kleinen Button, der zum Beispiel in einer Titelzeile links oder rechtsbündig (Variante mit R) angezeigt werden kann.
:
} ).AddHeader( {
Text: 'Überschrift' + ControlPanels.SmallButtonR('Text','Function()','Blue'),
:
} )...
ControlPanels.SimpleButton( Text, Code, Color, Size, Right, Margin )
Beschreibung siehe ControlPanels.Button().
ControlPanels.Update( Panels )
Ruft die Funktion ControlPanel.Update() für die bei Panels angegeben ControlPanel Objekte auf.
Die betroffenen Panels können als ControlPanel oder über ihren Namen (String) angegeben werden. Es können einzelne oder ein Array von Panels angegeben werden. Wird kein Argument angegeben, werden alle Panel der Liste PanelList behandelt.
ControlPanels.UpdateLayout( Panels )
Ruft die Funktion ControlPanel.UpdateLayout() für die bei Panels angegeben ControlPanel Obejkte auf. UpdateLayout() wird intern automatisch aufgerufen, wenn sich die Seitengrösse, das Seitenlayout oder die Sichtbarkeit von Seitenelementen mit ControlPanels verändert. Die Panels berechnen dann ihre Grössen entsprechend dem neuen Platzangebot neu.
Die betroffenen Panels können als ControlPanel oder über ihren Namen (String) angegeben werden. Es können einzelne oder ein Array von Panels angegeben werden. Wird kein Argument angegeben, werden alle Panel der Liste PanelList behandelt.
ControlPanels.Invalidate( Panels, UpdateGui )
Ruft die Funktion ControlPanel.Invalidate() für die bei Panels angegeben ControlPanel Objekte auf.
Die betroffenen Panels können als ControlPanel oder über ihren Namen (String) angegeben werden. Es können einzelne oder ein Array von Panels angegeben werden. Wird kein Argument oder null angegeben, werden alle Panel der Liste PanelList behandelt.
Invalidate verwirft den Zustand aller ControlPanel-Felder, sodass diese beim nächsten Update() auf jeden Fall ihre Werte vom Model holen und neu anzeigen. Dies ist nützlich, wenn zum Beispiel in der Zwischenzeit zwar nicht ein Modellwert geändert wurde, aber dessen Darstellungsformat. So können die Anzeigefelder gezwungen werden, ihre Werte im neuen Format anzuzeigen. Invalidate wird im Zusammenhang mit UnitsData, FormatRef, DigitsRef, MultRef und UnitsRef verwendet oder wenn die sprachabhängige formatierung des NumFormatters geändert wurde.
ControlPanels.Reset( Panels, CallModelChangeCB )
Ruft die Funktion ControlPanel.Reset() für die bei Panels angegeben ControlPanel Obejkte auf.
Die betroffenen Panels können als ControlPanel oder über ihren Namen (String) angegeben werden. Es können einzelne oder ein Array von Panels angegeben werden. Wird kein Argument oder null angegeben, werden alle Panel der Liste PanelList behandelt.
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 mit der Funktion ControlPanels.ResetButton(), welcher als Aktion Reset ruft:
var model = new MyModel();
ControlPanels.NewPanel( {
NCols: 2, OnModelChange: Compute, ...
} ).AddHeader( {
Text: 'Überschrift' + ControlPanels.ResetButtonR(), ColSpan: 4
} )...
function Reset() {
ControlPanels.Reset();
Compute();
}
function Compute() {
model.Compute();
ControlPanels.Update();
}
Beachte, dass durch den Aufruf von ControlPanels.Reset() die Funktion Compute() standardmässig nicht automatisch aufgerufen wird, nachdem alle Modellwerte zurückgesetzt wurden. So können wie im Beispiel gezeigt die Reset() Aufrufe für mehrere Panels zusammengefasst werden, ohne dass für jedes Panel Compute() ausgeführt wird. Durch den Aufruf von ControlPanels.Update() in der Funktion Compute() werden danach die ControlPanel-Felder auf den neuen Stand gebracht.
ControlPanels.ConnectDom( Panels )
Ruft die Funktion ControlPanel.Init() für die bei Panels angegeben ControlPanel Objekte auf (es braucht keine Funktion ControlPanel.ConnectDom(), Init() erfüllt diese Aufgabe auch).
Die betroffenen Panels können als ControlPanel oder über ihren Namen (String) angegeben werden. Es können einzelne oder ein Array von Panels angegeben werden. Wird kein Argument angegeben, werden alle Panel der Liste PanelList behandelt.
ConnectDom() sucht alle Dom-Element der Webseite, welche von den ContolPanel gesteuert werden und verlinkt die Panels mit diesem Dom-Elementen.
Diese Funktion kommt zur Anwendung, wenn die Dom-Elemente dynamisch per Javascript erzeugt und gelöscht werden, zum Beispiel:
function AddNewPanel() {
var newPanel = ControlPanels.NewPanel( .... ).AddTextField(...)...;
var newPanelHtml = newPanel.GetHtml();
var oldPanelsHtml = xInnerHtml( 'myPanels' );
var newPanelsHtml = oldPanelsHtml + newPanelHtml;
xInnerHtml( 'myPanels', newPanelsHtml );
// here all ControlPanel links are broken
// because all panels are destroyed and recreatet in xInnerHtlm()
// so we have to reconnect the panels now:
ControlPanels.ConnectDom();
}
Siehe auch CP-Anwendung: ConnectDom.
ControlPanels.AddBeforeInitHandler( )
Installiert eine Funktion, welche vor der automatischen Initialisierung der Panels in der PanelList gerufen wird. Es können beliebig viele Funktionen durch mehrfaches Aufrufen dieser Funktion installiert werden.
Diese Funktion ist nützlich, wenn garantiert werden muss, dass ein Modell initialisiert sein muss, befor die zugewiesenen Controlpanels darauf zugreifen:
ControlPanels.AddBeforeInitHandler(
function() {
Model1.Init();
Model2.Init();
:
}
);
oder
ControlPanels.AddBeforeInitHandler( function() { Model1.Init(); } );
ControlPanels.AddBeforeInitHandler( function() { Model2.Init(); } );
:
ControlPanels.Init( Panels )
Ruft die Funktion ControlPanel.Init() für die bei Panels angegeben ControlPanel Objekte auf.
Die betroffenen Panels können als ControlPanel oder über ihren Namen (String) angegeben werden. Es können einzelne oder ein Array von Panels angegeben werden. Wird kein Argument angegeben, werden alle Panel der Liste PanelList behandelt.
Init() veranlasst, dass die aktuellen Modell-Werte ausgelesen werden und bei den ControlPanel-Feldern als Startwert gespeichert werden. Mit Reset() kann dadurch 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() verbindet schliesslich alle Panels mit ihren Dom-Elementen der Webseite.
Init() wird automatisch nach dem Laden der Seite gerufen und muss daher in den meisten Fällen nicht explizit gerufen werden. Das automatische Aufrufen von Init() kann wenn nötig bei der Funktion NewPanel() mit dem Argument AutoInit: false unterdrückt werden.
Wenn vor dem Initialisieren der Controlpanels die Modelle zuerst initialisiert werden müssen, können entsprechende Funktionen mit AddBeforeInitHandler() installiert werden.
ControlPanels.SetDefaults( Panels, updateGui )
Ruft die Funktion ControlPanel.SetDefaults() für die bei Panels angegeben ControlPanel Objekte auf.
Die betroffenen Panels können als ControlPanel oder über ihren Namen (String) angegeben werden. Es können einzelne oder ein Array von Panels angegeben werden. Wird kein Argument angegeben, werden alle Panel der Liste PanelList behandelt.
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 ControlPanels.Update() gerufen um die Defaultwerte jetzt in die Felder zu schreiben.
ControlPanels.IsDisplayed( PanelName )
Gibt true zurück, wenn das ControlPanel PanelName 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.
ControlPanels.IsEnabled( PanelName, FieldName )
Jeder Typ von ControlPanel-Feld behandelt das aktivieren/deaktivieren individuell verschieden. Deshalb braucht es die Funktion IsEnabled() zur Abfrage des enabled-Zustandes. Bei Checkbox-Felder gibt es zum Beispiel pro Feld mehrere Items, die unabhängig voneinander aktiviert/deaktiviert werden können. In diesem Fall ist FieldName der Name eines Items, nicht des Feldes.
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.
Der enabled-Zustand kann mit der Funktion SetEnabled() gesetzt werden.
ControlPanels.SetEnabled( Panels, FieldName, Enabled )
Ruft die Funktion ControlPanel.SetEnabled() für die bei Panels angegeben ControlPanel Objekte auf.
Die betroffenen Panels können als ControlPanel oder über ihren Namen (String) angegeben werden. Es können einzelne oder ein Array von Panels angegeben werden. Wird kein Argument oder null angegeben, werden alle Panel der Liste PanelList behandelt.
Wenn FieldName nicht definiert oder '' ist, werden alle Felder der entsprechenden Panel 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.
SetEnabled() kann zum deaktivieren/aktivieren von Panel-Feldern verwendet werden. Deaktivierte Panel-Felder werden grau gezeichnet und können nicht mehr interaktiv verändert werden. Sie zeigen jedoch den aktuellen Zustand ihrer Modell-Properties weiterhin an.
Über die Referenzen EnabledRef kann erreicht werden, dass sich Panel-Felder automatisch aufgrund von Modell-Properties aktivieren/deaktivieren. Wenn EnabledRef definiert ist, hat SetEnabled() für das entsprechende Element keine Wirkung. Der Enabled-Zustand wird dann allein durch das referenzierte Modell-Property gesteuert.
Der aktuelle enabled-Zustand eines Panel-Feldes kann mit IsEnabled() abgefragt werden.
ControlPanels.DeletePanels( Panels )
Ruft die Funktion ControlPanel.Delete() für die bei Panels angegeben ControlPanel Objekte auf.
Die betroffenen Panels können als ControlPanel oder über ihren Namen (String) angegeben werden. Es können einzelne oder ein Array von Panels angegeben werden. Wird kein Argument angegeben, werden alle Panel der Liste PanelList behandelt.
Delete() löst die Verbindung zu den Dom-Elementen der Panels und alle internen Verbindungen zwischen Panel und Panel-Feldern und die Panels werden aus der PanelList entfernt. Damit wird der Speicher dieser Objekte freigegeben.
Delete() muss nur verwendet werden, wenn auf der Webseite dynamisch per Javascript Panels erzeugt und gelöscht werden. Beim Verlassen der Webseite werden die Panels automatisch gelöscht.
ControlPanels.Get( PanelName )
Sucht in der PanelList nach dem Panel mit dem Namen PanelName und gibt dieses Panel zurück. Wenn kein Panel mit diesem Namen gefunden wird, gibt die Funktion null zurück.
ControlPanels.GetField( PanelName, FieldName )
Sucht in der PanelList nach dem Panel mit dem Namen PanelName und darin ein Feld mit dem Namen FieldName. Bei Checkbox-Feldern wird FieldName auch mit den Namen der CpCheckboxItems verglichen. Passt ein solcher Name, wird das Checkbox-Feld zurückgegeben.
Wird das Feld nicht gefunden, wird null zurückgegeben.
Ein Feld kann auch über die Funktion ControlPanel.GetField() gesucht werden, wenn man ein ControlPanel vorliegen hat.
ControlPanels.GetIx( PanelName )
Sucht in der PanelList nach dem Panel mit dem Namen PanelName und gibt den Index auf dieses Panel in der Liste zurück. Wenn kein Panel mit diesem Namen gefunden wird, gibt die Funktion -1 zurück.
ControlPanels.ForEachPanel( Func, Panels )
Ruft die Funktion Func() für die bei Panels angegeben ControlPanel Objekte auf.
Die betroffenen Panels können als ControlPanel oder über ihren Namen (String) angegeben werden. Es können einzelne oder ein Array von Panels angegeben werden. Wird Panels nicht angegeben, werden alle Panel der Liste PanelList behandelt.