Business App Leitfaden für Anpassungen

13.7.6. Widget Vorschau implementieren

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.