Actions

Eine Klasse kann verschiedene Aktionen beinhalten welche im Kontext der Entität ausgeführt werden können.

Die Konfiguration ist dabei analog einem normalen Property mit einigen zusätzlichen Möglichkeiten:

Zuweisen der Aktion die ausgeführt werden soll inklusive Rückgabewert
Definition wie die Aktion angezeigt werden soll (in Listen, Detail etc.)

Die Builder Methode sieht wie folgt aus:

Builder.Add.Action(...)
ClassBuilder.Add.Action(...)

Um einen Body zuzuweisen stehen folgende Overloads zur Verfügung:

Methode	Beschreibung
`Body<Person, PersonService>((person, service) => service.Execute(person))`	Der `PersonService` wird über den IoC ausgelöst und die Aktion `Execute` mit der aktuellen Person ausgeführt.
`Body<List<Person>, PersonService>((people, service) => service.Execute(people))`	Der `PersonService` wird über den IoC ausgelöst und die Aktion `Execute` mit der aktuellen Liste von Personen ausgeführt. Diese Aktion ist hilfreich wenn eine Aktion z.B. auch auf einer Selektion von Objekten ausgeführt werden kann.
`Body<PersonService>((personService) => personService.Execute)`	Direkte Zuweisung eines Delegate. Die Signatur der Methode muss dabei einen Parameter vom Typ `IDataObject` oder einer Ableitung davon zur Verfügung stellen.
`Body<Person, PersonService>()`	Der `PersonService` muss das Interface `IActionAware<in IDataObject>` implementieren. Der `PersonService` selbst wird über den IoC aufgelöst.

Die generische Methode um eine Aktion direkt mit den MetaActionEventArgs auszuführen steht ebenfalls zur Verfügung. Es wird aber davon abgeraten diese zu verwenden. Die Abkapslung in Services erhöht die Testbarkeit der jeweiligen Aktionen und verhindert das Business-Logik direkt in die Builders geschrieben wird.

Jede Aktion kann definieren welche Änderungen sie vorgenommen hat und drückt diese über den Rückgabetyp aus.

Rückgabetyp	Beschreibung
`MetaActionResult.None()`	Keine Änderungen. Die Daten im Client werden nicht neu geladen.
`MetaActionResult.CallingObjectChanged()`	Das aufgerufene Objekt muss neu geladen werden.
`MetaActionResult.MultipleObjectsChanged()`	Das aufgerufene und alle verlinkten Objekte müssen neu geladen werden.

Als optionaler Parameter kann bei allen Methoden folgendes definiert werden:

Parameter

Beschreibung

FeedbackType

Kann definieren ob die Aktion erfolgreich war:

None (keine Meldung wird angezeigt)
Success
Warning
Error

DynamicString

Meldung die dem Benutzer angezeigt wird.

Soll zusätzlich zur Rückmeldung noch eine Navigation erfolgen so kann die Klasse NavigationLinkActionResult verwendet werden. Der NavigationLinkAspect muss dabei als Parameter zur Verfügung gestellt werden.

Aktionen auf Listen

Die oben beschriebenen Aktionen können auch auf Listen eingebunden werden. Dazu steht ein Overload zur Verfügung welcher eine Liste von Objekten zur Verfügung stellt. Dies kann hilfreich sein wenn eine Aktion z.B. auf eine Selektion von Objekten ausgeführt wird und nur ein Resultat erwartet wird.

Wird eine Aktion auf eine Liste von Objekten ausgeführt aber nur eine Methode unterstützt die Einzelobjekte behandelt so wird das letzte Resultat dem Client zurückgegeben und die restlichen verworfen.

Wenn Aktionen auf mehreren Objekten ausgeführt werden können so wird empfohlen immer eine Liste von Objekten zu unterstützen.

Aktionen mit Parameter

Einige Aktionen erfordern eine Eingabe um erfolgreich ausgeführt werden zu können.

Um eine Aktion mit Parametern auszustatten stehen dieselben Methoden wie oben beschrieben zur Verfügung mit der Ergänzung eines zusätzlichen Type-Argument welches den Parameter-Typ identifiziert.

Methode	Beschreibung
`Body<Person, Contact, PersonService>((person, contact, service) => service.Execute(person, contact))`	Der `PersonService` wird über den IoC ausgelöst und die Aktion `Execute` mit der aktuellen Person ausgeführt.
`Body<PersonService>((personService) => personService.Execute)`	Direkte Zuweisung eines Delegate. Die Signatur der Methode muss dabei einen Parameter vom Typ `IDataObject` und des entsprechenden Parameter enthalten oder einer Ableitung davon zur Verfügung stellen.
`Body<Person, Contact, PersonService>()`	Der `PersonService` muss das Interface `IActionAware<in TDataObject, TParameter>` implementieren. Der `PersonService` selbst wird über den IoC aufgelöst.

Der Parameter für die Aktion wird im Client über ein Popup abgefragt und danach an die entsprechende Aktion weitergeleitet. Es stehen dieselben Rückgabetypen wie bei einer normalen Aktion zur Verfügung.

Aktionen mit Bestätigung

Aktionen können optional eine Bestätigung des Benutzers einholen. Dies ist hilfreich wenn eine Aktion potentiell schwerwiegende Konsequenzen haben könnte.

Das folgende Snippet fragt nach der Bestätigung des Benutzers bevor die Aktion ausgeführt wird:

builder.Get.Class(nameof(elements.Person)).Add.Action("TestActionWithConfirmation")
        .RequiresConfirmation()
        .Content(German, "Inhalt")
        .Title(German, "Titel")
        .ContinueCaption(German, "Weiter")
        .CancelCaption(German, "Abbrechen");

Die Captions sind optional. Wird nichts angegeben werden die Standard-Übersetzungen verwendet.

Platzierung von Aktionen

Für die Platzierung von Aktionen in einer Listen- und Detail-Ansicht, es gibt drei Möglichkeiten:

Selektion-Aktion: Buttons, die erscheinen, wenn man mehrere Elemente in einer Liste angewählt hat.
Aktionen anzeigen in einer Liste bzw. in einer Reihe.
Aktion wird in einer Reihe neben dem Trash Button, über die drei punkte angezeigt und wird auf einem Klick aufgerufen.

Listen-Ansichten

Bei den Listen Ansichten - ListLayout kann man die Aktionen über die Methode SetListAction() anhängen:

SetListAction(
  [NotNull] this T element, 
  bool showInListSelection = true, 
  bool showInListRow = true, 
  bool isOverflowByDefault = false)

list.Add.Link(metadata.Person.LowerCaseNameListAction)
        .Element.SetListAction(true, true, true);

Detail-Ansichten

Bei der Detailansicht - Detail Layout gib es ebenfalls drei Möglichkeiten um die Aktion zu platzieren:

Als eine Standard Aktion in der Sidebar.
In den Inhalt der Detail-Ansicht.
Es besteht die Möglichkeit ebenfalls die Aktion als primäre oder sekundäre Aktion anzuzeigen.

Eine Standard-Aktion in der Sidebar zu implementieren, muss folgendes Vorgehen eingehalten werden:
1. Es wird eine Variable als Aktionen deklariert und wird und die Sidebar Funktion wird dem Layout angehängt.

var sidebar = elements.Person.Add.Sidebar()

1.1 Anschliessend wird der Sidebar eine Aktion angehängt und über die Add. Action Methode die entsprechende Aktion aufgerufen.

var actions = sidebar.Add.Actions();
actions.Add.Action(metadata.Person.LowerCaseNameDetailAction);

1.2 Um eine Aktion in dem Detail Ansicht Inhalt platzieren zu können, muss man folgendes implementieren, im folgenden Beispiel werden wir die Aktion in einer Reihe integrieren:

row.Add.Link(metadata.Person.LowerCaseNameDetailAction);

In dem beiden Fällen ist es möglich die Art die Aktion zu steuern, ob es sich um eine primäre Aktion oder als eine sekundäre Aktion handelt. Die Methode IsClassAction beinhaltet drei Parameter, durch die die Optionen der Aktion gesteuert werden können.

showAsMainAction: Zeige es an als eine Hauptaktion
showAtStartOfGroup: Zeige es am Anfang der Gruppe von den Aktionen
isPrimary: Ist es eine primäre Aktion, hierdurch wird das Styling der Aktion geändert.

bool showAsMainAction = false,
bool showAtStartOfGroup = false,
bool isPrimary = false)

Elements.Controls.Add.Action("SampleAction").IsClassAction(true, true, true)

Die SampleAction ist in diesem Beispiel eine Hauptaktion, ist die erste Aktion in der Gruppe von Aktionen, und ist eine primäre Aktion, hierdurch wird das Styling angepasst.

Berechtigungen

Aktionen können grundsätzlich nur von authentifizierten Usern ausgeführt werden. Die Ausnahme bilden Aktionen die im Client direkt implementiert sind.

Standardmässig benötigt der User Lese-Berechtigung auf der Klasse auf welcher die Aktion sich befindet. Nur dann ist eine Ausführung möglich. Diese Restriktion kann pro Aktion angepasst werden um zu verhindern das Aktionen ausgeführt werden die Daten verändern:

      Elements.Person.Add.Action("SampleAction")
        .PermissionRequired(GenericOperation.Create);

Eine so definierte Aktion kann nur von einem User ausgeführt werden welcher über “Create” Berechtigung auf der Entität verfügt.

Erweiterte Restriktionen müssen aktuell in der Aktion selbst implementiert werden.

Resultate

Das Resultat einer Aktion ist grundsätzlich frei wählbar. Standardmässig werden aber die MetaActionResult unterstützt und vom Client interpretiert.

Damit das zusammenstellen dieses Resultat etwas einfacher ist kann der MetaActionResultBuilder verwendet werden.

    var result = MetaActionResult.Builder()
      .WithChanges(MetaActionChanges.CallingObject)
      .WithAbsoluteNavigation("https://encodo.ch", OpenInTarget.Popup)
      .WithFeedback(MetaActionFeedbackType.Warning, new DynamicString(("en", "Custom Message")))
      .Build();

Dies produziert ein Resultat welches zur angegebenen Website navigiert.

Es stehen weitere Signaturen für eine Objekt-Navigation und Klassen-Navigation (Liste) zur Verfügung. Auch kann übersteuert werden welche Objekte sich geändert haben und was für ein Feedback genau gegeben werden soll.