Formation « Des champs administrables avec ACF »

Le champ galerie d’ACF, avec lightbox et diaporama

Lecture : 9 minutes • 13

Dans ce cours nous allons voir comment tirer parti du champ galerie d’ACF pour créer, comme vous vous en doutez, une galerie, mais aussi un diaporama animé, et ajouter une Lightbox grâce à un petit peu de Javascript.

Présentation du champ galerie

Le champ galerie est l’un de mes champs préférés, car il permet de faire plein de choses avec les images : une galerie certes, mais également un diaporama animé (slider). Et pour couronner le tout on va terminer avec une Lightbox toute simple.

Une galerie gérée par ACF
Exemple de rendu de notre galerie

ACF nous offre un joli champ pour gérer facilement plusieurs images et les réorganiser :

Le champ Galerie d'ACF dans WordPress
L’interface du champ est ergonomique

Passons sans plus attendre à la configuration !

Configuration du groupe de champs

On va commencer par créer notre groupe de champ. Allez dans ACF > Groupes de champs > Ajouter. Si vous avez importé mon fichier JSON, le groupe de champ devrait déjà être pésent.

Les réglages du champ

On va ajouter un seul champ pour le moment, qu’on va appeler Galerie et qui sera du type Galerie.

Panneau des réglages du champ galerie d'ACF
Les réglages principaux de notre champ Galerie

Par contre, j’aime bien mettre le nom du champ (son slug) en anglais, car il sera utilisé dans le code source. Du coup, j’opte pour gallery.

En ce qui concerne le format de sortie, on va choisir ID de l’image. On n’a besoin que de leurs identifiants, car on va faire appel par la suite à des fonctions natives de WordPress qui vont générer le HTML des images pour nous.

On ne touche pas aux autres options mais certaines pourraient être intéressantes selon votre besoin :

  • Vous pouvez par exemple demander un minimum de 4 images ;
  • Interdire les images plus petites que 1000px ;
  • Interdire les fichiers plus lourds que 2Mo ;
  • Ou encore restreindre à des formats jpg seulement ;

Ces paramètres peuvent s’avérer très pratiques si votre site possède des rédacteurs qui ne feraient pas forcément attention à l’optimisation des images. Ces gardes-fous vous permettraient de garantir les meilleures performances possibles.

Assigner le groupe de champs

On va maintenant assigner notre groupe à un modèle de page. Mais avant ça j’ai créé un modèle de page nommé gallery.php et que j’ai placé dans le dossier templates de mon thème.

PHP
templates/gallery.php

Dans le bloc « Assigner ce groupe de champs » de ACF, vous devriez pouvoir sélectionner Modèle de page • est égal à • Champ Galerie.

Capture d'écran de l'interface de gestion des champs ACF
La configuration de notre champ Galerie

Donc, notre champ Galerie va apparaitre lorsque je vais créer une nouvelle page et lui assigner le modèle de page Champ Galerie. On va tester.

Allez dans Pages > Ajouter, puis dans la colonne des réglages à droite cherchez Attributs de page, et choisissez le modèle Champ Galerie.

Il faut choisir le modèle de page pour voir apparaitre notre groupe de champ
Pensez à choisir le modèle pour voir apparaitre le groupe de champs

À ce moment là, le groupe de champs devrait apparaitre en bas de la page ! C’est le moment d’ajouter quelques images à notre galerie :

Le champ galerie dans l'interface d'administration de WordPress
Le champ galerie après sélection de quelques images

Une fois vos images choisies, vous allez pouvoir les réorganiser par un simple glisser / déposer. Vous pouvez supprimer une image en cliquant sur la croix qui apparaît au survol, et des actions de groupe sont disponibles pour réorganiser les images ou inverser leur ordre.

Bien, maintenant que tout est prêt, passons au code pour afficher notre galerie.


Pour plus d’informations sur les réglages possibles du champ galerie, rendez-vous sur la documentation officielle d’ACF.

Documentation du champ galerie

Elle est très bien écrite et ultra claire. C’est d’ailleurs sûrement l’une des meilleures documentations techniques qu’il m’a été donné de lire.

Créer une galerie

Tout est prêt côté backend, mais c’était la partie la plus facile. Maintenant place au code ! Bon, en réalité, ce n’est pas très compliqué car le code qu’on va utiliser est toujours le même, peu importe le cas !

Pour ce premier exemple, on va afficher une simple galerie, à l’aide de PHP et d’un petit peu de CSS.

Côté PHP

Le code PHP est à mettre à l’endroit où on veut afficher la galerie, dans notre template. Ça peut être avant the_content(), ou après. Comme vous voulez !

PHP
templates/gallery.php

La première chose qu’on fait, c’est récupérer le contenu de notre champ via la fonction get_field(). Et c’est bien notre slug de champ que l’on indique ici, donc le nom gallery en anglais que l’on a défini précédemment.

Ensuite, on définit la taille d’image qu’on va vouloir récupérer, on choisit Full pour le moment.

On continue avec un test : si la galerie a au moins une image, alors on va créer une balise <ul> pour commencer notre « liste » d’images.

Enfin, on lance une boucle Foreach (pour chaque image trouvée…). La seule donnée qu’on a pour le moment est l’identifiant de l’image.

On va donc utiliser 2 fonctions de WordPress pour nous aider :

  • wp_get_attachment_url() permet de récupérer l’URL de l’image en grande taille ;
  • Et wp_get_attachment_image() permet de générer la balise image, avec la prise en charge du srcset.

Pour cette dernière, on indique en second paramètre la taille de l’image à afficher, donc notre taille full. Dans WordPress cela veut dire qu’il va prendre la version originale de l’image.

Le srcset sera généré automatiquement et proposera au navigateur des versions plus petites pour le responsive.

Coté CSS

Si vous essayez en l’état, vos images devraient déjà apparaitre, mais sans aucune mise en forme. Alors afin de rentre le tout plus esthétique, on va ajouter une petite dizaine de lignes de CSS, en utilisant notamment Flexbox pour créer une grille simple.

CSS
style.css

Pas besoin de plus pour un résultat sympathique. Les images s’affichent 3 par 3 et comme j’en ai sélectionné 8 en tout, les 2 dernières occupent l’espace restant et s’affichent plus grandes.

Capture d'écran de notre galerie photo ACF
Notre galerie ACF avec un peu de CSS flex

Améliorer l’alignement et le ratio des images

Par contre, comme les images n’ont pas toutes le même ratio, c’est-à-dire la même proportion hauteur / largeur, elles ne sont pas toutes alignées par le bas, ce qui n’est pas très esthétique. On va donc aller corriger ça.

Pour cela on doit contraindre les images à avoir la même taille. Et on a vu comment le faire dans le cours sur les tailles d’images :

PHP
functions.php

Le dernier paramètre est le plus important : passé à true, il indique que je veux forcer cette taille exactement. WordPress va donc faire en sorte de « découper » ce qui dépasse. En créant une taille d’image gallery-thumb, j’assure donc des images à 1200px de large sur 800px de haut.

Mais cette taille ne sera appliquée que lorsque l’on importera de nouvelles images. On va donc faire appel à un plugin pour regénérer les différentes tailles de mes images :

Regenerate Thumbnails

Regenerate Thumbnails

Recrée les miniatures pour une ou plusieurs de vos images téléversées. Utile si vous changez de tailles d’images ou de thème.

Par Alex Mills (Viper007Bond)

Il va passer sur toutes les images de ma bibliothèque, et appliquer les nouveaux formats.

Allez dans Outils > Regénérer les miniatures d’images. Vous devriez voir votre nouvelle taille d’image dans la liste. Cliquez sur Regénérer les miniatures et laissez faire l’outil.

L'outil de redimensionnement des images.
Regenerate Thumbnail en plein travail

Maintenant, on va retourner dans le PHP et on va changer notre variable $size. On lui indique cette fois qu’on veut notre nouveau format gallery-thumb de 1200×800.

PHP
templates/gallery.php

Enregistrez, rechargez la page, et ça devrait être beaucoup mieux !

Capture d'écran de la galerie ACF, avec cette fois les images bien cadrées
Notre galerie bien cadrée

Nos images ont maintenant toutes la même taille et le même ratio largeur/hauteur, ce qui donne un rendu bien plus esthétique dans notre galerie.

Ajouter une Lightbox

Maintenant on va ajouter une lightbox pour, qu’au clic sur une image, on puisse l’agrandir sans quitter la page. Et comme on est des guedins, on va la faire nous même, sans faire appel à une librairie jQuery.

Vous allez voir que c’est bien plus simple que ce qu’il n’y paraît.

Les (trop) grandes images

On a déjà préparé le terrain en mettant un lien sur chaque image. L’URL de celle-ci était récupérée via la fonction wp_get_attachment_url().

PHP
templates/gallery.php

Le saviez-vous ?

WordPress n’ira pas chercher l’image en taille originale si celle-ci dépasse 2560px, à la place, il affichera une version plus petite, automatiquement redimensionnée par WordPress, à 2560px tout pile.

De cette manière, on évite de charger en lightbox des images lourdes. Ayant pris mes images sur Unsplash, celles-ci peuvent parfois faire plus de 8000px et dépasser les 20Mo !

Quand je fais le test en cliquant sur l’image, on voit à la fin de son URL -scaled.jpg. C’est la version à 2560px de WordPress. En téléchargeant l’image et en ouvrant l’inspecteur du Mac, j’en ai bien la confirmation.

L'image qui apparait à l'écran n'est pas l'originale, mais celle redimensionnée à 2560px par WordPress
L’image est bien celle redimensionnée à 2560px

C’est une bonne taille, ça permet d’avoir une image nette et pas trop lourde, même sur des écrans à haute densité de pixels comme les écrans Retina.

Le code de notre lightbox

On va maintenant ajouter le code nécessaire à notre lightbox, et pour cela on va intervenir dans le HTML, le CSS, et le JS.

Lorsque l’on va cliquer sur une image, on aura un fond noir transparent et l’image par-dessus :

Capture d'écran de la lightbox
La lightbox affiche un voile noir transparent ainsi que l’image

Côté PHP

Côté template, on va simplement ajouter une <div> dans le pied de page. C’est elle qui servira de support plein écran pour afficher à la fois notre image, et le fond noirci.

PHP
footer.php

Côté CSS

Pour le CSS, une seule classe suffira. On va créer un élément qui est caché par défaut, qui prendra tout l’écran une fois affiché, avec un fond noir transparent.

CSS
style.css

On prépare aussi notre image qui sera affichée en image de fond. Elle sera : centrée, non répétée, et elle occupera le plus d’espace disponible grâce à la propriété CSSbackground-size: contain.

Habituellement, on utilise cette propriété pour mettre des images en fond de section, mais on applique alors cover : l’image occupe toute la zone, quitte à être rognée. Mais dans notre cas, on veut que l’image apparaisse en entier. Il y aura donc des zones inoccupées, et c’est pour cela qu’on applique un voile noir autour.

Afin de bien comprendre la différence visuelle entre les deux, j’ai réalisé un CodePen à ce sujet. N’hésitez pas à le consulter !

Côté JS

Et enfin, au niveau Javascript, une petit quinzaine de lignes fait également l’affaire :

JS
js/script.js

On récupère tout d’abord l’élément du DOM de notre Lightbox, désigné par la classe .lightbox.

Ensuite on a 2 fonctions : la première pour ouvrir la lightbox, et la seconde pour la fermer.

l’instruction e.preventDefault() permet de capter l’événement navigateur et l’annuler. Si on ne le fait pas, le lien sera suivi et on quittera la page.

On va récupérer juste après l’URL de l’image, qui se trouve dans l’attribut href de notre lien. Et la magie intervient au moment où on indique cette URL en image de fond de notre lightbox, qu’on fait apparaitre juste après.

Conseil

J’ai fait le flemmard en utilisant jQuery mais il n’aurait pas été bien plus compliqué de le faire en JS natif.

Essayez, et si tout s’est bien passé, votre Lightbox devrait apparaitre lorsque vous cliquez sur une image, de la même manière que sur ce site !

Créer un diaporama animé

Le champ galerie nous permet d’afficher une liste d’image, mais rien ne nous oblige à l’afficher sous forme de galerie. Après tout, on pourrait très bien faire un diaporama animé avec l’aide d’une bibliothèque jQuery !

Un slider animé avec la librairie jQuery Flexslider
Un slider à la place d’une galerie !

Pour cet exemple, je vous propose d’utiliser la librairie Flexslider de WooCommerce. Elle est simple à mettre en place, légere et responsive.

Une fois l’archive téléchargée, je vais faire le tri. On a seulement besoin de ces fichiers :

  • Les styles, nommé flexliser.css ;
  • Le script, nommé jquery.flexslider-min.js ;
  • Et le dossier fonts qui contient les flèches précédent / suivant.

Je les place dans un dossier lib/flexslider que je crée dans mon thème. Par convention on dira que lib contient les librairies externes, mais c’est complètement arbitraire.

On va maintenant aller charger ces ressources depuis notre functions.php :

PHP
functions.php

Notez que notre script dépend désormais de jQuery, mais également de Flexslider !

Je vous montre comment charger proprement les styles et scripts dans la formation développeur de thèmes, c’est dans le même hook que ça se passe. Il faut juste bien penser à mettre jquery en dépendance de flexslider, afin que celui-ci soit chargé toujours après. Sinon ça va planter.

Préparer le champ ACF

Et maintenant je vais aller créer un nouveau champ ACF, toujours dans mon groupe “Galerie”. Ce sera là encore un champ galerie, mais cette fois je l’appellerai slider.

Capture d'écran de l'interface de gestion de champs ACF
Le second champ, pour le slider

On va également en profiter pour renvoyer cette fois un tableau de données (array) à la place de l’ID des images.

Enregistrez, et retournez dans votre page pour ajouter quelques images à ce champ.

Ajouter le code PHP et JS

Voici maintenant le code PHP à ajouter dans notre template, à la suite de l’autre par exemple.

PHP
templates/gallery.php

La classe .flexslider est importante car c’est elle qui va dire qu’on veut en faire un slider en JS.

Vous pouvez mettre un var_dump() afin de voir quelles données ACF nous renvoie sur les images sélectionnées. Et il y en a pas mal !

Capture d'écran des données renvoyées par la galerie ACF
Le var_dump() renvoie plein de données pour chaque image

On voit notamment qu’on a un sous-tableau sizes contenant les URL vers chaque format d’image. Pour afficher l’image en 1200px, je peux donc appeler $image['sizes']['gallery-thumb'].

Et enfin, pour activer notre slider, il nous suffira d’une seule ligne de JS à ajouter à la suite de notre script :

JS
js/script.js

Normalement, si tout va bien, ça devrait fonctionner ! Si ce n’est pas le cas, ouvrez la console par un clic droit > Inspecter, puis en allant dans l’onglet Console. Vérifiez qu’il n’y a pas de souci :

  • Est-ce qu’une erreur est affichée dans la console en rouge ?
  • Est-ce qu’un fichier n’a pas réussi à être chargé : erreur 404 ?

Pour ce dernier cas, vérifiez que vous avez indiqué les bonnes URL lors des chargements de scripts.

Pour terminer en beauté, rendons notre diaporama compatible avec notre lightbox. Pour cela, il suffit d’ajouter notre sélecteur dans le JS :

JS
js/script.js

N’oubliez pas la virgule entre les 2 sélecteurs, afin de bien les distinguer (ils n’ont pas de relation de parenté). Et voilà !


Vous savez maintenant utiliser le champ galerie d’ACF et l’utiliser pour tous vos besoins ! Peu importe le cas de figure, ce sera toujours le même code PHP à utiliser.

On a vu la méthode avec les ID d’image, et celle avec les données sous forme de tableau PHP. À vous de choisir la solution qui vous convient le mieux.

Et après, libre à vous de choisir la mise en forme, et venir y ajouter des scripts par-dessus !

13

Questions, réponses et commentaires

  1. Julien

    Le 19 décembre 2021

    Bravo et Merci pour ce super tuto !
    Seul bémol avec le résultat final : dans le composant ACF Gallery, on ne peut pas trier facilement les images le top serait de pouvoir faire du drag’n’drop ou bien d’ajouter des options de tri. Aurais-tu une astuce à partager ? Merci.

    1. Maxime BJ

      Le 19 décembre 2021

      Il y a le drag’n’drop et quelques options de tri dans ce champs. En général, c’est déjà pas mal du tout je trouve !

  2. Thibault

    Le 25 septembre 2022

    Bonjour
    Merci pour ce tutoriel
    J’ai un problème pour le slider, quand je regarde la console ça me met
    script.js?ver=1.0:1 Uncaught TypeError: $ is not a function
    at script.js?ver=1.0:1:17

    1. Maxime BJ

      Le 25 septembre 2022

      Il semblerait que tu n’aies pas mis jQuery dans la liste des dépendances de ton script. Du coup il se charge avant jQuery (qui déclare la variable $) et ça créé une erreur.

      1. Thibault

        Le 25 septembre 2022

        Merci,
        Pour ajouter jQuery est-ce que le code suivant suffit ? Vu que jQuery est déjà inclus dans WP

        // Déclarer jQuery
        wp_enqueue_script(‘jquery’ );

        Il s’agit du code fourni dans le chapitre charger les scripts

        1. Maxime BJ

          Le 25 septembre 2022

          Il faut surtout rajouter la dépendance à jQuery lors de l’appel de ton script de lightbox. J’en parle dans ce cours : https://capitainewp.io/formations/developper-theme-wordpress/charger-les-scripts-et-les-styles/ et c’est le troisième paramètre de wp_enqueue_script().

          1. Thibault

            Le 26 septembre 2022

            Merci Maxime ! En effet j’ai relu point par point le chapitre.
            En fait mon script jquery ne se faisait jamais charger donc j’ai changé la version avec

            wp_deregister_script( ‘jquery’ );
            wp_enqueue_script( ‘jquery’, ‘https://ajax.googleapis.com/ajax/libs/jquery/3.3.1/jquery.min.js’, false, ‘3.3.1’, true );

            Et ça fonctionne désormais !
            Encore merci !

  3. Armelle

    Le 8 décembre 2023

    Bonjour, je suis en train de suivre votre tuto, par contre chez moi ACF gallery est en version pro, est ce bien le cas ?
    Merci par avance

    1. Maxime BJ

      Le 8 décembre 2023

      Oui tout à fait, il fait parti des champs de la version Pro, ainsi que le champ répéteu, le champ flexible et les blocs ACF pour Gutenberg.

      1. armelle

        Le 9 décembre 2023

        Merci pour votre réponse,
        Comment est ce que je peux faire créer une galerie sans ACF pro ?
        Merci par avance

        1. Maxime BJ

          Le 10 décembre 2023

          L’alternative serait d’utiliser le champ répéteur avec un champ image, mais malheureusement il fait également partie de la version Pro d’ACF, donc hélas, à part payer, je n’ai pas d’autre solution.

  4. jencode

    Le 7 février 2024

    Moi je ne peux ajouter qu’une seule photo

    1. Maxime BJ

      Le 7 février 2024

      Vérifie que tu as bien utilisé le champ Galerie et non pas image, et aussi que tu n’as pas ajouté une contrainte de limite à 1 seule image. Normalement ce champ fonctionne plutôt bien il ne devrait donc pas poser de souci.

Laisser un commentaire