Gedys CXM: Leitfaden für Anpassungen

13.7.7. Listen-Widget

__sth2. Grundlagen

Der Listen-Widget-Framework ist in erster Linie dazu gedacht einen Entwickler in die Lage zu versetzen, einfach und unkompliziert Daten aller Art in einer Liste innerhalb der Anwendung anzeigen lassen zu können.

Er bietet aber ebenso die Möglichkeit komplexer Anpassungen, um beispielsweise – auch grafisch – eigene Filter zu implementieren (wie im Wiedervorlagen-Widget des „BA.FollowUp“-Moduls geschehen) und verschiedenste Aktionen auf die angezeigten Daten auszuführen.

Der Framework besteht aus einem generischen Listen-Widget-Controller mit zugehöriger Listen-Widget-Mvc-View, einer Listen-Widget-TypeScript-Klasse und mehreren auf einander aufbauenden Basisklassen, die ein Entwickler zur Erstellung eines eigenen Listen-Widgets erweitern muss. Die TypeScript-Klasse verwendet ein gesondertes client-seitiges Listensteuerelement, welches selbstständig mit dem Listen-Widget-Controller zusammenarbeitet. Die Kommunikation zwischen Controller und Listensteuerelement erfolgt über HTTP und JSON.

Für die (Meta-)Datenversorgung des Listen-Widgets stehen dem Entwickler zahlreiche Model-Klassen zur Verfügung.

Das Listen-Widget-Steuerelement

Basisklassen und Schnittstellen

Die Basisimplementierung des Listen-Widgets besteht aus vier auf einander aufbauenden Widget-Klassen und einer Schnittstelle IListWidget. Die Schnittstelle legt fest, welche Methoden und Eigenschaften ein List-Widget haben muss, allerdings implementieren die Basisklassen viele davon schon selbst, so dass in der Endimplementierung des Entwicklers hauptsächlich die abstrakten Methoden implementiert werden müssen. Alle anderen Methoden können nach Belieben ebenfalls überschrieben werden.

Die Listen-Widget-Basisklassen haben einen – optional zwei – generische Parameter; das und die Vererbungshierarchie sehen wie folgt aus:

Die oberste Vererbungsebene bildet die Klasse

public abstract class ListWidget<T, C> : Widget, IListWidget where C : ListControlContextBase, new()

Davon erben einmal die Vereinfachung

public abstract class ListWidget<T> : ListWidget<T, ListControlContextBase>

und die abstrakte Basisklasse

public abstract class OrmListWidget<T, C> : ListWidget<T, C> where T : OrmBase where C : ListControlContextBase, new()

Letztere hat eine weitere Vereinfachung

public abstract class OrmListWidget<T> : OrmListWidget<T, ListControlContextBase> where T : OrmBase

Der generische Parameter T bezeichnet immer den Typen der Quelldaten, die dieses Widget anzeigen wird.

In der Grundimplementierung ListWidget können diese Daten von einem beliebigen Typen sein, in der konkreteren Implementierung OrmListWidget ist dieser Typ auf OrmBase (oder konkreter) festgelegt.

Der zweite (optionale) Parameter C bezeichnet den Typen für das Laufzeitkontextobjekt, welches in jede in der Schnittstelle definierte Methode hineingegeben und über die Methode CreateContextq erstellt wird.

Wird C nicht angegeben, so wird standardmäßig ListControlContextBase verwendet.

Das implementierte Listen-Widget ist dafür zuständig sowohl die eigentlichen Anzeigedaten als auch die Metadaten für das Listensteuerelement entsprechend der Schnittstelle zu liefern.

Folgende Methoden müssen zwingend vom Entwickler implementiert werden:

ListControlColumn[] GetColumns(C context)

Liefert eine Reihe von Definitionen für die Spalten, die das Widget in der Liste in der gelieferten Reihenfolge anzeigen soll.

IQueryable<T> GetDataQuery(C context)

Erzeugt die Basis-Query auf die anzuzeigenden Daten.

IOrderedQueryable<T> OrderQuery(IQueryable<T> query, C context)

Sortiert die übergebene Query nach Belieben aber auf eine konstante Art und Weise; ist notwendig, um die Paging-Funktionalitäten „Skip“ und „Take“ verwenden zu können.

ListControlRowDataBase[] CreateRowData(IQueryable<T> query, C context)

Äquivalent zu Datenprovidern wird hier aus der gegebenen Query ein Array von Rückgabedaten erstellt.

Konsumieren von Daten

Um Daten von der Seite oder anderen Widgets zu konsumieren, erben Sie von DataListWidget anstelle von ListWidget. Hier können sie mittels WidgetParameterDefinition definieren, welche Parameter Typen das Widget lesen kann. Mehr dazu im Kapitel Parameter und im Kapitel Parameter konsumieren.
h3. Datenbeschaffung / GetData

Die GetData-Methode auf dem Widget hat eine Standardimplementierung in ListWidget<T,C>, die im Notfall überschrieben werden kann und die üblicherweise von einem Daten-Controller während der Aktion GetData aufgerufen wird.

Der Ablauf in dieser Methode ist:

  • GetDataQuery
  • ApplyFiltersToQuery (in diesem Zuge dann ApplyFilter)
  • CalculateTotalCount (falls RequireTotalCount angefragt wurde)
  • OrderQuery (mit anschließendem Skip und Take, das ist nicht anpassbar)
  • CreateRowData

Der Datenrückgabetyp ListControlRowDataBase der CreateRowData-Methode ist leer und abstrakt, d. h. er muss von einem Entwickler, der entsprechend Daten liefern möchte, um die benötigten Eigenschaften erweitert werden. Der Name der Spaltenmetadaten korreliert mit den hier vergebenen Eigenschaftsnamen (siehe Beispiel, Firmenname „Name“).

Die Daten, welche hier zurück geliefert werden, lassen sich grob in zwei Arten aufteilen: Daten, die zur Berechnung und im Hintergrund benötigt werden und Daten, welche tatsächlich angezeigt werden sollen.

Bei ersteren empfiehlt es sich, als Variablentyp im Row-Data-Model einen einfachen und unverfänglichen C#-Typen zu verwenden (string, int, bool, Guid, etc.).

Daten, die angezeigt werden sollen, jedoch unterliegen üblicherweise Formatierungen (Schriftgrößen, arten und -farben, Datums und Nummernformatierungen, etc.), daher sollten solche Daten im Row-Data-Model über die Model-Klassen im Unter-Namespace DataDefinitions definiert werden.

Als konkrete Beispiele könnten man hier eine Icon-Spalte nennen, die entsprechend so deklariert werden sollte:

public ListControlDataImage StatusImage { get; set; }

Ein weiteres Beispiel wäre eine Datumsspalte:

public ListControlDataDate EndDate { get; set; }

Eine solche Deklaration wie die zweite hier sagt also dem Listen-Framework, dass die Daten jeder Zelle in der Spalte EndDate eine Standarddatumsformatierung erhalten sollen. Der verwendete Typ im Row-Data-Model definiert also den Zellentypen der Liste.

Das ist wichtig zu verstehen, da jeder dieser Datendefinitionstypen (außer Image) mehrzeilig sein kann und diese Formatierung auf jede Zeile angewendet wird, wenn dies in der zugehörigen Inhaltklasse nicht anders angegeben wird.

Folgende Zellentypen/Datendefinitionstypen stehen zur Verfügung:

  • ListControlDataText
  • ListControlDataNumber
  • ListControlDataDate
  • ListControlDataDateTime
  • ListControlDataImage

Image tanzt ein wenig aus der Reihe, hier kann (muss) man bei der Erstellung ausschließlich die Url auf das Bild und einen Tooltip für selbiges angeben:

new ListControlDataImage (string url, string title)

Mehr kann man hier auch schon nicht machen, daher gelten alle folgenden Informationen für alle anderen Datendefinitionsklassen!

Diese anderen Klassen funktionieren alle mehr oder weniger identisch und haben die gleichen Konstruktoren (daher das Ganze einfach nur am Beispiel ListControlDataText):

new ListControlDataText(string text)
new ListControlDataText(string text, string cssClass)
new ListControlDataText(params ListControlDataContent[] lines)

Der hier gezeigte Parameter string text variiert natürlich bei den anderen Inhalttypen entsprechend.

Die ersten beiden Konstruktoren sind selbsterklärend, es wird in der Zelle ein Text angezeigt und optional mit einer css-Klasse versehen. Beim letzten Konstruktor können beliebig viele Inhaltsobjekte angeben werden, die mehrere Textzellen darstellen.

Die Klasse ListControlDataContent wird intern von den anderen Konstruktoren verwendet, es ist über diesen letzten Konstruktor möglich, Objekte dieses Typs direkt zu übergeben.
Instanziiert werden können sie wie folgt:

new ListControlDataContent()
new ListControlDataContent(object content)
new ListControlDataContent(object content, string cssClass)
new ListControlDataContent(object content, string cssClass, string convertFunction)
new ListControlDataContent(object content, string cssClass, string convertFunction, string renderFunction)

Der Inhalt ist hier object, da diese Klasse für jeden Inhaltsttypen verwendet wird. Es kann eine css-Klasse übergeben werden, die auf die entsprechende Zeile angewendet wird, und – und das ist nun besonders interessant – es kann eine JavaScript-Funktion angegeben werden, die client-seitig die String-Formatierung übernimmt. Diese Konvertierungsfunktion wird von manchen Inhaltstypen automatisch gesetzt, wenn sie nicht schon vom Entwickler in einem Content-Objekt selbst angegeben wurde.

Das heißt, der Inhaltstyp ListControlDataDate wird die Standardfunktion zur Textkonvertierung für Datumswerte (ohne Zeit) ListControl.ConvertDateToString setzen, wenn ich als Entwickler nicht über ein Content-Objekt selbst sage, dass ich eine andere Funktion verwenden will.

Das bringt uns in die Lage, die Inhalte von Zellen auch mischen zu können. Es ist also am Ende möglich, in einer Datumszelle drei Zeilen unterzubringen, bei denen die ersten beiden Zeilen als normales Datum formatiert werden, die dritte aber als Nummer oder normaler Text.

Anstelle der Klasse ListControlDataContent kann auch die Klasse ListControlDataContentWithInlineImage verwendet werden. Diese erbt von ListControlDataContent und ermöglicht es zusätzlich eine Image-Url anzugeben, welche vor dem Text angezeigt wird. Sie verfügt über die Eigenschaften ImageUrl, zum Angeben einer entsprechenden URL , sowie ImageIsIcon. Setzen sie ImageIsIcon auf true, wenn sie den in den Themes definieten Filter auf das Bild anwenden möchten. Möchten Sie dies nicht, weil es sich beispielsweise um ein Foto oder ein Logo handelt, welches seine Farben niemals verändern soll, setzen sie ImageIsIcon auf false.

Wie alles andere im Framework lassen sich auch diese Inhaltsklassen sehr leicht um eigene Klassen erweitern. Eine entsprechende Klasse muss den Basistypen ListControlDataBase erweitern.

Einfachstes Beispiel eines Listen-Widgets

Das quasi einfachste Listen-Widget, das man implementieren kann, wäre (in diesem Beispiel) eins, das nur eine Liste von Firmennamen anzeigt. Dazu muss es eine Row-Data-Klasse implementieren, die den Firmennamen beinhaltet, es muss die Spalte definieren, die den Firmennamen anzeigen soll, es muss die Query auf die Firmendaten erzeugen, diese sortieren und daraus am Ende Row-Data-Objekte erzeugen.

[Serializable]
[Toolbox(EnumConfigurationType.PageConfigurationGuid)]
public class CompanyWidget : OrmListWidget<OrmCompany>
{
	public class CompanyRowBase : ListControlRowDataBase
	{
		public ListControlDataText Name { get; set; }
	}

	public CompanyWidget()
	{
		Id = "[INSERT YOUR WIDGET GUID]".ToGuid();
		ToolboxName = "Company-Widget";
	}

	protected override ListControlColumn[] GetColumns(ListControlContextBase context)
	{
		return new ListControlColumn[]
		{
			new ListControlColumn { DataField = nameof(CompanyRowBase.Name), MinWidth = 200 }
		};
	}

	protected override IQueryable<OrmCompany> GetDataQuery(ListControlContextBase context)
	{
		return Api.ORM.GetQuery<OrmCompany>();
	}

	protected override IOrderedQueryable<OrmCompany> OrderQuery(IQueryable<OrmCompany> query, ListControlContextBase context)
	{
		return query.OrderBy(ff => ff.Name);
	}

	protected override ListControlRowDataBase[] CreateRowData(IQueryable<OrmCompany> query, ListControlContextBase context)
	{
		return query.Select(ff => new CompanyRowBase { 
			Name = new ListControlDataText(ff.Name) 
		}).ToArray();
	}
}

Das Beispiel um Aktionen erweitern

Im Prinzip gibt es drei Arten von Aktionen, die in solch einem Widget verwendet werden können:

  • Aktion bei Einzelklick auf einen Listeneintrag
  • Aktion bei Doppelklick auf einen Listeneintrag
  • Aktionen, die beim Betreten mit dem Mauszeiger angezeigt und per Einzelklick aktiviert werden können

Um diese Aktionen nutzen zu können, müssen die folgenden Methoden im Widget entsprechend überschrieben werden:

protected override ListControlRowAction[] GetRowActions(ListControlContextBase context)
{
	ListControlRowAction[] actions = new ListControlRowAction[]
	{
		new ListControlRowAction
		{
			ActionMethodId = "My.Edit.ActionId",
			Title = "Edit",
			IconUrl = IconHelper.GetIconUrl("pencil", RequestIconSizeEnum.Size32x32, ColorTranslator.FromHtml("#4D4D4D"))
		},
		new ListControlRowAction
		{
			ActionMethodId = "My.Finish.ActionId",
			Title = "Finish",
			IconUrl = IconHelper.GetIconUrl("ok", RequestIconSizeEnum.Size32x32, ColorTranslator.FromHtml("#4D4D4D"))
		}
	};

	return actions;
}

protected override string GetRowClickActionMethodId(FollowUpContext context)
{
	return "My.SingleClick.ActionId";
}

protected override string GetRowDoubleClickActionMethodId(FollowUpContext context)
{
	return "My.DoubleClick.ActionId";
}

Das Beispiel um Filter erweitern

Häufig will man gar nicht alle Daten anzeigen sondern den Benutzern die Möglichkeit geben, diese Daten auf bestimmte Fälle einzuschränken. Hierfür benötigt man Filter, und um diese definieren und verwenden zu können, muss im Widget Folgendes implementiert werden:

protected override ListControlFilterBase[] GetFilters(ListControlContextBase context)
{
	ListControlFilterBase[] result = new ListControlFilterBase[]
	{
		new ListControlFilterSelect
		{
			Id = "[INSERT FILTER GUID]".ToGuid(),
			Width = 170,
			Items = new ListControlFilterItem[]
			{
				new ListControlFilterCriteriaItem
				{
					Caption = "All companies",
					Key = "all",
					Criteria = new OperandValue(true)
				},
				new ListControlFilterCriteriaItem
				{
					Caption = "Name starts with 'A'",
					Key = "a",
					Criteria =  new FunctionOperator(FunctionOperatorType.StartsWith, new OperandProperty(nameof(OrmCompany.Name)), new OperandValue("A"))
				},
			},
			DefaultSelectedKey = "all",
		}
	}
}

Dieses Beispiel sorgt dafür, dass in der Toolbar der Liste eine Combobox mit den Einträgen „All companies“ und „Name starts with ‚A‘“ erscheint. Die Verwendung von ListControlCriteriaFilterItems ist hier möglich, da es sich bei dem Widget um die Ableitung eines OrmWidgets handelt, Formel-Filterelemente können im Standard automatisch ausgeführt bzw. auf die Query angewendet werden.

Wäre die Query nicht von einem OrmBase-Typen, so könnten nur Filterelemente des Typs ListControlFilterItem verwendet werden. In diesem Fall müsste zusätzlich die Methode ApplyFilter überschrieben werden, um entsprechende Filterelemente auf die Query anzuwenden.

Wenn ganz eigene Filter und Filterelementtypen zum Einsatz kommen oder Abläufe angepasst werden müssen, kann es auch sein, dass zusätzlich noch die Filterverwaltungsmethode ApplyFiltersToQuery überschrieben werden muss, die sich dann um die Anwendung aller aktiven Filter kümmern muss.

Wer interessiert ist und Zugriff auf den Quellcode hat: Das Wiedervorlagen-Widget im Modul „BA.FollowUp“ ist hierfür ein Beispiel.

Tiefergehende Anpassungen

Für komplexe Anpassungen können im Konstruktor der Widget-Klasse auch ein eigener Listen-Controller (Eigenschaft ControllerName) und eine eigene TypeScript-Widget-Klasse („GetTSClassName()“) angegeben werden, wobei Letzteres allerdings Teil des generellen Widget-Frameworks ist.

Der Listen-Widget-Controller und die Listen-Widget-Mvc-View

Der ListWidgetController ist ein Standard-Widget-Controller, der die für die Versorgung eines Listensteuerelements notwendige Schnittstelle IListControlDataSource implementiert und daher mit einem Listensteuerelement verwendet werden kann. Als Widget-Controller implementiert er zusätzlich eine Index-Aktion, die beim Aufruf des Widgets aufgerufen wird. Die Methode GetMetaData ist zwar vollständig implementiert, sie wird aber in der Standardauslieferung nicht verwendet.

Im Widget-Fall werden die Metadaten in der Index-Methode von der Listen-Widget-Implementierung gesammelt, über ein View-Model an die Mvc-View weitergegeben und dort in data-Attributen des Listen-Basis-DIV-Elements (anchor) hinterlegt.

Die generelle Abfolge beim Abruf der Metadaten, also auch bei „GetMetaData“, ist folgende:

  • CreateContext
  • UpdateContext
  • GetRowActions
  • GetColumns
  • GetFilters
  • GetRowClickActionMethodId
  • GetRowDoubleClickActionMethodId
  • GetKey
  • GetLocale (veraltet)

Beim Abruf von Daten, sei es durch Scrollen der Liste, Anwenden eines Filters oder einfach nur durch Drücken des Refresh-Knopfes, wird die Aktion GetData aufgerufen. Hier ist der Ablauf wie folgt:

  • CreateContext
  • UpdateContext
  • GetData

Die Standardimplementierungen der Daten- und Metadaten-Methoden auf den Listen-Widget-Basisklassen gehen davon aus, dass der übergebene Laufzeitkontext nicht null ist und die Eigenschaft ControllerResult ein gültiges, vorgefertigtes Rückgabeobjekt beinhaltet.

Dieses Objekt ist für Daten vom Typ ListControlGetData und für Metadaten vom Typ ListControlGetMetaData (oder jeweils konkreter).

Die Methode UpdateContext

Die Methode UpdateContext sieht folgendermaßen aus

public virtual void UpdateContext(ListControlContextBase context, IListWidget widget)

Hier können im Controller noch dynamische Änderungen am Context vorgenommen werden.
Im Falle eines Listen-Widgets, welches Daten Daten konsumiert, können hier beispielsweise diese Daten an den Kontext übergeben werden.

Die ListWidget-TypeScript-Klasse

Die zu jedem Widget gehörende TypeScript-Klasse erbt von der Klasse Widget und überschreibt im Falle des Listen-Widgets die Funktion OnContentLoaded, um dort das client-seitige Listensteuerelement zu erstellen.

Diese Klasse kann bei Bedarf durch eine eigene Klasse erweitert werden; in einem solchen Fall muss die neue Klasse über die Eigenschaft GetTSClassName() der Widget-Implementierung bekannt gegeben werden.

Die TypeScript-Klasse beinhaltet folgende Funktionen, die in abgeleiteten Klassen überschrieben werden können:

OnContentLoaded(): void

Ermittelt die Erstellparameter für das Listensteuerelement durch einen Aufruf an GetCreateParameters und erstellt anschließend das Listensteuerelement durch den Aufruf von CreateListControl.

GetControlId(): string

Berechnet die Id der DevExtreme-Komponente des Listensteuerelements.

GetListContainer(): JQuery

Ermittelt das JQuery-Element des Listenbasiselements (anchor). Ruft GetControlId auf.

GetCreateParameters(): BA.Ui.ClientSideControls.List.ListControlCreateParameters

Ermittelt die Erstellparameter aus den data-Attributen des Listen-Containers. Ruft GetListContainer und InitCustomFilters auf.

CreateListControl(createParameters: BA.Ui.ClientSideControls.List.ListControlCreateParameters): BA.Ui.ClientSideControls.List.ListControl | JQueryPromise<BA.Ui.ClientSideControls.List.ListControl>

Erstellt das Listensteuerelement. Der Rückgabewert hängt von der in abgeleiteten Klassen verwendeten Erstellmethodik ab, im Standard ist dies aber immer einfach nur ListControl.

InitCustomFilters(_: BA.Ui.ClientSideControls.List.ListFilter[]) : void

Erlaubt die grafische Initialisierung eigener Filter (für Beispiel siehe Wiedervorlagen-Widget im Modul „BA.FollowUp“).

Anhang (Klassenbeschreibungen)

Alle C#-Model-Typen befinden sich unterhalb des Namespace BA.Core.Models.ListControlModels.

Controller-Models (C#)

ListControlGetData

Das Model ist selbst ein ActionResult und wird automatisch nach JSON serialisiert.

  • int? TotalCount
    Die Gesamtzahl an möglichen Datensätzen, die in der Liste angezeigt werden könnten, wenn man ganz nach unten scrollt. Muss nur befüllt werden, wenn dies bei der Anfrage entsprechend angegeben war (s. RequireTotalCount).
    Hinweis: Wird als totalCount an den Client ausgeliefert.
  • ListControlRowDataBase[] Data
    Array von Daten, welche an den Client ausgeliefert werden. Dies sind ALLE Daten, die der Anforderung entsprechen, sie werden aber nicht zwingend alle angezeigt (von den Metadaten abhängig).
  • Dictionary<string, object> CustomProperties
    Zusätzliche Daten, die von Anpassungen verwendet werden können, im Standard ist dieses Dictionary leer.
    Hinweis: Die verwendeten Werttypen müssen für eine ordnungsgemäße Funktion serialisierbar sein!

ListContolGetMetaData

Das Model ist selbst ein ActionResult und wird automatisch nach JSON serialisiert.

  • public string RowClick { get; set; }
    ActionMethodId, welche ausgeführt wird, wenn eine Zeile per Einzelklick angeklickt wird.
    Hinweis: Wird als rowclick an den Client ausgeliefert.
  • public string RowDoubleClick { get; set; }
    ActionMethodId, welche ausgeführt wird, wenn eine Zeile per Doppelklick angeklickt wird.
    Hinweis: Wird als rowdoubleclick an den Client ausgeliefert.
  • public ListControlColumn[] Columns { get; set; }
    Die Spaltendefinitionen, die das Listensteuerelement anzeigen soll.
    Hinweis: Wird als columns an den Client ausgeliefert.
  • public ListControlFilterBase[] Filters { get; set; }
    Die Filter, die das Listensteuerelement anzeigen soll.
    Hinweis: Wird als filters an den Client ausgeliefert.
  • public ListControlRowAction[] RowActions { get; set; }
    Die Zeilenaktionen, die das Listensteuerelement anzeigen soll.
    Hinweis: Wird als rowactions an den Client ausgeliefert.
  • public Dictionary<string, object> CustomProperties { get; set; } = new Dictionary<string, object>();
    Zusätzliche Daten, die von Anpassungen verwendet werden können, im Standard ist dieses Dictionary leer.
    Hinweis: Wird als customproperties an den Client ausgeliefert.
  • public bool ShowTotalCount { get; set; }
    Flag, ob unterhalb der Liste eine Zeile mit der Gesamtzahl an Listeneinträgen angezeigt werden soll.
    Hinweis: Wird als showtotalcount an den Client ausgeliefert.
  • public string Locale { get; set; }
    Das Kürzel für die Spracheinstellungen des Benutzers (z. B. “en”).
    Hinweis: Die Verwendung dieser Eigenschaft gilt als veraltet und wird von Client nicht mehr ausgewertet. Die Spracheinstellungen des Benutzers werden an globaler Stelle gesetzt.
  • public string Key { get; set; }
    Name der Spalte, deren Inhalt für einen Eintrag als Schlüssel dient, dieser Wert ist im Standard leer.
    Hinweis: Wird als key an den Client ausgeliefert.

ListControlGetDataOptions

Das Model ist eine Zusammenfassung von Parametern, welche vom Listensteuerelement beim Holen von Daten mitgeschickt werden, um den Abruf der Daten zu konkretisieren.

  • int Skip
    Anzahl an Datensätzen, die vom Beginn der Daten übersprungen werden sollen, bevor das Ergebnis befüllt wird. Dient dem Paging der DevExtreme-Komponente.
  • int Take
    Anzahl an Datensätzen, die ab dem ermittelten Beginn der Daten zurückgeliefert werden sollen. Dient dem Paging der DevExtreme-Komponente.
  • bool RequireTotalCount
    True, wenn die DevExtreme-Komponente zum erfolgreichen Verarbeiten der Anforderung die mögliche Gesamtzahl aller Daten benötigt.
  • string ActiveFilters
    JSON-Serialisiertes Objekt des Typs Dictionary<Guid,string>, welches eine Zuordnung zwischen einer Filter-Id und dem zu diesem Filter aktuell aktiven Filtereintrag (Key) enthält.

Metadaten-Models (C#)

ListControlColumn

Spaltendefinitionen ListControlColumn legen grundsätzlich fest, welche Daten in welcher Reihenfolge angezeigt werden und wie breit diese Spalten sein sollen. Objekte dieses Typs werden sofort in ein Format umgewandelt, welches client-seitig direkt von der DevExtreme-Komponente als Spaltendefinition verwendet werden kann.
Der Typ beinhaltet häufig verwendete Eigenschaften, kann aber über „CustomProperties“ beliebige der von der Komponente angebotenen Eigenschaften abbilden:

  • string DataField
    Name der Eigenschaft der Zeilendaten (Ableitung von ListControlRowDataBase), welche in dieser Spalte dargestellt werden soll.
    Hinweis: Wird als dataField an den Client ausgeliefert.
  • int? Width
    Genaue Breite der Spalte in Pixeln (fix), muss nicht zwingend gefüllt sein (dynamisch).
    Hinweis: Wird als width an den Client ausgeliefert.
  • int MinWidth = 20
    Minimale Breite der Spalte in Pixeln, verwendet 20px, wenn nichts anderes angegeben wurde.
    Hinweis: Wird als minWidth an den Client ausgeliefert.
  • bool Visible = true
    Flag, ob die Spalte in der UI sichtbar ist oder nicht.
    Hinweis: Wird als visible an den Client ausgeliefert.
  • string Alignment
    Ausrichtung des Spalteninhalts, akzeptiert „left“, „center“ und „right“.
    Hinweis: Wird als alignment an den Client ausgeliefert.
  • Dictionary<string, object> CustomProperties
    Inhalte in diesem Dictionary werden auf das Rückgabeobjekt erweitert, das heißt, dass Entwickler hier einfach zusätzliche Eigenschaften hineinlegen können, die dann von der DevExtreme-Komponente direkt ausgewertet werden. Dokumentation

ListControlFilterBase / ListControlFilterMultiItemBase / ListControlFilterSelect

Filterdefinitionen ListControlFilterBase definieren jeweils einen Filter, der eine oder mehrere Auswahlmöglichkeiten (FilterItems) hat. Diese Basisklasse ist abstrakt und muss durch eine konkrete Implementation erweitert werden; im Standard ist dies ListControlFilterMultiItemBase (ebenfalls abstrakt und definiert Filter mit mehreren Filtereinträgen) und davon abgeleitet ListControlFilterSelect, welches der Typ ist, der im Standard final an dieser Stelle verwendet werden kann. Dieser enthält folgende Eigenschaften:

  • Guid Id
    Identifikations-GUID des gesamten Filters.
    Hinweis: Wird als id an den Client ausgeliefert.
  • string FilterType
    Typ des Filters. Unterstützt im Standard aktuell „selection“ und „custom“. Wenn „custom“ gesetzt wird, muss außerdem CustomFilterType mit einem eigenen frei wählbaren Typnamen belegt werden.
    Hinweis: Wird als type an den Client ausgeliefert.
  • string CustomFilterType
    Eigener Typname, wenn FilterType „custom“ ist.
    Hinweis: Wird als customType an den Client ausgeliefert.
  • int Width
    Breite des UI-Elements. Wird bei „custom“ nicht zwingend ausgewertet (Entwickler ist dafür zuständig).
    Hinweis: Wird als width an den Client ausgeliefert.
  • ListControlFilterItem[] Items
    Enthaltene Filterelemente.
    Hinweis: Wird als items an den Client ausgeliefert.
  • string DefaultSelectedKey
    Schlüssel (Key) eines Filterelements, welches direkt nach dem erstellen der Liste automatisch ausgewählt sein soll.
    Hinweis: Wird als defaultSelected an den Client ausgeliefert.

Der Typ muss außerdem die Methode

ListControlFilterItem GetItem(string key = null)

implementieren, um ein konkretes Filterelement aus dem Filter abrufen zu können.

ListControlFilterItem

Der Typ definiert einen einzelnen Filtereintrag, der in der Ui angezeigt werden kann.

  • Caption
    Anzeigetext des Filtereintrags
  • Key
    Hintergrundwert des Filtereintrags, der auch zum Server kommuniziert wird.

Hiervon abgeleitet ist:

ListControlCriteriaFilterItem

Der Typ implementiert zusätzlich zu ListControlFilterItem

  • Criteria
    Ein programmierter CriteriaOperator (Formel), der verwendet werden kann, um diesen Filter automatisch auf eine Query eines Orm-Typs anzuwenden.
    Hinweis: Funktioniert nicht mit nicht-Orm-Queries, dieser Parameter wird nicht serialisiert.

ListControlRowAction

Der Typ definiert eine Aktion, welche auf einer Datenzeile ausgeführt werden kann. Das beinhaltet die auszuführende Aktion selbst sowie verschiedene Anzeigedaten.

  • Guid Id
    Einzigartige ID der Aktion.
  • string Title
    Text des Tooltips, der über dem Icon der Aktion angezeigt wird.
  • string IconUrl
    URL des Icons, welches in der UI als Schaltfläche der Aktion verwendet wird.
  • string ActionMethodId
    ActionMethodId, welche über den Action-Framework aufgerufen wird, wenn die Aktion geklickt wird.
  • string VisibilityFunction
    Optional: Name einer JavaScript-Funktion, welche aufgerufen wird, um zu entscheiden, ob die entsprechende Aktion client-seitig gerendert wird oder nicht.
  • Dictionary<string, object> ActionParameters
    Optional: Key/Value-Paare, welche serverseitig ermittelt an die Aktion übergeben werden sollen. Diese stehen dann als CustomData-Objekt innerhalb der übergebenen Daten unter dem Schlüssel ActionParameters zur Verfügung.

Datenbezogene Models (C#)

Siehe GetData in den vorherigen Abschnitten

Wichtige client-seitige Typen (TypeScript)

ListControlCreateParameters

Wird zur Erstellung des Listensteuerelements verwendet.

  • anchor: ListContainer
    Ein HTML-DIV-Element, welches als Basiselement für das DevExtreme dxDataGrid verwendet wird.
  • locale: string
    Das Sprachkürzel des Benutzers (veraltet)
  • listDataController: string
    Name des Controllers, der die Daten für die Liste liefert. Das ist wirklich nur der Name (ListData, ohne Controller), der Controller muss sich in der Applikation befinden.
  • rowActions: ListRowAction[]
    Array mit Definitionen der Aktionen, welche über jeder Zeile eingeblendet werden, wenn der Benutzer mit der Maus darüber fährt.
  • columns: ListColumn[]
    Array mit Definitionen der anzuzeigenden Spalten.
  • toolbarItems: ListToolbarItem[]
    Array mit Definitionen der anzuzeigenden Toolbar-Items.
  • rowClickMethodId: string
    ActionMethodId der Aktion, die beim einfachen Klicken einer Listenzeile ausgeführt werden soll.
  • rowDoubleClickMethodId: string
    ActionMethodId der Aktion, die beim doppelten Klicken einer Listenzeile ausgeführt werden soll.
  • showTotalCount: boolean
    Flag, ob unter der Liste noch eine Zeile mit der Gesamtzahl an Zeilen angezeigt werden soll.
  • additionalServiceParameters: CustomData
    Liste von Key/Value-Paaren, die bei Anfragen an den angegebenen Controller immer genau so mitgeschickt werden sollen.
  • customProperties: CustomData
    Zusätzliche Daten bei Anpassungen

ListContainer

Das Interface erbt von HTMLDivElement und beinhaltet nach der Listenerstellung und während des Betriebes folgende Informationen:

  • customProperties: CustomData
    Zusätzliche Daten bei Anpassungen
  • ActiveFilters: CustomData
    Enthält alle derzeit aktiven Filterelemente (Key) pro Filter (Id).
  • ListInstance: List
    Die erstellte Instanz des dxDataGrid

List

Das Interface List erbt momentan einfach nur von DevExpress.ui.dxDataGrid und hat keine weiteren Inhalte. Referenz

ListRowAction

Das Interface definiert eine Aktion, welche auf einer Datenzeile ausgeführt werden kann und entspricht in seinen Inhalten dem C#-Typen ListControlRowAction (siehe C#-Typ: ListControlRowAction).

Die Angabe von VisibilityFunction und ActionParameters ist optional.

ListColumn

Das Interface ListColumn erbt momentan einfach nur von DevExpress.ui.dxDataGridColumn und hat keine weiteren Inhalte. Es entspricht den Inhalten von ListControlColumn (s. C#-Typ: ListControlColumn) und wird direkt vom dxDataGrid interpretiert. Referenz

ListToolbarItem

Das Interface ListToolbarItem erbt von DevExpress.ui.dxToolbarItem und beinhaltet als zusätzliche Information

type: string

Objekte des Typs ListControlFilterSelect (siehe C#-Typ: ListControlFilterBase / ListControlFilterMultiItemBase / ListControlFilterSelect) und ListControlFilterItem (siehe C#-Typ: ListControlFilterItem / ListControlFilterCriteriaItem) werden unter Zuhilfenahme der statischen Funktion CreateFilter auf der Klasse List.ToolbarItems in Objekte dieses Typs konvertiert.

Es ist möglich (wird aber im Standard nicht getan) der Toolbar außer den Filtern des Listen-Frameworks noch weitere, eigene Elemente hinzuzufügen. Referenz