====== User Defined Fields - Zusatzfelder ======

Ab Version 3.3 ist es möglich, FH-Complete mit User Defined Fields zu erweitern.
Derzeit können Personen und Prestudenten mit Zusatzfeldern erweitert werden.
Dadurch können bei Interessenten, Studierenden und Mitarbeitern zusätzliche Felder hinzugefügt werden.
Diese können im FAS verwaltet und auch wieder exportiert werden.

===== Features von UserDefinedFields =====

  * Verschiedene Arten von Eingabefeldern
     * Textfeld
     * Dropdown
     * Checkbox

  * Validierung der Eingabe mit Regular Expression
  * Dynamische Dropdowns die aus der Datenbank befüllt werden
  * Mehrsprachige Bezeichnung
  * Default Werte
  * Sortierung der Felder

===== Hinzufügen von UserDefinedFields =====

Um UserDefinedFields hinzuzufügen, muss in der Datenbank in der Tabelle system.tbl_udf definiert werden welche UDF in welcher Tabelle zur Verfügung stehen sollen. Dies wird mit Hilfe eines JSON Schema definiert.

Um Beispielsweise die Schuhgröße erfassen zu können wird in der Tabelle system.tbl_udf folgender Eintrag hinzugefügt:

**schema**: public \\
**table**: tbl_person \\
**jsons**: \\
<code>
[{
	"name": "udf_schuhgroesse",
	"description": "udf/schuhgroesseDescription",
	"placeholder": "udf/schuhgroessePlaceholder",
	"title": "udf/schuhgroesseTitle",
	"type": "dropdown", 
	"sort":1,
	"defaultValue":"43",
	"listValues": {
		"enum": [
		 "42","43"
		]
	  },
        "requiredPermissions": ["basis/person"]
}]
</code>

Die Bezeichnungen werden mehrsprachig erfasst und daher im Phrasensystem in der Datenbank abgelegt. Dazu muss für die app "core" die Phrase "udf/schuhgroesseDescription" und "udf/schuhgroessePlaceholder" erstellt werden.
Dies erfolgt in den Tabellen system.tbl_phrase, system.tbl_phrasentext und system.tbl_app.

Nachdem die Einträge angelegt wurden, werden die Eingabefelder im FAS im Karteireiter Zusatzfelder angezeigt:
{{:fas:udf_fas.png?800|}}

===== Hintergrundinformationen =====

In der Datenbank existiert die Tabelle system.tbl_udf in dieser wird gespeichert welche Tabellen mit UserDefinedFields erweitert werden können.

<code>
system.tbl_udf
  table_schema varchar
  table_name varchar
  udf_schema jsonb
</code>

Die Grundstruktur wie das udf_schema JSON aussieht wird in einem eigenen JSON Schema definiert. Dieses wird im Filesystem abgelegt.
udfmasterschema.json

In vordefinierten Tabellen wird eine Spalte udf_values hinzugefügt. In dieser Spalte werden die Daten der UserDefinedFields gespeichert.

zB 
<code>
public.tbl_person
  person_id
  vorname
  nachname
  ....
  udf_values jsonb
</code>

==== Aufbau udfmasterschema.json ====

<code>
{
	"title": "UDF",
	"type": "object",
	"tableswhitelist":{
		"type": "string",
		"enum": ["tbl_person", "tbl_prestudent","tbl_mitarbeiter","tbl_lehrveranstaltung","tbl_lehreinheit"]
	},
	"properties": {
		"name": {
			"type": "string"
		},
		"description": {
			"type": "array",
		},
		"placeholder": {
			"type": "array",
		},
		"title":{
			"type": "array",
		},
		"type": {
			"type": "string",
			"enum": ["checkbox","textfield","textarea","date","dropdown","multipledropdown"]
		},
		"sort":{
			"type": "integer"
		},
		"defaultValue":{
			"type": "string"
		},
		"validation":{
			"type": "object",
			"properties": {
				"required":{
					"type": "boolean"
				},
				"min-length":{
					"type": "integer"
				},
				"max-length":{
					"type": "integer"
				},
				"min-value":{
					"type": "integer"
				},
				"min-value":{
					"type": "integer"
				},
				"regex":{
					"type": "object",
					"properties": {
						"language": "string",
						"expression": "string"
					}
				}
			},
		},
		"listValues":{
			"type": "object",
			"properties": {
				"sql":{
					"type":"string"
				},
				"enum":{
					"type":"array"
				},
			},
		},
	},
	"required": ["type","name"]
}
</code>

==== Aufbau udf_schema in system.tbl_udf ====

<code>
[{
	"name": "udf_schuhgroesse",
	"description": "udf/schuhgroesseDescription",
	"placeholder": "udf/schuhgroessePlaceholder",
	"title": "udf/schuhgroesseTitle",
	"type": "dropdown", 
	"sort":1,
	"defaultValue":"43",
	"validation": {
		"required":true,
		"min-value":10,
		"max-value":100,
		"regex":[{
				"language": "php",
				"expression": "/[1-9]*/"
		},{
				"language": "js",
				"expression": "/[0-9]*/"
		}]
	},
	"listValues": {
		"enum": [
		 "42","43"
		]
	  },
       "requiredPermissions": ["basis/person"]
},
{
	"name": "udf_kleriker",
	"description": "udf/klerikerDescription",
	"placeholder": "udf/klerikerPlaceholder",
	"title": "udf/klerikerTitle",
	"type": "checkbox", 
	"sort":2,
	"defaultValue":false,
        "requiredPermissions": ["basis/person"]
}]
</code>

   * **name:** Definiert den Namen des UserDefinedFields. Der Name muss zwingend mit udf_ beginnen!
   * **description:** Name einer Phrase - Die Phrase enthält einen Beschreibungstext des UDF der dann in der GUI als Infotext angezeigt wird
   * **placeholder:** Name einer Phrase - Die Phrase enthält einen Text der dann als Placeholder-Text bei Textfeldern angezeigt wird
   * **title:** Name einer Phrase - Bezeichnung des Eingabefeldes und der GUI
   * **type:** definiert die Art des Eingabefeldes (dropdown, checkbox, Textfeld, etc)
   * **sort:** Sortierreihenfolge innerhalb der UDF Felder
   * **defaultValue:** Defaultvalue - kann true, false oder ein Text sein
   * **listValues:** Definiert die auszuwählenden Einträge bei Dropdowns.
   * **validation:** Diverse Validierungen für das UDF (never performed if type is equal to checkbox, its value can only be **true** or **false**)
   * **Required rules:**
    * If required === false && value to be saved == (null || false) => validation avoided
    * If required == false && value to be saved != null => validation performed
    * If required == true => validation performed && value cannot be null
    * If required == true && value to be saved == (null || false) => raise error: required field
    * If raised error required field => validation is not performed

Bei den ListValues können derzeit keine Phrasennamen verwendet werden.
Statt enum kann hier auch sql verwendet werden. Dabei wird anstatt einer fixen Liste ein SQL Befehl hinterlegt der die Daten für das Dropdown liefert.
Der SQL muss 2 Spalten mit den verpflichtenden Titeln "id" und "description" zurückliefern, wobei "id" der Wert ist, der im UDF gespeichert wird und "description" der angezeigte Text im UDF.

==== Aufbau udf_values ====

Die Spalte udf_values in tbl_person enthält lediglich die Daten des Eingabefeldes:
<code>
{
     "udf_schuhgroesse": "44",
     "udf_kleriker": true,
     "udf_arrayvalue": ["1", "2"],
     "udf_nullvalue": null,
     "udf_stringvalue": "string"
}
</code>

==== Beispiele ====

<code>
[{
	"name": "udf_example1",
	"sort": 1,
	"type": "multipledropdown",
	"title": "udf/example1Title",
	"listValues": {
		"enum": [40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50]
	},
	"validation": {
		"regex": [
			{"language": "php", "expression": "/^[0-9]+$/"},
			{"language": "js", "expression": "/[0-9]*/"}
		],
		"required": true,
		"min-value": 40,
		"max-value": 50
	},
	"description": "udf/example1Description",
	"placeholder": "udf/example1Placeholder",
	"defaultValue": 42,
        "requiredPermissions": ["basis/person"]
},
{
	"name": "udf_example2",
	"sort": 2,
	"type": "dropdown",
	"title": "udf/example2Title",
	"listValues": {
		"enum": [[10, 50], [11, 51], {"id": 12, "description": 52}, [13, 53], [14, 54], [15, 55], [16, 56], [17, 57], [18, 58], [19, 59]]
	},
	"validation": {
		"regex": [
			{"language": "php", "expression": "/^[0-9]+$/"},
			{"language": "js", "expression": "/[0-9]*/"}
		],
		"required": false,
		"min-value": 10,
		"max-value": 19
	},
	"description": "udf/example2Description",
	"placeholder": "udf/example2Placeholder",
	"defaultValue": 15,
        "requiredPermissions": ["basis/person"]
},
{
	"name": "udf_example5",
	"sort": 5,
	"type": "dropdown",
	"title": "udf/example5Title",
	"listValues": {
		"sql": "WITH RECURSIVE t(id, description) AS (VALUES (10, 60) UNION ALL SELECT id + 1, description + 1 FROM t WHERE id < 20) SELECT id, description FROM t"
	},
	"validation": {
		"regex": [
			{"language": "php", "expression": "/^[0-9]+$/"},
			{"language": "js", "expression": "/[0-9]*/"}
		],
		"required": false,
		"min-value": 10,
		"max-value": 19
	},
	"description": "udf/example5Description",
	"placeholder": "udf/example5Placeholder",
	"defaultValue": 12,
        "requiredPermissions": ["basis/person"]
},
{
	"name": "udf_example3",
	"sort": 3,
	"type": "textarea",
	"title": "udf/example3Title",
	"validation": {
		"regex": [
			{"language": "php", "expression": "/^[a-zA-Z0-9]+$/"},
			{"language": "js", "expression": "/^[a-zA-Z0-9]+$/"}
		],
		"required": true,
		"min-length": 2,
		"max-length": 20
	},
	"description": "udf/example3Description",
	"placeholder": "udf/example3Placeholder",
	"defaultValue": "Ex3",
        "requiredPermissions": ["basis/person"]
},
{
	"name": "udf_example4",
	"sort": 4,
	"type": "textfield",
	"title": "udf/example4Title",
	"validation": {
		"regex": [
			{"language": "php", "expression": "/^[0-9]+$/"},
			{"language": "js", "expression": "/[0-9]*/"}
		],
		"required": false,
		"min-value": 1,
		"max-value": 99,
		"min-length": 1,
		"max-length": 2
	},
	"description": "udf/example4Description",
	"placeholder": "udf/example4Placeholder",
	"defaultValue": 1,
        "requiredPermissions": ["basis/person"]
},
{
	"name": "udf_example6",
	"sort": 6,
	"type": "checkbox",
	"title": "udf/example6Title",
	"validation": {
		"required": true
	},
	"description": "udf/example6Description",
	"defaultValue": false,
        "requiredPermissions": ["basis/person"]
}]
</code>