[SPIP 1.4] El bucle DOCUMENTS (documentos) devuelve una lista de documentos multimedia asociados (a un artículo, a una sección, o eventualmente las imágenes asociadas a una breve).
<BOUCLEn(DOCUMENTS){criterios...}>
Este bucle no sólo maneja los documentos asociados que no se muestren en el texto de un artículo, sino que también permite acceder a las imágenes [1], a las miniaturas de previsualización y a los documentos ya insertados en el cuerpo del artículo.
Recordemos entonces que la utilización más frecuente del bucle DOCUMENTS llevará (por lo menos) los criterios siguientes (ver a continuación las explicaciones):
<BOUCLEn(DOCUMENTS){mode=document}{doublons}>
Los criterios de selección
Un bucle DOCUMENTS se utiliza en general dentro de un artículo o una sección [2].
- {id_article} devuelve los documentos del artículo cuyo identificador es id_article.
- {id_rubrique} devuelve los documentos de la sección cuyo identificador es id_rubrique.
- {id_breve} devuelve los documentos de la breve cuyo identificador es id_breve.
Cuidado: aquí no es posible utilizar el criterio {id_secteur}; los documentos están pensados para que vayan íntimamente ligados a los artículos y a las secciones; no para llamarlos solos, sin dichos elementos (en SPIP se habla de «documentos adjuntos»).
Los criterios de presentación
- {mode=document} o {mode=image} permite indicar si se desea llamar a los documentos multimedia, o las imágenes (en efecto, las imágenes asociadas con un artículo y, en su caso, insertadas en él, son ahora tratadas como documentos en «modo» mode=image).
Nota: En sitios SPIP existentes antes de la versión 1.4, existe la costumbre de que no se puedan ver las imágenes que no están insertadas dentro del texto del artículo. En realidad, si uno agrega un bucle DOCUMENTS en mode=image en un sitio existente, se arriesga a ver reaparecer en este bucle imágenes que no estaban destinadas a ser mostradas en el sitio público. Por lo tanto, no uses este bucle más que en sitios creados con la versión 1.4 o posterior, o bien procede con mucha precaución (verifica uno por uno los artículos antiguos para evitar la publicación de imágenes parásitas).
- {extension=...} permite seleccionar los documentos por su extensión (extensión de fichero multimedia, por ejemplo «.mov», «.ra», «.avi», ...). Esto puede ser utilizado, por ejemplo, para realizar un portafolio de imágenes, es decir un bucle que sólo muestra los documentos de tipo imagen, y luego un segundo bucle con una presentación gráfica diferente, los otros tipos de documentos:
<BOUCLE_portfolio(DOCUMENTS){id_article}{extension==jpg|png|gif}{mode=document}{doublons}>
Este BOUCLE_portfolio recupera los documentos adjuntos a un artículo, que no están ya colgados en el texto del artículo, y cuya extensión puede ser «jpg», «png» o «gif».
- {doublons} tiene aquí una importancia particular: permite no sólo no mostrar documentos que ya aparecen en otros bucles, sino también no volver a mostrar documentos que ya están integrados dentro del texto de un artículo. Si se olvida este criterio, el bucle devolverá todos los documentos asociados a un artículo, incluidos los que ya estén publicados dentro del texto [3].
Las balizas
- #LOGO_DOCUMENT devuelve el logo de un documento, es decir su miniatura de previsualización, a no ser que el autor del artículo haya subido manualmente su propio logo de documento. Para una imagen, la miniatura de previsualización es una versión reducida de ésta, cuando el servidor que hospedaje puede construirla [4]; si no, utiliza un icono estándar en función del tipo de fichero.
- #URL_DOCUMENT es la dirección URL del fichero multimedia. Para mostrar una miniatura que lleve hacia el archivo multimedia haciendo clic en ella, utilizaremos el código siguiente:
[(#LOGO_DOCUMENT|#URL_DOCUMENT)]
- #TITRE devuelve el título del documento.
- #DESCRIPTIF devuelve el descriptivo del documento.
- #FICHIER [SPIP 1.8.2] muestra el nombre de archivo del documento. Un uso interesante de esta baliza es combinada con el filtro reduire_image, en el supuesto de un portafolio, para mostrar la imagen reducida mejor que su logo; por ejemplo utilizando:
[<a
href="#URL_DOCUMENT">(#FICHIER|reduire_image{500}) </a>]
- #TYPE_DOCUMENT devuelve el tipo (archivo Quicktime, archivo Real...) del documento multimedia.
- #TAILLE muestra el tamaño del fichero multimedia. Se proporciona este valor en octetos. Para archivos voluminosos, se podrá aplicar el filtro taille_en_octets, que lo convertirá sucesivamente, para simplificarlo, en bytes (octetos), en kilobytes, o incluso en megabytes:
[(#TAILLE|taille_en_octets)]
- #LARGEUR (anchura) y #HAUTEUR (altura) devuelven las dimensiones en pixels.
- #ID_DOCUMENT devuelve el número de documento.
- #EMBED_DOCUMENT es una baliza de utilización muy específica: permite incluir directamente los ficheros de formatos que lo permiten (imágenes, vídeo, sonido) directamente en la página web. Sin embargo, se debe evitar utilizar sistemáticamente esta baliza para insertar directamente los documentos en la página sin un control estricto: de lo contrario, corres el riesgo de aumentar enormemente el tiempo de carga de tus páginas.
Esta baliza puede ser completada por parámetros propios de los formatos utilizados (una vez más: de uso sumamente específico). Por ejemplo, para que un vídeo o un sonido se inicie sin acción previa de la persona visitante:
[(#EMBED_DOCUMENT|autostart=true)]