Modèles <media> : documentation Développeur

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.

Une variante par extension

Il est également 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 format BMP : modeles/media_image_bmp.html.

Ainsi, un plugin peut venir compléter les modèles <media> uniquement pour certaines extensions, sans que la syntaxe d’appel ne soit modifiée.

Par exemple, le plugin lecteur multimédia prenant en charge la lecture de fichier mp3 pourrait proposer un modèle media_audio_mp3.html qui appelle le player fourni par le plugin. L’appel dans le texte de l’article rest inchangé :<media123|embed> qui saura tout seul trouver le bon modèle.

Ce fonctionnement présente quelques avantages :

• l’appel est inchangé ce qui simplifie l’apprentissage des rédacteurs ;
• en cas de désactivation du plugin lecteur multimédia, <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>. [1].

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, sont ajoutées, 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 avec 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 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_extension où extension 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 <media> 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).

Nouvelles balises fournies par le plugin

Ces balises peuvent s’utiliser dans une boucle DOCUMENTS dans un modèle media.

#MEDIA_LEGENDE

Calcule la légende d’un document. Les paramètres legende, titre, descriptif, credits, poids et type sont récupérés dans l’environnement. Le précise le conteneur (div ou dl), le second la largeur de la légende. Exemples d’utilisation : #MEDIA_LEGENDE{'dl',#GET{width}} ou #MEDIA_LEGENDE{'div',#GET{width}}.

#MEDIA_AFFICHER_LEGENDE

Renvoie un espace si on doit afficher une légende, rien sinon.

#MEDIA_IMAGE_RETAILLEE

Renvoie le fichier d’une image retaillée selon les paramètres passés au modèle. Les paramètres taille, hauteur, largeur, alt et titre sont récupérés dans l’environnement. Exemple d’utilisation : #MEDIA_IMAGE_RETAILLEE{#LOGO_DOCUMENT} ou #MEDIA_IMAGE_RETAILLEE{#URL_DOCUMENT}.

#MEDIA_LIEN

Calcule le lien, si lien demandé, sur le document. Il faut lui passer Les paramètres lien, titre_lien et sont récupérés dans l’environnement. Retourne l’objet passé en argument entouré, le cas échéant, des balises <a> et </a> adéquates. Exemple d’utilisation : #MEDIA_LIEN{#LOGO_DOCUMENT} ou #MEDIA_LIEN{#MEDIA_IMAGE_RETAILLEE{#LOGO_DOCUMENT}}.

#MEDIA_TAILLE

Renvoie la taille du media après redimensionnement si besoin. Les paramètres taille, hauteur et largeur sont récupérés dans l’environnement. Exemple d’utilisation : #MEDIA_TAILLE{largeur} ou #MEDIA_TAILLE{hauteur}.

#MEDIA_IGNORE_PARAMS

Renvoie un tableau des paramètres à ignorer à utiliser avec les filtres env_to_params et env_to_attribute. Exemples : [(#ENV*|env_to_attributs{#MEDIA_IGNORE_PARAMS})] ou [(#ENV*|env_to_params{#MEDIA_IGNORE_PARAMS})].

Identification des documents vus

Sous SPIP 2.1, les documents vus dans un article sont identifiés via la fonction media_traiter_modeles du fichier inc/marquer_doublons_doc.php.

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

Sous SPIP 3, il est possible d’étendre la liste des documents via un pipeline. La surcharge a donc été supprimée.