Startseite Rules Engine – Erste Schritte
🔎

Rules Engine – Erste Schritte

Sebastian Herd
Von Sebastian Herd
• 4 Artikel

2. Arbeit mit Formularfeldern

Erstellen der Formularfelder Allgemeine Vorgehensweise: Erstellen Sie unter Verwendung des Paperless-Builders wie gewohnt per Drag-and-Drop alle Blöcke, die Sie für Ihr Formular benötigen. Blöcke, die während des Ausfüllens des Formulars nur unter bestimmten Bedingungen angezeigt werden sollen, können ebenfalls zu diesem Zeitpunkt bereits angelegt werden. Später werden Sie diese mit Hilfe von Sichtbarkeits-Regeln entsprechend dynamisch aus- und einblenden. Sie sollten für jeden Block einen individuellen Slug festlegen. Dabei ist es sinnvoll, Slugs ausdrucksstark, aber möglichst kurz zu wählen. Später werden Sie über die Slugs in JavaScript-Code auf Formularblöcke und deren Eigenschaften zugreifen. Sie können den Slug eines Blockes bearbeiten, indem Sie diesen entweder direkt in der Kopfzeile der Block-Einstellungen anpassen, oder im aufklappbaren Reiter Erweitert bearbeiten. Für Blöcke mit Auswahloptionen, also Radio- und Checkbox-Blöcke, sollten Sie außerdem für jede Auswahloption einen individuellen Slug vergeben. Über diesen Slug können Sie später erfragen, ob die entsprechende Auswahloption gewählt wurde. Sie können die Slugs der Auswahloptionen eines Blockes bearbeiten, indem Sie im Reiter Optionen auf Erweitert klicken (bis einschließlich vier Auswahloptionen), oder auf den Button Auswahloptionen verwalten klicken (ab fünf Auswahloptionen). Beispiele im Formular: Erstellen Sie zunächst ein neues Paperless-Formular. Sie werden in diesem Schritt alle erforderlichen Blöcke im Formular anlegen. Diese sind zunächst wie gewohnt einfache, statische Blöcke. In Schritt 3 und 4 werden Sie diese nachträglich mit dynamischem Verhalten versehen. Nachfolgend werden alle Blöcke im Detail beschrieben. Das fertige Formular soll am Ende folgendermaßen aussehen: Fragen Sie zunächst unter Verwendung von Texteingabe-Blöcken die Kontaktinformationen des Teilnehmers ab: In den Einstellungen der jeweiligen Blöcke vergeben Sie dabei passende Slugs. Vergeben Sie die folgenden Slugs: First Name: first_name Last Name: last_name E-Mail Address: email Contact Number: phone Als nächstes fragen Sie mit Hilfe eines Radio-Blocks den Besucher-Typ des Teilnehmers ab. Versehen Sie den Block mit dem Slug registration_type. Auf Basis des gewählten Typs, soll sich das Dokument später dynamisch anpassen. Daher ist es wichtig, auch die Auswahloptionen mit passenden Slugs zu versehen: Es folgen: Ein Datei-Upload-Block, mit welchem Studenten ihre Studienbescheinigung hochladen können. Slug: cert_enrollment Ein weiterer Radio-Block, mit welchem freiwillige Helfer ihre Wunsch-Schicht angeben können. Slug: shift_preferences Beachten Sie, für die Auswahloptionen auch wieder Slugs zu vergeben: Ein stylisierter Gruppen-Block mit einem Text-Block, der freiwillige Helfer und solche Teilnehmer, die einen Vortrag halten werden, darauf hinweisen soll, dass der Veranstaltungsorganisator in Kürze Kontakt aufnehmen wird. Slug: note Daraufhin sollen alle Teilnehmer, die nicht als Studierende teilnehmen, die Möglichkeit haben, sich mit einem Checkbox-Block für Workshops anzumelden, welche als Ergänzung zu den allgemein zugänglichen Vorträgen angeboten werden. Slug: workshop_selection Vergeben Sie auch hier wieder Slugs für die einzelnen Auswahloptionen: 1. Textblöcke Außerdem bekommen alle Nicht-Studierenden ein Konferenz-Shirt. Ein weiterer Text-Block soll Teilnehmenden den T-Shirt Aufdruck anzeigen, der auf Basis ihrer Angaben erstellt wird. Wie Sie Text in Text-Blöcken mit Hilfe von Variablen dynamisch anpassen können, lernen Sie in Schritt 4 dieses Guides. Slug: shirt_text Teilnehmenden soll außerdem in einem weiteren Text-Block der individuell angepasste Preis für die Konferenzteilnahme angezeigt werden. Slug: price_text 2. Kontodaten-Block Im Anschluss soll allen zahlenden Teilnehmenden ein Kontodaten-Block angezeigt werden, um ihre Zahlungsinformationen zu hinterlegen. Slug: payment_details 3. Unterschrift Block Abschließend können Teilnehmende das Formular digital mit einem Unterschrift-Block unterschreiben. Slug: signature

Zuletzt am 15. August aktualisiert

3. Bedingte Sichtbarkeit

Regeln für Bedingte Sichtbarkeit 💡 In diesem Abschnitt werden Sie lernen, wie Sie mit dynamischen Regeln die Sichtbarkeit einzelner Blöcke während des Ausfüllens steuern können. Eine Regel für Bedingte Sichtbarkeit erstellen: Wählen Sie zunächst den Block aus, für den Sie eine Bedingte Sichtbarkeitsregel implementieren wollen. Aktivieren Sie in den Blockeinstellungen den Schalter Bedingte Sichtbarkeit. Anschließend öffnet sich ein Code-Editor, in welchem Sie mit JavaScript eine Sichtbarkeitsregel formulieren können. 💡 Im Code-Editor können Sie beliebige JavaScript Funktionalität implementieren. Neben der Unterstützung von Auto-Complete bietet der Editor Ihnen außerdem nützliche Debug-Informationen, wie eine Übersicht über alle Elemente des Dokuments und die Ausgabe von Berechnungsergebnissen oder Fehlermeldungen in Echtzeit. Die Bedingte Sichtbarkeit eines Blockes kann jederzeit durch Klicken des Buttons Bedingte Sichtbarkeit in den Blockeinstellungen weiter angepasst werden. Beispiele im Formular: Der erste Block, der mit einer Bedingten Sichtbarkeit versehen werden soll ist der Datei-Upload-Block für Studienbescheinigungen mit dem Slug cert_enrollment. Dieser soll nur Studierenden angezeigt werden. Folgen Sie dafür zunächst den oben genannten Schritten 1 bis 3, um die Bedingte Sichtbarkeit für diesen Block zu aktivieren. Im Code-Editor kann nun anhand von JavaScript-Code eine Regel formuliert werden: blocks.registration_type.options.student.selected; Die Bestandteile des Code-Snippets kurz erklärt: blocks ist ein fester Bestandteil der Rules Engine API und ermöglicht den Zugriff auf alle Blöcke eines Formulars anhand ihrer Slugs. registration_type ist der Slug des Radio-Blocks, mit dem Teilnehmende ihren Besuchertyp wählen können. Alle Blöcke können über ihren Slug nach dem Schema blocks.<slug> angesprochen werden. options ist ebenfalls ein fester Bestandteil der Rules Engine API und ermöglicht für Radio- und Checkbox-Blöcke Zugriff auf alle Auswahloptionen. student ist der Slug einer konkreten Auswahloption. Auswahloptionen können ähnlich wie Blöcke ebenfalls über ihre Slugs nach dem Schema options.<slug> angesprochen werden. selected ist ebenfalls fester Bestandteil der Rules Engine API und gibt für die jeweilige Auswahloption zurück, ob diese gerade ausgewählt ist, oder nicht. Es wird also aus allen Blöcken (blocks), für den Block mit dem Slug registration_type überprüft, ob aus dessen Auswahlmöglichkeiten (options) die Option mit dem Slug student ausgewählt (selected) wurde. Der Radio-Block für Helferschichten (shift_preferences) soll hingegen lediglich freiwilligen Helfern angezeigt werden. Analog zum vorherigen Block, lässt sich diese Regel mit folgendem Code-Snippet umsetzen: blocks.registration_type.options.volunteer.selected; Alternativ lässt sich der Auswahlstatus einer Option auch über die Funktion isOptionSelected() abfragen: blocks.registration_type.isOptionSelected("volunteer"); isOptionSelected(”<slug>”) ist fester Bestandteil der Rules Engine API und ist äquivalent zu options.<slug>.selected , profitiert jedoch nicht im gleichen Maße von den Auto-Complete Funktionen des Editors und ist daher weniger intuitiv in der Benutzung. Die Block-Gruppe mit Hinweistext (note) soll freiwilligen Helfern (volunteer) und Vortragenden (speaker) angezeigt werden. Sie können die Ergebnisse der jeweiligen Abfragen mit logischen Ausdrücken, z.B. einem ODER (||), verknüpfen um mehrere Optionen zu berücksichtigen. blocks.registration_type.options.volunteer.selected || blocks.registration_type.options.speaker.selected; Da sich der Preis, den der Teilnehmer zu zahlen hat, erst ermitteln lässt, wenn dieser einen Besuchertyp gewählt hat, soll der Texteingabe-Block für den Preis erst angezeigt werden, wenn eine Auswahloption des Blocks registration_type ausgewählt worden ist. blocks.registration_type.hasOptionSelected(); hasOptionSelected() ist fester Bestandteil der Rules Engine API und gibt für Radio-Blöcke Auskunft, ob mindestens eine Auswahloption ausgewählt ist. Die beiden Blöcke workshop_selection und shirt_text sollen allen Teilnehmern außer Studenten angezeigt werden, da diese zwar kostenlos teilnehmen dürfen, aber im Gegenzug keine Workshops buchen können und kein Konferenz-Shirt erhalten. Sie können mehrere Blöcke mit der gleichen Regel versehen, indem Sie diese zunächst gruppieren. Wählen Sie hierfür die betreffenden Blöcke aus und pressen Sie anschließend Strg + G . Die Gruppe kann über den Befehl Strg + Shift + G bei Bedarf wieder aufgelöst werden. Gruppieren Sie nun die beiden Blöcke workshop_selection und shirt_text und versehen Sie die Block-Gruppe mit der folgenden Regel: blocks.registration_type.hasOptionSelected() && !blocks.registration_type.options.student.selected; Hier werden wieder zwei Abfragen mit einem logischen Ausdruck, nämlich einem UND (&&) verknüpft. Zunächst wird abgefragt, ob NICHT (!) die Option student ausgewählt ist. Da dies allerdings auch vor dem Ausfüllen immer bereits der Fall ist und die Gruppe somit von Beginn an angezeigt werden würde, wird mit hasOptionSelected() zusätzlich geprüft, ob überhaupt schon eine Option des Blocks registration_type ausgewählt ist. Gruppen sparen Zeit und Aufwand, wenn mehrere Blöcke mit der selben Sichtbarkeitsregel versehen werden sollen. Wird die Gruppe später wieder aufgelöst, verfällt die Regel allerdings für alle Blöcke der Gruppe.

Zuletzt am 15. August aktualisiert

4. Variablen

Regeln als Variablen In manchen Fällen ist es sinnvoll, Regeln nicht pro Block zu definieren, sondern als formularweite JavaScript Variable anzulegen. Eine solche Variable kann wiederum in einzelnen Blöcken abgefragt werden, um deren Bedingte Sichtbarkeit zu bestimmen. Dies ist besonders sinnvoll für Regeln, die für viele Blöcke relevant sind, und / oder deren Berechnung aufwändiger ist. Darüber hinaus kann das Ergebnis der Regel-Berechnung als Variable in Text-Blöcken verwendet werden. Eine Variable erstellen: Klicken Sie auf den Reiter Regeln am rechten Bildschirmrand. Klicken Sie anschließend auf das Plus-Zeichen, um eine neue Regel zu erstellen. Wählen Sie in der Maske den Typ JavaScript Variable. Vergeben Sie einen kurzen, aber ausdrucksstarken Namen für die neue Regel. Klicken Sie nun auf Erstellen. Anschließend öffnet sich ein Code-Editor, in welchem Sie mit JavaScript eine Regel formulieren können. Beispiele im Formular: JavaScript Variablen für Bedingte Sichtbarkeit nutzen: Anhand des payment_details Blocks werden Sie nun zunächst lernen, wie eine JavaScript Variable für die Bedingte Sichtbarkeit verwendet werden kann. Legen Sie dazu, wie zuvor beschrieben, eine JavaScript Variable has_to_pay an. Das Ziel ist, zu überprüfen, ob der Teilnehmer einem der Besuchertypen regular, vip, oder speaker angehört oder ob er einen Workshop gebucht hat. Beides führt dazu, dass der Teilnehmer eine Teilnahmegebühr zahlen muss und die Zahlungsdaten als Pflichtfeld angezeigt werden. Versehen Sie dafür die Variable has_to_pay mit folgendem Code: const payingAttendees = ["regular", "vip", "speaker"]; const isPayingAttendee = payingAttendees.includes(blocks.registration_type.selectedOption.slug); const workshopSelected = blocks.workshop_selection.anyOptionSelected(); isPayingAttendee || workshopSelected; ⚙️ selectedOption ist fester Bestandteil der Rules Engine API und gibt für Radio-Blöcke die ausgewählte Option zurück. ⚙️ slug ist fester Bestandteil der Rules Engine API und gibt den Slug einer Auswahloption zurück. Es wird also zunächst geprüft, ob der Slug des gewählten Besuchertyps regular, vip, oder speaker lautet. ⚙️ anyOptionSelected() ist fester Bestandteil der Rules Engine API und gibt für Checkbox-Blöcke Auskunft, ob mindestens eine Auswahloption ausgewählt ist Hier wird also geprüft, ob der Besucher mindestens einen der angebotenen Workshops ausgewählt hat. Anschließend können Sie in der Bedingten Sichtbarkeit des Blockes payment_details das Ergebnis der JavaScript Variable abfragen: tokens.has_to_pay; ⚙️ tokens ist fester Bestandteil der Rules Engine API und ermöglicht den Zugriff auf alle von Ihnen definierten JavaScript Variablen nach dem Schema tokens.<Name der Variable>. JavaScript Variablen im Text referenzieren: 💡 JavaScript Variablen können ähnlich wie Platzhalter auch direkt in Text-Blöcke integriert werden. Legen Sie hierfür zunächst eine neue JavaScript Variable mit dem Namen shirt_text an. Fügen Sie nun den folgenden Code ein, um den Vornamen, Nachnamen und den Besuchertyp des Besuchers zu einem String zusammenzusetzen: blocks.first_name.value + " " + blocks.last_name.value + ": " + blocks.registration_type.selectedOption.name + " Attendee" ⚙️ value ist fester Bestandteil der Rules Engine API und ermöglicht für Texteingabe-Blöcke den Zugriff auf den eingegebenen Text. ⚙️ name ist fester Bestandteil der Rules Engine API und gibt für Radio und Checkbox-Blöcke den Anzeige-Text der entsprechenden Auswahloption zurück. Klicken Sie anschließend in den Text-Block, den Sie zuvor zum Anzeigen des T-Shirt Aufdrucks angelegt haben (Slug: shirt_text), und fügen Sie die Variable am Ende des Textes ein. Die JavaScript Variable wird nun gelb unterlegt im Text angezeigt. Abschließend möchten Sie nun auch die Teilnahmegebühr anzeigen, die sich für jeden Teilnehmenden individuell aus dem gewählten Besuchertyp und der Anzahl ausgewählter Workshops ergibt. So soll der reguläre Preis 300 Euro betragen, der VIP-Preis 400 Euro und der Preis für Vortragende 100 Euro, während Studierende und Helfer keine Grundgebühr zahlen. Zusätzlich sollen für jeden gebuchten Workshop weitere 50 Euro hinzukommen. Erstellen Sie hierfür nun eine weitere Variable price mit folgendem JavaScript Code: const base_prices = { "regular": 300, "vip": 400, "speaker": 100, "volunteer": 0, "student": 0 }; const registration_type = blocks.registration_type.selectedOption.slug; const number_of_workshops = blocks.workshop_selection.selectedOptions.length; const workshop_price = 50 * number_of_workshops; const total_price = base_prices[registration_type] + workshop_price; total_price; ⚙️ selectedOptions ist fester Bestandteil der Rules Engine API und gibt für Checkbox-Blöcke alle ausgewählten Auswahloptionen zurück. Fügen sie die Variable price anschließend wie zuvor in den Text-Block price_text ein.

Zuletzt am 15. August aktualisiert