Paramètres des widgets

Intégration agenda

data-base-url

Cet attribut spécifie une url de base qui servira pour ouvrir les événements lors d'un clic.

Important : L'URL précisée doit pointer vers une implémentation d'agenda existante: le code d'intégration se contente de renvoyer le visiteur cliquant sur une vignette événement vers ce lien, complété du code URL de l'événement. Ce fonctionnement est compatible avec une implémentation faite avec le module Drupal ou la librairie agenda-portal.

En ajoutant l'attribut data-base-url="https://mon-site.com/agenda" au <blockquote> du code d'intégration les événements seront ouverts dans un nouvel onglet sur la page https://mon-site.com/agenda/slug-evenement.

Exemple :

<blockquote data-base-url="https://mon-site.com/agenda" class="oa-agenda" align="center">
    <p lang="fr">Voir les événements de <a
      href="https://openagenda.com/agendas/5109558?relative%5B0%5D=current&relative%5B1%5D=upcoming"
        >
            <strong>Fête de la musique 2024</strong>
        </a>
    </p>
</blockquote>
<script async src="https://cdn.openagenda.com/js/widgets.js" charset="utf-8"></script>

En précisant oa comme valeur plutôt qu'une URL, le visiteur sera renvoyé vers le détail de l'événement sur openagenda.com

data-filters

Cet attribut prend en compte une liste de filtres à afficher dans l'intégration. Les codes à fournir, séparés par des virgules, sont les mêmes qu'utilisés en URL lorsque des filtres sont activés sur l'accueil de l'agenda ou sur son administration.

Exemple :

<blockquote
  class="oa-agenda"
  align="center"
  data-filters="search,geo,timings,themes,publics"
>
  <p lang="fr">Voir les événements de <a href="https://openagenda.com/agendas/64168411?relative%5B0%5D=current&relative%5B1%5D=upcoming"><b>Limoges</b></a></p>
</blockquote>
<script async src="https://cdn.openagenda.com/js/widgets.js" charset="utf-8"></script>

data-primary-color

Ce paramètre vous permet de définir une couleur principale personnalisée pour correspondre au mieux à votre charte graphique.

Exemple :

<blockquote
  class="oa-agenda"
  align="center"
  data-primary-color="#FF5733"
>
  <p lang="fr">Voir les événements de <a href="https://openagenda.com/agendas/64168411?relative%5B0%5D=current&relative%5B1%5D=upcoming"><b>Limoges</b></a></p>
</blockquote>
<script async src="https://cdn.openagenda.com/js/widgets.js" charset="utf-8"></script>

Dans cet exemple, la couleur principale du widget sera définie sur #FF5733 (un orange vif).

data-image-list

Ce paramètre vous permet de contrôler l'apparence des images affichées dans le widget. Grâce à des valeurs flexibles, vous pouvez ajuster des propriétés comme le format, les dimensions ou le ratio d'aspect des images. Ce paramètre accepte plusieurs valeurs séparées par un point-virgule ;.

Valeurs possibles :

  • contain ou cover : Correspond à la propriété CSS object-fit.
  • ratio : Définit le ratio d'aspect via aspect-ratio (exemple : ratio:1 pour un carré).
  • maxHeight ou height : Contrôle la hauteur maximale ou fixe via max-height ou height (exemple : maxHeight:400px).

Exemple :

<blockquote
  class="oa-agenda"
  align="center"
  data-image-list="contain;maxHeight:400px"
>
  <p lang="fr">Voir les événements de <a href="https://openagenda.com/agendas/64168411?relative%5B0%5D=current&relative%5B1%5D=upcoming"><b>Limoges</b></a></p>
</blockquote>
<script async src="https://cdn.openagenda.com/js/widgets.js" charset="utf-8"></script>

Dans cet exemple, les images utiliseront le mode contain pour conserver leurs proportions et auront une hauteur maximale de 400 pixels.

Autre exemple :

<blockquote
  class="oa-agenda"
  align="center"
  data-image-list="cover;ratio:1"
>
  <p lang="fr">Voir les événements de <a href="https://openagenda.com/agendas/64168411?relative%5B0%5D=current&relative%5B1%5D=upcoming"><strong>Limoges</strong></a></p>
</blockquote>
<script async src="https://cdn.openagenda.com/js/widgets.js" charset="utf-8"></script>

Ici, les images seront affichées en mode cover avec un ratio d’aspect carré (1:1).

Configurer le gestionnaire de widgets OpenAgenda

Le moyen le plus simple de créer un widget OpenAgenda pour sites Web (un agenda, un événement) consiste à copier et coller le code HTML généré dans la modale d'export.

Pour des performances et une fiabilité optimales, incluez le script widgets.js dans votre modèle

Incluez le gestionnaire de widgets OpenAgenda une fois dans votre modèle de page pour optimiser les performances de votre page Web.

Si votre site utilise plusieurs widgets, vous pouvez configurer une seule fois les widgets OpenAgenda dans vos pages, ce qui rendra votre site plus rapide.

<script>window.oa = (function(d, s, id) {
  var js, fjs = d.getElementsByTagName(s)[0],
    t = window.oa || {};
  if (d.getElementById(id)) return t;
  js = d.createElement(s);
  js.id = id;
  js.src = '/index.js';
  js.async = true;
  fjs.parentNode.insertBefore(js, fjs);

  t._e = [];
  t.ready = function(f) {
    t._e.push(f);
  };

  return t;
}(document, 'script', 'oa-wjs'));</script>

Cet extrait de code optimise le chargement de la manière suivante :

  • Attribue un identifiant (ID) HTML unique, oa-wjs, à l'élément pour vérifier facilement si le fichier JavaScript est déjà présent sur la page. Si cet ID existe déjà, le chargement est arrêté immédiatement.
  • Charge le JavaScript de OpenAgenda de manière asynchrone pour améliorer les performances des sites web.
  • Initialise une file d'attente de fonctions asynchrones pour stocker les fonctions dépendantes jusqu'à ce que le script soit disponible.
  • Place cet extrait avant tout autre JavaScript sur votre page qui pourrait dépendre de la file d'attente de fonctions asynchrones oa.ready.

Ignorer les balises de script des intégrations

Si vous incluez le chargeur JavaScript de Twitter sur chaque page, vous n'avez pas besoin d'inclure l'élément <script> généré par une modale d'export. Vous pouvez supprimer l'élément <script> supplémentaire du code HTML généré.

Initialisation du contenu intégré après le chargement d'une page

La plupart des intégrations d'OpenAgenda seront bien servies par le code d'intégration recommandé trouvé dans la modale d'export, mais vous souhaiterez peut-être optimiser comment et quand les widgets JavaScript d'OpenAgendaanalysent le DOM de la page pour découvrir de nouveaux éléments HTML éligibles à une augmentation en widget.

Si le contenu est inséré dynamiquement dans une page (par exemple, en cas de chargement différé ou en utilisant une technique pushState pour naviguer entre les pages), il est nécessaire d'analyser les nouveaux widgets à l'aide de la fonction oa.widgets.load().

oa.widgets.load();

Appelé sans argument, widgets-js recherchera dans toute l'arborescence DOM document.body les widgets non initialisés. Pour de meilleures performances, transmettez un objet HTMLElement pour restreindre la recherche uniquement aux enfants de l'élément.

Exemple:

oa.widgets.load(  document.getElementById("container"));

Événements système

Attente de ressources asynchrones

Charger le fichier widgets.js de manière asynchrone nécessitera d'attendre avant de lier les événements : les fonctions que vous appelez n'existent pas encore. Vous devrez encapsuler vos liaisons d'événements dans une fonction de rappel telle que la file d'attente de fonctions asynchrones oa.ready, qui sera invoquée une fois que tout sera chargé.

oa.ready(function (oa) {  // ...});