Dynamischer Katalog: Formularelemente

Geändert am Di, 20 Aug um 10:00 VORMITTAGS

Das Plug-In bietet die Möglichkeit Feldbeschreibungen eines Mandant-Katalog bzw. einer URL zu laden und im Designer als bereits konfigurierte Elemente anzubieten. Das ist nützlich, wenn man zum Beispiel Formularvorlagen flexibel speichern möchte, um sie in jedem Mandanten des Systems zu verwenden. Manchmal auch, um speziell konfigurierte Felder, die man immer wieder benötigt, nachnutzen zu können.

Inhalt

Konfiguration der Plugin-Bundle-Properties

Schlüssel	Pflichtfeld	Bedeutung
com.xima.custom.catalogue.name*	Ja	Nachdem ein "Katalog" in „Dateien & Templates“ -> „Dateien“ des Mandanten hinterlegt wurde, fügt man den Namen der Datei hier ein.
com.xima.custom.catalogue.url	Nein	Ist eine URL hinterlegt, werden Kataloginformationen nicht mehr aus den Ressourcen des Mandanten geladen, sondern von der entsprechenden URL. Beim Laden des Kataloges setzt sich die URL anschließend aus den Werten der Parameter: com.xima.custom.catalogue.url + com.xima.custom.catalogue.name zusammen. Fehlende / werden automatisch ergänzt

Hinweis
Wenn Kataloge über Dateien und Templates geladen werden sollen, kann das Plug-In nur als Mandant Plug-In verwendet werden. Das heißt, dass das Plug-In im Mandanten installiert werden muss. 

Bei der Verwendung von Katalogen, die über eine URL angebunden werden, kann das Plug-In als 
System- oder Mandant Plug-In verwendet werden.

Verwenden des Kataloges in Mandant Ressourcen

Zunächst wird das "dynamischer Katalog"- Plug-In in dem gewünschten Mandanten installiert.

Hier befinden sich die zwei Dateien, die dem Plug-In von Haus aus zur Verfügung stehen. Die Dateien mit dem Namen catalogue.json & form4676.json werden unter Dateien & Templates > Dateien des Mandanten hochgeladen, in dem auch das Plug-In installiert wurde.

Jeder neue Katalog, der hinzufügt werden soll, wird ebenfalls dort hinterlegt und die Beschreibung des Kataloges erfolgt im JSON-Format.

Der Name der Datei wiederum wird in den Plug-In-Einstellung bei Mandant > Plugins unter com.xima.custom.catalogue.name* eingetragen.

Auf der rechten Seite bei "catalogue.json" kann der eigene Katalog mit seinem Datei-Namen hinterlegt werden.

Die Beschreibung des Kataloges erfolgt innerhalb der Datei und in Form eines JSON-Arrays. Hier werden die Metainformationen des gewünschten Kataloges hinterlegt. Es kann in einer Katalog-Datei auf mehrere JSON-Dateien referenziert werden.

Die Metainformationen müssen mindestens „name“ und „id“ pro Katalog enthalten.

Für die bereitgestellten Beispieldateien würde dies folgendermaßen aussehen:

Die Datei, die die Beschreibung des Kataloges enthält, heißt catalogue.json. In der catalogue.json befinden sich nun die Metainformationen zu der JSON-Datei form4676.json.

Die Metainformationen für form4676.json müssen also in der catalogue.json folgendermaßen hinterlegt sein:

[
 {
 "name":"Basiselemente", /* Name, wie er im Formulardesigner unter externer Katalog zu sehen ist*/
  "id":"form4676.json", /*die Referenz auf die Katalog-Datei*/
 "parse": "form" /*Die Übersetzung in ein Formular*/
 },

/* Nachfolgend, ein weiterer eigener Katalog: */
 {
 "name":"Ich bin Katalog II",
 "id":"elements_2.json"
 }
]

Bei "name" wird der Name der Elementliste eingetragen, so wie diese auch im Designer bei "externer Katalog" angezeigt wird.

Die "id" muss eindeutig sein und ist der Name der Datei, in der die Elementbeschreibungen zu den Formularfeldern hinterlegt werden muss.

Hinweis:
Wollen Sie das Beispiel hier aus der Hilfe verwenden, ist es unabdingbar, die Informationen die mit dieser Auskommentierung hinterlegt sind /*...*/ in der Katalogbeschreibung zu entfernen.

Die Elementbeschreibung in der JSON-Datei

Damit ein Element des Formulars als Katalogfeld angeboten wird, muss es über ein Label verfügen und vom Typ Textfeld, Textarea, Auswahl, Checkbox oder Upload sein!

In Bezug auf das Beispiel der beiden JSON-Dateien, die zu dem Plug-In gehören, soll sich an dieser Stelle mit dem Inhalt der form4676.json beschäftigt werden. Denn die Elementbeschreibung bezieht sich auf Formularelemente. Speziell auf die Typen Textfeld, Textarea, Auswahl, Checkbox oder Upload.
Andere JSON-Inhalte können vom Plug-In nicht erkannt und verarbeitet werden. Entsprechend gilt für die nachfolgenden Punkte, dass es sich um Beschreibungen der Elemente eines Formulars handelt.

Parameter innerhalb der Katalogbeschreibung

Schlüssel	Pflichtfeld	Bedeutung
name	ja	Angezeigter Name im Designer
id	ja	Eindeutiger Identifikator des Kataloges / Dateiname der Mandantressource
type	nein	"form" – Verwenden eines in FORMCYCLE angelegten Formulars als Elementliste "url" – Laden einer Elementbeschreibung über eine URL
form	wenn "type" gleich form	ID des Formulars das als Elementliste verwendet werden soll
url	wenn "type" gleich url	Adresse von welcher die Elementbeschreibungen geladen werden soll
parse	nein	"form" – Muss gesetzt werden, wenn es sich bei der Elementbeschreibung um eine Formularbeschreibung aus dem FORMCYCLE Designer handelt (über die Option Formular lokal speichern)

Vorhandenes Formular als Elementbeschreibung verwenden

Soll ein vorhandenes Formular als Katalogbasis verwenden werden, kann in der Katalogbeschreibung zusätzlich die Information "type" form und die "id" des Formulars hinterlegt werden.

[ 
  { 
    "type":"form", 
    "name":"Formular", 
    "id":"formular_1008", 
    "form":"1008" 
  }
]

Damit die Metainformationen, das Formular auch übersetzen also parsen können, ist es notwendig, bei Mandant > Dateien & Templates > Dateien die JSON zu hinterlegen.

Aus einem Formular lässt sich diese sehr gut generieren. Im Folgenden eine Schritt für Schritt-Anleitung zur Erstellung einer JSON-Datei aus einem Formular.

Anleitung zur Erstellung einer JSON aus einem Formular

Um aus einem Formular eine JSON-Datei zu machen, muss man entweder in ein bestehendes Formular in den Formulardesigner wechseln oder aber man legt ein neues Formular an. In diesem neuen Formular müssen die gewünschten Felder in den Designer gezogen und so zusammengestellt werden, wie diese später gespeichert und gedownloadet werden soll.

Nun muss das Formular im Formulardesigner exportiert werden.

Über Exportieren steht die Option frei Formulardesigner

Es öffnet sich an dieser Stelle ein Pop-up - Fenster, bei dem eine Auswahl möglich ist, ob nur das Formular oder nur der Workflow gedownloadet werden soll.

Hier kann man ein Formular getrennt von seinem Workflow speichern. Die Ausgabe der Datei erfolgt als JSON. "Nur Webformular" wird für den dynamischen Katalog verwendet.

Das Webformular, dass nun exportiert werden soll, wird als JSON-Datei gespeichert, also jenes Format, das für den dynamischen Katalog gebraucht wird. Diese JSON-Datei kann nun in dem eigenen Mandanten in Dateien & Templates hochgeladen werden.

Nun müssen Sie die Metainformationen Ihres Formulars im JSON-Format, in eine Datei wie z.B. die catalogue.json eintragen. Damit der externe Katalog, die im Formular verwendeten Formularfelder anzeigen kann.

Am Ende sollte das Ergebnis im Formulardesigner so aussehen:

Damit man die Elementliste im Formulardesigner sieht, muss man den Reiter "Externer Katalog" klicken. Danach werden die Elemente des Formulars angezeigt, dessen Metainformationen vorher in die catalogue.json geschrieben wurden.

Hinweis
Mussfelder, die über den externen Katalog angezeigt werden, sind rot hervorgehoben. Alle anderen Felder werden schwarz angezeigt.

Elementbeschreibung über eine URL laden

Um eine Elementbeschreibung über eine URL zu laden, benötigt man zunächst eine Datei im JSON-Format, die die Metainformationen von Formularbeschreibungen enthält. Eine andere JSON-Datei akzeptiert formcycle nicht.

Als Beispiel soll diese URL dienen, die JSON enthält, wiederum Metainformationen zu anderen Katalogen.

https://customer.formcycle.eu/index.php/s/CDOc2axLSJwXU5O/download

Diese URL muss nun in zwei Teile zerlegt werden, einmal in die Basis-URL und einmal in den Katalognamen.
Wie im nachfolgenden Beispiel zu sehen, ist der Katalogname: CDOc2axLSJwXU5O/download

Die Basis-URL bezeichnet die URL bis zu dem Namen der JSON-Datei, der Name der hinterlegten JSON-Datei gehört in com.xima.custom.catalogue.name*

Die Basis-URL, die in der com.xima.custom.catalogue.url-Property eingetragen wird, setzt sich wieder zusammen mit dem Wert aus dem Parameter com.xima.custom.catalogue.name. Das ergibt dann die vollständige URL unter welcher die Katalogbeschreibung geladen wird.

Verwenden eines externen Kataloges über eine URL

Soll die Katalogbeschreibung nicht über die Mandantressourcen, sondern über eine URL geladen werden, muss für die Property com.xima.custom.catalogue.url eine gültige Basis-URL zu den Katalogdateien hinterlegt werden. Die Beschreibung erfolgt analog zu dem unter Punkt 3 gezeigten Schema.