This loop gives not only access to documents which are attached to an item. It gives also access to images (SPIP treats attached images as a specific type of document), thumbnails and to those documents which are already inserted in the body of the article.
In most cases you will probably use the loop DOCUMENTS with at minimum the following criteria (explanations follow):
<BOUCLEn(DOCUMENTS){mode=document}{doublons}>
Criteria
The DOCUMENTS loop is normally used inside an article or a section (maybe in a news item, but there you can only retrieve images).
- {id_document} returns the document identified by id_document. Since the identifier of each document is unique, this criterion will only return a single record or none.
- {id_article} gives a list of documents of the article identified by id_article.
- {id_rubrique} gives a list of documents of the section identified by id_rubrique.
- {id_breve} gives a list of documents of the news item identified by id_breve (It is impossible to attach other types of multimedia documents to a news item, only images. The loop DOCUMENTS in connection with a news item is therefore very specific).
Note: It is impossible to use the criteria {id_secteur}; documents can only be attached to articles and sections (and news items, but only images), so you can only call them from within such other loops or contexts.
The display criteria
- {mode=document} or {mode=image} enables to call either only multimedia documents or images (when SPIP processes a page, images inserted into the text are treated as documents of mode=image).
- {extension=...} lets you select those documents with a particular extension, for example "mov", "ra" or "avi". This can be useful for a grouping of downloads with the same file type. You can have one loop for images, one for sound, one for pdf, with a different icon and layout for each of the document types. You can also group the extensions of your choice:
<BOUCLE_portfolio(DOCUMENTS){id_article}{extension==jpg|png|gif}{mode=document}{doublons}>
This loop for example only calls those documents not called by any other loop (doublons) and with the extentions "jpg", "png" or "gif" (note the PHP-like operator "==" as comparison and "|" as the operator for "or").
- {distant} allows you to select documents according to whether they are remote or not. This means if they are stored on another site or if they have been downloaded to the local current web site space. We can specify {distant=oui} and {distant=non} respectively. (see also Managing documents)
- {doublons} has a particular meaning in this loop. This criterion not only prevents the selection of documents already selected in another loop, but also excludes any documents which have been inserted within the text of the article (see the example above). [1] If this criterion is forgotten, all the documents associated with the article will be selected by the loop, including those which are displayed within the text of the article.
- {vu=non} allows you to exclude documents embedded in the text or chapter of the article (it is possible to include other fields in the tests using the $GLOBALS[’medias_liste_champs’]).
- {largeur >= 1000} allows you to select image documents whose width is greater than or equal to 1000 pixels.
- {hauteur < 1000} allows you to select image documents with a height of less than 1000 pixels.
- {portrait} filters the documents and only retains those whose height is greater than their width.
- {paysage} filters the documents and only retains those whose width is greater than their height.
- {carre} filters the documents and retains only those whose height is equal to their width.
Ranking criteria
Since SPIP 3.2, in addition to the criteria common to all loops, the DOCUMENTS loop has a {par rang_lien} criterion which allows linked documents to be ordered by their rank.
- See also par rang_lien
Tags
- #LOGO_DOCUMENT shows the logo (preview thumbnail) of the document. If an article thumbnail is not available, SPIP uses a standard icon according to the type of document.
- #URL_DOCUMENT is the URL of the multimedia document. It can be used to display a clickable thumbnail leading to the document:
[(#LOGO_DOCUMENT|#URL_DOCUMENT)]
- #TITRE shows the title of the document.
- #DESCRIPTIF shows the description of the document.
- #CREDITS allows you to enter the credits of a document (for example the name of the photographer for a photo).
- #FICHIER displays the document’s file name, or more precisely, its relative URL. To get just the filename itself, pass this tag’s output through a filter: [(#FICHIER|basename)].
One interesting usage of this tag is combined with the image_reduire filter within a portfolio, so as to display a reduced version of the image rather that a logo; e.g. by using
[<a
href="#URL_DOCUMENT">(#FICHIER|image_reduire{500}) </a>]
- #TYPE_DOCUMENT shows the type of the document (Quicktime file, Real file...). (Note: it shows a description in words, not the extension itself, e.g. "Word" and not "doc").
- #EXTENSION SPIP 2.0 displays, as its name suggests, the extension of the file’s format, e.g.pdf, jpeg, move, ra.
- #MEDIA returns the media type: image, audio, video or file.
- #TAILLE shows the size of the document in bytes. For large documents, this value will quickly become illegible; you can apply the filter taille_en_octets, which will break the number down to kilobytes or megabytes:
[(#TAILLE|taille_en_octets)]
- #LARGEUR and #HAUTEUR show the width and height of the image in pixels.
- #MIME_TYPE displays the MIME type of the file e.g. image/jpeg —, cf. Internet media type.
- <#DATE is the upload date of the document. It can be changed after adding the document. See the article “Managing Dates” for details on how to use this tag.
- #ID_DOCUMENT shows the ID of the document.
- #DISTANT is a tag which displays "oui" (yes) or "non" (no) depending on whether the document is remote (referenced by a full URL) or not.
Example: #URL_DOCUMENT[(#DISTANT|=={oui}|oui)|parametre_url{name,value}]
- #EMBED_DOCUMENT can be used specifically to include authorised data formats (video, sound) directly into the web page rather than as simply a reference. With the most recent versions of SPIP, this tag has been deprecated, as it is simply a special case of using model (see Using models) which offer more flexible and more efficient embedding of such documents.
This tag can be supplemented with parameters specific to the formats used, e.g.
#MODELE{emb, autostart=true}