Configuration du bouton Add to Calendar

Si vous utilisez le service PRO, l’attribut « prokey » permet de relier le bouton à l’un de vos événements.
Dans ce cas, aucun autre paramètre ne doit être défini dans le code, puisque tout est géré à 100 % dans l’interface d’administration Add to Calendar PRO.

Si un groupe d’événements est configuré à la fois pour un abonnement et une liste d’événements, le bouton d’abonnement s’affiche par défaut. Utilisez cet attribut pour afficher plutôt la liste des événements.

Paramètres facultatifs de group-overview :

• years-only (Boolean) : masque le sélecteur de mois et affiche tous les événements de l’année sélectionnée.
• type (String) : list (par défaut), cards ou compact.
• from (String) : date et heure ISO UTC limitant la borne inférieure. Elle ne peut pas être antérieure au 1er janvier de l’année précédente.
• to (String) : date et heure ISO UTC limitant la borne supérieure. Elle ne peut pas précéder from.
• no-details (Boolean) : ouvre la fenêtre des options de calendrier au lieu de renvoyer vers la page de destination.
• no-add (Boolean) : désactive toutes les interactions. Les entrées n’ont ni lien, ni action calendrier, ni badge d’ajout, quels que soient les autres paramètres.
• custom-domain (String ; nom d’hôte, par ex. events.acme.com) : utilise ce domaine pour les liens des pages de destination. Le domaine doit aussi être configuré dans Add to Calendar PRO.
• add-via-list (Boolean) : ajoute un badge discret d’ajout au calendrier. Avec no-details, il fait partie du lien de l’événement et ouvre les options avec le reste de l’entrée.

Le titre de votre événement.

Il doit s’agir d’une chaîne plutôt courte.
Le nom reste obligatoire si vous utilisez le paramètre « dates » (plusieurs dates). Il sert alors de valeur de secours et de nom à la série d’événements.
Dans le cas d’un abonnement, le nom sert de nom de calendrier pour les services Microsoft.

Prend en charge les pseudo-balises HTML de mise en forme : [url], [br], [hr], [p], [strong], [u], [i], [em], [li], [ul], [ol], [h*] (comme h1, h2, h3, ...).
Définissez le texte d’un lien selon ce schéma : [url]https://....|Texte du lien[/url].

(En cas de problème de compatibilité, vous pouvez utiliser des accolades {} au lieu des crochets [].)

(Apple, Yahoo et Microsoft Teams ne sont pas entièrement pris en charge ; le contenu est automatiquement converti en texte brut, avec uniquement les sauts de ligne et les liens.)

Exemple

Une date doit respecter le format YYYY-MM-DD défini par ISO-8601.

Vous pouvez utiliser le mot magique « today » pour définir dynamiquement le jour actuel. Ajouter « +5 » à la fin ajoute automatiquement 5 jours à la date calculée.

De manière non officielle, un format tel que « YYYY-MM-DDTHH:MMZ » fonctionne également.

Exemple

Si elle n’est pas définie, l’événement est considéré comme durant toute la journée.

Une date doit respecter le format YYYY-MM-DD défini par ISO-8601.

Si aucune date de fin n’est définie, elle est supposée identique à la date de début. Le mot magique « today » définit dynamiquement le jour actuel. Ajouter « +5 » ajoute automatiquement 5 jours à la date calculée.

De manière non officielle, un format tel que « YYYY-MM-DDTHH:MMZ » fonctionne également.

Si elle n’est pas définie, l’événement est considéré comme durant toute la journée.

Ce champ n’est pas obligatoire, mais il est recommandé d’ajouter un fuseau horaire.
Vous en trouverez une liste sur Wikipédia.

La valeur « currentBrowser » permet d’utiliser dynamiquement l’heure du navigateur de l’utilisateur. Utilisez-la avec prudence, car l’heure de l’événement différera alors selon l’utilisateur, ce qui n’est généralement pas souhaitable.
Le fuseau horaire n’intervient que lorsque start-time et end-time sont définis.

Cette option convertit l’heure et le fuseau horaire selon les réglages de chaque utilisateur.

Avec la valeur « true », l’heure est convertie dans le fuseau horaire de l’utilisateur.
Cela diffère du fuseau artificiel « browserTime », qui ne modifie que le fuseau et non l’heure elle-même.
Utilisez cette option avec prudence : modifier le fuseau pour chaque utilisateur peut avoir des effets indésirables. Cette opération devrait normalement être effectuée par son application de calendrier !

Peut contenir n’importe quelle valeur.

S’il s’agit d’une URL, l’événement est classé comme « événement en ligne » dans la déclaration schema.org.
Un événement en ligne n’apparaît pas sur le bouton de type date. En outre, l’heure de ce type de bouton est convertie dans le fuseau de l’utilisateur (également lorsque le lieu vaut « Global », « Worldwide » ou « Online »).

Permet de gérer les modifications d’un événement conformément à la spécification iCalendar RFC5545.

Exemple

Doit être un nombre entier positif.
Doit augmenter lorsque vous modifiez l’événement.

Exemple

Par défaut, l’événement est marqué comme occupé/libre/disponible selon les réglages du calendrier de l’utilisateur.
Pour Apple, iCal et Google, vous pouvez imposer cette valeur avec les options « busy » ou « free ».

L’identifiant unique de l’événement tel qu’il est utilisé dans le fichier iCal.

Il ne peut contenir que des lettres, des chiffres et des tirets, et doit compter moins de 255 caractères.
Un identifiant unique universel (UUID) aléatoire encodé en hexadécimal est recommandé.

Utilisez le schéma « NOM|E-MAIL » (par ex. « Jean Dupont|jean.dupont@gmail.com »).

L’organisateur apparaît dans les données enrichies schema.org ainsi que dans le fichier iCal.
Cette option modifie aussi le traitement des fichiers ics (iCal) : les calendriers ne se contentent plus d’enregistrer l’événement, mais le considèrent comme une invitation que l’on peut accepter ou refuser.

Exemple

Utilisez le schéma « NOM|E-MAIL » (par ex. « Jean Dupont|jean.dupont@gmail.com »), ou uniquement l’adresse e-mail car le nom est facultatif.
Cette option permet de mettre à jour un événement dans le calendrier d’un utilisateur si celui-ci charge également le nouveau fichier iCal.

Un seul participant peut être indiqué.
Ce participant doit être la personne qui enregistre l’événement.
Si vous ne disposez pas de cette information, n’utilisez pas cette option !

Lorsque vous indiquez un participant, vous devez aussi indiquer un organisateur.

Pour définir une série d’événements, utilisez l’objet « dates ».

Il reprend la structure de date du niveau racine, mais permet de définir plusieurs événements. Les valeurs racine remplacent celles de l’objet « dates », sauf le nom lorsqu’il y a plusieurs dates (le nom racine devient alors le titre de la série). Cas particulier : l’« UID » racine ne s’applique qu’au premier sous-événement, puisqu’il doit être unique. Les suivants reçoivent de nouveaux UID aléatoires.

Attributs de chaque sous-événement :

• name
• description
• start-date
• start-time
• end-date
• end-time
• time-zone
• use-user-tz
• location
• status
• sequence
• availability
• uid
• organizer
• attendee
• la plupart des options ics, voir plus bas

Exemple

Définit des événements récurrents.

Cette option désactive Yahoo et Microsoft (ainsi que Google sous iOS), qui ne les prennent actuellement pas en charge ; les utilisateurs peuvent toujours employer iCal. Si aucune option ne reste, iCal sert de solution de secours.
Il n’est pas possible d’utiliser plusieurs dates (option dates) avec la récurrence.

Vous pouvez utiliser toute RRULE valide sauf BYHOUR, BYMINUTE et BYSECOND (générateur).

À la place, les paramètres de récurrence simplifiés suivants peuvent générer la RRULE en arrière-plan. Dans ce cas, indiquez dans « recurrence » la fréquence (daily, weekly, monthly, yearly) plutôt que la RRULE.

Exemple

Définit l’intervalle entre les répétitions.
« 3 » signifie « une fois sur trois ».

Définit une date de fin.
Nous la convertissons automatiquement en valeur COUNT correcte, car UNTIL n’est pas pris en charge par toutes les applications.

Définit un nombre maximal de répétitions.
Si recurrence-until et recurrence-count sont fournis, la première limite atteinte l’emporte. Sans aucun des deux, la répétition est illimitée.

Définit les jours de la semaine (MO, TU, WE, TH, FR, SA, SU) où l’événement a lieu, par exemple s’il est lié au mardi plutôt qu’au 24.
Nécessite une fréquence hebdomadaire.
Un nombre peut préciser, par exemple, le troisième lundi (3MO).
Plusieurs valeurs sont possibles, séparées par des virgules.

Utilisez cette option à la place de « byDay » pour choisir un jour numéroté (1, 2, ... 31) plutôt qu’un jour de la semaine.
Nécessite une fréquence mensuelle.
Plusieurs valeurs sont possibles, séparées par des virgules.

Définit les mois (1, 2, 3, ... 12) où l’événement doit avoir lieu.
Nécessite une fréquence annuelle.
Plusieurs valeurs sont possibles, séparées par des virgules.

Définit un jour précis comme début de la semaine.

Au lieu de fournir un événement prédéfini, vous pouvez héberger un calendrier et proposer de s’y abonner (un calendrier hébergé est requis).
Pour proposer l’abonnement avec le bouton, vous devez aussi définir l’option ics-file.

« Name » et « start-date » restent nécessaires à des fins d’organisation, mais tous les autres paramètres d’événement peuvent être omis. Pour les services Microsoft, « Name » sert de nom au calendrier. Microsoft Teams n’est pas encore pris en charge et Yahoo ne l’est plus ; les deux sont désactivés automatiquement, tout comme les autres services Microsoft sur mobile.

Si le navigateur ne reconnaît aucune application de calendrier installée, un écran vide peut apparaître. La version PRO atténue ce problème avec un écran intermédiaire explicatif.

Exemple

Le fichier iCal/ics est créé dynamiquement.
Cela présente quelques inconvénients, car il peut être bloqué dans de rares cas.
Cette option permet de rediriger plutôt vers un fichier ics existant.

Dans le cas d’un abonnement, indiquez ici le calendrier externe.

Avec plusieurs dates et un organisateur ou un statut, préparez plusieurs fichiers ics : celui de la première date est indiqué ici, puis chaque date suivante cherche un fichier de même nom auquel est ajouté un numéro à partir de 2 (par ex. « event-2.ics »).

Pour attribuer un nom précis à tout fichier ics (iCal) généré, utilisez l’option ical-file-name.

Ajoute une alarme. Indiquez les minutes avant le début (par ex. "30") ou une durée ISO 8601 brute (par ex. "-PT1H").

Ajoute un lien canonique (propriété URL) à l’événement. Il doit s’agir d’une URL http(s) valide.

Associe à l’événement une liste de catégories séparées par des virgules.

Définit la classification de l’événement.

Définit la priorité de 0 (indéfinie), 1 (maximale) à 9 (minimale).

Ajoute des coordonnées géographiques. Avec « location », Apple Calendar affiche un aperçu de carte.

Joint des fichiers par URL (liste d’URL http(s) séparées par des virgules), comme un PDF ou un billet.

Exclut des dates d’un événement récurrent (liste séparée par des virgules). Nécessite « recurrence » et ne peut pas être définie par entrée de date.

Le champ « Created » prend par défaut l’heure de génération et de téléchargement. Utilisez cette option pour fixer un horodatage UTC statique, par ex. « 20231201T103000Z ».

Le champ « Updated » prend par défaut l’heure de génération. Utilisez cette option pour fixer un horodatage UTC statique, par ex. « 20231201T103000Z ».

Tableau des calendriers de la liste. Avec un seul type, son icône remplace l’icône standard et l’action est directe. Certaines options peuvent être exclues selon les autres réglages ; « ical » devient « apple » sous iOS. options-mobile définit les appareils mobiles et options-ios remplace ce choix sous iOS (pas sur Mac).

Plusieurs styles intégrés influencent aussi d’autres paramètres. Essayez-les. « none » ne charge aucun CSS et « custom » exige le fichier de « custom-css ». Seul le style par défaut est inclus ; les autres se chargent à la demande ou via les imports de styles. Importez styles/all pour tous les enregistrer ; voir « style-source » et « load-all-styles ».

Affiche le bouton en ligne plutôt qu’en bloc.

Charge un fichier CSS externe avec button-style « custom ». Le CSS personnalisé n’est pas chargé en SSR.

Exemple

Remplace l’URL de base des styles et langues chargés à la demande. Elle doit viser le dossier contenant styles/ et locales/.

Précharge tous les styles pour un changement à l’exécution sans délai réseau. Uniquement avec une balise script ; avec npm, importez les modules ou styles/all.

Affiche un bouton par calendrier.

Remplace le texte du bouton.

La liste s’ouvre généralement au survol ; choisissez « click » pour l’ouvrir au clic.

Affiche la liste en menu, superposition ou fenêtre. Le menu choisit automatiquement le haut ou le bas ; les variantes statiques imposent la direction.

Place le bouton et le menu au-dessus de tout pour éviter les conflits de mise en page, avec un léger coût de performance.

Rend l’arrière-plan totalement transparent.

Masque l’icône du bouton.

Masque les icônes de la liste.

Masque l’icône des fenêtres d’information.

Masque le texte du bouton.

Masque les textes de la liste.

Après un clic, une coche marque l’événement comme enregistré, sauf sans libellé, avec buttons-list ou atcb_action. Cette option la désactive aussi dans les autres cas.

Définit le traitement d’un événement passé : « disable » désactive le bouton et « hide » le masque. Ne s’applique pas aux événements récurrents.

Nombre de 0 à 10. Une valeur vaut partout ; jusqu’à trois valeurs ciblent les grands, moyens et petits écrans. Avec deux, la seconde vaut pour moyens et petits.

Choisissez clair, sombre, le réglage système ou « bodyScheme », qui suit les classes « atcb-dark » ou « dark » de html/body.

Sélectionne les traductions incluses, avec prise en charge RTL. L’anglais est intégré ; les autres langues se chargent à la demande ou par import. Les locales complètes préfèrent le pack et le format de date régionaux.

Remplace les textes via un objet JSON et des clés aplaties comme label.addtocalendar. Les libellés personnalisés remplacent les traductions et acceptent les pseudo-balises de description.

Exemple

Remplace les variables CSS globales du bouton. Consultez les fichiers CSS du dépôt. style-light est la valeur par défaut ; définissez style-dark pour le mode sombre.

Remplace les variables CSS globales du bouton ; consultez le début du fichier CSS correspondant dans le dépôt.

Enrichit les données schema.org. Utilisez au moins une image absolue de 720 px, idéalement trois images de 1920 px aux formats 1x1, 4x3 et 16x9.

Désactive les données schema.org générées automatiquement lorsque name, start-date et location sont définis.

Définit l’identifiant lisible utilisé pour le suivi ; par défaut un nombre croissant, unique et sans caractères spéciaux.

Contourne l’aide WebView iPhone uniquement dans votre propre application si le téléchargement s’ouvre dans le navigateur et si ics-file est fourni.

Supprime le discret marquage qui soutient ce projet open source gratuit, tout en respectant la licence.

Ajoute l’attribut « nonce » aux scripts et styles intégrés pour les CSP strictes.

Incrémentez cette valeur pour forcer un nouveau rendu.

Permet aux réglages locaux de remplacer ceux de l’application PRO. Prudence : cela peut créer des incohérences.

Affiche les erreurs de configuration dans la console et à la place du calendrier ; utile lors de la première intégration.