Vyhledávání OpenSearch

Dokument popisující vyhledávání

Popis vyhledávání je tvořen jednoduchým XML dokumentem v MIME typu application/opensearchdescription+xml s následující strukturou:

<OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/">
    <ShortName>PHP triky</ShortName>
    <Description>Vyhledává frázi, % nahrazuje libovolný počet znaků</Description>
    <Url template="http://php.vrana.cz/atom.php?search={searchTerms}" type="application/atom+xml"/>
    <Url template="http://php.vrana.cz/hledat.php?search={searchTerms}" type="text/html"/>
    <Contact>vrana@php.net</Contact>
    <Tags>php weblog</Tags>
    <Image type="image/gif" width="150" height="100">http://php.vrana.cz/logo.gif</Image>
    <Image type="image/x-icon" width="16" height="16">http://php.vrana.cz/favicon.ico</Image>
    <Developer>Jakub Vrána</Developer>
    <Language>cs</Language>
</OpenSearchDescription>

Jednotlivé značky mají tento význam:

ShortName (povinné)

Maximálně 16znakový název vyhledávací služby

LongName

Maximálně 48znakový název vyhledávací služby

Description (povinné)

Maximálně 1024znakový popis vyhledávací služby

Url (povinné)

URL zajišťující vyhledávání s povinnými atributy template (bude vysvětleno dále) a type (MIME typ stránky s výsledky vyhledávání, tedy např. text/html nebo application/atom+xml) a nepovinnými indexOffset (číslo prvního výsledku vyhledávání, výchozí je 1) a pageOffset (číslo první stránky s výsledky vyhledávání, výchozí je 1)

Query

S atributem role="example" se používá pro příklad vyhledávání, vyhledávaný řetězec se uvádí do atributu searchTerms, obsah značky je prázdný

Tags

Maximálně 256 znaků dlouhý seznam značek oddělených mezerami

Image

Adresa obrázku charakterizujícího vyhledávání s nepovinnými atributy type (MIME typ obrázku, tedy např. image/x-icon nebo image/png), width a height (ikona s rozměry 16×16 se používá ve vyhledávacích polích prohlížečů, obrázek s rozměry 64×64 v agregátorech vyhledávání)

Contact

E-mailová adresa správce tohoto dokumentu

Developer

Maximálně 64 znaků dlouhé jméno správce tohoto dokumentu

Attribution

Maximálně 256 znaků dlouhé poděkování

SyndicationRight

Práva pro toto vyhledávání, možné hodnoty jsou open (výchozí), limited (výsledky vyhledávání se nesmí předávat dalším klientům), private (výsledky vyhledávání se nesmí zobrazovat uživatelům) nebo closed (klient nesmí toto vyhledávání používat)

AdultContent

Hodnoty false, FALSE, 0, no nebo NO vyjadřují nepřítomnost obsahu pouze pro dospělé (výchozí hodnota), jakákoliv jiná hodnota jeho přítomnost

Language

Umožňuje určit jazyk (např. cs), který toto vyhledávání podporuje (pokud vyhledávání podporuje více jazyků, uvede se tato značka víckrát), výchozí hodnota je * (vyhledávat lze v jakémkoliv jazyce)

InputEncoding

Určuje kódování, ve kterém má být předán dotaz, výchozí hodnota je UTF-8, značek může být uvedeno více

OutputEncoding

Určuje kódování, ve kterém jsou k dispozici výsledky, výchozí hodnota je UTF-8, značek může být uvedeno více

Maska pro vyhledávání

Maska pro vyhledávání se zadává do atributu Url template a ve své nejjednodušší podobě má tvar http://example.com/search?q={searchTerms}. Ve složených závorkách mohou být uvedeny tyto parametry:

searchTerms

Vyhledávací dotaz

count

Počet výsledků na jednu stránku požadovaný klientem

startIndex

Požadované pořadí prvního vráceného výsledku vyhledávání

startPage

Číslo požadované stránky

language

Jazyk, ve kterém má být vyhledávání provedeno, výchozí hodnota je  *

inputEncoding

Kódování dotazu

outputEncoding

Požadované kódování výsledků vyhledávání

Za parametry, které nejsou v našem vyhledávání povinné, lze přidat ?, což způsobí, že se v případě jejich neznámé hodnoty použije prázdný řetězec.

Výsledky vyhledávání

Stránka s výsledky vyhledávání odpovídá MIME typu určenému atributem Url type, může však být doplněna o tyto značky ze jmenného prostoru  http://a9.com/-/spec/opensearch/1.1/:

totalResults

Celkový počet nalezených výsledků, výchozí hodnota je pořadí posledního nalezeného záznamu na této stránce

startIndex

Pořadí prvního výsledku vyhledávání na této stránce, výchozí hodnota odpovídá atributu Url indexOffset

itemsPerPage

Počet výsledků na stránku, výchozí hodnota odpovídá skutečnému počtu výsledků na této stránce

Query

S atributem role="request" se používá pro uvedení dotazu, kterému výsledek vyhledávání odpovídá

V HTML dokumentech se místo samostatných značek používá značka <meta> ve formátu <meta name="startIndex" content"1">. Značka Query se v HTML dokumentech neuvádí.

Výchozí hodnoty jednotlivých značek zajišťují, že pokud prezentujeme všechny výsledky vyhledávání na jedné stránce, žádnou značku uvádět nemusíme.

Zveřejnění vyhledávání

O tom, že náš server podporuje vyhledávání ve formátu OpenSearch, můžeme dát prohlížeči a dalším službám vědět podobně jako o syndikačních formátech RSS a Atom. Dělá se to přidáním značky <link rel="search" type="application/opensearchdescription+xml" href="cesta k OpenSearch dokumentu" title="název vyhledávací služby"> do části <head> HTML dokumentu. Stejnou značku lze přidat i do syndikačního formátu Atom a při uvedení jmenného prostoru http://www.w3.org/2005/Atom i do RSS.

Tímto způsobem se o vyhledávání mohou automaticky dozvědět služby, které tento formát podporují a v závislosti na hodnotě značky SyndicationRight ho rovnou začít využívat. O existenci dokumentu OpenSearch můžeme dát vědět i explicitně, např. na mateřském A9.com je formulář pro přidání nového zdroje na adrese http://opense­arch.a9.com/new­Column.jsp. Validátor na tomto serveru kontroluje ve výsledcích vyhledávání přítomnost značek totalResults, startIndex a itemsPerPage, které jsou ale podle specifikace nepovinné.

Rozšíření

Formát OpenSearch je dále rozšiřitelný, v současné době jsou k dispozici 4 rozšíření: Referrer (umožňuje určit původ vyhledávání), Relevance (umožňuje určit relevanci výsledků), Parameter (umožňuje vyhledávat i pomocí jiných metod než GET a určit kódování přenášených dat, může se tedy hodit např. pro vyhledávání obrázků podobných zadanému) a Suggestions (umožňuje implementovat našeptávač).

Podpora v prohlížečích

Pokud uživatel prohlížeče Internet Explorer 7 zavítá na server podporující OpenSearch, prohlížeč tento server automaticky přidá do vyhledávacího pole. Uživatel potom server může uložit trvale. Prohlížeč podporuje i rozšíření Referrer (posílá IE-Address pro vyhledávání z adresního řádku nebo IE-SearchBox pro hledání z vyhledávacího políčka). Internet Explorer 7 podporuje výsledky v HTML i v syndikačních formátech.

V prohlížeči Firefox 2 se server ve vyhledávacím poli rovněž zobrazí, kromě toho lze server stejně jako v Internet Exploreru 7 také přidat explicitně pomocí JavaScriptového kódu window.external.AddSearchProvider('cesta k OpenSearch dokumentu'). Tento kód bude nejspíš nabízen ve formě běžného odkazu na stránce. Firefox 2 pracuje pouze s výsledky vyhledávání ve formátu HTML, syndikační formáty využít nedokáže. Prohlížeč podporuje i rozšíření Suggestions.

Prohlížeč Opera 9 formát OpenSearch zatím nepodporuje.

Závěr

Formát OpenSearch je implementačně velice jednoduchý (pro jednoduchou integraci do rozšířených systémů jsou navíc k dispozici knihovny) a uživatelům moderních prohlížečů může vyhledávání podstatně zpříjemnit, takže jeho nasazení není důvod odkládat.