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 (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) :
<BOUCLEn(DOCUMENTS){mode=document}{doublons}>
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_document} sélectionne le document dont l’identifiant est id_document. Comme l’identifiant de chaque document est unique, ce critère ne retourne qu’une ou zéro réponse.
- {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 »).
- {mode=logoon} permet de récupérer un document qui sert de logo. En effet, depuis Spip 4.0, les logos sont traités comme des documents, permettant ainsi de leur donner un titre, un descriptif, etc.
- {mode=logooff} permet de récupérer un document qui sert de logo de survol.
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, les images associées à l’article et éventuellement insérées dans le texte sont traités comme des documents en mode=image).
- {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 :
<BOUCLE_portfolio(DOCUMENTS){id_article}{extension==jpg|png|gif}{mode=document}{doublons}>
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 ».
- {media=...} permet de sélectionner les documents selon leur type :
« image », « audio » ou « video » ou « file ».
Ainsi, dans la boucle précédente, le critère {extension==jpg|png|gif} peut également s’écrire ainsi : {media=image}.
- {distant} permet de sélectionner les documents selon qu’ils soient distant ou non. C’est à dire stockés sur un autre site ou téléchargés dans l’espace web du site. On précisera {distant=oui} et {distant=non} respectivement. (voir Gestion des documents)
- {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 [1].
- {vu=non} permet d’exclure les documents intégrés dans le texte ou le chapo de l’article (il est possible d’inclure d’autres champs dans les tests au moyen de la globale medias_liste_champs).
- {largeur >= 1000} permet de sélectionner les documents de type image dont la largeur est supérieure ou égale à 1000 pixels.
- {hauteur < 1000} permet de sélectionner les documents de type image dont la hauteur est inférieure à 1000 pixels.
- {portrait} filtre les documents et ne retient que ceux dont la hauteur est plus grande que la largeur.
- {paysage} filtre les documents et ne retient que ceux dont la largeur est plus grande que la hauteur.
- {carre} filtre les documents et ne retient que ceux dont la hauteur est égale à la largeur.
Les critères de classement
Depuis SPIP 3.2, en plus des critères communs à toutes les boucles, la boucle DOCUMENTS possède un critère {par rang_lien} qui permet d’ordonner les documents liés selon leur rang.
- Voir par rang_lien
Les balises
- #LOGO_DOCUMENT affiche le logo (vignette de prévisualisation) associé au document ; 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 :
[(#LOGO_DOCUMENT{#URL_DOCUMENT})]
- #TITRE affiche le titre du document.
- #DESCRIPTIF affiche le descriptif du document.
- #CREDITS permet de renseigner les crédits d’un document (par exemple le nom du photographe pour une photo).
- #ALT permet de renseigner le texte alternatif d’une image.
- #FICHIER affiche le nom de fichier du document, plus précisément son URL relative. Pour obtenir le nom de fichier seul, on passera ce filtre : [(#FICHIER|basename)].
Une utilisation intéressante de cette balise est combinée avec le filtre image_reduire, dans le cadre d’un portfolio pour afficher une réduction de l’image plutôt que de son logo ; par exemple en utilisant
[<a href="#URL_DOCUMENT">(#FICHIER|image_reduire{500})</a>]
- #TYPE_DOCUMENT affiche le type (fichier mp4, fichier mp3...) du document multimédia.
- #EXTENSION affiche l’extension du format du fichier, par exemple : pdf, jpeg, mp4.
- #MEDIA renvoie le type de média : image, audio, video ou file.
- #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 :
[(#TAILLE|taille_en_octets)]
- #LARGEUR et #HAUTEUR fournissent les dimensions en pixels.
- #MIME_TYPE affiche le type MIME du fichier — par exemple : image/jpeg —, cf. Type de média internet.
- #DATE est la date de mise en ligne du document. (Modifiable après l’ajout). Voir « La gestion des dates » pour des détails sur l’utilisation du champ #DATE.
- #ID_DOCUMENT affiche le numéro du document.
- #DISTANT est une balise qui affiche « oui » ou « non » selon que le document est distant (référencé par une url) ou pas.
- #EMBED_DOCUMENT est une balise
permettant d’incruster le document dans la page produite plutôt que de le référencer. Cette balise est aujourd’hui dépréciée, étant un cas particulier des
modèles (voir Utiliser les modèles) qui permettent de moduler cette incrustation de manière plus souple et plus efficace.
Cette balise peut être complétée de paramètres propres aux formats utilisés, par exemple :
#MODELE{emb, autostart=true}
- #MODE peut valoir ’image’, ’document’, ’logoon’, ’logooff’, ’vignette’ selon la nature d’un document.
Voir aussi
- Les balises #LOGO_XXX