Add to Calendar Button Konfiguration

Wenn du unseren PRO-Service nutzt, kannst du das "prokey"-Attribut nutzen, um den Button mit einem bestimmten Event zu verknüpfen.
In diesem Fall müssen ansonsten keine weiteren Parameter im Code definiert werden, da die weitere Verwaltung zu 100% im Add to Calendar PRO Admin-Bereich erfolgt.

Wenn eine Event-Gruppe sowohl für ein Abonnement als auch für eine Event-Liste konfiguriert ist, wird standardmäßig der Abonnement-Button angezeigt. Mit diesem Attribut wird stattdessen die Event-Liste angezeigt.

Optionale Einstellungen für group-overview:

• years-only (Boolean): Blendet die Monatsauswahl aus und zeigt alle Events des gewählten Jahres unter Monatsüberschriften.
• type (String): list (Standard), cards oder compact.
• from (String): UTC-ISO-Zeitstempel für die untere Grenze. Der Wert darf nicht vor dem 1. Januar des Vorjahres liegen.
• to (String): UTC-ISO-Zeitstempel für die obere Grenze. Der Wert darf nicht vor from liegen.
• no-details (Boolean): Öffnet bei Auswahl eines Events das Modal mit den Kalenderoptionen, anstatt auf die Landingpage zu verlinken.
• no-add (Boolean): Deaktiviert alle Event-Interaktionen. Einträge haben weder Landingpage-Link noch Kalenderaktion oder Hinzufügen-Marke, unabhängig von den anderen Einstellungen.
• custom-domain (String; Hostname, bspw. events.acme.com): Nutzt diese Domain für Landingpage-Links. Die Domain muss auch in Add to Calendar PRO konfiguriert sein.
• add-via-list (Boolean): Ergänzt eine dezente Kalender-Hinzufügen-Marke. Mit no-details ist sie Teil des Event-Links und öffnet zusammen mit dem restlichen Eintrag die Kalenderoptionen.

Der Titel deines Events.

Sollte ein eher kurzer String sein.
Auch Pflicht, sofern du die "dates"-Option nutzt (Multi-Date). In diesem Fall dient der Wert als Fallback und Name für die Termin-Reihe.
Bei Nutzung der Kalender-Abonnement-Funktion wird der Wert für die Microsoft-Services zudem als Kalendar-Name genutzt.

Unterstützt HTML-Pseudo-Tags zur Formatierung: [url], [br], [hr], [p], [strong], [u], [i], [em], [li], [ul], [ol], [h*] (wie etwa h1, h2, h3, ...).
Einen Link-Text spezifizierst du mit folgendem Schema: [url]https://....|URL Text[/url].

(Bei Kompatibilitätsproblemen kannst du auch geschweifte {} anstelle von eckigen [] Klammern 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.)

Beispiel

Ein Datum muss im Schema YYYY-MM-DD gemäß ISO-8601 formatiert sein

Du kannst das Wort "today" nutzen, um dynamisch den jeweils aktuellen Tag zu setzen. Wenn du bspw. "+5" hinzufügst, werden automatisch 5 Tage aufaddiert.

Inoffiziell werden Formate wie "YYYY-MM-DDTHH:MMZ" auch unterstützt.

Beispiel

Sofern nicht spezifiziert, wird das Event als Ganztages-Event abgebildet.

Ein Datum muss im Schema YYYY-MM-DD gemäß ISO-8601 formatiert sein

Du kannst das Wort "today" nutzen, um dynamisch den jeweils aktuellen Tag zu setzen. Wenn du bspw. "+5" hinzufügst, werden automatisch 5 Tage aufaddiert.

Inoffiziell werden Formate wie "YYYY-MM-DDTHH:MMZ" auch unterstützt.

Sofern nicht spezifiziert, wird das Event als Ganztages-Event abgebildet.

Kein Pflichtfeld, aber wärmstens empfohlen.
Eine Liste valider Zeitzonen findest du auf Wikipedia.

Du kannst "currentBrowser" als Wert nutzen, um dynamisch die Zeitzone des jeweiligen Nutzers (Browser) zu wählen. Nutze diese Funktion mit Vorsicht, da dies bedeutet, dass die Zeitangabe für das Event je Nutzer unterschiedlich sein kann, was meist nicht gewollt ist.
Eine Zeitzone ist nur relevant, wenn start-time und end-time spezifiziert sind.

Diese Option transformiert Zeit und Zeitzone in die Einstellungen des jeweiligen Nutzers.

Wenn du diese Option auf "true" setzt, wird die Zeit in die des Nutzers umgerechnet.
Dies verhält sich anders als die künstliche "browserTime"-Zeitzone, welche nur die Zeitzone, nicht aber die Zeit selbst, anpasst.
Verwende diese Option mit Bedacht, da das Manipulieren der Zeitzone pro Nutzer unerwünschte Nebeneffekte haben kann. Dies sollte normalerweise vom Kalender-Programm des Nutzers übernommen werden!

Kann alles mögliche sein.

Wenn es eine URL ist, so wird das Event innerhalb der Schema.org-Daten als "Online-Event" klassifiziert.
Ein Online-Event wird auf Date-Buttons nicht angezeigt. Zusätzlich werden in diesem Fall Zeitangaben auf diesem Button-Type in die Zeitzone des Nutzers übertragen (geschieht auch bei den Werten "Global", "Worldwide" und "Online").

Kann genutzt werden, um Änderungen an einem Event zu verwalten.
Gemäß der iCalendar-Spezifikation RFC5545.

Beispiel

Muss eine positive ganze Zahl sein.
Muss größer werden, wenn Veränderungen am Event vorgenommen werden.

Beispiel

Standardmäßig wird ein Event gemäß der Standard-Einstellung im Kalender des jeweiligen Nutzers als beschäftigt/verfügbar gespeichert.
Für Apple-, iCal- und Google-Kalender kann dieser Wert mittels dieser Option erzwungen werden.

Die einzigartige ID eines Events, wie sie für iCal-Dateien genutzt wird.

Darf nur Buchstaben, Ziffern und Bindestriche enthalten; kleiner 255 Zeichen gesamt.
Ein Hex-kodierter zufälliger "Universally Unique Identifier" (UUID) wird empfohlen.

Schema "NAME|E-MAIL" (bspw. "Max Muster|max.muster@gmail.com").

Der "Organizer" wird innerhalb der Schema.org-Daten sowie in iCal-Dateien integriert.
Sofern diese Option gesetzt wird, werden ics-Dateien (iCal) von Kalendern auch anders gehandhabt. Anstatt einfach nur das Event zu speichern, wird es als Einladung betrachtet, die man annehmen oder ablehnen kann.

Beispiel

Schema "NAME|E-MAIL" (bspw. "Max Muster|max.muster@gmail.com") oder einfach nur eine E-Mail-Adresse (Name ist optional).
Mit dieser Option kannst du ein Event im Kalender eines Nutzers aktualisieren, wenn dieser Nutzer auch die neue iCal-Datei speichert.

Es kann nur 1 "attendee" gesetzt werden
Diese Person muss gleichzeitig diejenige sein, die das Event speichert.
Wenn du nicht über diese Information verfügst, solltest du die Option nicht nutzen!

Wenn du einen "attendee" definierst, muss auch die "organizer" option gesetzt sein.

Mit dem "dates"-Objekt kannst du eine Termin-Reihe spezifizieren.

Es beinhaltet die gleichen Termin-Parameter wie die Haupt-Ebene, bietet aber die Möglichkeit mehrere Events zu definieren. Root-Level-Werte überschreiben Werte im "dates"-Objekt - mit Ausnahme des Namens, wenn es mehrere Termine gibt (dann wird der Root-Name zum Titel der Veranstaltungsreihe). Die "UID" wird nur für das erste Event übernommen (da die ID einzigartig sein muss). Weitere Events erhalten eine eigene, zufällig generierte ID.

Attribute je Sub-Event-Block:

• name
• description
• start-date
• start-time
• end-date
• end-time
• time-zone
• use-user-tz
• location
• status
• sequence
• availability
• uid
• organizer
• attendee
• die meisten ICS-Optionen - siehe weiter unten

Beispiel

Definiert wiederkehrende Events.

Diese Optione deaktiviert die Yahoo- und Microsoft-Kalendar-Optionen (sowie Google unter iOS), da die Funktion dort aktuell nicht unterstützt wird (in diesen Fällen können Nutzer weiterhin auf die iCal-Datei zurückgreifen). Bleibt keine Option übrig, wird iCal als Fallback aktiviert.
Beachte, dass es nicht möglich ist, mehr als 1 Termin (dates option) gemeinsam mit der recurrence option zu verwenden.

Du kannst jede valide RRULE mit Ausnahme von BYHOUR, BYMINUTE und BYSECOND nutzen, um eine entsprechende Regel anzuwenden (Generator-Tool).

Alternativ zur RRULE kannst du auch die folgenden einfacheren und spezifischeren Einstellungen nutzen. Diese generieren die RRULE automatisch für dich im Hintergrund.
In diesem Fall würdest du als Wert für die "recurrence"-Option lediglich die Frequenz (täglich, wöchentlich, ...) anstelle der kompletten RRULE definieren.

Beispiel

Bestimmt den Abstand zwischen Wiederholungen.
"3" würde "jedes dritte Vorkommnis" beschreiben.

Definiert ein End-Datum.
Wir wandeln diesen Wert automatisch in einen korrekten COUNT-Wert um, da UNTIL nicht von allen Anwendungen unterstützt wird.

Definiert die maximale Anzahl an Wiederholungen.
Sofern recurrence-until und recurrence-count definiert sind, gilt, was zuerst eintritt. Sofern keiner der Werte gegeben ist, erfolgt die Wiederholung endlos.

Bestimmt die Wochentage (MO, TU, WE, TH, FR, SA, SU), an denen das Event stattfindet. Sinnvoll, sofern ein Termin an den Wochentag (bspw. Dienstag) und kein bestimmtes Datum geknüpft ist.
Erfordert eine wöchentlichen Frequenz.
Kann um Zahlen erweitert werden, um Regeln auszudrücken, wie den 3ten Montag (3MO).
Mehrere Tage möglich; durch Komma getrennt.

Nutze diese Option anstelle von "byDay", sofern du dich auf ein bestimmtes Datum (1, 2, ... 31) anstatt eines Wochentags beziehen möchtest.
Erfordert ein monatliche Frequenz.
Mehrere Werte möglich; durch Komma getrennt.

Beschreibt die Monate (1, 2, 3, ... 12), in denen das Event wiederholt wird.
Erfordert ein jährliche Frequenz.
Mehrere Werte möglich; durch Komma getrennt.

Definiert einen bestimmten Wochentag als Wochenstart.

Alternativ zur Angabe eines bestimmten vordefinierten Events kannst du auch einen Kalender bereitstellen und ihn zum Abonnieren anbieten (erfordert einen gehosteten Kalender).
Um das Abonnement über den Button anzubieten, musst du zusätzlich die icsFile-Option definieren.

"Name" und "start-date" wären für organisatorische Zwecke immer noch erforderlich, aber jeder andere Event-Parameter kann im Abonnementfall übersprungen werden.
Für Microsoft-Dienste wird der "Name" als Name für den Kalender verwendet.
Microsoft Teams wird noch nicht unterstützt, während Yahoo nicht mehr unterstützt wird. Beide werden automatisch deaktiviert. Gleiches gilt für andere Microsoft-Dienste auf mobilen Geräten.

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.

Beispiel

Die iCal/ics-Datei wir dynamisch generiert.
Dies hat den Nachteil, dass der Prozess in seltenen Fällen vom Browser des Nutzers blockiert werden kann.
Mit dieser Option kannst du stattdessen auf eine bestehende ics-Datei verweisen.

Im "subscribe"-Fall muss hier der externe Kalender referenziert werden.

Falls du mehrere Termine und einen "organizer" oder "status" definiert hast, musst du mehrere ics-Dateien vorhalten. Die Datei für den ersten Termin wird hier referenziert, während alle weiteren Termine eine Datei mit dem gleichen Namen zzgl. einer fortlaufende Nummer (beginnend mit 2) benötigen (bspw. "event-2.ics").

Wenn du einen bestimmten Namen für die generierte ics-Datei (iCal) definieren möchten, kannst du diesen über die Option ical-file-name definieren.

Fügt eine Erinnerung hinzu. Setze die Minuten vor Event-Beginn (etwa "30") oder eine rohe ISO-8601-Dauer (etwa "-PT1H").

Hängt einen kanonischen Link (die URL-Property) an das Event. Muss eine valide http(s)-URL sein.

Verschlagwortet das Event mit einer kommaseparierten Liste von Kategorien.

Setzt die Klassifizierung des Events.

Setzt die Priorität von 0 (undefiniert) über 1 (höchste) bis 9 (niedrigste).

Ergänzt Geo-Koordinaten. Zusammen mit der regulären "location"-Option rendert Apple Calendar seine Karten-Vorschau.

Hängt Dateien per URL an (eine kommaseparierte Liste von http(s)-URLs) - etwa ein Agenda-PDF oder ein Ticket.

Schließt Termine aus einer Terminserie aus (eine kommaseparierte Liste von Terminen). Erfordert die "recurrence"-Option und ist die einzige dieser Optionen, die nicht pro Datums-Eintrag gesetzt werden kann.

Das "Created"-Feld in der iCal-Datei erhält grundsätzlich den Zeitpunkt, zu welchem die Datei generiert und heruntergeladen wird.
Nutze diese Option, um stattdessen einen bestimmten Timestamp zu setzen.

Spezifiziere den Zeitpunkt als UTC Timestamp. Bspw. "20231201T103000Z".

Das "Updated"-Feld in der iCal-Datei erhält grundsätzlich den Zeitpunkt, zu welchem die Datei generiert und heruntergeladen wird.
Nutze diese Option, um stattdessen einen bestimmten Timestamp zu setzen.

Spezifiziere den Zeitpunkt als UTC Timestamp. Bspw. "20231201T103000Z".

Array an Kalender-Arten, die in der Liste erscheinen.

Sofern du nur 1 Option definierst wird der Button das Icon dieser Option anzeigen sowie direkt die jeweilige Kalender-Aktion auslösen und keine Auswahlliste öffnen (Singleton-Case).

Optionen können deaktiviert werden, wenn sie aufgrund anderere Einstellungen nicht unterstützt werden!
Auf iOS-Geräten wird die ical-Option durch "apple" ersetzt.

Du kannst eine andere Liste an Optionen für mobile Geräte definieren, indem du die optionsMobile-Option nutzt. Wenn du auch die optionsIOS-Option setzt, wird diese für iOS (nicht Mac!) berücksichtigt, während options-mobile für Android und andere mobile Geräte gilt.

Es gibt mehrere integrierte Button-Stile (Themes), die auch einige weitere Parameter beeinflussen.
Wir empfehlen die Optionen der Reihe nach auszuprobieren, um herauszufinden, wie sie sich im Detail verhalten.

"none" würde gar kein CSS laden, während "custom" eine externes CSS-Datei über die "custom-css"-Option erfordert.

Nur der Default-Style Teil des Skripts - jeder andere Style lädt automatisch bei Bedarf (wenige KB), oder ohne Netzwerk-Anfrage via import 'add-to-calendar-button/styles/3d' und Co. beim Bundling. Um alle Styles auf einmal zu registrieren, nutze import 'add-to-calendar-button/styles/all'. Siehe auch die Optionen "style-source" und "load-all-styles".

Rendert den Button inline anstelle des standardmäßigen Block-Styles.

Du kannst eine externe CSS-DAtei anstelle der integrierten Optionen laden.
Spezifiziere die URL der Datei hier und nutze die buttonStyle-Option "custom".
Beachte, dass benutzerdefiniertes CSS im SSR nicht geladen wird!

Beispiel

Überschreibt die Basis-URL, von welcher On-Demand-Assets (Button-Styles jenseits des Defaults, Sprachpakete jenseits von Englisch) geladen werden.

Standardmäßig laden diese von dort, wo auch das Skript selbst gehostet ist. Setze diese Option, wenn du das Skript in einem exotischen Setup selbst hostest oder die Assets von einem dedizierten Ort ausliefern möchtest. Die URL sollte auf das Verzeichnis zeigen, welches die styles/- und locales/-Ordner enthält.

Lädt alle Button-Style-Deltas bereits bei der Initialisierung.

Nur sinnvoll, wenn du die "button-style"-Option zur Laufzeit wechselst (etwa in einem Live-Theme-Switcher) und der Wechsel ohne Netzwerk-Verzögerung greifen soll.

Diese Option funktioniert nur bei Einbindung des Buttons über einen Script-Tag, nicht über das npm-Paket. Bei npm müssen die benötigten Style-Module stattdessen importiert werden - oder import 'add-to-calendar-button/styles/all' registriert alle Styles auf einmal.

Erzeugt einen Button je Kalender-Typ anstelle eines Buttons mit Liste.

Diese Option überschreibt den Text auf dem Button.

In den meisten Fällen wird das Erscheinen der Kalendar-Link-Liste über Hover ausgelöst.
Wenn du stattdessen eine Klick-Interaktion erzwingen möchtest, kannst du dies über diese Option definieren.

Die Kalender-Link-Liste kann als Dropdown, Overlay oder Modal dargestellt werden.

Der Dropdown-Stil berücksichtigt auch die Position auf dem Bildschirm und zeigt die Liste je nach Situation über oder unter dem Button an. Nutze den Wert "dropdown-static", bzw. "dropup-static", um sie immer unterhalb oder oberhalb anzuzeigen.

Diese Option rendert das Dropdown zusammen mit dem Button über allem anderen - ähnlich der Modal-Option.
Dies kann nützlich sein, wenn dein Layout und die HTML-Struktur nicht mit der Standard-Option, bei der das Dropdown direkt am Button gerendert wird, kompatibel ist.

Aufgrund der zusätzlichen Berechnungen geht dies mit kleinen Performance-Einbußen einher.

Mit dieser Option wird der Hintergrund vollständig transparent erzeugt.

Diese Option verbirgt das Icon auf dem Button.

Diese Option verbirgt die Icons in der Kalender-Link-Liste.

Diese Option verbirgt das Icon in den Modal-Dialogen.

Diese Option verbirgt den Text auf dem Button.

Diese Option verbirgt die Texte in der Kalender-Link-Liste.

Nach Klick auf einen Kalender-Link wird das Event als "gespeichert" markiert und ein Icon auf den Button gesetzt.
Dies ist nicht der Fall, wenn der Text auf dem Button verborgen wird, die buttonsList-Option gesetzt ist oder mit der atcb_action-Variante gearbeitet wird.
Nutze diese Option hier, um das Icon auch in allen anderen Fällen zu verbergen.

Diese Option bestimmt, was passiert, sollte ein Termin in der Vergangenheit liegen.
Wenn du sie auf "disable" setzt, wird der Button deaktiviert, bei "hide" vollständig ausgeblendet. In beiden Fällen kann der Nutzer das Event nicht mehr speichern.

Beachte, dass die Funktion bei wiederkehrenden Events nicht greift!

Du kannst eine Zahl zwischen 0 und 10 spezifizieren, um den Button zu skalieren.

Du kannst 1 Zahl (bspw. "5") oder bis zu 3 Werte (bspw. "8|6|4") definieren. Bei mehreren Werten wird der erste für große, der zweite für mittlere und der dritte für kleine Bildschirme gesetzt.
Sofern 2 Werte angegeben werden, so gilt der zweite für mittlere und kleine Bildschirme.

Jeder Button kommt mit einem Dark- und Light-Theme.

Mit der Optiomn "light-mode" kann dies explizit ausgewählt werden. Du kannst auch den Wert "system" nutzen, um automatisch den Wert des Betriebssystems des Nutzers zu übernehmen.
Mit dem Wert "bodyScheme" wird automatisch nach der class "atcb-dark" (oder "dark") im html oder body tag Ausschau gehalten - der Button lässt sich in diesem Fall dynamisch dem Stil der Webseite anpassen.

Wählt inkludierte Übersetzungen. Basissprachen nutzen ISO-639-1-Codes; RTL wird unterstützt. Englisch ist integriert, andere laden bei Bedarf oder per Locale-Import. Vollständige Locales wie en_GB nutzen bevorzugt regionale Pakete und Datumsformate.

Überschreibt alle Text-Blöcke mittels JSON und flachen Locale-Keys wie label.addtocalendar; eigene Labels überschreiben Übersetzungen und unterstützen die Description-Pseudo-Tags. Umbenannte Keys sind in den Sprachdateien dokumentiert.

Beispiel

Du kannst globale CSS Variabeln des Buttons überschreiben. Siehe CSS-Dateien im Repository. Beispiel: style-light="--btn-background: #2f4377; --btn-text: #fff; --font: Georgia, 'Times New Roman', Times, serif;". style-light definiert den Standard; style-dark den Dark Mode.

Du kannst globale CSS Variabeln des Buttons überschreiben. Alle möglichen Einträge findest du zu Beginn der jeweiligen CSS-Datei im Repository.

Bilder reichern Schema.org-Daten an. Mindestens eine absolute URL mit 720px Breite; ideal sind drei 1920px Bilder in 1x1, 4x3 und 16x9.

Sofern du "name", "start-date" und "location" definierst, werden automatisch Schema.org-Daten generiert. Mit dieser Option kann dies verhindert werden.

Jedes Element besitzt eine sprechende Tracking-ID: "atcb-btn-IDENTIFIER" bzw. "atcb-btn-IDENTIFIER-google". Standard ist eine aufsteigende Nummer; überschreibbar (einzigartig, keine Sonderzeichen).

In iPhone-WebViews können ics-Dateien nicht direkt geladen werden; daher erscheint eine Anleitung. Nur in eigener App umgehen, wenn Downloads im Standardbrowser und ics-file explizit möglich sind.

Standardmäßig gibt es ein dezentes Branding zur Unterstützung des freien Open-Source-Projekts. Diese Option entfernt es lizenzkonform.

Fügt allen Inline-Script- und Style-Tags ein "nonce"-Attribut hinzu; nützlich für strikte Content-Security-Policy.

Nutze dieses Attribut, um einen Button durch Hochzählen des Werts neu zu rendern.

Ist diese Option aktiv, überschreiben Einstellungen die PRO-App-Werte. Nutze dies mit Vorsicht, da Inkonsistenzen entstehen können!

Zeigt Fehlkonfigurationen in der JavaScript-Konsole und rendert einen Fehler statt des Kalenders. Hilfreich bei der ersten Implementierung.