Le laboC’est quoi ce truc ?
oEmbed est un protocole ouvert qui permet d’insérer le contenu d’une page web dans une autre page. Le contenu inséré peut être de plusieurs types : photo, vidéo, URL ou extrait HTML.
L’échange d’information a lieu entre un site client et un site serveur. Par exemple, le site client peut afficher une représentation d’une page web telle qu’une image ou une vidéo. Le serveur doit disposer d’un service utilisant l’API oEmbed pour permettre aux clients de récupérer les informations de la représentation à afficher.
Comment ça marche ?
Du côté client, l’utilisation du plugin est simple. En effet, par défaut le plugin transforme automatiquement les liens vers les sites qui implémentent l’API oEmbed. Pa exemple, si on insère l’url suivante dans le texte d’un article :
http://www.flickr.com/photos/dan1977/5087662622/
Celle-ci sera automatiquement remplacée par le contenu correspondant :
http://www.flickr.com/photos/dan1977/5087662622/
Voir quelques exemples d’utilisation du plugin sur le site démonstration.
Avec SPIP 3, le plugin insère aussi ces traitements dans le formulaire d’ajout de documents de SPIP (dans la partie documents distants). Il suffit d’ajouter un document distant dont l’url est celle de la page où se trouve le contenu à récupérer. Voir la vidéo ci-dessous pour une petite démonstration.
http://spip.arscenic.tv/medias/r-d/plugins/multimedia/article/demo-du-plugin-oembed
Une fois le document ajouté, vous pouvez l’insérer dans le contenu de votre article comme n’importe quel document.
- si le document est une image, vous pouvez l’insérer avec le raccourci
<imgXX> - si le document est une vidéo, vous pouvez l’insérer avec le raccourci
<embXX>
Et je peux faire ça avec n’importe quel site ?
Non, pour des raisons de sécurité le plugin utilise une liste blanche de sites autorisées. Par défaut, cette liste contient les sites suivants : youtube, blip.tv, vimeo, dailymotion et flickr. La liste blanche est éditable depuis la page de configuration du plugin (accessible dans le menu Configuration > oEmbed).
Vous pouvez ajouter un nouveau site serveur (ou provider) à la liste blanche, pour cela il vous faudra deux informations :
- scheme : schéma d’URL correspondant au site (vous pouvez utiliser * comme wildcard)
- endpoint : URL à laquelle le service oEmbed du site est disponible
Par exemple, pour ajouter le site Flickr à la liste blanche il suffit d’ajouter un provider avec les paramètres suivants :
- scheme : http://*.flickr.com/*
- endpoint : http://www.flickr.com/services/oembed/
Voici une liste non exhaustive de providers supplémentaires au format JSON.
Traitements automatiques
La page de configuration vous permet aussi de paramétrer les automatismes du plugin :
- activer/désactiver la transformation automatique des urls dans le texte ;
- activer/désactiver la détection automatique des providers sans tenir compte de la liste blanche (attention aux failles XSS).
Côté serveur
Le plugin ajoute des liens de déclaration oEmbed dans l’entête des pages du site. Ces liens permettent aux autres sites de découvrir que votre site est "compatible" oEmbed.
Les paramètres à fournir pour permettre à un autre site d’ajouter le votre à sa liste blanche de providers sont les suivants :
- scheme : http://urldevotresite.net/*
- endpoint : http://urldevotresite.net/services/oembed/
Le contenu renvoyé lors d’une requête oembed est généré par les squelettes situés dans le répertoire plugins/oembed/inclure/. Ces squelettes sont personnalisables, vous pouvez y insérer des boucles et balises afin de renvoyer le code d’embed d’un document audio/vidéo, une image tirée du portfolio d’un article, etc.
Par exemple, pour une requête depuis une page d’article le contenu renvoyé est le suivant :
code d'un squelette commenté