Aquest bucle gestiona no solament els documents adjunts no instal·lats al text d’un article, sinó que també pot accedir a les imatges (a partir de la versió 1.4, les imatges són gestionades, a nivell de programa, com un gènere específic de documents), a les vinyetes de visualització prèvia i als documents ja inserits en el cos de l’article.
Recordem, a títol d’informació, que en el bucle DOCUMENTS el què farem servir amb més freqüència (ús corrent) seran, com a mínim, els criteris següents (explicacions a continuació):
<BOUCLEn(DOCUMENTS){mode=document}{doublons}>
Els criteris de selecció
Un bucle DOCUMENTS s’utilitza generalment a l’interior d’un article o d’una secció (eventualment en una breu, però aquí el seu ús quedarà reservat a la recuperació d’imatges, el que serà molt específic).
- {id_document} selecciona el document que té com identificador id_document. Com que l’identificador de cada document és únic, aquest criteri només retorna una o cap resposta.
- {id_article} retorna els documents de l’article que tenen com a identificador id_article.
- {id_rubrique} retorna els documents de la secció id_rubrique.
- {id_breve} retorna els documents de la breu id_breve (no és possible associar documents multimèdia a una breu, només imatges; l’ús d’un bucle DOCUMENTS en aquest marc serà doncs molt específic).
Preneu bona nota: no és possible fer servir aquí el criteri {id_secteur} ; els documents són concebuts per estar lligats íntimament als articles i a les seccions, i no cridats sols sense aquests elements (a l’SPIP es parla de «documents adjunts»).
Els criteris de publicació
- {mode=document} o {mode=image} permet indicar si es vol cridar els documents multimèdia o les imatges (efectivament, d’ara endavant les imatges associades a l’article i eventualment inserides a l’article són tractades com documents en mode=image).
N.B. Ens els llocs SPIP existents abans de la versió 1.4, era habitual no poder publicar imatges que no estiguessin inserides a l’interior del text de l’article. De fet, si ajunteu un bucle DOCUMENTS en mode=image en un lloc que ja existia, correu el risc de veure aparèixer en aquest bucle imatges que el seu destí no era estar publicades al lloc públic. Per tant, utilitzeu aquest bucle només en aquells llocs creats a partir de la versió 1.4, o bé procediu amb molta precaució (verifiqueu els antics articles per evitar la publicació d’imatges paràsit).
- {extension=...} permet de seleccionar els documents segons la seva extensió (extensió de fitxer multimèdia, per exemple «mov», «ra», «avi»...). Es pot fer servir, per exemple, per realitzar un dossier o catàleg, és a dir un primer bucle que mostri només els documents del tipus imatge, a continuació, en un segon bucle amb una presentació gràfica diferent, els altres tipus de documents:
<BOUCLE_portfolio(DOCUMENTS){id_article}{extension==jpg|png|gif}{mode=document}{doublons}>
Aquest BOUCLE_portfolio recupera els documents adjunts a un article, que no estiguin en el text de l’article, i que poden tenir les extensions «jpg», «png» o «gif».
- {distant} permet, a partir d’SPIP 1.8.2, seleccionar els documents segons si són distants o no. És a dir, emmagatzemats en un altre lloc Web o baixats des de l’espai web del lloc. Precisarem {distant=oui} i {distant=non} respectivament. (Veure SPIP 1.8.2)
- {doublons} pren aquí una particular importància: permet no solament no publicar aquells documents que ja han estat publicats per un altre bucle, sinó també no tornar a mostrar els documents que ja estan a l’interior d’un article. Si s’oblida aquest criteri, el bucle publicarà tots els documents associats a un article, inclosos els que ja han estat publicats a l’interior del text [1].
Les etiquetes
- #LOGO_DOCUMENT publica el logotip (miniatura de previsualització) associat a aquest article; si no s’ha instal•lat, manualment per l’autor, una vinyeta personalitzada, l’SPIP utilitza, segons el tipus de fitxer del que es tracti, una vinyeta estàndard.
- #URL_DOCUMENT és l’URL del fitxer multimèdia. Per publicar una vinyeta clicable que apunti cap al document multimèdia, farem servir el codi següent:
[(#LOGO_DOCUMENT|#URL_DOCUMENT)]
- #TITRE mostra el títol del document.
- #DESCRIPTIF mostra la descripció del document.
- #FICHIER SPIP 1.8.2 mostra el nom del fitxer del document, més concretament el seu URL relatiu. Per obtenir el nom del fitxer sol, hem de passar aquest filtre: [(#FICHIER|basename)].
Una utilització interessant d’aquesta etiqueta es combina amb el filtre image_reduire, en el marc d’un portafolis per mostrar una reducció de l’imatge més que del seu logotip; per exemple utilitzant
[<a
href="#URL_DOCUMENT">(#FICHIER|image_reduire{500}) </a>]
- #TYPE_DOCUMENT mostra el tipus (fitxer Quicktime, fitxer Real...) del document multimèdia .
- #EXTENSION SPIP 2.0 com el seu nom indica, mostra l’extensió del format del fitxer, per exemple: pdf, jpeg, move, ra.
- #TAILLE mostra la talla del fitxer multimèdia. Aquesta xifra l’SPIP ens la dóna en bytes. Pels fitxers molt grans, aquest valor esdevé ràpidament inutilitzable; podem aplicar llavors el filtre taille_en_octets, que ens mostrarà el fitxer successivament en bytes, en kB o en MB:
[(#TAILLE|taille_en_octets)]
- #LARGEUR i #HAUTEUR proporcionen les dimensions en píxels.
- #MIME_TYPE mostra el tipus MIME del fitxer — per exemple: image/jpeg —, cf. Type de média internet.
- #DATE ens indica la data que s’ha posat en línia un document. (Es pot modificar després de ser afegit). Veure «La gestió de les dates» per tal de conèixer més detalls sobre l’ús del camp #DATE.
- #ID_DOCUMENT mostra el número del document.
- #DISTANT és una etiqueta que mostra «si» o «no» segons si el document és distant (referenciat per un URL) o no.
- #EMBED_DOCUMENT és una etiqueta que permet incrustar el document a l’interior de la pàgina produïda més que no pas referenciar-la. Aquesta etiqueta, actualment, està desvalorada, essent un cas particular dels models (veure Utilitzar els models) que permeten modular aquesta incrustació de manera més àgil i eficaç.
Aquesta etiqueta pot ser complementada amb paràmetres propis als formats utilitzats, per exemple:
[(#EMBED_DOCUMENT|autostart=true)]
però preferirem aquell en què es tradueix automàticament al present:
#MODELE{emb, autostart=true}
