Widget
Damit ein Widget in die Übersicht gezogen werden und eine Vorschau anzeigen kann, muss dieses Widget das Interface IPreviewableWidget implementieren.
Dieses Interface definiert die beiden Eigenschaften
bool ShowsTitleInPreview
string PreviewActionName
und die Methode
IWidgetPreviewProvider GetWidgetPreviewProvider()
welche dann auch im Widget implementiert werden müssen.
bool ShowsTitleInPreview
Diese Eigenschaft bestimmt, ob das Widget in seiner Vorschau einen Titel anzeigen soll oder nicht. Soll es einen Titel anzeigen, so kann diese Eigenschaft von einem Konfigurator oder programmatisch aktiviert werden (abhängig von den Attributen, welche in der Implementierung verwendet werden).
string PreviewActionName
Diese Eigenschaft bestimmt den Namen der Controller-Aktion, welche auf dem zu dem Widget gehörenden Controller aufgerufen wird, um die Vorschau zu rendern. Üblicherweise ist diese Eigenschaft vor Konfiguratoren verborgen und wird programmatisch gesetzt.
IWidgetPreviewProvider GetWidgetPreviewProvider()
Diese Methode ruft den Preview-Provider für das Widget ab, welcher die Daten für die Vorschau liefert. Um einen Preview-Provider anhand seiner Id abzurufen, kann folgende Hilfsmethode verwendet werden:
WidgetTools.GetWidgetPreviewProviderById(<id>)
Controller
Der Controller muss die im Widget angegebene Aktion implementieren, zum Beispiel
public PartialViewResult Preview()
Dort wird üblicherweise der Preview-Provider des Widgets abgerufen und auf diesem die Methode GetPreviewData
mit einem hier ebenfalls erstellten Parameter-Objekt aufgerufen. Welche Inhalte oder von welchem Typ dieses Parameter-Objekt haben muss, hängt vollkommen vom verwendeten Preview-Provider ab.
Der grundsätzliche Ablauf der Preview-Aktion ist also wie folgt:
IWidgetPreviewProvider provider = ((IPreviewableWidget)RequestedControl).GetWidgetPreviewProvider();
WidgetPreviewDataModelBase previewModel = provider.GetPreviewData(previewProviderParameters);
return PartialView(provider.PreviewViewPath, previewModel);
Die aufgerufene Razor-View kann dann anhand des empfangenen Models eine beliebige Ui implementieren.
PreviewProvider:
Eine Klasse wird durch zwei Dinge zu einem Preview-Provider:
- die Klasse implementiert das Interface
IWidgetPreviewProvider
und - die Klasse hat das Attribut
WidgetPreviewProvider
IWidgetPreviewProvider-Interface
Das Interface definiert die beiden Eigenschaften
string PreviewViewPath { get; }
Type ExpectedParameterType { get; }
und die Methode
WidgetPreviewDataModelBase GetPreviewData(object parameter)
string PreviewViewPath
Gibt den üblicherweise virtuellen Pfad zurück, unter dem die MVC-View (cshtml) liegt, welche die Darstellung der zugehörigen Vorschau beinhaltet, also z.B. "~/Views/Widgets/MyWidget/Preview.cshtml"
.
Type ExpectedParameterType
Liefert dem aufrufenden System die Information darüber, welcher Typ für den Parameter beim Aufruf von GetPreviewData
von diesem Preview-Provider erwartet wird.
WidgetPreviewDataModelBase GetPreviewData(object parameter)
Diese Methode macht die ganze Backend-Arbeit und liefert die Daten als Klasse des Typs WidgetPreviewDataModelBase
zurück, die von der Preview-View verarbeitet werden sollen. Entwickler können selbstverständlich ganz eigene Models implementieren, die von WidgetPreviewDataModelBase
ableiten, es stehen aber auch bereits einige fertige Models zur Verfüfung, welche eine gute Menge an Fällen abdecken dürften. Diese Models verwenden für ihre Werte üblicherweise sog. WidgetPreviewToken<T>
, welche die notwendigen Daten eines bestimmten Typs aufnehmen können.
Folgende vorgefertigte Models stehen zur Auswahl:
DefaultGridViewWidgetPreviewModel
, definiert:
public List<WidgetPreviewToken<object>> AdditionalInformation
GenericDataWidgetPreviewModel
, definiert:
public WidgetPreviewToken<object> Data
MultipleNumbersWidgetPreviewModel
, definiert:
public List<WidgetPreviewToken<int>> Numbers // Eine Liste mit Ganzzahl-Preview-Tokens
public WidgetPreviewToken<int> EmptyContent // Ein einzelnes Ganzzahl-Preview-Token, das verwendet werden soll, falls die Liste leer ist
SingleNumberLatestAndNextWidgetPreviewModel
, definiert:
public WidgetPreviewToken<DateTime> Latest
public WidgetPreviewToken<DateTime> Next
SingleNumberWidgetPreviewModel
, definiert:
public WidgetPreviewToken<int> MainInformation
VariableDataWidgetPreviewDataModel
, definiert:
public Dictionary<string, WidgetPreviewToken<int>> DataByKey
WidgetPreviewToken
Diese Klasse existiert, da zu einer Information normalerweise mehr gehört als zum Beispiel nur eine Ganzzahl. Hier können neben der Hauptinformation vom Typ noch weitere Informationen für die Preview-View untergebracht werden. Die Verwendung dieser Informationen ist selbstverständlich von der jeweilligen Implementierung der Vorschau-View abhängig.
WidgetPreviewToken<T>
enthält folgende Informationen:
public string Description
Die Beschreibung des gelieferten Werts, üblicherweise ein einzelnes Wort oder eine kurze Phrase, welche in der Vorschau angezeigt werden kann.public string Icon
Ein eventuelles Icon, welches zusätzlich zu anderen Informationen angezeigt werden soll.public T Data
Die eigentlichen Daten dieses Tokens.public string Tooltip
Der zu den Daten anzuzeigende Tooltip.public bool IsEmphasis
Die angezeigten Daten sollen optisch hervorgehoben werden.public bool UseIconAsLabel
Das Icon soll gar nicht als Bild dargestellt werden sondern der Name des Icons soll als Text ausgegeben werden
WidgetPreviewProvider-Attribut
Die Angabe des Attributs beinhaltet die Angabe einer eindeutigen ID und eines darstellbaren Namens für diesen Preview-Provider und optional n Typen von Orm-Klassen, mit denen dieser PreviewProvider arbeiten kann.
- Die Id wird selbstverständlich verwendet, um den Preview-Provider zu identifizieren und abrufen zu können. Hier hat es sich bewährt, den vollen Typnamen (also inklusive Namespace) der Klasse zu verwenden.
- Der Name wird von dem oben erwähnten Data-Provider verwendet, um den Preview-Provider mit irgendetwas Anderem als seiner Id zur Auswahl anzubieten.
- Die optionalen Typen können von einem ebenso optionalen
CDPModifier
verwendet werden, um die Auswahl der Preview-Provider einzuschränken.