Auswahl eines Datensatzes in einer fremden Tabelle (Fremdschlüssel)

Version	v5.3
Datum	25.03.2019
Bundle	addOn/input
Package	input/foreignKey
Ersteller	Dominik Hisler

Die Datensatzauswahl ermöglicht es Datensätze einer beliebigen Tabelle zu durchsuchen und diese einfach oder mehrfach auszuwählen. Zudem können Datensätze bei Bedarf bearbeitet und angelegt werden.

Aufbau des Plugins

Alle Bestandteile sind im Plugin input/foreignKey zu finden. Integriert werden kann diese Art des Eingabefeldes durch die Modelling und die Datenbankwidgets. Zudem zu beachten ist dass sich dieses Plugin in die Prozesse von Datensatz-Speicherung und Datensatz-Auslesen einklinkt und die zu speichernden oder zu lesenden Daten entsprechend transformiert.

Eine Property einer Entitiy, welche durch dieses Plugin verwaltet wird, enthält entweder einen Integer oder ein Integer-Array und muss auch mit den gleichen Datentypen befüllt werden.

Verwendung

Verwendung bei einem Feld der Modelling

Folgende Mindestkonfiguration muss als Feldkonfiguration hinterlegt werden:

feature: "input/foreignKey.[single|multiple|editable]"
inputForeignKeyEditExternal: [false|true]
foreignKeyCriteria: [Zusätzliche Suchkriterien]
relation:
    repository: "[Tabellenidentifikator]"
    column: "[Spaltenidentifikator]",
    datapool: "[Datenpoolidentifikator]"

Verwendung bei einem Feld des Datenbankwidgets

Folgende Mindestkonfiguration muss in der widget.json bei einer Spalte hinterlegt sein:

{
	// [...],
	"formType": "feature",
	"feature": "input/foreignKey.[single|multiple|editable]",
	"configuration": {
		// [...],
		"foreignKeyCriteria": [Zusätzliche Suchkriterien]
		"inputForeignKeyEditExternal": [false|true],
		"relation": {
			"repository": "[Tabellenidentifikator]",
			"column": "[Spaltenidentifikator]",
            "datapool": "[Datenpoolidentifikator]"
		}
	 }
	// [...]
}

Konfiguration

Parametererklärung

Bezeichnung	Mögliche Werte	Beschreibung
`feature`	input/foreignKey.single input/foreignKey.multiple input/foreignKey.editable	Legt den Feature-Aufruf für brandbox fest. Der Funktionsumfang der einzelnen Möglichkeiten ist weiter unten beschrieben.
foreignKeyCriteria	Ein oder mehrere Einträge. Schlüssel des Eintrags entspricht einem eindeutigen Feldidentifikator und der Wert einem erwarten Wert im angegebenen Feld. Der Platzhalter `%` ist gestattet.	Legt ein oder mehrere zusätzliche Suchkriterien für mögliche Datensätze fest. Gemeinsam mit einem durch den Benutzer definierten Suchfilter werden alle Kriterien mit einer UND-Verknüpfung verbunden und damit die entsprechende Datenbanktabelle durchsucht.
inputForeignKeyEditExternal	`true` oder `false`	Legt fest, dass man direkt in einen ausgewählten Datensatz springen kann ohne die aktuellen Änderungen zu speichern. Hierzu wird bei aktiver Einstellung ein zusätzlicher Button neben dem Eingabefeld angezeigt. Diese Einstellung wird nur beachtet, wenn der Wert von `feature` auf `input/foreignKey.editable` gesetzt ist.
`repository`	Eindeutiger Identifikator einer Datentabelle	Aus der hier angegebenen Tabelle werden die auswählbaren Datensätze ausgelesen.
`column`	Eindeutiger Identifikator eines Feldes	Werden auswählbare Datensätze zur Auswahl präsentiert oder durchsucht wird dieses Feld genutzt.
`datapool`	Eindeutiger Identifikator eines Datenpools	Diese Eigenschaft ist gilt ausschließlich für Tabellen welche über die Tabellenstrukturen definiert wurden. Hier muss ein entsprechender Identifikator hinterlegt werden. Diese Eigenschaft darf auf einen leeren Wert gesetzt werden. Hierbei wird der Datenpool automatisch ermittelt wenn die aktuelle Tabelle und die Tabelle, auf welche der Fremdschlüssel zeigt, eine Tabellenstruktur-Tabelle ist und zuvor ein entsprechender Datenpool geöffnet wurde.

Funktionsumfänge

Wert in `feature`	Beschreibung
input/foreignKey.single	Einfaches Auswahlfeld ohne erweiterte Funktionen
input/foreignKey.multiple	Feld mit Mehrfachauswahl von einem oder mehreren Datensätzen. Keine Bearbeiten- und Anlegen-Funktion.
input/foreignKey.editable	Einfach-Auswahlfeld für einen Datensatz mit Buttons für die Bearbeitung und das Anlegen eines neuen Datensatzes. Wurde die Option `inputForeignKeyEditExternal` auf `true` gesetzt wird hier zusätzlich ein Button angezeigt welches direkt zu dem ausgewählten Datensatz führt.

Events

Methode	Eingabe	Rückgabe	Beschreibung
`getCriteria`	`array`	`array`	This event can be subscribed to when it is neccessary to manipulate the possible entries of a foreign key input field. The subscribers are expected to manipulate the array of criteria that is processed when a foreign key input field is searching for its possible entries.
`getParameter`	base\widget\lib\field array	`array`	This event can be subscribed to when it is neccessary to manipulate the array of parameters that are provided to the search function of a foreign key input field when it searches for its entries.
`getQueryBuilderCriteria`	`array` `base\widget\lib\widget\interfaces\columnInterface` `doctrine\lib\repository\repositoryAbstract`	`array`	This event can be subscribed to when it is neccessary to manipulate the possible results when searching for a foreign key value by using the search filter in uiBase. The subscribers are expected to manipulate the array of criteria that is processed when "component/querybuilder" build the search query.
`save`	`doctrine\lib\entityAbstract` `array`	`void`	This event can be subscribed to when it is neccessary to mainpulate the save proccess when creating a new dataset via the "Create dataset"-button of the foreign key input field.
`onPopulateButton`	`foreignkey\lib\event\dto\dtoPopulateButtons` `styleguide\brandbox\entity\button[]` `string`	`void`	This event can be subscribed to when it is neccessary to add or remove buttons from the foreign key input field.