SPIP

[ar] [ast] [bg] [br] [ca] [co] [cpf] [cs] [da] [de] [en] [eo] [es] [eu] [fa] [fon] [fr] [gl] [id] [it] [ja] [lb] [nl] [oc] [pl] [pt] [ro] [ru] [sk] [sv] [tr] [uk] [vi] [zh] Espace de traduction

Download

The DOCUMENTS loop

March 2004 — updated on : October 2010

All the versions of this article:

Introduced with SPIP 1.4 , the DOCUMENTS loop returns a list of multimedia documents associated to a specific article, a section or possibly images included in a news item.

<BOUCLEn(DOCUMENTS){criteria...}>


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 probably use the loop DOCUMENTS with at minimum the following criteria (explanations follow):

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

Note: In SPIP sites preceding 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 version 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 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:

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} is available since SPIP 1.8.2 for selecting documents depending on 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 SPIP 1.8.2)

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

-  #FICHIER SPIP 1.8.2 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

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

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

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

is valid, but we would prefer that you opt for what this would automatically translate into in the current version:

Footnotes

[1However, if the criterion is used with a name, e.g. {doublons myname}, then the documents inserted within the text of the article will not be excluded.


Show the template of this page Site powered by SPIP | Translation area | Private area