Profi-Konfiguration

Integrierte Optionen nutzen

Oft stürzen sich Nutzer direkt in sehr komplexe Schemata, obwohl es zahlreiche Möglichkeiten gibt, mit den inkludierten und idiotensicheren Funktionen zu arbeiten.

Prüfe die "Konfiguration"-Seite für alle Einstellungs-Optionen und Funktionalitäten.

Die folgenden Beispiele illustrieren die grundsätzliche Vielfalt der inkludierten Stile und zeigen doch nur einen sehr kleinen Ausschnitt dessen.

Styles überschreiben

Grundsätzlich ist es nicht möglich den CSS-Style direkt zu manipulieren, da der Button in seinem eigenen "ShadowDOM" gerendert wird.
Es gibt allerdings eine kleine Hintertür, über die du einige Variablen doch überschreiben kannst.
Du kannst CSS-Variablen, die an den Host (= the <add-to-calendar-button> tag) gebunden sind.
Spezifiziere deine invididuellen Werte über das "styleLight"-Attribut für den Standard-Look und über das "styleDark"-Attribut für den Dark-Mode.

Die möglichen Variablen unterscheiden sich ein wenig von Button-Theme zu Button-Themen. Wirf hierzu einen Blick in die entsprechende CSS-Datei im Repository an (du findest die möglichen Werte in der Sektion "Global colors and shadows").

Beachte, dass dies nicht mit dem Button-Stil "none" oder dem atcb_action-Ansatz (siehe #10) kompatibel ist.

Eine externe CSS-Datei laden

Ein weiterer möglicher Ansatz besteht darin eine externe CSS-Datei zu laden. Hierzu musst du lediglich mit der Option "customCss" auf diese Datei verweisen und den Button-Stil "custom" setzen.
Die Datei kann natürlich auf dem gleichen Server wie deine Anwendung liegen; sollte aber nicht mit anderem css verknüpft sein. Aus Sicherheitsgründen ist die Nutzung von "../" im Pfad allerdings nicht zulässig. Absolute URLs werden entsprechend empfohlen.

Beachte, dass du dich um den Look aller (!) Elemente selbst kümmern musst, wenn du diesen Weg einschlägst.
Wir empfehlen eines der integrierten Stylesheets aus dem offiziellen Repository zu kopieren und zu verändern.

Bei Nutzung externer Dateien musst du außerdem sicherstellen, dass dein System das Laden externer Stylesheets nicht blockiert (bspw. über Content-Security-Policy-Regeln)

Im Beispiel halten wir das Ganze recht einfach und haben in dem externen Style lediglich die Farbe verändert.

Elemente via ::part selektieren

Du kannst den css ::part selector nutzen, um vorselektierte Elemente direkt über deinen regulären CSS-Code zu stylen.

Nachfolgende Elemente stehen hierzu zur Verfügung:

• atcb-button-wrapper
• atcb-button
• atcb-button-icon
• atcb-button-text
• atcb-list-wrapper
• atcb-list
• atcb-list-item
• atcb-list-item-close
• atcb-list-icon
• atcb-list-text
• atcb-modal-box

Einen eigenen Button nutzen

Zu guter Letzt kannst du auch den Button durch dein eigenes Element ersetzen.
Dies beeinflusst zwar nicht den Stil weiterer Elemente (wie die Kalender-Link-Liste), ermöglicht es dir aber, jedes beliebige Element auf deiner Seite als Trigger zu nutzen.
Wirf einen Blick auf die Sektion "10. Eigenen Button verknüpfen" am Ende dieser Seite.

Die Event-Beschreibung muss nicht nur simpler Plain Text sein!
Du kannst HTML Special Characters einfügen sowie bestimmte Formatierungs-Regeln nutzen.

Diese Regeln setzt du über HTML-Pseudo-Tags, die am Ende automatisch in echtes HTML transformiert werden.
(Wenn du den WordPress Plugin Shortcode nutzt, stört ']' den Code. In diesem Fall kannst du {*} anstelle von [*] nutzen.)
(Apple, Yahoo und Microsoft Teams werden hierbei nicht vollständig unterstützt und der Wert automatisch zu Plain Text transformiert, womit nur Zeilenumbrüche und Links dargestellt werden.)

Du kannst deinen Nutzern auch die Möglichkeit bieten, einen Kalender zu abonnieren - anstelle davon einen statischen Termin zu speichern.

Damit dies funktioniert, benötigst du einen öffentlich zugänglichen Kalender (.ics-Datei), dessen Adresse du über die "icsFile"-Option definierst. Setze nun noch die Option "subscribe" und du bist schon fertig.

"name" ist weiterhin eine verpflichtende Angabe. Alle weiteren Parameter sind in diesem Fall aber optional.
Bei Microsoft-Diensten wird der "name" als Name für den geteilten Kalender genutzt.
Beachte, dass es für den Abonnement-Modus keine Rich-Data-Generierung gibt.
(Sollte der Browser des Nutzers keine installierte Kalender-App erkennen, kann dies zu einer leeren Seite führen. Die PRO-Version optimiert dies mit einem erklärenden Zwischenbildschirm.)

Du kannst grundsätzlich jeden Text-Block anpassen.

Für den Text auf dem Button kannst du hierzu ganz einfach die "label"-Option nutzen.

Für alle anderen Text-Blöcke (bspw. "Schließen" im Modal-Listen-Typ) kannst du die Option "customLabels" nutzen.
Hierbei musst du eine JSON-Struktur spezifizieren, die den jeweiligen Text zu dem zu ändernden Text-Key definiert.
Wirf einen Blick auf die Quellcode-Datei atcb-i18n.js in unserem Repository. Sie beinhaltet alle verfügbaren Optionen (Text-Keys).
Texte werden je nach gewählter Sprache übersetzt. Ein individueller Text wird auch jede Übersetzung überschreiben.

(Falls du Texte lediglich übersetzen möchtest, prüfe zunächst die "language"-Option!)

Falls du im Umgang mit iCal-Einstellungen erfahren bist, kannst du die Optionen "uid", "sequence", "created", "updated", "attendee" und "status" (TENTATIVE, CONFIRMED, CANCELLED) manuell steuern.

Beachte, dass diese Optionen nur von den iCal und Apple Kalendar-Links unterstützt werden (und auch dann nicht von allen Kalender immer sauber erkannt werden)!

Um ein bestehendes Event zu aktualisieren (bspw. den Status) muss die "sequence"-Nummer aufsteigen, ein jüngeres "updated"-Datum bei gleichem "created"-Datum gesetzt, die gleiche "uid" und die "organizer"-Option gegeben sein.

Einige Kalender erfordern zudem einen "attendee". Sollte dein "Update" des Event kein Status-Wechsel auf "CANCELLED" sein, ist dieser in jedem Fall verpflichtend!
Der "attendee" muss die Person sein, die das Event bei sich speichert. Wenn du diese Information hast, kannst du die Update-Funktionalität nutzen. Ansonsten muss davon abgeraten werden.

Jeder generierter Button erhält stets seine eigene unique ID. Diese wird nach dem Schema "atcb-btn-X" erzeugt, bei welchem "X" eine aufsteigende Zahl ist.
Die einzelnen Kalender-Links erhalten als ID diese Button-ID zzgl. des Kalendar-Typs - bspw. "atcb-btn-5-google".

Du kannst das automatisch erzeugte "X" mit deiner eigenen ID überschreiben, indem du die Option "identifier" spezifizierst.
Dies kann bspw. für Tracking-Funktionalitäten auf deiner Webseite hilfreich sein.

Beachte, dass der Wert eindeutig sein muss und für kein weiteres Element genutzt werden darf!

Bei Nutzung der atcb_action Funktion verhält es sich minimal anders. Das Skript nutzt das genannte Schema nur, wenn das auslösende Element keine ID besitzt.

Wir tracken jede Aktion auf dem Button für dich.
Die Daten kannst du auf 2 Arten auslesen.

1. Tracke selbst das atcb-last-event Attribut, welches an jedem Button erzeugt wird. Es zeigt das jeweils letzte Event zusammen mit dem jeweiligen Trigger an (Schema: "EVENT:TRIGGER"; Beispiel: "openList:atcb-btn-1").
2. Nutzer den Data Layer.

Wir speichern alle Events direct im Data Layer, der wiederum bspw. vom Google Tag Manager und Google Analytics gelesen werden kann.

In wenigen seltenen Fällen, in welchen du bspw. kein Event mit einem bestimmten Ort und Zeit nutzt, kann es hilfreich sein die Zeitzone dynamisch dem Ort des jeweiligen Nutzers zuzuordnen.
Bspw. ein Event, welches den Nutzer daran erinnern soll, um 8 Uhr morgens seine Zähne zu putzen - egal, wo auf der Welt er sich befindet.

In diesen Fällen kannst du den Wert "currentBrowser" in der "timeZone"-Option nutzen.
Die Zeitangabe des Events wird dann automatisch an die Zeitzone des jeweiligen Nutzers angepasst.

Apps auf mobilen Endgeräten, die den so genannten "WebView" nutzen, zeigen Probleme mit der Art, wie wir .ics-Dateien erzeugen und dynamisch ausliefern.
Aus diesem Grund fangen wir diese Fälle ab, kopieren stattdessen eine URL in die Zwischenablage des Nutzers und zeigen eine Anleitung an, wie das Event mit wenigen Zusatzschritten gespeichert werden kann.

Auch wenn dies Best Practice für Webseiten und Web-Apps darstellt, kann es hinderlich sein, wenn du deine eigene native/hybride App erstellst, in welcher du selbst volle Kontrolle über die WebView-Einstellungen hast.

Auch wenn die dynamische Erzeugung von .ics-Dateien auch in diesem Fall nicht funktionieren würde, kannst du eine statische DAtei über die "icsFile"-Option ausliefern.
In diesem Fall solltest du zusätzlich die "bypassWebViewCheck"-Option setzen, um den genannten Workaround zu deaktivieren.

Bitte stelle sicher, dass folgendes auf dein Projekt zutrifft!

• Du entwickelst deine eigene native/hybride App.
• Du öffnest in der App den Standard-Browser des Geräts und nutzt nicht den WebView.
• Du hast eine dedizierte .ics-Datei zur Verfügung und verweist auf diese über die "icsFile"-Option.

Für alle Entwickler, die extrem "custom" arbeiten wollen, bieten wir die Option die Kalender-Link-Liste programmatisch zu öffnen.
Dies eröffnet dir dir Möglichkeit jedes Element als Button/Trigger zu nutzen.

Theoretisch muss dieses Element kein Button sein. Wir raten allerdings stark dazu, da es die User Experience wesentlich positiv beeinflusst (bspw. durch die Unterstützung von Tastatur-Navigation, etc.).
Wenn du kein Button-Element nutzt, öffnet sich die Kalendar-Liste als Modal. Gibt es ein Button-Element kannst du auch den Overlay-Dropdown-Stil über die Option listStyle wählen (beachte, dass die übrigen Optionen mit atcb_action nicht unterstützt werden). Der Modal-Stil ist der Standard und wird auch empfohlen.

Schritt 1: Import

Wenn du das Skript via CDN einbindest kannst du diesen Schritt überspringen.
Wenn du das Skript über das npm Package ntuzt, musst du zunächst die "atcb_action"-Funktion importieren. Ändere dein Import-Statement entsprechend.

Schritt 2: Config und Trigger

Im Anschluss musst du die Config und den Trigger der Funktion definieren.
Dies kann je nachdem wie deine Entwicklungsumgebung aussieht, sehr unterschiedlich aussehen - hier bist du der Experte.

Im Beispiel nutzen wir einen recht einfachen Button und Prozess zu Demonstrationszwecken.

First things first:
Woimmer möglich, laden wir das Skript asynchron, sodass es das Rendern deiner Seite nicht blockiert.
Wenn du es allerdings als ES Modul einbindest, ändert sich dieses Verhalten in der Regel.
Neben dem Umstand, dass einige JavaScript-Frameworks andere Kniffe anbieten, um Komponenten asynchron zu laden, kannst du folgendes versuchen, um das Ladeverhalten und die Bundle-Size zu optimieren.

Leider können wir keine einfache Tree-Shaking-Lösung anbieten, da dies dem Ansatz des Skripts widerspricht - ein flexibler Web-Component, welcher sich zur Laufzeit anpassen lässt.

Das ES-Package kommt in 4 Varianten:

1. Default: Beinhaltet alles und reduziert das Risiko von Fehlfunktionen.
2. no-pro: Entspricht dem Default, solange du nicht die PRO version nutzt.
3. unstyle: Entspricht dem Default, aber ohne CSS-Informationen (Style).
4. no-pro-unstyle: Kein integriertes css, keine PRO-Funktionalitäten.

Um die Bundle-Size zu reduzieren, kannst du die unstyle Version mit

import 'add-to-calendar-button/unstyle'