Este loop gere não apenas os documentos anexos não instalados no texto de uma matéria, mas pode também aceder às imagens (oas imagens são geridas, ao nível do programa, como um tipo específico de documentos), às vinhetas de previsualização e aos documentos já inseridos no corpo da matéria.
Para referência, usaremos mais frequentemente (uso corrente) o loop DOCUMENTS com, no mínimo, os critérios aabaixo (explicações a seguir):
<BOUCLEn(DOCUMENTS){mode=document}{doublons}>
Os critérios de seleção
Um loop DOCUMENTS é usado geralmente no interior de uma matéria ou de uma seção (eventualmente numa nota, mas aqui o uso será reservado à recuperação de imagens, de modo bem específico).
- {id_document} seleciona o documento cujo identificador é id_document. Como o identificador de cada documento é único, este critério retorna apenas 1 ou 0 como resposta.
- {id_article} retorna os documentos da matéria cujo identificador é id_article.
- {id_rubrique} retorna os documentos da seção id_rubrique.
- {id_breve} retorna os documentos da nota id_breve (não é possível associar documentos multimédia a uma nota, apenas imagens; o uso de um loop DOCUMENTS nesta situação será bem específico).
Note: não é possível usar aqui o critério {id_secteur}; os documentos são concebidos para serem intimamente ligados às matérias e às seções, e não serem chamados sem esses elementos (chamamos em SPIP de "documentos anexos").
- {mode=logoon} permite recuperar um documento que serve de logo. Com efeito, depois do SPIP 4.0, os logos são tratados como documentos, permitindo assim dar-lhes um título, uma descrição etc.
- {mode=logooff} permite recuperar um documento que serve de logo de hover.
Os critérios de exibição
- {mode=document} ou {mode=image} permitem especificar se quer-se chamar documentos multimédia, ou imagens (com efeito, as imagens associadas à matéria e eventualmente inseridas no tesxto são tratadas como documentos em mode=image).
- {extension=...} permite selecionar os documentos de acordo com a sua extensão (extensão do ficheiro multimédia, por exemplo, "mov", "ra", "avi"...). Isto pode ser usado para, por exemplo, criar um porfolio, ou seja, um loop que só exibe documentos do tipo imagem, e um segundo loop a seguir, com layout diferente, dos outros tipos de documentos:
<BOUCLE_portfolio(DOCUMENTS){id_article}{extension==jpg|png|gif}{mode=document}{doublons}>
Este BOUCLE_portfolio recupera os documentos anexos a uma matéria, ainda não exibidos no texto da matéria, cujas extensões possam ser "jpg", "png" ou "gif".
- {media=...} permite selecionar os documentos de acordo com o seu tipo:
"image", "audio" ou "video" ou "file".
Assim, no loop precedente, o critério {extension==jpg|png|gif} pode igualmente ser escrito assim: {media=image}.
- {distant} permite selecionar documentos consoante sejam remotos ou não. Ou seja, se estão alojados noutro site, ou presentes no espaço web do site. Usa-se {distant=oui} e {distant=non} respectivamente. (ver Gestão de documentos)
- {doublons} toma aqui uma importância especial: permite não apenas não reexibir os documentos já exibidos por outro loop, mas também não reexibir os documentos já integrados no interior de uma matéria. Ao se omitir este critério, serão exibidos todos os documentos associados a uma matéria, inclusive os que já tenham sido exibidos dentro do texto [1].
- {vu=non} permite excluir os documentos integrados no texto ou cabeçalho da matéria (pode-se incluir outros campos nos testes por meio de globale medias_liste_champs).
- {largeur >= 1000} permite selecionar documentos do tipo imagem em que a largura seja superior ou igual a 1000 pixels.
- {hauteur < 1000} permite selecionar documentos do tipo imagem em que a altura seja inferior a 1000 pixels.
- {portrait} exibe apenas os documentos em que a altura é maior do que a largura.
- {paysage} exibe apenas os documentos em que a largura é maior do que a altura.
- {carre} exibe apenas os documentos em que a altura é igual à largura.
Os critérios de ordenação
Após o SPIP 3.2, além dos critérios comuns a todos os loops, o loop DOCUMENTS possui um critério {par rang_lien} que permite ordenar os documentos anexos segundo a sua posição.
- Ver par rang_lien
As tags
- #LOGO_DOCUMENT exibe o logo (vinheta de pré-visualização) associada ao documento; se uma vinheta personalizada não foi instalada manualmente pelo autor da matéria, o SPIP usará uma vinheta padrão, de acordo com o tipo de ficheiro.
- #URL_DOCUMENT é o URL do ficheiro multimédia. Para exibir uma vinheta clicável apontando para o documento multimédia, usa-se o código a seguir:
[(#LOGO_DOCUMENT{#URL_DOCUMENT})]
- #TITRE exibe o título do documento.
- #DESCRIPTIF exibe a descrição do documento.
- #CREDITS permite indicar os créditos de um documento (por exemplo, o nome do fotógrafo de uma foto).
- #ALT permite indicar o texto alternativo de uma imagem.
- #FICHIER exibe o nome do ficheiro do documento, mais precisamente o seu UrL relativo. Para obter apenas o nome do ficheiro, usa-se o filtro: [(#FICHIER|basename)].
Um uso interessante desta tag é combiná-la com o filtro image_reduire, no contexto de um portfolio, para exibir uma redução da imagem, em vez do seu logo; por exemplo, ao usar
[<a href="#URL_DOCUMENT">(#FICHIER|image_reduire{500})</a>]
- #TYPE_DOCUMENT exibe o tipo (ficheiro mp4, ficheiro mp3...) do documento multimédia.
- #EXTENSION exibe a extensão do formato do ficheiro, por exemplo: pdf, jpeg, mp4.
- #MEDIA exibe o tipo de média: image, audio, video ou file.
- #TAILLE exibe o tamanho do ficheiro multimédia. Este número é fornecido em bytes. Para ficheiro grandes, este valor torna-se rapidamente inusável; pode-se aplicar o filtro taille_en_octets, que exibirá sucessivamente em bytes, kilobytes ou mesmo em megabytes:
[(#TAILLE|taille_en_octets)]
- #LARGEUR et #HAUTEUR fornecem as dimensões em pixels.
- #MIME_TYPE exibe o tipo MIME do ficheiro — por exemplo: image/jpeg —, cf. Tipo de mídia da Internet.
- #DATE é a data de poblicação do documento. (Alterável após inclusão). Ver "A gestão das datas" para os detalhes sobre o uso do campo #DATE.
- #ID_DOCUMENT exibe o identificador do documento.
- #DISTANT é uma tag que exibe "oui" ou "non" se o documento é, respectivamente, remoto (referenciado por um URL) ou local.
- #EMBED_DOCUMENT é uma tag que permite incorporar o documento na página gerada, em vez de apenas o referenciar. Esta tag está obsoleta, sendo um caso particular dos modèles (ver Usando os modelos) que permitem modular esta incorporação de modo mais flexível e eficaz.
Esta tag pode ser complementada por parâmetros específicos dos formatos usados, por exemplo:
#MODELE{emb, autostart=true}
- #MODE ter como valor ’image’, ’document’, ’logoon’, ’logooff’, ’vignette’ segundo a natureza de um documento.
Ver também
- As tags #LOGO_XXX