oEmbed

Que troço é esse ?

oEmbed é um protocolo aberto que permite inserir conteúdo de uma página web em uma outra página web. O conteúdo inserido por ser de diferentes tipos : foto, video, URL ou parte de HTML.

A troca de informações acontece entre um site cliente e um site servidor. Por exemplo, o site cliente pode exibir uma representação de uma página web como uma imagem ou um video. O servidor deve dispor de um serviço que utilize o API oEmbed para permitir aos clientes de recuperar as informações da representação a ser exibida.

Como funciona ?

Para o cliente, a utilização do plugin é simples. Por padrão o plugin transforma automaticamente :

• as URL entre < e > em qualquer lugar do texto : <https://www.flickr.com/photos/romytetue/4651342894/>
• as URL sozinhas em um paragrafo : dois comandos enter (novo paragráfo), URL, depois mais dois comandos enter.

Se o site para o qual a URL direciona implementa o API oEmbed, este é complementado por um extrato do conteúdo fornecido pelo site. Por exemplo, se a seguinte URL é inserida em um texto de artigo, o código será :

https://www.flickr.com/photos/romytetue/4651342894/

A URL será automaticamente substituída pelo seguinte conteúdo :

Com SPIP 3, o plugin insere também estes tratamentos no formulário para anexar documentos de SPIP (na parte de documentos distante). É necessário acrescentar um documento distante o qual a URL seja de uma página na qual se encontra o conteúdo a ser recuperado. Ver o video abaixo para uma pequena demonstração.

https://medias.spip.net/medias/r-d/plugins-26/multimedia/article/demo-du-plugin-oembed

Uma vez o documento acrescentado, você pode inseri-lo no conteúdo do seu artigo como qualquer documento.

• se o documento é uma imagem, você pode inseri-lo com o atalho <imgXX>
• se o documento é um video, você pode inseri-lo com o atalho <embXX>

E eu posso fazer isso com qualquer site ?

Não, por razões de segurança o plugin utiliza uma lista branca de sites autorizados. Por padrão, esta lista contém os seguintes sites : youtube, blip.tv, vimeo, dailymotion, flickr, soundcloud, slideshare, yfrog, instagram, rdio, huffduffer, nfb, dotsub, clikthrough, kinomap, photobucket, smugmug, meetup, wordpress, blogs.cnn, techcrunch, my.opera, viddler et collegehumor (consultar a lista completa).

Para acrescentar um novo site servidor (ou provider) à lista branca é necessário duas informações :

• scheme : esquema da URL correspondente ao site (você pode utilizar * como wildcard)
• endpoint : URL a qual o serviço oEmbed do site está disponível.

Por exemplo, para acrescentar o site devianART à lista branca só é necessário acrescentar um provider com os seguintes parâmetros :

• scheme : http://*.deviantart.com/art/*
• endpoint : http://backend.deviantart.com/oembed

O acréscimo pode ser feito com a ajuda da pipeline oembed_lister_providers ou através da personalização do conteúdo da variável global $GLOBALS['oembed_providers'].

Por exemplo, em um plugin de prefixo meuplugin declarando a seguinte pipeline em plugins/monplugin/monplugins_pipelines.php :

function monplugin_oembed_lister_providers($providers){

	$providers['http://*.deviantart.com/art/*'] = 'http://backend.deviantart.com/oembed';

	return $providers;
}

Ou sem utilizar plugins, diretamente no seu arquivo config/mes_options.php :

$GLOBALS['oembed_providers'] = array(
	'http://*.deviantart.com/art/*' => 'http://backend.deviantart.com/oembed',
);

Eis uma lista não exaustiva de provider suplementares->https://github.com/panzi/oembedendpoints/blob/master/endpoints-simple.json] no formato JSON.

Tratamentos automáticos

A página de configuração permite também de configurar os parâmetros automáticos do plugin :

• largura/altura por padrão dos blocos de Oembed
• ativar/desativar a transformação automática das URLs no texto : isto diz respeito às URLs sozinhas em um parágrafo, pois as URLs entre < e > serão sempre convertidas ;
• ativar/desativar a detecção automática dos providers sem levar em consideração a lista branca (atenção às falhas XSS).
• desativar a inserção dos cabeçalhos que declaram o site como provider.

Funções de pós-tratamento

É possível declarar funções de pós-tratamento que agirão sobre os dados enviados pelo site fonte (ou provider). A nomeação destas funções segue a seguinte convenção oembed_posttraite_{$provider_name}_$type[_dist] afim de permitir a declaração de pós-tratamento em função da fonte de dados.

Por exemplo, o plugin fornece uma função de pós-tratamento para soundcloud :

function oembed_input_posttraite_soundcloud_rich_dist($data){

	$data['media'] = 'sound';
	$data['html'] = preg_replace(",width=['\"][0-9]+['\"],i",'width="100%"',$data['html']);

	if (!isset($data['thumbnail_url'])){
		$data['thumbnail_url'] = find_in_path("oembed/input/vignettes/soundcloud.png");
	}

	return $data;
}

Esta função define que o conteúdo enviado é som e depois ela modifica a largura do leitor audio, e para terminar ela define uma vinheta padrão se uma vinheta não está presente.

Ver a fonte na « zone ».

Mudanças no servidor

O plugin acrescenta links de declaração oEmbed no cabeçalho das páginas do site. Estes links permitem aos outros sites a descoberta de que o seu site é « compatível » oEmded e que ele pode, dessa forma, ser utilizado como fornecedor de conteúdo (ou provider).

Os parâmetros que devem ser fornecidos para permitir que um outro site de acrescentar o seu site à sua lista branca de providers são os seguintes :

• scheme : http://urldevotresite.net/*
• endpoint : http://urldevotresite.net/oembed.api/

Para que o endereço do serviço funcione é necessário ativar o arquivo .htaccess fornecido de forma padrão por SPIP.

O conteúdo que é enviado no momento de um demanda oembed é gerado pelos esqueletos situados no repertório spip-contrib-extensions/oembed/oembed/output/modeles. Estes esqueletos são personalizados e você pode inserir laços (boucles) e balises para enviar o código de oEmbed de um documento audo/video, uma imagem retirada do portfolio de um artigo, etc.

Por exemplo, para uma demanda a partir da URL http://contrib.spip.net/GIS-4 o conteúdo enviado é o seguinte :

{
    "version": "1.0",
    "type": "rich",
    "provider_name": "SPIP-Contrib",
    "provider_url": "http://contrib.spip.net",
    "title": "GIS 4",
    "author_name": "b_b",
    "width": "480",
    "height": "295",
    "url": "http://contrib.spip.net/GIS-4",
    "html": "<h4 class='title'><a href='http://contrib.spip.net/GIS-4'>GIS 4</a></h4><blockquote class='spip'>\n<p>Présentation et nouveautés <br class='autobr' />\nLa version 4 de GIS abandonne la libraire Mapstraction au profit de Leaflet. Cette librairie permet de s’affranchir des librairies propriétaires tout en gardant les mêmes fonctionnalités, elle propose même de nouvelles fonctions.<br class='autobr' />\nCette nouvelle version de GIS permet d’utiliser différents fonds de carte sans avoir à charger des scripts externes, seuls les scripts locaux de Leaflet et des plugins nécessaires sont chargés dans vos pages. À ce jour, le plugin propose plus de&amp;amp;amp;amp;nbsp;(...)</p>\n</blockquote>\n"
}

Ver o códio online.

Veja como é a exibição a partir do site SPIP cliente :