Configuración del botón Add to Calendar

Si utilizas el servicio PRO, puedes usar el atributo «prokey» para conectar el botón con uno de tus eventos.
En este caso no es necesario definir ningún otro parámetro en el código, ya que todo se gestiona al 100 % desde el panel de administración de Add to Calendar PRO.

Si un grupo de eventos está configurado tanto para suscripción como para una lista de eventos, se muestra de forma predeterminada el botón de suscripción. Usa este atributo para mostrar en su lugar la lista de eventos.

Ajustes opcionales para group-overview:

• years-only (Boolean): oculta el selector de mes y muestra todos los eventos del año seleccionado.
• type (String): list (predeterminado), cards o compact.
• from (String): fecha y hora ISO UTC que limita el extremo inferior. No puede ser anterior al 1 de enero del año previo.
• to (String): fecha y hora ISO UTC que limita el extremo superior. No puede preceder a from.
• no-details (Boolean): abre el modal de opciones de calendario en vez de enlazar a su página de destino.
• no-add (Boolean): desactiva todas las interacciones. Las entradas no tienen enlace, acción de calendario ni insignia para añadir, independientemente de los demás ajustes.
• custom-domain (String; nombre de host, como events.acme.com): usa este dominio para los enlaces de destino. El dominio también debe configurarse en Add to Calendar PRO.
• add-via-list (Boolean): añade una discreta insignia para agregar al calendario. Con no-details, forma parte del enlace del evento y abre las opciones junto con el resto de la entrada.

El título de tu evento.

Debe ser una cadena más bien corta.
El nombre sigue siendo obligatorio si estableces el parámetro «dates» (varias fechas). En ese caso actúa como valor alternativo y nombre de la serie de eventos.
En una suscripción, el nombre se utiliza como nombre del calendario en los servicios de Microsoft.

Admite pseudoetiquetas HTML para el formato: [url], [br], [hr], [p], [strong], [u], [i], [em], [li], [ul], [ol], [h*] (como h1, h2, h3, ...).
Define el texto de un enlace con este esquema: [url]https://....|Texto del enlace[/url].

(Si hay problemas de compatibilidad, puedes usar llaves {} en lugar de corchetes [].)

(Apple, Yahoo y Microsoft Teams no son totalmente compatibles; el valor se transforma automáticamente en texto plano y solo conserva saltos de línea e hipervínculos.)

Ejemplo

Una fecha debe tener el formato YYYY-MM-DD definido por ISO-8601.

Puedes usar la palabra mágica «today» para establecer dinámicamente el día actual. Añadir «+5» al final suma automáticamente 5 días a la fecha calculada.

De forma no oficial, también funciona un formato como «YYYY-MM-DDTHH:MMZ».

Ejemplo

Si no se establece, el evento se define como «de todo el día».

Una fecha debe tener el formato YYYY-MM-DD definido por ISO-8601.

Si no se establece una fecha final, se supone que es igual a la fecha inicial. La palabra mágica «today» establece dinámicamente el día actual. Añadir «+5» suma automáticamente 5 días a la fecha calculada.

De forma no oficial, también funciona un formato como «YYYY-MM-DDTHH:MMZ».

Si no se establece, el evento se define como «de todo el día».

No es obligatorio, pero se recomienda añadir una zona horaria.
Puedes consultar una lista en Wikipedia.

Puedes usar «currentBrowser» para emplear dinámicamente la hora del navegador del usuario. Úsalo con precaución, porque la hora del evento será distinta para cada usuario, algo que normalmente no es deseable.
La zona horaria solo se aplica cuando se definen start-time y end-time.

Esta opción transforma la hora y la zona horaria según los ajustes de cada usuario.

Si la estableces en «true», la hora se convierte a la zona horaria del usuario.
Es distinto de la zona horaria artificial «browserTime», que solo transforma la zona, no la hora en sí.
Úsala con precaución: manipular la zona horaria por usuario puede tener efectos secundarios no deseados. Normalmente debería hacerlo la aplicación de calendario del usuario.

Puede contener cualquier valor.

Si es una URL, el evento se clasifica como «evento en línea» en la declaración de schema.org.
Los eventos en línea no aparecen en el botón de fecha. Además, la hora de este tipo de botón se convierte a la zona horaria del usuario (también si la ubicación es «Global», «Worldwide» u «Online»).

Permite gestionar cambios en un evento según la especificación iCalendar RFC5545.

Ejemplo

Debe ser un número entero positivo.
Debe aumentar cuando realices cambios en el evento.

Ejemplo

De forma predeterminada, el evento se marca como ocupado/libre/disponible según la configuración del calendario del usuario.
En Apple, iCal y Google puedes forzar este valor con las opciones «busy» o «free».

El identificador único del evento tal como se utiliza en el archivo iCal.

Solo puede contener letras, dígitos y guiones, y debe tener menos de 255 caracteres.
Se recomienda un identificador único universal (UUID) aleatorio codificado en hexadecimal.

Usa el esquema «NOMBRE|CORREO» (p. ej. «Juan Pérez|juan.perez@gmail.com»).

El organizador aparece tanto en los datos enriquecidos de schema.org como en el archivo iCal.
Esta opción también cambia cómo se procesan los archivos ics (iCal): los calendarios ya no se limitan a guardar el evento, sino que lo consideran una invitación que se puede aceptar o rechazar.

Ejemplo

Usa el esquema «NOMBRE|CORREO» (p. ej. «Juan Pérez|juan.perez@gmail.com»), o solo el correo, ya que el nombre es opcional.
Esta opción permite actualizar un evento en el calendario de un usuario si este también carga el nuevo archivo iCal.

Solo se puede especificar 1 asistente.
Debe ser la persona que guarda el evento.
Si no dispones de esta información, no uses esta opción.

Si especificas un asistente, también debes especificar un organizador.

Para definir una serie de eventos puedes usar el objeto «dates».

Contiene la misma estructura de fecha que el nivel raíz, pero permite definir varios eventos. Los valores raíz prevalecen sobre los del objeto «dates», excepto el nombre cuando hay varias fechas (el nombre raíz se convierte en el título de la serie). La «UID» es un caso especial: solo usa la información raíz en el primer subevento, pues debe ser única. Los siguientes reciben UID nuevas generadas al azar.

Atributos por bloque de subevento:

• name
• description
• start-date
• start-time
• end-date
• end-time
• time-zone
• use-user-tz
• location
• status
• sequence
• availability
• uid
• organizer
• attendee
• la mayoría de opciones ics; consulta más abajo

Ejemplo

Define eventos recurrentes.

Desactiva las opciones de Yahoo y Microsoft (y Google en iOS), porque actualmente no las admiten; los usuarios aún pueden usar iCal. Si no queda ninguna opción, iCal se establece como alternativa.
No es posible usar más de una fecha (opción dates) junto con recurrence.

Puedes usar cualquier RRULE válida excepto BYHOUR, BYMINUTE y BYSECOND (generador).

Como alternativa, los siguientes ajustes simplificados pueden generar la RRULE en segundo plano. En ese caso, en «recurrence» se define la frecuencia (daily, weekly, monthly, yearly) en lugar de la RRULE.

Ejemplo

Define el intervalo entre repeticiones.
«3» significa «cada tercera».

Define una fecha final.
La convertimos automáticamente al valor COUNT correcto, ya que UNTIL no es compatible con todas las aplicaciones.

Define un límite máximo de repeticiones.
Si se indican recurrence-until y recurrence-count, prevalece el que ocurra primero. Si no se indica ninguno, se repite indefinidamente.

Define los días de la semana (MO, TU, WE, TH, FR, SA, SU) en que ocurre el evento, por ejemplo si está ligado al martes y no al día 24.
Requiere frecuencia semanal.
Puede incluir un número para indicar, por ejemplo, el tercer lunes (3MO).
Admite varios valores separados por comas.

Usa esta opción en lugar de «byDay» si quieres un día numerado (1, 2, ... 31) en vez de un día de la semana.
Requiere frecuencia mensual.
Admite varios valores separados por comas.

Define los meses (1, 2, 3, ... 12) en los que debe ocurrir el evento.
Requiere frecuencia anual.
Admite varios valores separados por comas.

Define un día concreto como inicio de la semana.

Como alternativa a un evento predefinido, puedes alojar un calendario y ofrecer su suscripción (requiere un calendario alojado).
Para ofrecerla mediante el botón también debes especificar ics-file.

«Name» y «start-date» siguen siendo necesarios por motivos organizativos, pero los demás parámetros del evento pueden omitirse. En los servicios de Microsoft, «Name» se usa como nombre del calendario. Microsoft Teams aún no es compatible y Yahoo ya no lo es; ambos se desactivan automáticamente, al igual que otros servicios de Microsoft en móviles.

Si el navegador no reconoce ninguna aplicación de calendario instalada, puede mostrar una pantalla en blanco. La versión PRO lo evita mediante una pantalla intermedia explicativa.

Ejemplo

El archivo iCal/ics se crea dinámicamente.
Esto tiene algunos inconvenientes, ya que en casos excepcionales puede bloquearse.
Esta opción permite redirigir a un archivo ics existente.

En una suscripción debes definir aquí el calendario externo.

Si hay varias fechas y se ha establecido organizer o status, debes preparar varios archivos ics: aquí se especifica el de la primera fecha y las posteriores buscan un archivo con el mismo nombre y un número añadido a partir del 2 (p. ej. «event-2.ics»).

Para definir un nombre específico para cualquier archivo ics (iCal) generado, usa la opción ical-file-name.

Añade una alarma. Indica los minutos antes del inicio (p. ej. "30") o una duración ISO 8601 sin procesar (p. ej. "-PT1H").

Adjunta un enlace canónico (propiedad URL) al evento. Debe ser una URL http(s) válida.

Etiqueta el evento con una lista de categorías separadas por comas.

Establece la clasificación del evento.

Establece la prioridad desde 0 (indefinida), pasando por 1 (máxima), hasta 9 (mínima).

Añade coordenadas geográficas. Junto con «location», Apple Calendar muestra una vista previa del mapa.

Adjunta archivos mediante URL (lista de URL http(s) separadas por comas), como una agenda PDF o una entrada.

Excluye fechas de un evento recurrente (lista separada por comas). Requiere «recurrence» y es la única que no puede definirse por entrada.

El campo «Created» usa por defecto la hora de generación y descarga. Usa esta opción para fijar una marca UTC estática, p. ej. «20231201T103000Z».

El campo «Updated» usa por defecto la hora de generación. Usa esta opción para fijar una marca UTC estática, p. ej. «20231201T103000Z».

Array de calendarios de la lista. Con un solo tipo, su icono sustituye al predeterminado y la acción es directa. Algunas opciones pueden excluirse según otros ajustes; «ical» se sustituye por «apple» en iOS. options-mobile define los móviles y options-ios sustituye esa selección en iOS (no Mac).

Hay varios estilos integrados que también afectan a otros parámetros. Pruébalos. «none» no carga CSS y «custom» requiere el archivo de «custom-css». Solo el estilo predeterminado está incluido; los demás se cargan bajo demanda o mediante imports. Importa styles/all para registrarlos todos; consulta «style-source» y «load-all-styles».

Renderiza el botón en línea en vez de como bloque.

Carga un CSS externo con button-style «custom». El CSS personalizado no se carga en SSR.

Ejemplo

Sustituye la URL base de estilos e idiomas cargados bajo demanda. Debe apuntar al directorio que contiene styles/ y locales/.

Precarga todos los estilos para cambiarlos en tiempo de ejecución sin retraso de red. Solo funciona con etiqueta script; con npm importa los módulos o styles/all.

Muestra un botón por calendario.

Sustituye el texto del botón.

La lista suele abrirse al pasar el cursor; usa «click» para abrirla al hacer clic.

Muestra la lista como desplegable, superposición o modal. El desplegable elige arriba o abajo; las variantes estáticas fuerzan la dirección.

Coloca el botón y el desplegable sobre todo para evitar conflictos de diseño, con un pequeño coste de rendimiento.

Hace el fondo totalmente transparente.

Oculta el icono del botón.

Oculta los iconos de la lista.

Oculta el icono de los modales.

Oculta el texto del botón.

Oculta los textos de la lista.

Tras pulsar, una marca indica que el evento se guardó, salvo sin etiquetas, con buttons-list o atcb_action. Esta opción también la desactiva en los demás casos.

Define qué ocurre con un evento pasado: «disable» desactiva el botón y «hide» lo oculta. No se aplica a eventos recurrentes.

Número de 0 a 10. Un valor se aplica siempre; hasta tres corresponden a pantallas grandes, medianas y pequeñas. Con dos, el segundo sirve para medianas y pequeñas.

Elige claro, oscuro, el ajuste del sistema o «bodyScheme», que sigue las clases «atcb-dark» o «dark» de html/body.

Selecciona las traducciones incluidas, con RTL. El inglés está integrado; los demás idiomas se cargan bajo demanda o por import. Las configuraciones regionales completas prefieren su paquete y formato de fecha regional.

Sustituye los textos mediante JSON y claves planas como label.addtocalendar. Las etiquetas personalizadas prevalecen y admiten las pseudoetiquetas de descripción.

Ejemplo

Sustituye las variables CSS globales del botón. Consulta los archivos CSS del repositorio. style-light es el valor predeterminado; define style-dark para el modo oscuro.

Sustituye las variables CSS globales del botón; consulta el inicio del archivo CSS correspondiente en el repositorio.

Enriquece los datos de schema.org. Usa al menos una imagen absoluta de 720 px; idealmente tres de 1920 px en 1x1, 4x3 y 16x9.

Desactiva los datos de schema.org generados automáticamente cuando se definen name, start-date y location.

Define el identificador legible usado para seguimiento; por defecto un número ascendente, único y sin caracteres especiales.

Omite la ayuda de WebView de iPhone solo en tu propia app si la descarga se abre en el navegador y se proporciona ics-file.

Elimina la discreta marca que apoya este proyecto gratuito de código abierto, respetando la licencia.

Añade «nonce» a scripts y estilos en línea para políticas CSP estrictas.

Incrementa el valor para forzar un nuevo renderizado.

Permite que los ajustes locales sustituyan los de la app PRO. Puede provocar incoherencias.

Muestra errores de configuración en la consola y en lugar del calendario; útil durante la primera integración.