Guia do Desenvolvedor de Aceleradores OpenService

Artigo
01/29/2010

Novidade no Windows Internet Explorer 8

No Internet Explorer 8, os Aceleradores são opções de menu contextual que podem acessar rapidamente aplicativos ou serviços Web de qualquer página da Web. Os usuários podem instalar Aceleradores a partir da Galeria de Serviços do Internet Explorer 8 ou de qualquer site que os anunciar. Os Aceleradores facilitam a cópia de informações de uma página da Web para outra. Este artigo descreve como definir e implantar Aceleradores baseados em XML.

O artigo contém as seguintes seções:

Pontos principais
Introdução
Categorias
Variáveis
- Parâmetros de modelo de URL
- Parâmetros baseados em formulário
- Tipos de seleção
- Implicações de segurança de variáveis de documento
Visualização
- Tamanho
- Conteúdo
- Navegação
Localização
- Exemplo em inglês
- Exemplo em espanhol
Instalação
Formato de Acelerador OpenService
Tópicos relacionados

Pontos principais

Os Aceleradores aparecem no menu de atalho do botão direito do mouse da página da Web no Internet Explorer. Eles são agrupados por função para que os usuários possam acessar rapidamente a tarefa desejada.
Os Aceleradores habilitam dois tipos de cenários: os usuários podem "visualizar" informações sem sair de uma página da Web ou "executar" para enviar conteúdo diretamente a um aplicativo ou serviço Web.
Um Acelerador baseado em XML usa arquivo XML para descrever o formato de solicitações HTTP para o servidor Web. Os dados do contexto de destino (seleção, link ou documento) são passados como variáveis em parâmetros de URL e/ou dados de formulário.
Para instalar Aceleradores baseados em XML a partir de um site, use o método window.external.AddService para avisar o usuário.

Introdução

Os Aceleradores permitem que você trabalhe com os dados de uma página da Web. Você pode selecionar algumas linhas de texto e enviá-las para um blog ou um email com um clique. Usando um Acelerador previamente instalado, essa ação "executa" a atividade desejada navegando até o site desejado com a parte selecionada do artigo já disponível no campo de edição. Você também pode trabalhar com os dados sem ir para outro site usando Aceleradores de "visualização"; por exemplo, você pode traduzir uma palavra ou mapear um endereço. Passe o cursor do mouse sobre um Acelerador para exibir a janela de visualização.

Captura de tela do Acelerador de mapa com visualização
Figura 1: Mapeando um endereço com um Acelerador de visualização.

Os Aceleradores são declarativos. Eles usam o envio HTTP para estabelecer comunicação entre o navegador e o site. Os Aceleradores baseados em XML são fáceis de criar, testar e implantar para os usuários.

Categorias

Os Aceleradores são agrupados por função para que os usuários possam acessar rapidamente a tarefa desejada. Você poderá definir o Acelerador padrão para uma determinada categoria ao instalar o Acelerador ou na caixa de diálogo Gerenciar Complementos.

Exemplos de serviços que existem hoje:

Adicionar: del.icio.us, Digg, Reddit
Blog: Windows Live Spaces, Windows Live Writer, Blogger
Definir: Encarta, Wikipedia, Dictionary.com
Mapear: Windows Live Map, Google Maps, Yahoo! Maps, MapQuest
Enviar: Windows Live Mail, Gmail, Yahoo! Mail
Traduzir: Windows Live Translation, AltaVista's Babel Fish, Google Translation

Se o Acelerador não se encaixar em uma categoria recomendada, você poderá definir sua própria categoria.

<os:activity category="Share">

A categoria deverá ser um verbo que o usuário reconheça e não pode estar vinculada a uma marca ou um aplicativo específico, para que outros Aceleradores de funcionalidade semelhante possam usar a categoria. Além disso, como o valor do atributo category é usado por Gerenciar Complementos para organizar os Aceleradores em grupos, ele deverá ser legível e ter as maiúsculas/minúsculas adequadas.

Variáveis

As propriedades do documento e o conteúdo são enviados ao provedor de serviços de Acelerador por meio de envios HTTP GET e/ou POST. Essas propriedades são expressas como variáveis de substituição que podem ser passadas como campos de formulário ou como parâmetros de URL. As variáveis podem ser especificadas diretamente no atributo action de os:execute e os:preview (chamado de "modelo de URL"), ou em elementos os:parameter.

Observação Você pode usar cookies para armazenar o estado e as credenciais de usuário.

As seguintes variáveis estão disponíveis:

Variável	Contexto	Description
{documentUrl}	Todos†	O href do documento.
{documentTitle}	Todos	O title do documento, se disponível.
{documentDomain}	Todos	Domínio de segundo nível efetivo do href do documento.
{documentHost}	Todos	Domínio totalmente qualificado do href do documento.
{selection}	seleção	Texto atualmente selecionado.
{link}	link	O href do link selecionado.
{linkText}	link	O innerText do link selecionado.
{linkRel}	link	O rel do link selecionado, se disponível.
{linkType}	link	O type do link selecionado, se disponível.
{linkDomain}	link	Domínio de segundo nível efetivo do href do link.
{linkHost}	link	Domínio totalmente qualificado do href do link.

†Não disponível durante a visualização fora do contexto de documento.

Alguns lembretes sobre variáveis:

Sempre encerre os nomes de variáveis entre chaves {}; por exemplo {selection}. Para especificar um caractere de chave literal na solicitação, use barras invertidas como caracteres de escape, como \{{selection}\}.
Um caractere "?" após o nome da variável indica que ela é opcional; por exemplo, {documentTitle?}.
Se qualquer variável obrigatória (não opcional) no modelo de URL não estiver disponível (por exemplo, tentando executar um Acelerador que inclui {linkRel} no atributo action em um link sem atributo rel), o Acelerador não poderá ser executado e sua entrada no menu de atalho estará esmaecida.
Se qualquer elemento os:parameter tiver um valor vazio por qualquer motivo, ele não aparecerá na solicitação.

Parâmetros de modelo de URL

Os parâmetros de URL transportam informações da página da Web para o serviço. Em uma solicitação get, todos os parâmetros serão passados na URL se você os especificar como elementos os:parameter ou adicionar variáveis diretamente ao modelo de URL.

Observação Se você especificar elementos os:parameter, os parâmetros de URL que seguem o ponto de interrogação (?) no modelo de URL não serão usados.

Assegure-se de identificar corretamente as variáveis opcionais no modelo de URL. Considere o seguinte modelo:

<os:execute method="get"
    action="http://example.com/service.aspx?url={documentUrl}&title={documentTitle?}" />

Neste exemplo, documentUrl é uma variável obrigatória e documentTitle é opcional. Se o valor de documentTitle estiver vazio, uma cadeia de caracteres vazia será usada para o parâmetro title na URL. Entretanto, se o valor obrigatório de documentUrl estiver vazio, o Acelerador estará indisponível (esmaecido) no menu de atalho do Acelerador.

Parâmetros baseados em formulário

Em uma solicitação post, os elementos os:parameter especificam os pares de nome/valor da entrada de formulário. O exemplo a seguir passa os mesmos valores como o anterior.

<os:execute method="post" action="http://example.com/service.aspx>
    <os:parameter name="url" value="{documentUrl}" />
    <os:parameter name="title" value="{documentTitle?}" />
</os:execute>

Se um parâmetro obrigatório (não opcional) estiver indefinido, ele será ignorado. Por exemplo, se {selection} fosse especificado mas não estivesse disponível, o parâmetro seria removido da solicitação.

Tipos de seleção

O texto selecionado pode ser interpretado de dois modos: como "texto" sem formatação (o padrão) ou como marcação "html". O tipo de seleção é definido no elemento os:parameter.

O texto selecionado é codificado conforme necessário pelo método de solicitação HTTP selecionado. Na URL, isso significa que caracteres não alfanuméricos são codificado por porcentagem e as quebras de linha são passadas como pares "CR LF" (%0D%0A). Se o usuário optar por enviar várias linhas de texto em uma seleção, o serviço Web deverá ser capaz de tratar o "CR LF" adequadamente.

observação de segurança Alerta de Segurança Os serviços Web que aceitam HTML como entrada devem ser configurados corretamente para tratar a entrada HTML arbitrária. Os serviços Web que permitem entrada arbitrária sem filtragem ou codificação são suscetíveis a ataques de injeção de HTML/script.

Se você criar um Acelerador que use um parâmetro {selection} do tipo html, verifique se o serviço Web está configurado para interpretá-lo corretamente. Analise o seguinte serviço, que ingenuamente aceita texto da cadeia de caracteres de consulta da URL e o coloca direto no atributo value de um input de texto usando ASP (Active Server Pages):

<input name="txtQueryString" size="60" maxlength="65000" value="<%=Request.QueryString("q")%>" />

Neste caso, se o serviço aceitasse o HTML do Acelerador, o texto de entrada poderia fechar prematuramente a marca de entrada e regravar partes da página da Web. Pior ainda, instruções SQL ou scripts mal-intencionados injetados dessa maneira poderiam ser executados no contexto do domínio que hospeda o site. Para ler mais sobre como validar a entrada para proteger seu aplicativo de ataques de injeção, consulte Como proteger-se contra ataques de injeção no ASP.NET (a página pode estar em inglês). Consulte também a discussão sobre injeção de scripts no lado do cliente usando innerHTML.

Implicações de segurança de variáveis de documento

Como as variáveis de documento poderiam ser usadas para rastrear usuários sem seu conhecimento, essas variáveis não podem ser usadas em determinados contextos.

As variáveis de documento não podem ser usadas por um Acelerador de visualização, exceto no contexto do documento.
A transmissão de variáveis de documento é proibida entre os protocolos HTTP e HTTPS, e de uma zona de segurança de menor restrição para uma de restrição mais alta, como de uma página na zona de intranet para um servidor na Internet.

Se uma variável de documento obrigatória não estiver disponível por qualquer motivo, a entrada do Acelerador no menu de atalho estará esmaecida.

Visualização

Um Acelerador pode oferecer uma visualização HTML opcional que seja exibida quando o usuário passar o cursor do mouse sobre um Acelerador no menu. As visualizações são úteis para a obtenção rápida de mapa, definição ou tradução in-loco, classificações de conteúdo ou links para conteúdo relacionado.

A janela de visualização deve ser usada para interação leve. Ela pode conter links que enviam o usuário a uma página da Web completa para obter mais informações. A visualização não impede o usuário de clicar no item de menu Acelerador.

A funcionalidade de visualização é expressa no arquivo de Acelerador OpenService pelo elemento os:preview. Quando o usuário passa o cursor do mouse sobre o item de menu, o Internet Explorer faz uma solicitação HTTP e exibe o HTML resultante na janela de visualização HTML.

Tamanho

A janela de visualização é limitada a 320 de largura e 240 de altura em uma tela de 96 dpi (pontos por polegada). Todo o conteúdo fora da região é cortado. Não é recomendável inserir conteúdo que exiba controles com barras de rolagem. O objetivo da funcionalidade de visualização é que o usuário veja rapidamente as informações sem muita interação.

Conteúdo

A visualização limita recursos do script ao mesmo domínio que o os:homepageUrl do Acelerador. Ela também dará suporte a controles Microsoft ActiveX se eles já tiverem sido instalados pelo usuário para o domínio.

Navegação

O usuário pode navegar na janela de visualização usando links. Para enviar o usuário a uma página da Web completa, defina o link para ser aberto em uma nova janela. Isso pode ser feito de duas maneiras:

Defina o atributo target para ser "_blank" como parte do hiperlink. Quando invocado pelo usuário, o navegador abrirá isto como uma nova guia.
```
<a href="gotosite.html" target="_blank">view full site</A>  
```

Use o método open e defina a URL de entrada como o site para o qual você deseja que o usuário navegue.

<FORM>
<INPUT type="button" value="View Full Site"
onClick="window.open(gotosite.html')" />
</FORM>

Localização

Um arquivo de Acelerador OpenService pode dar suporte a uma única localidade. Se o serviço der suporte a várias localidades, será necessário um arquivo XML separado para cada idioma. Além de usar texto adequado à localidade para os:name e os:description, o valor do atributo category também deve ser localizado no idioma do usuário. A página da Web que anuncia estes Aceleradores deve usar o cabeçalho accept-language da solicitação para determinar e exibir o arquivo XML correto para o usuário instalar.

Exemplo em inglês

<?xml version="1.0" encoding="UTF-8"?>
<os:openServiceDescription
    xmlns:os="https://www.microsoft.com/schemas/openservicedescription/1.0">
    <os:homepageUrl>http://maps.yahoo.com</os:homepageUrl>
    <os:display>
        <os:name>Map with Yahoo!</os:name>
    </os:display>
    <os:activity category="Map">
    ...
</os:openServiceDescription>

Exemplo em espanhol

<?xml version="1.0" encoding="UTF-8"?>
<os:openServiceDescription
    xmlns:os="https://www.microsoft.com/schemas/openservicedescription/1.0">
    <os:homepageUrl>http://maps.yahoo.com</os:homepageUrl>
    <os:display>
        <os:name>Mapa con Yahoo!</os:name>
    </os:display>
    <os:activity category="Mapa">
    ...
</os:openServiceDescription>

Se um usuário tiver Aceleradores de várias localidades instalados, cada um deles será exibido.

Instalação

O Internet Explorer 8 instala Aceleradores por meio da página da Web Guia de Serviços. Os sites também podem promover seus próprios Aceleradores.

A primeira etapa é publicar o arquivo XML do Acelerador OpenService em um servidor Web. Instalar um arquivo XML de Acelerador do sistema local não é permitido; porém, para fins de teste, você pode usar o localhost do Servidor de Informações da Internet da Microsoft (IIS) ou o servidor ASP.NET do Microsoft Visual Studio.

Em seguida, adicione um botão Acelerador de Instalação que chame o AddService quando clicado.

<button id="myButton"
    onclick="window.external.AddService('http://www.example.com/activity.xml')">
    Add MyMap to the shortcut menu in Internet Explorer 8</button>

É possível verificar se o usuário tem o Acelerador instalado chamando IsServiceInstalled. Para executar essa verificação, o domínio da página da Web deve corresponder ao domínio do os:homepageUrl especificado no arquivo de Acelerador OpenService.

window.onload = function() {
    if (window.external.IsServiceInstalled('http://www.example.com','map')) {
        document.getElementById('myButton').disabled = true;
    }
}

Se o valor de retorno for 0, o Acelerador não será instalado.

Formato de Acelerador OpenService

Esta seção explica os elementos, atributos e valores do formato de arquivo de Acelerador OpenService.

Exemplo

O Acelerador baseado em XML a seguir descreve a interação entre o navegador e um serviço de mapeamento.

<?xml version="1.0" encoding="UTF-8"?>
<os:openServiceDescription
    xmlns:os="https://www.microsoft.com/schemas/openservicedescription/1.0">
    <os:homepageUrl>http://maps.example.com</os:homepageUrl>
    <os:display>
        <os:name>Map with MyMap</os:name>
        <os:icon>http://www.example.com/favicon.ico</os:icon>
        <os:description>Map addresses easily with MyMap.</os:description>
    </os:display>
    <os:activity category="Map">
        <os:activityAction context="selection">
            <os:preview action="http://maps.example.com/preview.php?addr={selection}" />
            <os:execute action="http://maps.example.com/" method="get">
                <os:parameter name="addr" value="{selection}" type="text" /> 
            </os:execute>
        </os:activityAction>
    </os:activity>
</os:openServiceDescription>

os:openServiceDescription

<os:openServiceDescription
    xmlns:os="https://www.microsoft.com/schemas/openservicedescription/1.0">

O elemento raiz do arquivo de Acelerador OpenService é os:openServiceDescription. O atributo xmlns é obrigatório e deve ser https://www.microsoft.com/schemas/openservicedescription/1.0.

os:homepageUrl

<os:homepageUrl>http://maps.example.com</os:homepageUrl>

Obrigatório. O elemento os:homepageUrl define a URL principal do Accelerator—onde o usuário pode acessar o serviço por meio de navegação. Todas as URLs declaradas no arquivo de Acelerador OpenService devem usar o mesmo domínio que o os:homepageUrl.

os:display

<os:display>

Obrigatório. O elemento os:display descreve como o Acelerador é apresentado ao usuário. Ele contém os elementos os:name e os:icon.

os:name

<os:name>Map with MyMap</os:name>

Obrigatório. O os:name do Acelerador que é exibido para o usuário no menu de contexto. Os nomes de Aceleradores devem começar com um verbo seguido do provedor de serviços. Por exemplo, "Mapear no Windows Live" ou "Definir com a Encarta".

os:icon

<os:icon>http://www.example.com/favicon.ico</os:icon>

Opcional. O elemento os:icon fornece uma URL para um ícone de 16 x 16 pixels para este Acelerador. O nome de domínio usado deve corresponder a os:homepageUrl.

os:description

<os:description>Map addresses easily with MyMap.</os:description>

Opcional. O elemento os:description fornece uma descrição mais longa para o Acelerador que é exibido na caixa de diálogo Gerenciar Complementos.

os:activity

<os:activity category="Map">

Obrigatório. O elemento os:activity contém toda a funcionalidade de um Acelerador.

Cada os:activity deve especificar um atributo category para descrever o tipo de funcionalidade que oferece. Os Aceleradores são organizados por categoria no menu de contexto do navegador, assim os usuários podem acessar rapidamente o tipo de operação desejado. Os usuários podem selecionar o Acelerador padrão para uma determinada categoria quando o Acelerador é instalado ou usando a caixa de diálogo Gerenciar Complementos. Os Aceleradores padrão são apresentados no menu de contexto do navegador, e todos os outros são listados em um submenu. Consulte a seção Categorias para obter mais informações.

os:activityAction

<os:activityAction context="selection">

Obrigatório. Cada os:activityAction especifica a interação com o provedor de serviços com base no destino do Acelerador. O atributo context opcional especifica o destino. O padrão é selection.

Contexto	Descrição
document	O documento atual. Sempre disponível.
selection	Padrão. O texto selecionado. O Acelerador só fica disponível quando se clica em uma região selecionada.
link	Um hiperlink. O Acelerador está disponível apenas para links.

os:preview

<os:preview action="http://maps.example.com/preview.php?addr={selection}" />

Opcional. O elemento os:preview define o conteúdo da janela HTML exibido quando o usuário passa o cursor do mouse sobre o Acelerador. Ele compartilha os mesmos atributos e elementos filho que o elemento os:execute. Leia a seção Visualização para obter mais detalhes.

A URL do atributo action pode conter nomes de variáveis que são substituídos quando o comando é executado. Para obter mais informações, consulte a seção sobre Variáveis.

os:execute

<os:execute action="http://maps.example.com/" method="get">

Obrigatório. O elemento os:execute especifica a ação principal disparada quando o usuário invoca o Acelerador. Assim como os:preview, ele pode conter variáveis de substituição no atributo action ou como elementos os:parameter separados.

Os seguintes atributos são definidos para os:execute e os:preview:

Atributo	Obrigatório?	Descrição
action	Sim	O modelo de URL a ser usado para o envio HTTP.
method	Não	O tipo de método HTTP a ser usado (get, post). O padrão é `get`.
enctype	Não	O tipo de conteúdo que é enviado ao servidor. O padrão é `application/x-www-form-urlencoded`.
accept-charset	Não	O conjunto de caracteres usado para o envio. O padrão é `utf-8`.

os:parameter

<os:parameter name="addr" value="{selection}" type="text" />

Opcional. O elemento os:parameter fornece um modo alternativo de expressar os valores a serem usados. Os atributos name e value obrigatórios definem entradas de cadeia de caracteres específicas ao serviço e normalmente se referem a variáveis de Acelerador. Consulte a seção Variáveis para obter uma lista.

O atributo type opcional é usado para transformar a variável {selection} em HTML ou texto sem formatação. O padrão é text.

Tópicos relacionados

Adicionar provedores de Aceleradores ao Internet Explorer 8 (a página pode estar em inglês)

Compartilhar via