Questo ciclo gestisce non solo i documenti allegati non inseriti nel testo di un articolo, ma può accedere anche alle immagini (dalla versione 1.4 le immagini sono gestite, a livello di programma, come un genere specifico di documento), alle icone di anteprima e ai documenti già inseriti nel corpo dell’articolo.
Va ricordato che si utilizzerà molto spesso (uso frequente) il ciclo DOCUMENTS con, al minimo, i criteri seguenti (spiegazione a seguire):
<BOUCLEn(DOCUMENTS){mode=document}{doublons}>
I criteri di selezione
Il ciclo DOCUMENTS si utilizza in genere all’interno di un articolo o di una rubrica (eventualmente anche di una breve, ma in questa sede l’uso è riservato al recupero di immagini, quindi è molto specifico).
- {id_document} seleziona il documento il cui identificativo è id_document. Poiché l’identificativo di ogni documento è univoco, questo criterio ottiene o una o zero risposte.
- {id_article} restituisce i documenti dell’articolo il cui identificativo è id_article.
- {id_rubrique} restituisce i documenti della rubrica id_rubrique.
- {id_breve} restituisce i documenti della breve id_breve (non è possibile associare documenti multimediali a una breve, solo immagini; l’uso di un ciclo DOCUMENTS in questo caso sarà quindi molto specifico).
N.B.: non è possibile utilizzare il criterio {id_secteur} in questo contesto; i documenti sono concepiti per essere intimamente legati agli articoli e alle rubriche e non possono essere richiamati da soli, senza questi elementi (in SPIP si definiscono "documenti allegati").
I criteri di visualizzazione
- {mode=document} o {mode=image} permette di indicare se si vuole chiamare i documenti multimediali oppure le immagini (in effetti, ormai le immagini associate all’articolo e eventualmente inserite nell’articolo sono trattate come documenti in mode=image).
N.B. Nei siti creati con una versione di SPIP precedente alla 1.4, l’uso consolidato è di non poter visualizzare le immagini che non sono inserite all’interno del testo dell’articolo. In realtà, se si aggiunge un ciclo DOCUMENTS in mode=image su un sito già esistente si rischia di veder apparire in questo ciclo delle immagini che non erano destinate alla pubblicazione sul sito pubblico. Pertanto, utilizzare un tale ciclo esclusivamente su un sito creato con la versione 1.4, oppure procedere con molte precauzioni (verificate i vecchi articoli per evitare la pubblicazione di immagini parassite).
- {extension=...} permette di selezionare i documenti secondo l’estensione (estensione del file, per esempio "mov", "ra", "avi"...). Ciò può essere utilizzato, ad esempio, per realizzare una galleria d’immagini (o porfolio), ovvero un ciclo che mostri solo i documenti di tipo immagine; un secondo ciclo, poi, mostrerà gli altri tipi di documento con una presentazione grafica differente:
<BOUCLE_portfolio(DOCUMENTS){id_article}{extension==jpg|png|gif}{mode=document}{doublons}>
Questo ciclo BOUCLE_portfolio restituisce i documenti allegati a un articolo, non quelli già mostrati nel testo di un articolo, e le estensioni dei file possono essere "jpg", "png" o "gif".
- {distant} permette, da SPIP 1.8.2, di selezionare i documenti in base al fatto che essi siano distanti o meno. In altre parole, se essi sono registrati su un altro sito oppure ospitati sullo stesso spazio web del proprio sito. A tal fine si deve precisare, rispettivamente, {distant=oui} oppure {distant=non}. (vedi SPIP 1.8.2)
- {doublons} in questa sede ha un’importanza particolare: non solo permette di non mostrare nuovamente documenti già mostrati da un altro ciclo, ma di non mostrare nuovamente anche i documenti già integrati all’interno di un articolo. Se questo criterio viene dimenticato verranno mostrati tutti i documenti associati a un articolo, compresi quelli che sono già mostrati all’interno del testo. [1].
I segnaposti
- #LOGO_DOCUMENT mostra il logo (icona di anteprima) associato all’articolo attuale; se l’autore dell’articolo non ha inserito manualmente alcuna icona personalizzata, SPIP utilizza un’icona standard secondo il tipo di file.
- #URL_DOCUMENT è l’URL del file multimediale. Per visualizzare un’icona cliccabile che punti al documento multimediale si scriverà il seguente codice:
[(#LOGO_DOCUMENT|#URL_DOCUMENT)]
- #TITRE mostra il titolo del documento.
- #DESCRIPTIF mostra la descrizione del documento.
- #FICHIER [SPIP 1.8.2] visualizza il nome del file del documento. Un’utilizzo interessante di questo segnaposto è la sua combinazione insieme al filtro image_reduire, nel quadro di un portfolio per visualizzare una riduzione dell’immagine invece che il suo logo; per esempio, utilizzando:
[<a
href="#URL_DOCUMENT">(#FICHIER|image_reduire{500}) </a>]
- #TYPE_DOCUMENT mostra il tipo (file Quicktime, file Real...) del documento multimediale.
- #TAILLE mostra la dimensione del file multimediale. Questo valore è espresso in byte. Per i file molto grandi questo valore è praticamente inutilizzabile; in tal caso è possibile applicare il filtro taille_en_octets che visualizzerà la dimensione in byte, in kilobyte o in megabyte, in successione:
[(#TAILLE|taille_en_octets)]
- #LARGEUR e #HAUTEUR danno le dimensioni in pixel.
- #MIME_TYPE visualizza il tipo MIME del file — per esempio: image/jpeg —, cfr. Type de média internet.
- #DATE è la data di pubblicazione online del documento. (Modificabile dopo l’aggiunta). Vedere «La gestione delle date» per dettagli sull’utilizzo del campo #DATE.
- #ID_DOCUMENT mostra il numero del documento.
- #EMBED_DOCUMENT l’uso di questo segnaposto è molto specifico: permette di includere i file di formati autorizzati (video, audio) direttamente nella pagina Web; si raccomanda di non utilizzare sistematicamente questo segnaposto, poiché è sconsigliato inserire i documenti nelle pagine senza effettuare un controllo severo (a meno che non si voglia allungare a dismisura i tempi di caricamento delle pagine...). Il segnaposto può essere completato con parametri specifici al formato utilizzato (anch’essi di uso molto specifico), per esempio:
[(#EMBED_DOCUMENT|autostart=true)]
- #DISTANT è un segnaposto che visualizza «oui» oppure «non» a seconda se il documento è distante (un URL diverso dal proprio sito) oppure no.