Champ de fichier ACF : Guides d’utilisation et d’affichage

Le champ Fichier est l'un des nombreux types de champs ACF. Il permet d'"ajouter" des pièces jointes de la médiathèque à n'importe quelle page.

Contrairement au champ Image , qui ne permet de sélectionner que des images (.png, .jpg, . gif et autres) le champ Fichier vous permet de choisir un fichier avec n'importe quelle extension de votre bibliothèque de médias, y compris divers types de fichiers, comme .pdf et .doc

En outre, contrairement au champ Image, il ne fournit pas d'aperçu du fichier sélectionné, de sorte que vous ne pouvez voir que le nom et la taille du fichier. En général, les développeurs utilisent ce type de champ pour créer un lien de téléchargement ou d'ouverture de fichier.

Le champ prend en charge de nombreuses extensions de fichiers. Vous pouvez trouver la liste des extensions autorisées pour tous les types de fichiers sur la page wordpress.org correspondante.

Le champ Fichier de l'ACF dispose de 3 options dans le paramètre Type de retour : File Array, File URL et File ID. Ce paramètre n'affecte pas l'apparence du champ pour les éditeurs d'administration. Il contrôle cependant le format de la valeur que vous obtenez en retour dans le code lorsque vous demandez la valeur du champ à la base de données.

C'est pourquoi je vous suggère d'utiliser l'option "File ID". C'est le meilleur choix pour les performances et il vous permet d'obtenir des données supplémentaires sur la pièce jointe sélectionnée, comme le nom du fichier ou la date de téléchargement. Évitez l'option "File URL", à moins que vous n'en ayez besoin pour un objectif spécifique. En effet, elle ne vous permet pas d'obtenir des informations supplémentaires sur la pièce jointe.

Comme nous l'avons mentionné, le champ Fichier fonctionne avec la bibliothèque multimédia et vous permet d'ajouter toutes sortes de pièces jointes aux pages. Mais il faut savoir que lorsque vous "ajoutez" un fichier, cela signifie en fait "joindre", et non pas copier. Le champ n'est qu'un intermédiaire entre une page et la médiathèque. Il associe l'identifiant du fichier que vous avez choisi à la méta-poste de la page en cours. Cela signifie qu'il n'est pas nécessaire de créer des doublons ou des copies physiques du fichier.

Même dans le cas où vous téléchargez une nouvelle pièce jointe via la boîte de dialogue de téléchargement de champ, le fichier sera téléchargé dans la médiathèque comme une pièce jointe ordinaire, le champ de fichier ne stockant que l'ID de la pièce jointe. De cette manière, vous pouvez "attacher" un fichier à plusieurs pages sans créer de copies.

Vous devrez toujours donner des noms clairs à vos pièces jointes et vous devriez vraiment essayer d'éviter de télécharger le même fichier plusieurs fois. En effet, la médiathèque ne sait pas si la pièce jointe téléchargée est entièrement nouvelle ou si elle existe déjà. Si vous n'êtes pas sûr, faites une recherche rapide dans la médiathèque avant de télécharger. Sinon, vous risquez d'avoir de nombreux maux de tête avec plusieurs copies de la même chose.

En outre, le paramètre Format de retour n'affecte pas non plus la valeur stockée. Il s'agit toujours d'un ID de pièce jointe. Si vous n'avez pas sélectionné le format de retour "File ID", à chaque fois que vous demandez le champ, le plugin ACF effectuera un travail supplémentaire pour convertir l'ID de pièce jointe sauvegardé dans un autre format.

Les shortcodes sont l'une des fonctionnalités les plus puissantes et les plus faciles à utiliser de WordPress. Les shortcodes vous permettent d'"appeler" des fonctions PHP directement dans votre éditeur, comme Gutenberg. Cela vous permet d'afficher des éléments de contenu dynamiques.

Pour créer un shortcode, vous devez écrire du code PHP. Mais nous n'allons pas le faire aujourd'hui, nous allons utiliser un plugin gratuit appelé ACF Views. Il fera tout le travail pour nous, et vous permettra d'afficher n'importe quel champ ACF, en utilisant des shortcodes générés automatiquement. Lisez comment afficher les champs ACF sans codage pour connaître tous les avantages de l'approche par shortcodes.

Nous avons joint ci-dessous un tutoriel vidéo qui montre comment afficher les champs ACF sur une seule page en utilisant l'approche shortcode. La vidéo est commune à tous les types de champs ACF. Plus de tutoriels vidéo sur la chaîne YouTube officielle .

Mais n'hésitez pas à sauter la vidéo car nous fournissons ci-dessous un guide complet, étape par étape, exactement pour le champ Fichier ACF.

Si vous voulez suivre le guide, vous devez :

1. installer le plugin ACF Views sur votre site WordPress. N'oubliez pas de l'activer. Il s'agit d'un module complémentaire à ACF, vous devrez donc également
2. Installer le plugin gratuit Advanced Custom Fields (ACF) et l'activer.

Après avoir activé le plugin ACF Views, vous verrez un nouvel élément dans votre menu d'administration, appelé "ACF Views".

Cet élément a un sous-menu, avec plusieurs éléments, mais nous n'aurons besoin d'utiliser que celui appelé 'ACF Views'.

Cliquez sur le bouton "Ajouter nouveau" pour créer une vue .

Note : Le terme "View" est le nom donné au type de message spécial fourni par le plugin. Chaque Vue est une liste de champs ACF à afficher, de sorte que vous pouvez avoir plusieurs Vues différentes pour afficher différents champs (ou ensembles de champs) pour différents posts/pages.

Donnez ensuite un nom à votre Vue, vous pouvez utiliser n'importe quoi qui décrit la Vue. Ce nom ne sera affiché que dans la liste des vues , ce qui facilitera sa recherche. J'ai appelé ma vue "Catalogue de pages".

Vous devez maintenant attribuer un nouveau champ à votre vue . Cliquez sur le bouton "Ajouter un champ" et sélectionnez votre "Groupe" dans la liste déroulante. Dans mon cas, le groupe porte le nom de "Page fields". Continuez ensuite à sélectionner le champ cible dans la liste, j'ai sélectionné "Catalogue (fichier)".

Remarque : le type de champ est indiqué entre parenthèses après le nom du fichier. Vous pouvez donc facilement identifier le type d'un champ dans la liste déroulante.

Vous devriez également voir que le type est "fichier". Définissez une "étiquette de lien" pour notre futur lien. Ou laissez-le vide, si vous voulez que le plugin le récupère à partir de la pièce jointe sélectionnée.

En général, chaque View peut avoir un nombre illimité de champs ACF, mais dans notre cas, nous n'en utiliserons qu'un seul.

Cliquez sur le bouton "Publier" pour enregistrer et publier votre Vue. Dès qu'elle est publiée, vous remarquerez que des codes courts ont été générés dans un bloc situé à droite de l'écran d'édition de votre vue. Chaque Vue a son propre shortcode avec un ID unique (la structure du shortcode est la même pour toutes les Vues, mais les arguments sont uniques).

[acf_views view-id="xxxx" name="x"]

Nous devons maintenant copier le shortcode. Pour ce faire, cliquez sur le bouton 'Copier dans le presse-papiers' sur le premier shortcode.

Maintenant que nous avons tout préparé, nous sommes prêts à afficher le champ Fichier.

Visitez votre page cible, c'est là que vous aurez le champ Fichier. N'oubliez pas de vérifier qu'il y a une pièce jointe dans votre champ Fichier, et collez le shortcode à l'endroit de votre choix dans le contenu de la page.

Pour coller le shortcode avec l'éditeur Gutenberg, il suffit de cliquer sur le bouton plus dans la barre supérieure et de choisir le bloc "Shortcode" dans la liste. Collez ensuite votre shortcode dans le bloc et cliquez sur le bouton "Mettre à jour" pour enregistrer votre article/page.

Visitez la page pour voir le résultat. Si vous avez tout fait correctement, vous devriez voir le fichier sélectionné s'afficher dans le contenu sous la forme d'un lien, avec l'étiquette que vous avez définie. Ou avec le nom du fichier joint si vous l'avez laissé vide.

Si vous ne voyez pas votre lien, revenez en arrière et éditez la page. Assurez-vous d'avoir joint un fichier au champ du fichier ACF, car si le champ est vide, il n'y aura rien à afficher.

Dans la plupart des cas, nous devrions transformer le champ Fichier en un lien à montrer aux utilisateurs. Ainsi, lorsqu'ils essaient de télécharger la pièce jointe ou de l'ouvrir dans un nouvel onglet du navigateur, c'est facile pour eux. Pour ce faire, vous devez obtenir l'URL du fichier (et probablement aussi son nom), puis créer le code HTML du lien.

Le code sera différent en fonction du type de retour sélectionné. Des exemples sont donnés ci-dessous.

1. Code PHP pour afficher le champ Fichier avec le format de retour "ID" :

<?php

// don't forget to replace 'file' with your field name
$fileID = get_field('file');
if ($fileID) {
   // $fileID is an ID (integer) of a Post with the Attachment type. 
   // we need to use the built-in WP functions to get necessary data
    $url = wp_get_attachment_url($fileID);
    $name = get_post($fileID)->post_title ?? '';
    // displays the file. Each %s in the string will be replaced with the related argument
    printf("<a href='%s' download='%s'>%s</a>", esc_attr($url), esc_attr($name), esc_html($name));
}

2. Code PHP pour afficher le champ Fichier avec le format de retour "Array" :

<?php

// don't forget to replace 'file' with your field name
$fileData = get_field('file');
if ($fileData) {
    // displays the file. Each %s in the string will be replaced with the related argument
    printf("<a href='%s' download='%s'>%s</a>", 
     esc_attr($fileData['url']), esc_attr($fileData['filename']), esc_html($fileData['filename']));
}

3) Code PHP pour afficher le champ Fichier avec l' "URL" Format de retour :

<?php

// don't forget to replace 'file' with your field name
$fileUrl = get_field('file');
if ($fileUrl) {
    // displays the file. Each %s in the string will be replaced with the related argument
    printf("<a href='%s' download='prices.pdf'>Prices.pdf</a>", esc_attr($fileUrl));
}

Nous avons utilisé l'attribut download (read more) pour indiquer au navigateur du client qu'au lieu d'être ouvert, ce fichier doit être téléchargé. La valeur de l'attribut sera utilisée comme nom du fichier à télécharger. Supprimez l'attribut si vous souhaitez que ce fichier soit ouvert au lieu d'être téléchargé.

Avec le format de retour "URL", nous devons coder en dur le nom du fichier. Il n'y a aucun moyen d'utiliser ce code pour différents fichiers ou de le modifier sans éditer le code. C'est pourquoi il est préférable de toujours choisir le format de retour "ID".

Pour en savoir plus, regardez la vidéo ci-dessous et lisez l'article officiel d'ACF.

Vous avez examiné de plus près le champ Fichier ACF et la manière de l'utiliser et de l'afficher. Nous avons montré les aspects importants à retenir lors de l'utilisation de ce type de champ.

Il est utile de savoir que vous pouvez avoir plusieurs champs (même de groupes différents) dans une seule Vue, et vous pouvez styliser la sortie des champs en utilisant le champ de code CSS (voir l'onglet Avancé de la Vue). Le plugin ajoutera ce CSS uniquement sur les pages où vous utilisez le shortcode. Vous n'avez donc pas besoin de chercher un endroit où le placer.

Visitez le site officiel d'ACF Views pour obtenir plus d'informations sur le plugin, vous pouvez également trouver des liens vers la chaîne YouTube du plugin qui contient des tutoriels vidéo et la documentation du plugin. Ces ressources vous aideront à vous familiariser plus rapidement avec le plugin.