The DOCUMENTS loop

[SPIP 1.4]The DOCUMENTS Loop returns a list of multimedia documents associated to a specific article, a section or images included in a news item.

This loop gives not only access to documents which are attached to an item. It gives also access to images (since version 1.4, SPIP treats attached images as separate documents), thumbnails and to those documents which are already inserted in the body of the article.

In most cases you will probabaly use the loop DOCUMENTS with at minimum the following criteria (explanation follows):

Criteria

The DOCUMENTS loop is normally used inside an article or a section (maybe in a news item, but there you can only retreive 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 response 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 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.

-  {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).

Note: In SPIP sites preceeding version 1.4, it was impossible to display attached documents unless inserted inside the text of the article. If you apply a DOCUMENTS loop in mode=image to a site created prior to verion 1.4, you will see those images again that were attached, but not inserted into the main text (and therefore not visible before version 1.4). If your website has been created with a version prior to 1.4, be very cautious with this loop. You might want to browse through the old pages to avoid publication of "parasite" images.

-  {extension=...} lets you select those documents with a particular extention, 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 extentions of your choice:

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»).

-  {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.

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:

-  #TITRE shows the title of the document.

-  #DESCRIPTIF shows the description of the document.

-  #TYPE_DOCUMENT shows the type of the document (file Quicktime, file Real...). (Note: it shows a description in words, not the extention, i.e. «Word» and not «doc»).

-  #TAILLE shows the size of the document in octets. For large documents, this value will quickly render unreadable; you can apply the filter taille_en_octets, which will break the number down to kilo-octets and mega-octets:

-  #LARGEUR et #HAUTEUR shows width and height of the image in pixels.

-  #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.

-  #EMBED_DOCUMENT can be used specifically to include authorized data formats (video, sound) directly into the web page. You should not use this tag systematically without strict control (unless you want to blow the band width of your web site and have a word from your provider). The tag can be completed with the parameters specific to the format used, (once again: handle with care!) for example: