[SPIP 1.4] La boucle DOCUMENTS retourne une liste de documents multimédia associés (à un article, à une rubrique, éventuellement les images incluses dans une brève).
Cette boucle gère non seulement les documents joints non installés dans le texte d’un article, mais peut aussi accéder aux images (depuis la version 1.4, les images sont gérées, au niveau du programme, comme un genre spécifique de documents), aux vignettes de prévisualisation et aux documents déjà insérés dans le corps de l’article.
Pour mémoire, on utilisera donc le plus fréquemment (utilisation courante) la boucle DOCUMENTS avec, au minimum, les critères suivants (explications ci-après) :
Les critères de sélection
Une boucle DOCUMENTS s’utilise en général à l’intérieur d’un article ou d’une rubrique (éventuellement dans une brève, mais ici l’utilisation sera réservée à la récupération d’images, ce qui sera très spécifique).
{id_article} retourne les documents de l’article dont l’identifiant est id_article.
{id_rubrique} retourne les documents de la rubrique id_rubrique.
{id_breve} retourne les documents de la brève id_breve (il n’est pas possible d’associer des documents multimédia à une brève, seulement des images ; l’utilisation d’une boucle DOCUMENTS dans ce cadre sera donc très spécifique).
Notez bien : il n’est pas possible d’utiliser ici le critère {id_secteur} ; les documents sont conçus pour être intimement liés aux articles et aux rubriques, et non à être appelés seuls sans ces éléments (on parle dans SPIP de « documents joints »).
Les critères d’affichage
{mode=document} ou {mode=image} permet d’indiquer si l’on veut appeler les documents multimédia, ou les images (en effet, désormais les images associées à l’article et éventuellement insérées dans l’article sont traités comme des documents en mode=image).
N.B. Dans les sites SPIP existant avant la version 1.4, l’habitude a été prise de ne pas pouvoir afficher les images qui ne sont pas insérées à l’intérieur du texte de l’article. De fait, si vous ajoutez un boucle DOCUMENTS en mode=image sur un site déjà existant, vous risquez de voir réapparaître dans cette boucle des images qui n’étaient pas destinées à être publiées sur le site public. Donc, n’utilisez une telle boucle que sur un site créé avec la version 1.4, ou bien procédez avec beaucoup de précautions (vérifiez les anciens articles pour éviter la publication d’images parasites).
{doublons} prend ici une importance particulière : elle permet non seulement de ne pas réafficher des documents déjà affichés par une autre boucle, mais également de ne pas réafficher les documents déjà intégrés à l’intérieur d’un article. Si l’on oublie ce critère, on affichera tous les documents associés à un article, y compris ceux qui auraient déjà été affichés à l’intérieur du texte.
{extension=...} permet de sélectionner les documents selon leur terminaison (terminaison du fichier multimédia, par exemple « mov », « ra », « avi »...). Cela peut être utilisé par exemple pour réaliser un porfolio, c’est-à-dire une boucle n’affichant que les documents de type image, une seconde boucle ensuite, avec une présentation graphique différente, les autres types de documents :
Cette BOUCLE_portfolio récupère les documents joints à un article, non déjà affichés dans le texte de l’article, et donc les extensions des fichiers peuvent être « jpg », « png » ou « gif ».
Les balises
#LOGO_DOCUMENT affiche le logo (vignette de prévisualisation) associé à cet article ; si une vignette personnalisée n’a pas été installée manuellement par l’auteur de l’article, SPIP utilise une vignette standard selon le type du fichier.
#URL_DOCUMENT est l’URL du fichier multimédia. Pour afficher une vignette cliquable pointant vers le document multimédia, on utilisera donc le code suivant :
#TITRE affiche le titre du document.
#DESCRIPTIF affiche le descriptif du document.
#TYPE_DOCUMENT affiche le type (fichier Quicktime, fichier Real...) du document multimédia.
#TAILLE affiche la taille du fichier multimédia. Ce chiffre est fourni en octets. Pour de gros fichiers, cette valeur devient rapidement inutilisable ; on pourra donc lui appliquer le filtre taille_en_octets, qui affichera successivement en octets, en kilooctets, ou même en mégaoctets :
#LARGEUR et #HAUTEUR fournissent les dimensions en pixels.
#ID_DOCUMENT affiche le numéro du document.
#EMBED_DOCUMENT est une balise à l’utilisation très spécifique : elle permet d’inclure directement les fichiers de formats autorisés (vidéo, sons) directement dans la page Web ; il faut éviter d’utiliser systématiquement cette balise, car il est déconseillé d’insérer systématiquement les documents dans les pages sans un contrôle strict (sauf à faire exploser la durée de chargement de vos pages Web...). La balise peut être complétée de paramètres propres aux formats utilisés (encore une fois : utilisation très spécifique), par exemple :
