Notre extension pour WordPress vous permet d'intégrer vos agendas hébergés chez https://openagenda.com directement sur votre site WordPress

L'extension est publiée sur le répertoire officiel https://wordpress.org et est disponible en logiciel libre sur github.com.

Utilisation de base

A l'activation, l'extension crée un nouveau type de contenu personnalisé appelée Agendas dans votre administration. Créez simplement un nouvel agenda, et fournissez l'UID de l'agenda que vous souhaitez afficher dans la boite de réglages de votre agenda.

Un nouvel élément de menu Agendas est créé, pour vous permettre d'administrer vos agendas et réglages.

Vous pouvez laisser la zone de contenu vide, cette dernière étant remplie automatiquement avec vos événements.

Créez un nouvel Agenda, puis entrez l'UID unique de votre agenda dans la boite Réglages de l'agenda sur la droite.

Vos événements seront automatiquement affichés après votre contenu, s'il n'est pas vide. Si vous voulez plus de contrôle sur où vos événements seront affichés, utilisez le code court [openagenda] dans votre contenu.

Réglages

Réglages généraux

Les réglages généraux de l'extension se trouve sous le lien Agendas > Réglages dans le menu d'administration.

Toutes les données relatives à votre clé API ou vos agendas peuvent être trouvées sur votre compte https://openagenda.com.

Les réglages sont regroupés sous deux onglets : Général et Intégrations

La page de réglages vous permet d'entrer votre clé API et d'ajuster d'autres réglages.

La page de réglages généraux propose les réglages suivants :

  • Clé API OpenAgenda : votre clé d'API. Il est obligatoire de fournir une clé API pour utiliser l'API Openagenda. Vous pourrez la trouver sur votre compte https://openagenda.com
  • Autoriser les contenus embarqués : si vos événements contiennent des contenus embarqués, coché cette case pour autoriser les balises HTML correspondantes.
  • Charger les styles par défaut : l'extension propose des styles minimaux, et s'appuie le plus possible sur les styles de votre thème. Désactiver cette option pour vous appuyer entièrement sur les styles du thème.
  • Durée du cache : pour des raisons de performances, les requêtes simples vers Openagenda sont mises en cache temporaire. Ce réglage contrôle la durée d'expiration de ce dernier, en secondes
  • Supprimer tous les contenus des agendas lors de la désinstallation : Contrôle si vous voulez supprimer tous les contenus de type Agenda lors de la désinstallation.
  • Supprimer tous les réglages de l'extension lors de la désinstallation : contrôle si vous voulez supprimer les réglages de l'extension (ceux de cette page) lors d'une désinstallation.

Réglages d'intégrations

L'onglet Integrations vous permet de d'affiner vos réglages pour les différentes intégrations offertes par l'extension.

Réglages OpenStreetmap :

  • Lien du fond de carte par défaut : Lien vers le fond de carte utilisé par les cartes de l'extension.
  • URL des crédits du fond de carte : Lien des crédits affiché par défaut sur les cartes OpenStreetMaps.

Réglages CloudImage :

  • Clé API CloudImage : Si vous souhaitez optimiser et servir vos images via CloudImage, renseignez votre clé API ici.

Réglages de permaliens

Dans vos réglages de permaliens (Réglages > Permaliens) vous avez la possibilité de changer le préfixe utilisé pour les pages agendas. Par contre, vous ne pouvez pas laisser ce champ vide, car cela créerait un conflit avec les pages simples de WordPress.

Réglages de l'outil de personnalisation

Aussi, dans l'outil de personnalisation de WordPress (Apparence > Personnaliser) vous disposez d'une section supplémentaire contenant divers réglages liés à l'apparence des agendas. Pour le moment, seul un réglage de couleur est disponible.

Une nouvelle section dans l'outil de personnalisation contient vos réglages d'apparence.

Comment obtenir l'UID de mon agenda ?

L'UID de l'agenda que vous souhaitez afficher peut être trouvé directement sur la page de l'ageda en question, sur https://openagenda.com. Rendez-vous sur le site, puis cliquez sur Chercher un agenda, et utiliser la recherche pour trouver votre agenda.

Votre UID est juste sous les filtres, dans la colonne latérale.

Une fois sur la page de votre agenda, faite défiler un peu vers le bas, et vous trouverez son UID juste sous le dernier filtre, en bas de la colonne latérale.

Le widget Filtre et les codes courts

Pour permettre aux utilisateurs de trouver rapidement les événements pertinents, l'extension fournit un widget Filtre. Placez le widget dans votre colonne latérale ou dans n'importe quelle autre zone de widgets, choisissez un filtre, et si nécessaire ajustez ses réglages.

Ajouter des fonctionnalités de filtre sur vos agendas grâce au widget Filtre

Pour intégrer les filtres directement dans votre contenu ou à d'autres endroits de vos modèles de pages, l'extension fournit des codes courts.

Chacun des codes courts listés ici, (sauf [openagenda]) correspond à un filtre disponible via le widget. Aussi, les codes courts et les widgets filtres disposent des mêmes paramètres et chaque attribut de code court correspond à un réglage du filtre disponible dans le widget.

[openagenda]

Affiche l'agenda. Vous n'avez pas besoin d'utiliser ce code court de façon explicite, car il est automatiquement injecté sur vos pages agendas.

Cependant, si vous avez besoin d'insérer du contenu avant ou après la liste de vos événements, ce code court vous permettra de contrôler où s'affichera la liste de vos événements.

[openagenda_filter_active]

Affiche les filtres actifs. Ne prends aucun paramètre.

[openagenda_filter_choice]

Affiche une liste à choix selon le champ choisi. Il prends les paramètres suivants:

  • field : l'identifiant du champ à afficher (ex: cities, keywords, departments, favorites , etc...)
  • additional_field : l'identifiant du champ additionnel à afficher. Ne fonctionne que si field vaut additional_field.
  • page_size : le nombre de choix à afficher avant le bouton "Plus d'options".

Vous pouvez trouver la liste des champs additionnels disponibles pour votre agenda dans la section Formulaire des réglages de votre agenda (ex : https://openagenda.com/[votre-agenda]/admin/schema ).

[openagenda_filter_calendar]

Affichie un calendrier. Ne prends aucun paramètre.

[openagenda_filter_map]

Affiche une carte interactive pour localiser et rechercher les événements. Le code court prends les paramètres suivants :

  • map_tiles_link : URL du fond de carte à utiliser. Par défaut vaut https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png
  • map_auto : Autoriser la mise à jour automatique de la carte au défilement.

[openagenda_filter_relative]

Permet de filtrer les événements passés ou à venir. Ne prends aucun paramètre.

[openagenda_filter_search]

Affiche un champ de recherche. Le code court prend les paramètres suivants:

  • placeholder : texte de substitution du champ.

[openagenda_preview]

Affiche une prévisualisation des prochains événements. Le code court prend les paramètres suivants:

  • uid : UID de l'agenda à prévisualiser.
  • size : Nombre d'événements à afficher (3 par défaut)
  • filters : Query string representing filters to apply to the request. To ensure it works properly and avoid breaking the shortcode, you should urlencode the query string. You can do so via a simple tool like https://www.urlencoder.org/
  • links : Accepts oa or an empty string. If set to oa, event links will point to events pages on https//openagenda.com instead of local pages.

Personnalisation

Les modèles utilisés pour la liste des événements et les événements simples peuvent être personnalisés simplement dans votre thème enfant.

Créez simplement un dossier openagenda/ dans votre thème enfant, copiez-collez-y le modèle que vous voulez surcharger. Les modèles par défaut utilisés par l'extension se trouvent dans son dossier templates/.

L'extension fournit un certain nombre de fonctions pour afficher les données de vos événements, dans le fichier inc/template-tags.php. Vous pouvez aussi écrire vos propres fonctions dans votre thème enfant.

Aussi, l'extension fournit un certain nombre de hooks vous permettant de personnaliser l'HTML généré ou de filtrer la plupart des données.

Cette extension utilise les données hébergées et fournies par https://openagenda.com. En utilisant l'extension, vous acceptez les termes d'OpenAgenda ainsi que sa politique de confidentialité. Assurez-vous de les lire avant d'utiliser cette extension.

Aussi, même si cette extension ne nécessite pas la création d'un compte sur https://openagenda.com, il est fortement recommandé d'en créer un.

Les cartes affichées par l'extension utilisent les données venant de https://openstreetmap.org et utilise la bibliothèque JavaScript Leaflet. En utilisant cette extension, vous acceptez les termes d'OpenStreetMap, sa politique d'utilisation acceptable ainsi que sa politique de confidentialité.

Les icônes utilisées dans  l'extension sont les Genericons, sous licence GPL 2.0.

Documentation pour développeurs

Surcharge des modèles

Vous pouvez construire des modèles personnalisés pour la vue liste ou la vue événement simple. Les modèles par défaut sont situés dans le dossier templates/ de l'extension. Vous pouvez copier-coller le modèle à surcharger dans un dossier nommé openagenda/ situé à la racine de votre thème enfant, puis personnaliser son contenu.

L'extension cherchera d'abord les modèles dans le dossier openagenda/  du thème enfant, puis dans celui du thème parent, et enfin dans le dossier templates/ de l'extension.

Références des fonctions

Le fichier inc/template-tags.php contient les fonctions utilisées dans les modèles pour afficher les données liées aux événements. Le fichier inc/helper-functions.php contient les fonctions utilisées à divers endroits pour formatter les données ou aider pour des tâches variées.

Voici une liste des principales fonctions dont vous aurez besoin pour personnaliser vos modèles.

openagenda_get_event( $uid = false )

Retourne l'événement correspondant à l'UID passé en paramètre, ou l'événement en cours dans la boucle.

Notez que la fonction n'envoie aucune requête vers https://openagenda.com, mais cherche parmi les événements pour lesquels une requête a déjà été effectuée. Elle renverra false si aucun événement ne peut être trouvé parmi les événements de la page en cours.

openagenda_get_field( $field, $uid = false )

Cette fonction retourne la valeur correspondant au champ passé en paramètre, pour l'événement correspondant à l'UID donné ou pour l'événement courant dans la boucle si aucun UID n'a été fourni.

Pour la plupart des champs, la fonction lit le retour API brut, sauf permalink et timings qui nécessitent un traitement particulier.

Pour les champs multilingue, la valeur renvoyée est celle de la locale courante.

Si vous avez simplement besoin de lire une valeur dans le retour API brut, alors c'est cette fonction qu'il faut utiliser.

Les valeurs retournées sont filtrables via ce filtre : apply_filters( 'openagenda_field', $value, $field, $uid );

openagenda_field( $field, $uid = false )

Comme openagenda_get_field( $field, $uid = false ) mais échappe et affiche la valeur.

openagenda_esc_field( $value, $field )

Cette fonction est utilisée par openagenda_field() pour échapper le champ de façon adéquate, selon le type de champ.

Retourne ou affiche un permalien d'événement, correspondant à l'UID passé en paramètre ou l'événement courant dans la boucle. Le paramètre use_context est utilisé sur les vues liste pour ajouter une chaîne sur l'URL représentant la page d'origine ainsi que les filtres actifs.

Le retour de la fonction passe dans le filtre suivant :  apply_filters( 'openagenda_event_permalink', $permalink, $uid, $use_context );

openagenda_get_event_image( $size = '', $uid = false )

Retourne l'HTML utilisé pour afficher une image d'événement. Par défaut, une image de 700px de large est utilisée.

Le paramètre $size accepte 'thumbnail', 'full' . La taille thumbnail est de 200px par 200px, et la taille 'full' correspond à l'image originale téléversée par l'utilisateur.

Si vous utilisez l'intégration avec CloudImage, la fonction accepte aussi un tableau d'argument CloudImage au lieu d'un identifiant de taille pour premier paramètre. Par exemple, vous pouvez passer array( 'width'=> 500, 'height' => 500, 'grey' => 1 ) pour afficher une image de 500px par 500px en noir et blanc, traitée par CloudImage.

Pour utiliser cette intégration, vous avez besoin d'un compte utilisateur sur https://cloudimage.io, et de renseigner votre clé API dans les réglages d'Intégrations de l'extension. La documentation sur les paramètres acceptés se trouve sur https://docs.cloudimage.io/go/cloudimage-documentation-v7

L'HTML retourné passe dans le filtre suivant : apply_filters( 'openagenda_event_image', $html, $uid, $size );

openagenda_event_image( $size = '', $uid = '' )

Affiche une image d'événement.

openagenda_event_timing( $display = 'date', $uid = false, $echo = true )

Affiche les prochaines dates et heures pour un événement donné, dans un format correspondant au paramètre $display. Si aucun $uid n'est fourni, les dates et heures de l'événement courant dans la boucle utilisés.

Le paramètre $display accepte 'date'(par défaut), ou 'relative'. Si 'relative' est utilisé, la date et heure du prochain événement est affiché dans un format relative lisible (ex : "Dans une semaine"), sinon la date est affiché.

L'HTML retourné passe dans le filtre suivant : apply_filters( 'openagenda_event_timing', $html, $uid, $display );

openagenda_event_timings( $uid = false, $echo = true )

Affiche une liste formattée de toutes les occurences d'un événement.

L'HTML retourné passe dans le filtre suivant : apply_filters( 'openagenda_event_timings', $html, $uid, $months );

openagenda_event_map( $uid = false, $echo = true )

Affiche ou retourne l'HTML de la carte correspondante au lieu de l'événement passé en paramètre ou de l'événement courant dans la boucle, si aucun n'est fourni.

L'HTML retourné passe dans le filtre suivant : apply_filters( 'openagenda_event_map_html', $html, $uid );

openagenda_favorite_badge( $uid = false, $echo = true )
Affiche ou retourne l'HTML du bouton pour mettre un événement en favoris. Les événements mis en favoris peuvent être affichés sur le devant du site en utilisant le widget Filtre Openagenda.

L'HTML retourné passe dans le filtre suivant : apply_filters( 'openagenda_event_favorite_badge', $html, $uid, $agenda_uid, $icon_active, $icon_inactive, $text );

openagenda_event_share_buttons( $uid = false, $echo = true )

Affiche ou retourne l'HTML correspondant aux boutons de partage. Par défaut, des liens pour partager vers Twitter, Facebook, et LinkedIn sont affichés. Vous pouvez ajouter vos liens à l'aide de ce filtre : apply_filters( 'openagenda_sharers', $sharers, $uid, $event ).

L'HTML retourné passe dans le filtre suivant : apply_filters( 'openagenda_sharers_html', $html, $uid, $event );

openagenda_pagination( $args = array() )

Affiche des liens de pagination sur la vue liste. Son fonctionnement est très proche de la fonction native de WordPress paginate_links(). Les arguments par défauts sont :

$args = array(
    'end_size'     => 2,    // Number of items to display after the first page or before the last page
    'mid_size'     => 2,    // Number of page to display around the current page
    'label_format' => '%s', // format used in sprintf() function to display labels. Can be used to wrap labels in additional HTML.
    'prev_label'   => __( 'Previous page', 'openagenda' ),   // Previous page label
    'next_label'   => __( 'Next page', 'openagenda' ),       // Next page label
);

Les arguments passent dans le filtre suivant : apply_filters( 'openagenda_page_links_args', $args, $uid ) .

L'HTML retourné passe dans le filtre suivant : apply_filters( 'openagenda_page_links', $links, $uid );

Retourne le permalien de l'agenda correspondant à l'UID passé en paramètre, ou à l'agenda courant sur les pages agenda.

Le permalien passe par le filtre suivant : apply_filters( 'openagenda_permalink', $permalink, $uid )

openagenda_exports( $uid = false, $echo = true )

Affiche des liens pour exporter le contenu d'un agenda correspondant à l'UID passé en paramètre ou à l'agenda courant, sur la vue liste.

L'HTML retourné passe dans le filtre suivant : apply_filters( 'openagenda_exports_html', $html, $uid );

openagenda_filter( $filter, $args = array() )

Affiche un filtre. Le paramètre $filter accepte : 'active', 'choice', 'calendar', 'map', 'relative', 'search' . Le paramètre $args contient les paramètres passés au code court correspondant au filtre. Voir Le widget Filtre et les codes courts, plus haut.

Evitez d'utiliser cette fonction dans le modèle de la vue liste. Quand la liste des événements est rafraichie via AJAX, le contrôleur des filtres va perdre la connexion avec le filtre affiché dans le modèle, car l'élément DOM correspondant est enlevé et réaffiché quand la liste est rafraichie.

À noter: il est également possible d'ajouter des filtres en plaçant des codes HTML directement dans la page. Pour en savoir plus, cliquez ici: https://www.npmjs.com/package/@openagenda/react-filters

openagenda_navigation( $echo = true )

Affiche ou retourne l'HTML de la navigation entre les événements sur les vues simples.

L'HTML retourné passe dans le filtre suivant : apply_filters( 'openagenda_event_navigation', $html, $previous_link, $next_link );

Utilisé par openagenda_navigation().

Renvoie le lien utilisé pour calculer l'événement adjacent. Le contenu provenant d'un export JSON de l'agenda, sur les vues événements simples, un seul événement est retourné. De ce fait, les événements ne sont pas stockés en base de données et une référence directe à un événement adjacent n'est pas possible.

Un peu de travail est nécessaire en coulisses pour retrouver le lien vers l'événement suivant ou précédent, en fonction du contexte dans lequel l'utilisateur a navigué vers l'événement actuel. Cette fonction renvoie donc un lien vers une action admin-post.php ou ce calcul s'effectue.

L'HTML retourné passe dans le filtre suivant : apply_filters( 'openagenda_adjacent_event_link', $html, $uid, $direction );

Renvoie le lien retour vers la liste des événements, sur la vue événement simple.

L'HTML retourné passe dans le filtre suivant : apply_filters( 'openagenda_back_link', $html, $page_link, $page, $context );

openagenda_get_template( $slug )

Retourne le chemin vers un modèle. Cherche d'abord le modèle dans le dossier openagenda/ du thème enfant, puis dans le dossier openagenda/ du thème parent, et enfin dans le dossier templates/ de l'extension.

openagenda_get_locale()

Retourne le code correspondant à la locale actuelle, si supportée. Par défaut, elle vaut 'en'.

Des locales supportées supplémentaires peuvent être ajoutées via ce filtre : apply_filters( 'openagenda_supported_locales', $locales )

openagenda_language_switcher( $uid = false, $echo = true )

Affiche un menu des langues disponibles. Sur les vues listes, les langues disponibles dans tout l'agenda sont affichées. Sur les vues événement simple, seules les langues disponibles pour cet événement sont affichées.

Aussi, sur les vues liste, s'il est utilisé, le paramètre $uid doit correspondre à l'identifiant de l'agenda. Sur les vues événement simple, il doit correspondre à l'UID de l'événement.

La liste des langues disponibles est filtrable via le filtre suivant : apply_filters( 'openagenda_switcher_languages', $languages, $uid );

Note importante : cette fonction surcharge simplement la langue du contenu affiché par l'extension OpenAgenda. Elle ne modifie pas la langue du site. Pour des fonctionnalités multilingues plus complètes, utilisez une extension dédiée comme Polylang.

openagenda_get_image_dimensions( $size = 'thumbnail' )

Retourne un tableau contenant les dimensions des images correspondantes à la taille passée en paramètre.

Vous pouvez enregistrer de nouvelles tailles d'images via ce filtre : apply_filters( 'openagenda_image_sizes', $sizes ).

Vous pouvez personnaliser les dimensions retournées via ce filtre : apply_filters( 'openagenda_image_dimensions', $dimensions, $size ).

openagenda_is_i18n_field( $field )

Vérifie si le champ passé en paramètre est un champ multilingue.

Vous pouvez enregistrer de nouveaux champs multilingues via ce filtre : apply_filters( 'openagenda_i18n_fields', $i18n ).

openagenda_icon( $slug, $echo = true )

Affiche ou retourne une icone SVG.

Vous pouvez enregistrer de nouvelles icones via ce filtre : apply_filters( 'openagenda_icons', $icons ).

openagenda_is_single()

Retourne un booléen indiquant si la vue courante est une vue événement simple.

openagenda_is_archive()

Retourne un booléen indiquant si la vue courante est une vue liste.

openagenda_format_timing( $timing, $datetimezone = null )

Prend une entrée timing d'un événement, et formate sa date et son heure pour les différents affichages possibles. La fonction renvoie un tableau contenant les différents formats, basés sur une DateTimeZone PHP passée en paramètre ou le fuseau horaire du site.