Carnet Wiki

Modèles <media> : proposition de fonctionnement alternatif pour l’insertion des documents

Version 16 — Octobre 2010 — laurent

Le fonctionnement des modèles pour l’insertion des documents soulève régulièrement des questions, notamment parce <doc13>, <img13> ou encore <emb13> ne produisent pas le même résultat et que ce résultat, pour les images, dépend du fait d’être dans le portfolio ou non.

Comme l’écrit Romy,

<blockquote class="spip">

Qui sait expliquer clairement la différence entre les « images » et les « documents » de SPIP ? Quand faut-il utiliser le raccourci d’insertion <img314>, celui <doc314> ou encore <emb314> ? et quelles sont précisément leurs différences ? Pourquoi est-ce si difficile à retenir ?

</blockquote>

(Source : http://romy.tetue.net/mais-ou-est-p...)

Sur la liste SPIP-Zone, Cédric expliquait :

<blockquote class="spip">

Le sujet est un serpent de mer, contraint par la compatibilté ascendante. Pour le moment on a fait le choix de ne pas la casser, ce qui a des limites.

</blockquote>

(Source : http://permalink.gmane.org/gmane.co...)

Avant de poursuivre la discussion, on pourra lire la documentation officielle à cette adresse http://www.spip.net/fr_article3715.html.

Objectif

La présente proposition vise à proposer une nouvelle série de modèles ayant un comportement unifié et indépendant du mode des images. Ces modèles seront implémentés dans un premier temps dans un plugin dédié (modeles_media) avant d’envisager une éventuelle intégration au core.

Les modèles existants (doc, emb, img, image, audio, video, text, application) ne seront pas modifiés afin d’assurer la rétrocompatibilité.

Un unique modèle

Un Reprenant l’idée suggérée par Romy Têtue , un seul modèle sera à retenir avec un appel unifié de la forme [syntaxe  (…)" id="nh1">1] forme  :  :

<mediaXX|variante|alignement|parametres> où XX représente l’identifiant du document.

Volontairement, afin de distinguer le nouveau système du système actuel, on n’a pas repris <doc>.

Syntaxe générale

Syntaxe des modèles <media>

Trois variantes principales

Les modèles <media> reposent sur trois variantes principales : icone, vignette et embed.

<media12|icone> affichera l’icône représentant le type de document.

<media12|vignette> affichera une vignette du document. Il s’agira dans l’ordre :

  1. de la vignette personnalisée associée au document si elle existe.
  2. d’une vignette générée automatiquement à partir du document. Pour le moment, cela ne concerne que les images jpg, png ou gif mais le système est extensible (voir ci-après). La vignette générée est indépendante de la configuration de SPIP (que l’on ait activé ou non les vignettes automatiques dans Configuration > Fonctions avancées). Enfin, la taille de la vignette n’est pas déterminée par le paramètre de SPIP concernant les vignettes automatiques mais par le paramètre |taille transmis au modèle (voir ci-après).
  3. de l’icône du type de fichier si aucune vignette personnalisée n’est disponible et si aucune fonction de génération automatique de vignette n’est disponible pour ce type de fichier.

<media12|embed> permet d’incruster le document, l’incrustation étant fonction du type du document.

Il existe également d’autres variantes secondaires, décrites plus bas, qu’il n’est pas besoin de connaître pour un usage courant.

Alignement

L’alignement se précise comme actuellement avec |left, |center et |right.

Exemple : <media12|icone|right>

Afficher une légende

En l’absence de paramètres spécifiques, aucune légende n’est affichée.

Pour afficher une légende simple (titre + descriptif), on ajoutera simplement |legende au modèle. Par exemple : <media12|vignette|legende>.

Si l’on souhaite une légende complète (titre + descriptif + crédits + type de document + poids en octets), on indiquera |legende=complete. Par exemple : <media12|vignette|legende=complete>.

Il est également possible d’indiquer plus précisément les éléments qui devront composer la légende. Au lieu du paramètre |legende, on aura alors recours aux paramètres |titre, |descriptif, |credits, |type |poids. Par exemple, si on souhaite afficher uniquement le titre et les crédits on fera : <media12|icone|titre|credits>. Pour afficher seulement le type de document et son poids : <media12|icone|type|poids>.

Il est possible de personnaliser le titre, le descriptif et les crédits à afficher pour utiliser d’autres valeurs que celles associées au document (utile par exemple sur un site multilingue). On précisera alors simplement à ces trois paramètres les valeurs à prendre. Par exemple :

<media12|icone
    |titre=Un autre titre
    |descriptif=Un autre descriptif avec du {{gras}}, de l'{italique} et même une note[[de bas de page]].
    |credits=d'autres crédits>

On peut utilise les deux formes d’écritures. Pour afficher le titre du document, des crédits personnalisés et le poids du document : <media12|icone|titre|credits=autres crédits|poids>. Si on souhaite afficher la légende complète en personnalisant juste le titre : <media12|icone|legende=complete|titre=Mon autre titre>.

Ajouter un lien

En l’absence de paramètres spécifiques, aucun lien n’est ajouté au média.

Pour que le média pointe sur lui-même, on ajoutera simplement |lien. Il est possible de préciser un lien spécifique, par exemple <media12|icone|lien=http://www.monsite.net>. On peut utiliser les raccourcis SPIP pour les liens internes. Par exemple, pour pointer sur la rubrique 3 : <media12|icone|lien=rub3>.

Il est également possible d’utiliser la syntaxe suivante [<media12|icone>->rub3].

L’attribut title du lien est déterminé automatiquement par SPIP en fonction du lien. Cependant, il est possible de spécifier explicitement l’attribut title avec le paramètre |titre_lien. Par exemple : <media12|icone|lien=http://www.monsite.net|titre_lien=Un super site à visiter>.

Spécifier la taille

En l’absence de paramètres spécifiques, la taille du document sera utilisée (modifiable selon le type de fichier), notamment pour les vignettes.

Les modèles <media> proposent 4 tailles standards : icone, petit, moyen et grand. Ces quatre tailles peuvent être personnalisées dans la Configuration de SPIP, sous l’onglet Fonctions avancées.

On spécifiera la taille souhaitée en utilisant le paramètre |taille, par exemple : <media12|vignette|taille=petit>. Il est également possible de spécifier une taille précise en pixels de la manière suivante : <media12|vignette|taille=150>.

Les médias sont redimensionnés en respectant le ratio hauteur/largeur. Ainsi, |taille=150 redimensionnera le média de telle manière que son plus grand côté soit égal à 150 pixels.

Si on souhaite simplement spécifier une hauteur maximum de 150 pixels, on utilisera |hauteur=150. Pour une largeur maximum de 300 pixels, |largeur=300. On peut utiliser les deux paramètres en même temps : <media12|vignette|hauteur=150|largeur=300>.

Personnaliser le texte alternatif

Il est possible de personnaliser le texte alternatif ajouté aux images et autres médias avec le paramètre |alt. Par exemple : <media12|icone|alt=Texte alternatif sur l'icône>.

Cas du modèle appelé sans variante

Il peut arriver que le modèle soit appelé sans spécifier de variante (exemple : <media12>).

Dans cette situation indéterminée, plutôt que de ne rien afficher, le modèle retournera l’équivalent de <media24|vignette|legende|lien|taille=icone>.

Aide à l’insertion des modèles

Afin de faciliter l’insertion des nouveaux modèles, modeles_media fournit un formulaire d’insertion utilisable avec le plugin en test inserer_modeles (voir Comment déclarer un modèle pour le plugin « Insérer Modèles »). Si celui-ci est actif, alors une aide à l’insertion des modèles media sera disponible dans le porte-plume.

Variante logo

Il est possible de faire <media12|logo> qui affichera le logo du document. Le logo d’un document est calculé par SPIP de la manière suivante :

  1. la vignette personnalisée associée au document
  2. sinon, si c’est une image jpg, gif ou png et que l’option vignette automatique est activée dans les fonctions avancées, une vignette de l’image de 100 pixels de coté maximum (taille paramétrable)
  3. sinon l’icône du document.

Le logo d’un document affiche donc tantôt une vignette et tantôt l’icône du document selon la configuration de SPIP. On préférera donc l’usage des variantes icone et vignette à la place de la variante logo, vignette ne dépendant pas de la config de SPIP (que les rédacteurs ne connaissent pas toujours).

Variantes par groupe MIME et par extension

Une variante par groupe MIME

Reprenant le fonctionnement actuel de <emb>, la variante media_embed.html sous-traite le travail à plusieurs modèles en fonction du type MIME du document : media_image.html, media_audio.html, media_video.html, media_text.html et media_application.html.

Dès lors, il est possible d’utiliser également les variantes de la forme <mediaXX|image>, <mediaXX|audio>, <mediaXX|video>, <mediaXX|text> et <mediaXX|application>.

<mediaXX|embed> et <mediaXX|image> produiront exactement le même résultat si XX est une image. [2].

Une variante par extension

Il est possible de définir une variante par extension sous la forme modeles/media_groupeMIME_extension.html. Lors de l’incrustation d’un fichier, on vérifiera l’existence d’un modèle spécifique pour cette extension (modeles/media_groupeMIME_extension.html), sinon on utilisera le modèle générique du groupe MIME modeles/media_groupeMIME.html.

Pour les images, on a ainsi avoir un modèle générique modeles/media_image.html et un modèle spécifique pour le BMP : modeles/media_image_bmp.html.

Ainsi, avec le lecteur multimedia, pour la prise en charge des mp3, le plugin pourrait proposer un modèle media_audio_mp3.html qui appelle le player fourni par le plugin. Dans mon article, je mets juste <media123|embed> qui saura tout seul trouver le bon modèle. Maintenant, je désactive le lecteur multimedia, <media123|embed> sera toujours pris en charge par le modèle générique modeles/media_audio.html qui incrustera le MP3 dans une balise <object>. Ce qui est mieux qu’une simple icone dans le cas présent. [3].

Les filtres par type mime

Les modèles <media> reprennent les filtres par type mime utilisés dans l’actuel modèle <emb>. Voir : Les modèles d’incrustation de documents et leurs filtres (spip.net).

Classes ajoutées systématiquement

Quelque soit la variante utilisée, on ajoutera, en plus des classes usuelles spip_documents, spip_document_#ID_DOCUMENT et spip_documents_#ENV{align}, les classes suivantes : media_#ENV{variante} et media_#ENV{variante}_#EXTENSION.

Ajouter des modèles de légende

Il est possible de personnaliser les légendes à partir des modèles de légende. En effet, lorsqu’on appelle un modèle media avec |legende=malegende, le modèle media vérifie l’existence d’un modèle modeles/legende_malegende.html. Si ce modèle existe, alors il sera chargé en lui transmettant les variables suivantes : id (correspond à id_document), titre, descriptif, credits, type, poids (tel que transmis au modèle media), width qui correspond à la largeur attendue de la légende et conteneur qui vaut ’dl’ si la légende doit être inclue entre des balises

<dl></dl>.


Si le modèle <code>modeles/legende_malegende.html

n’existe pas, alors le modèle affichera une légende simple (comme si le modèle media avait été appelé avec |legende).

Pour un exemple de modèle de légende, voir modeles/legende_complete.html fournir dans le plugin modeles_media. Ce modèle peut être surchargé en copiant votre version dans le dossier squelettes.

La légende par défaut (correspondant à un appel simple de la forme |legende) peut être personnalisée en faisant un modèle modeles/legende_legende.html.

La génération automatique de vignettes dans le modèle media_vignette

Pour générer une vignette automatique, lorsque le document n’a pas de vignette spécifique, media_vignette test la présence d’un filtre filtre_media_generer_vignette_extensionextension correspond à l’extension du document.

Ce système permet de pouvoir étendre la génération des vignettes à autre chose que les images. On peut imaginer des plugins proposant par exemple de générer une image de la première page d’un document PDF, extrayant/téléchargeant la couverture de l’album d’un MP3 à partir de ces tags ID3, générant automatiquement une vignette pour une vidéo...

Par défaut, le plugin modeles_media ne génère des vignettes que pour les images jpg, png et gif, la vignette étant l’image elle-même. En effet, la vignette n’est volontairement pas redimensionnée à cette étape, le redimensionnement étant effectué directement dans le modèle en fonction des paramètres de taille transmis.

Pour récupérer dans un squelette la vignette générée automatiquement, on pourra utiliser [(#FICHIER|media_generer_vignette{#EXTENSION})] dans une boucle DOCUMENTS. On n’obtiendra rien si aucune vignette n’a pu être générée automatiquement.

Pour reproduire le comportement de media_vignette (à savoir la vignette associée explicitement à un document, sinon une vignette générée automatiquement, sinon l’icône), on utilisera [(#LOGO_DOCUMENT{vignette}|sinon{#FICHIER|media_generer_vignette{#EXTENSION}}|sinon{#LOGO_DOCUMENT{icone}})].

Modèles et HTML5

Les modèles <media> utilisent la balise #HTML5 pour utiliser les balises <figure>, <figcaption>, <audio>, <video>.

Le support du HTML5 reste basique, charge à d’autres plugins de surcharger les modèles pour une utilisation avancée des balises HTML5 (par exemple avec détection du navigateur pour proposer un lecteur flash si le navigateur ne prend pas en charge tel format).

À faire

Les documents vus dans un article sont identifiés via la fonction traiter_modeles du fichier inc/lien en lui passant $doublons=true.

Dans ce cas là, les documents vus sont identifiés en repérant les modèles img, doc et emb [4].

Il faudrait créer un pipeline permettant à un plugin d’ajouter à la liste des modèles de documents les modèles de documents qu’il fournit, afin que les modèles media soient pris en compte.