Zum Hauptinhalt springen
Alle KollektionenButler Knowledgebase
Webmaster Dokumentation
Webmaster Dokumentation

Eine detaillierte Anleitung zum Einbinden von Butlerapp in die Webseite.

Natallia Peshkur avatar
Verfasst von Natallia Peshkur
Vor über 2 Monaten aktualisiert

➤ Einführung

➤ Einrichtung

➤ Buchungsformular

➤ Veranstaltungstabelle

➤ Alle Filtermöglichkeiten

➤ Eingebundene Komponenten über GET Parameter steuern

➤ Probleme mit Google Ads
​

Einführung

Lieber Webmaster, bei Webbee haben wir uns das Ziel gesetzt nicht nur unserem Kunden die Arbeit leichter zu machen sondern auch dir bei der Einrichtung die Arbeit abzunehmen. Folgendes Vorgehen hat sich dabei beim Einbauen der Online-Buchung in die Website bewährt:

  1. Wir richten mit dem Kunden zusammen die Veranstaltungen ein.

  2. Wir erarbeiten mit dem Kunden zusammen, wo welche Buchen-Buttons oder Veranstaltungstabellen in die Seite eingebunden werden sollen

  3. Wir schicken dir ein Dokument, das beschreibt, wo du welche Buchungs-Links oder Veranstaltungstabellen in die Website einbauen sollst

  4. Du baust die Buchungs-Links und die Veranstaltungstabellen in die Website ein.

Bei Fragen kannst du dich gerne an uns unter der Nummer +49 30 16639833 oder per E-Mail team@butlerapp.de an uns wenden.

Im nachfolgenden ist die Integration im Detail beschrieben.

Einrichtung

1. Einbinden des Butlerapp Skripts

Es empfiehlt sich, das Skript am Ende des Body-Tags hinzuzufügen wie im gezeigtem Beispiel. Das Skript muss auf allen Seiten enthalten sein, auf denen Butlerapp Komponenten verfügbar sein sollen.

Achtung! TODO-INSERT-CUSTOMER-IDENTIFIER in der URL muss durch die Kundenkennung ersetzt werden. Wenn du dich unter der Adresse https://musterschule.butlerapp2.de in deinem Butler anmeldest, ist musterschule deine Kundenkennung.

<body> 
<!-- Website body --> 
<script src="https://TODO-INSERT-CUSTOMER-IDENTIFIER.butlerapp2.de/bee-react-form/bee-form.min.js"></script> 
<script>websail.init({ apiBaseUrl: 'https://TODO-INSERT-CUSTOMER-IDENTIFIER.butlerapp2.de' });</script> 
</body>

Hinweis: Die Init Methode init() muss nur einmal aufgerufen werden. Werden Inhalte z.B über AJAX nachgeladen wird dies automatisch mit DOM MutationObserver erkannt.

2. Erstellen einer Butlerapp Hauptseite

Erstelle eine leere Seite mit dem Pfad /w und füge die Butlerapp Hauptkomponente <div class="ws-element"></wsroot> an die Stelle ein, wo sonst der übliche Seiteninhalt wäre. Butlerapp rendert hier jetzt abhängig von der Adresszeile alle verfügbaren Komponenten: /w#/courses = Kurstabellen-Komponente oder /w#/bookcart = Buchungsformular.

Hinweis: Manche CMS Systeme z.B Jimdo entfernen unbekannte HTML Elemente. In diesem Fall kann anstatt eines HTML 5 Elements ein DIV Element verwendet werden. Vorher: <wsroot class="ws-element"></wsroot> Nachher: <div class="ws-element" data-ws-type="wsroot" data-ftagsnot="intern">. Alle in der Komponente verfügbaren Attribute erhalten zusätzlich den Prefix data- also z.B data-fcourses anstatt von fcourses, um standardkonform zu sein.

Buchungsformular

Anwendungsfälle

  1. Buchungsformular für alle Veranstaltungen (z.B wenn du einen "jetzt buchen" oder "alle Termine" Link im Hauptmenü der Internetseite einbauen möchtest)

  2. Buchungsformular für Veranstaltungen einer Kategorie (z.B wenn auf einer existierenden Veranstaltungs-Kategorieseite mit einem Button auf die Buchungsseite verlinkt werden soll)

  3. Buchungsformular für Veranstaltungen eines Veranstaltungsortes (z.B wenn auf einer Standortseite mit einem Button auf die Buchungsseite verlinkt werden soll)

  4. Buchungsformular für eine Veranstaltung (z.B wenn eine bestimmte Veranstaltung beworben werden soll)

  5. Buchungsformular für Veranstaltungen mit unterschiedlichen Merkmalen (wenn ein Buchungsformular auf einen bestimmten Anwendungsfall konfiguriert werden soll (Veranstaltungen in der nächsten Woche, mit Tags, u.s.w.) )

Einleitung

Standardmässig werden im Buchungsformular alle Veranstaltungen mit Filtermöglichkeiten nach Ort (wenn die Veranstaltungen an mehreren Orten stattfinden), Veranstaltungs-Kategorie und Monat angezeigt. Die Filtermöglichkeiten werden automatisch ausgeblendet, wenn diese in der URL bereits vorgegeben sind.

Buchungsformular für alle Veranstaltungen

  1. Beispiel Link: /w#bookcart

  2. Beispiel Komponente: <wsbookcart class="ws-element"></wsbookcart>

Buchungsformular für Veranstaltungen einer Kategorie

  1. Beispiel Link: /w#/bookcart?fcourses=snake_cased_category_name

  2. Beispiel Komponente: <wsbookcart class="ws-element" fcourses="snake_cased_category_name"></wsbookcart>

Im Backend findest du alle in "snake case" geschriebenen Kategorienamen im Feld "URL-Kürzel". Menüpunkt: "Zahnrad -> Veranstaltungskategorien"

Buchungsformular für Veranstaltungen eines Veranstaltungsortes

  1. Beispiel Link: /w#/bookcart?fplaces=snake_cased_category_name

  2. Beispiel Komponente: <wsbookcart class="ws-element" fplaces="snake_cased_place_name"></wsbookcart>

Im Backend findest du alle in "snake case" geschriebenen Kategorienamen im Feld "URL-Kürzel". Menüpunkt: "Zahnrad -> Adressen"

Buchungsformular für Veranstaltungen mit anderen Eigenschaften

Zusätzlich zu dem oben beschriebenen Filter "fcourses" und "fplaces" für Veranstaltungskategorien und Veranstaltungsorte sind weitere Filter Verfügbar, die flexibel miteinander kombiniert werden können. Diese sind im Abschnitt Alle Filtermöglichkeiten dokumentiert.

Veranstaltungstabelle

Anwendungsfälle

  1. Veranstaltungstabelle für alle Veranstaltungen (z.B wenn du einen "jetzt buchen" oder "alle Termine" Link im Hauptmenü der Internetseite einbauen möchtest)

  2. Veranstaltungstabelle für Veranstaltungen einer Kategorie (z.B wenn auf einer existierenden Veranstaltungs-Kategorieseite eine Tabelle mit den Terminen eingebaut werden soll)

  3. Veranstaltungstabelle für Veranstaltungen mit unterschiedlichen Merkmalen (z.B wenn eine Veranstaltungstabelle auf einen bestimmten Anwendungsfall konfiguriert werden soll (Veranstaltungen in der nächsten Woche, mit Tags, u.s.w.) )

Einleitung

Standardmässig werden in der Veranstaltungstabelle alle Veranstaltungen mit Filtermöglichkeiten nach Ort (wenn die Veranstaltungen an mehreren Orten stattfinden), Veranstaltungs-Kategorie und Monat angezeigt. Die Filtermöglichkeiten werden automatisch ausgeblendet, wenn diese über einen Filter in der URL bereits vorgegeben sind. Sind Kategorien bereits über einen Filter bestimmt, wird auch die hinterlegte Veranstaltungsbeschreibung über der Tabelle angezeigt (deaktivierbar).

Über weitere Einstellungen können die Filtermöglichkeiten und Spalten ausgeblendet werden oder die Reihenfolge angepasst werden.

Veranstaltungstabelle für alle Veranstaltungen

  1. Beispiel Link: /w#/courses

  2. Beispiel Komponente: <wscourselist class="ws-element"></wscourselist>

Veranstaltungstabelle für Veranstaltungen einer Kategorie

  1. Beispiel Link: /w#/courses?fcourses=snake_cased_category_name

  2. Beispiel Komponente: <wscourselist class="ws-element" fcourses="snake_cased_category_name" data-ftagsnot="intern"></wscourselist>

Im Backend findest du alle in "snake case" geschriebenen Kategorienamen im Feld "URL-Kürzel". Menüpunkt: "Zahnrad -> Veranstaltungskategorien"

Veranstaltungstabelle für Veranstaltungen eines Veranstaltungsortes

  1. Beispiel Link: /w#/courses?fplaces=snake_cased_category_name

  2. Beispiel Komponente: <wscourselist class="ws-element" fplaces="snake_cased_place_name"></wscourselist>

Weitere Einstellungen für Veranstaltungstabellen

Zusätzlich zu dem oben beschriebenen Filter "fcourses" und "fplaces" für Veranstaltungskategorien und Veranstaltungsorte sind weitere Filter Verfügbar, die flexibel miteinander kombiniert werden können. Diese sind im Abschnitt Alle Filtermöglichkeiten dokumentiert.

Spalten ein- und ausblenden und die Reihenfolge dieser Ändern

Spalten lassen sich über den Parameter „columns“ ein- und ausblenden. Durch die Anordnung der Spalten in diesem Parameter lässt sich zusätzlich die Reihenfolge der Spalten ändern.

Folgend sind die Spalten und deren Inhalt beschrieben:

  1. course Der Name der Veranstaltungskategorie oder Kategorien. Werden nur Veranstaltungen einer Kategorie in der Tabelle angezeigt, wird diese Spalte automatisch ausgeblendet.

  2. place Der Name des Veranstaltungsort. Werden nur Veranstaltungen eines Ortes in der Tabelle angezeigt, wird diese Spalte automatisch ausgeblendet.

  3. from Veranstaltungsanfang

  4. to Veranstaltungsende. Diese Spalte wird automatisch ausgeblendet wenn alle Veranstaltungen an einem Tag anfangen und enden.

  5. price wenn in der Veranstaltung nur ein Preis konfiguriert ist, der Preis der Veranstaltung. Wenn mehrere Preise konfiguriert sind, der geringster Preis mit der Formulierung „ab 200 €“

  6. info Insofern eingetragen, weitere Informationen zur Veranstaltung. Ist diese Spalte bei allen Veranstaltungen nicht ausgefüllt, wird sie automatisch ausgeblendet.

  7. trainer Name vom Trainer/ von der Trainerin

  8. remaining Verbleibende Plätze in der Veranstaltung mit der Formulierung „noch 3 Plätze frei“. Damit diese Spalte angezeigt wird, muss in der Software konfiguriert werden ab wievielen Plätzen diese Spalte angezeigt wird, z.B ab maximal 3 Plätzen. Ansonsten ist diese Spalte ausgeblendet.

  9. infolink Link, bei dem sich bei Klick eine genaue Beschreibung der Veranstaltung öffnet.

  10. booklink Link, bei dem sich bei Klick das entsprechende Buchungsformular der Veranstaltung öffnet. Ist die Veranstaltung ausgebucht, wird hier „ausgebucht“ angezeigt, insofern in Websail konfiguriert ist, das ausgebuchte Veranstaltungen weiter angezeigt werden sollen.

  11. appointments zeigt die Uhrzeiten in der Tabelle an.

  12. appointmentlist zeigt die Termine mit Datum und Uhrzeit in Form von einer Terminliste.

Standardmässig ist der Parameter columns auf course,place,from,to,info,remaining,infolink,booklink gestellt.

Die Reihenfolge lässt sich durch das anordnen der Spalten ändern. Es werden nur Spalten angezeigt, die im Parameter „columns“ konfiguriert sind. Sollen Beispielsweise nur die Spalten Veranstaltungsanfang und Buchen-Button in der Reihenfolge angezeigt werden sieht der Codeschnippsel wie folgt aus:

<wscourselist class="ws-element" columns="from,booklink"></wscourselist>

Filtermöglichkeiten ein- und ausblenden und die Reihenfolge dieser Ändern

Filtermöglichkeiten lassen sich über den Parameter filters ein- und ausblenden. Durch die Anordnung der Filter in diesem Parameter lässt sich zusätzlich die Reihenfolge ändern.

Folgend sind die Filtermöglichkeiten und deren Funktion beschrieben:

  1. „places“ Filter für den Veranstaltungsort. Ist bereits über den Parameter „fplaces“ ein Filter für Veranstaltungsorte gesetzt, wird dieses Feld ausgeblendet. Ist der Parameter „places“ im HTML-Element konfiguriert hat der Filter standardmässig diesen Wert. Die Möglichen Werte für den Filter sind im Backend unter „Konfiguration -> Adressen“ im Feld „URL-Kürzel“ einsehbar.

  2. „courses“ Filter für die Veranstaltungskategorie. Ist bereits über den Parameter „fcourses“ ein Filter für Veranstaltungsorte gesetzt, kann der Kunde hier die Unterkategorie auswählen (z.B Abendkurs oder Wochenendkurs). Ist der Parameter „courses“ im HTML-Element konfiguriert hat der Filter standardmässig diesen Wert. Die Möglichen Werte für den Filter sind im Backend unter „Konfiguration -> Veranstaltungskategorien“ im Feld „URL-Kürzel“ einsehbar.

  3. „months“ Filter für den Veranstaltungszeitraum. Der Kunde kann hier die Monate aussuchen, indem die Veranstaltung stattfinden soll (z.B Januar, Februar, ...). Ist bereits über den Parameter „fmonths“ ein Filter für den Veranstaltungszeitraum gesetzt, werden in diesem Feld nur die Monate angezeigt, die Im „fmonths“ Filter aufgeführt sind. Ist im „fmonths“ Filter nur ein Monat aufgeführt, wird diese Filtermöglichkeit ausgeblendet.​Sollen Beispielsweise nur die Filter courses und places in der Reihenfolge angezeigt werden entspricht der Codeschnippsel:
    ​
    ​<wscourselist class="ws-element" filters="courses,places"></wscourselist>

Suche für die Tabellenübersicht:

data-show-search-filter="true" wird das Suchfeld anzeigen


​data-show-search-filter="{number}" wird das Suchfeld anzeigen, wenn Anzahl der Einträge gleich oder höcher als "number" ist, z.B. data-show-search-filter="10" wird das Suchfeld dann einblenden, wenn 10 Einträge in der Tabelle vorhanden sind.
​

Weitere Einstellungsmöglichkeiten

  1. disableinfo Es werden keine Veranstaltungsbeschreibungen über der Tabelle angezeigt

  2. perpage Anzahl Einträge pro Seite

  3. page Seite

Weitere Darstellungsoptionen

Mit den Komponenten wscoursetable und wscourseaccordion können die Tabellen anders designed werden.
​
​

Alle Filtermöglichkeiten

Folgend sind alle Filtermöglichkeiten aufgelistet, die für das Buchungsformular oder eine eingebundene Veranstaltungstabelle verfügbar sind. Die Filter werden über die SQL AND Funktion verknüpft und schränken die Anzeige weiter ein.

  1. fcourses / fcoursesnot (eine oder mehrere Veranstaltungskategorien, siehe im Backend Konfiguration -> Veranstaltungskategorien -> URL-Kürzel)

  2. fplaces / fplacesnot (eine oder mehrere Veranstaltungsorte, siehe im Backend Konfiguration -> Orte -> URL-Kürzel)

  3. ftags / ftagsnot (eine oder mehrere Tags, siehe im Backend Konfiguration -> Tags -> URL-Kürzel)

  4. fmonths / fmonthsnot (Veranstaltungen in den Monaten 1 = Januar, 2 = Februar, ..., die Angabe mehrerer Monate ist möglich)

  5. fnextdays (Veranstaltungen die in den nächsten X Tagen stattfinden)

  6. fshortcut (Veranstaltungen die mit Kürzel Anfangen)

Eingebundene Komponenten über GET Parameter steuern

Alle oben aufgeführten Filter- und Einstellungsmöglichkeiten lassen sich auch über GET-Parameter ändern.

Beispiel Veranstaltungstabelle: ?fcourses=abendkurse&columns=from,to

Der Filter für Abendkurse wird gesetzt und es werden ausschliesslich die Spalten für den Veranstaltungsanfang- und Ende angezeigt.

Wenn mehrere Komponenten eingebunden sind, hat der GET-Parameter einen Prefix nach folgendem Schema: Der GET Parameter der Einstellung hat den Prefix wsc_1. Die Zahl 1 steht in diesem Fall für die erste Butlerapp Komponente, die in die Seite eingebunden ist. Die zweite Komponente kann entsprechend mit dem Parameter wsc_2 gesteuert werden. Einstellungen aus GET-Parameten überschreiben Einstellungen im HTML5-Element.

Probleme mit Google Ads

Das Skript versendet Daten per AJAX-Request an unseren Server. Dies kann von Google als Indiz gesehen werden, das die Website potenziell Schadsoftware enthält. Zusammen mit anderen Kriterien kann daraus folgend Google Ads wohlmöglich nicht aktiviert werden.

Dies kann mit Ihrem Google-Ansprechpartner geklärt werden, indem er euch auf die Whitelist setzt.

Variante 1: Mit Proxy

Wenn dies nicht klappt, kann auf dem Kundenwebserver ein Proxy-Skript installiert werden, welche die AJAX-Anfragen an unseren Server weiterleitet. Google sieht so nicht mehr, das Daten an einen anderen Server geschickt werden.

Statt der Standard Einbindung

<body>

<!-- Website body -->

<script src="https://TODO-INSERT-CUSTOMER-IDENTIFIER.butlerapp2.de/bee-react-form/bee-form.min.js"></script>

<script>websail.init({ apiBaseUrl: 'https://TODO-INSERT-CUSTOMER-IDENTIFIER.butlerapp2.de' });</script>

</body>

Sieht die Einbindung mit Proxy-Skript wie folgt aus:

<script src="https://TODO_PROXY_SCRIPT_URL_ON_CUSTOMER_SERVER?url=https%3A%2F%2FTODO-INSERT-CUSTOMER-IDENTIFIER.butlerapp2.de%2Fbee-react-form%2Fbee-form.min.js"></script>

<script>websail.init({ proxyUrl: 'https://TODO_PROXY_SCRIPT_URL_ON_CUSTOMER_SERVER?url=', apiBaseUrl: 'https://TODO-INSERT-CUSTOMER-IDENTIFIER.butlerapp2.de', urlEncodePath: true });</script>

Zudem muss ein Proxy-Skript auf eurem Webserver installiert werden. Eine PHP-Version findet sich unter folgendem Link:

https://gist.github.com/Mythli/ee2ee76030245e0121f4778d7b814f63

Variante 2: Mit Iframe

Die Seite https://TODO-INSERT-CUSTOMER-IDENTIFIER.butlerapp2.de/w kann per Iframe eingebunden werden.

Hat dies deine Frage beantwortet?