Ta strona używa ciasteczek (cookies), dzięki którym nasz serwis może działać lepiej. Dowiedz się więcej OK, rozumiem
WebHelp.pl Warsztat Artykuły Plugin wyszukiwarki

Warsztat / Artykuły i tutoriale

Plugin wyszukiwarki

Rafał Kukawski 7 czerwca 2011 komentarze ()

Odwiedzając niektóre witryny można zauważyć, że Firefox proponuje integrację z wyszukiwarką danej strony. Jeśli masz własną stronę, na której dostępna jest wyszukiwarka, poznasz jak stworzyć odpowiednią wtyczkę dla przeglądarek bazujących na specyfikacji OpenSearch.

Przykład wykrycia wtyczki wyszukiwania na stronie WWW

Stworzenie wtyczki wyszukiwania jest bardzo proste, ponieważ wystarczy nam edytor tekstowy, w którym przygotujemy plik XML o strukturze zdefiniowanej w specyfikacji OpenSearch. OpenSearch obsługiwany jest między innymi przez Firefoksa (od wersji 2 wzwyż) i Internet Explorera (od wersji 7 wzwyż).

Struktura pliku

Minimalny plik wtyczki wyszukiwania (dla działu JavaScript na forum Webhelp) prezentuje się następująco.

Kod: Zaznacz cały
<?xml version="1.0" encoding="UTF-8"?>
<OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/">
    <ShortName>WH | JavaScript</ShortName>
    <Description>Przeszukaj dział JavaScript na Webhelpie</Description>
    <Url type="text/html" template="http://forum.webhelp.pl/search.php?keywords={searchTerms}&amp;terms=all&amp;fid[]=25"/>
</OpenSearchDescription>

Głównym elementem dokumentu jest znacznik OpenSearchDescription wraz z odpowiednią przestrzenią nazw (atrybut xmlns). Wewnątrz głównego znacznika musi się pojawić ShortName stanowiący nazwę, która pozwoli użytkownikowi zidentyfikować wyszukiwarkę. Maksymalna wartość to 16 znaków czystego tekstu.

Kolejnym obowiązkowym elementem jest opis (znacznik Description), który powinien zawierać nie więcej niż 1024 znaki tekstu, także bez zagnieżdżonych znaczników.

Bardzo ważnym, a zarazem obowiązkowym elementem jest Url, w którym definiujemy szczegóły API naszej wyszukiwarki. API wyszukiwarki opisujemy w atrybucie template, w którym podajemy URLa, którego aplikacja ma odpytać. Specyfikacja OpenSearch opisuje zestaw pre-definiowanych zmiennych, które aplikacja obsługująca specyfikację powinna rozpoznawać i podmieniać wartościami. Na razie skupimy się na zmiennej searchTerms, która stanowi frazę którą chcemy użyć w wyszukiwaniu (w przeglądarkach jest to tekst wpisany przez użytkownika w pole wyszukiwania).

Dodatkowe elementy

Wtyczkę wyszukiwarki można rozszerzyć o dodatkowe elementy. Jest ich wiele, dlatego skupimy się na tych najbardziej przydatnych.

Przykładowo w znaczniku Contact można podać E-Mail kontaktowy, pod którym dostępna jest osoba zarządzająca wtyczką.

Kod: Zaznacz cały
<Contact>rafael@webhelp.pl</Contact>

zaś sam autor wtyczki może wyróżnić siebie w specjalnym znaczniku Developer, przy czym musi pamiętać o ograniczeniu do 48 znaków czystego tekstu.

Kod: Zaznacz cały
<Developer>Rafał Kukawski</Developer>

Plugin wyszukiwarki może zawierać też tagi. Zadaniem tagów jest opisanie kategorii dostarczanych wyników wyszukiwania. Służy do tego znacznik Tags, w którym wymieniamy wszystkie tagi odzielając je spacją. Separator w postaci spacji narzuca ograniczenie mówiące, że tagi mogą stanowić tylko pojedyncze wyrazy. Maksymalnie 256 znaków na cały zestaw tagów.

Kod: Zaznacz cały
<Tags>forum webhelp javascript</Tags>

Wtyczka może obok krótkiej nazwy posiadać jej dłuższą wersję. Służy do tego znacznik LongName, który może zawierać tekst (bez HTMLa) o długości maksimum 48 znaków.

Programy korzystające z wtyczki są zobligowane do korzystania z ShortName jeśli LongName jest nieobecny. Z tego powodu należy się raczej powstrzymać ze zbyt długimi nazwami, ze względu na zwykle ograniczoną ilość miejsca na nazwę w interfejsie programu, co może skutkować ucinaniem nazwy po kilkunastu znakach.

Kod: Zaznacz cały
<LongName>Dział JavaScript na forum Webhelp</LongName>

Z wyszukiwarką można powiązać też ikonę, którą zdefiniujemy w znaczniku Image.

Kod: Zaznacz cały
<Image width="16" height="16" type="image/x-icon">http://webhelp.pl/favicon.ico</Image>

Wszystkie atrybuty obrazu są opcjonalne.

Można wstawić więcej niż jedną ikonę, przykładowo ikony różnych rozmiarów. W takiej sytuacji aplikacja korzystająca z wtyczki powinna wybrać najbardziej pasujący do interfejsu rozmiar. Zaleca się tworzenie kwadratowych ikon, w rozmiarach 16x16 (preferowany typ to plik ikony. Wtedy w atrybucie type wpisujemy image/x-icon lub image/vnd.microsoft.icon) oraz 64x64 o typie PNG (image/png) lub JPG (image/jpeg).

Kod: Zaznacz cały
<Image width="16" height="16" type="image/x-icon">http://webhelp.pl/favicon.ico</Image>
<Image width="32" height="32" type="image/png">http://webhelp.pl/favicon.png</Image>
<Image width="64" height="64" type="image/png">http://webhelp.pl/favicon64.png</Image>

Firefox deklaruje się, że będzie cacheował wspomniane ikony. Istnieje jednak możliwość zapisu danych ikon bezpośrednio w pliku wtyczki, stosując Data URI Scheme. W ten sposób pozbywamy się dodatkowego żądania HTTP.

Kod: Zaznacz cały
<Image width="16" height="16" type="image/x-icon">data:image/x-icon;base64,AAABAAEAEBAAAAEACABoBQAAFgAAACgAAAAQAAAAIAAAAAEACAAAAAAAAAEAAAAAAAAAAAAAAAEAAAAAAADd1HcA////ANDERADy78wAw7QRAOXfmQDFtxgA2c9mAPv67gDu6rsAv68AAOHaiADGtxsA1MpVAMi6IgDv68AA7ei3AM3ANgD29N0Ax7geAOrkqgAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAEAYKCgoKCgoKCgoKCgoGEAwKCgoKCgoKCgoKCgoKCgwKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKChQSCgMJCgoBAAABCgoKCgoIAQ4BAQoKAQAAAQoKCgoOARILCAgCCgEAAAEKCgoKBwELCAkDAAoBAAABCgoKChQDDQELBQkKAQkJCAoKCgoSFAQBAgABCgESAQcKCgoKCgoKCgoKCgoBAAoKCgoKCgoKCgoKCgoKAQAKCgoKCgoKCgoKCgoKCgEACgoKCgoKCgoKCgoKCgoKCgoKCgoTCgoKCgoKCgoKCgoKCgoGDxEKCgoKCgoKCgoKCgoRDwAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=</Image>

Aby zakodować sobie obraz w base64 wystarczy skorzystać z poniższego skryptu PHP.

Kod: Zaznacz cały
<?php
echo base64_encode(file_get_contents($plik_obrazu));
?>

kompletny URI można uzyskać stosując poniższy skrypt Basha lub Pythonowy

Kod: Zaznacz cały
#!/usr/bin/env bash

# Dzięki dla Tomasza Elendta za skrypt
echo "data:$(file -b --mime-type $1);base64,$(base64 -w0 $1)"
Kod: Zaznacz cały
#!/usr/bin/env python

import sys
import mimetypes
import base64

try:
   fileName = sys.argv[1]
   f = open(fileName, 'r')
   
   mime = mimetypes.guess_type(fileName)[0]
   
   if mime is not None:
       encoded = base64.b64encode(f.read())
       
       print 'data:%s;base64,%s' % (mime, encoded)
   else:
       sys.stderr.write('Unknown mime type')
       sys.exit(3)
   f.close()
except IndexError:
   sys.stderr.write('Not enough arguments')
   sys.exit(1)
except IOError:
   sys.stderr.write('File does not exist')
   sys.exit(2)

W kodzie wtyczki wyszukiwania można wstawić znaczniki Query, które mogą zawierać dane niezbędne do wykonania żądania. Zaleca się wstawienie przynajmniej jednego elementu Query z rolą example, który aplikacja może wykorzystać do sprawdzenia działania wtyczki.

Kod: Zaznacz cały
<Query role="example" searchTerms="ajax" />

Aplikacje klienckie mogą obsługiwać specyficzne dla siebie role.

Na koniec wymienię znaczniki InputEncoding oraz OutputEncoding, w których wskazujemy na kodowania znaków obsługiwane przez wyszukiwarkę na stronie oraz zestaw znaków w jakim kodowane będą wyniki wyszukiwania.

Kod: Zaznacz cały
<InputEncoding>UTF-8</InputEncoding>
<OutputEncoding>UTF-8</OutputEncoding>

Znaczniki te mogą występować więcej niż raz, definiując w ten sposób listę akceptowanych przez wyszukiwarkę kodowań. Domyślnym kodowaniem w obydwu przypadkach jest UTF-8.

Aplikacja kliencka może poinformować wyszukiwarkę o preferowanym kodowaniu poprzez URL żądania.

Znacznik Language informuje aplikację kliencką o obsługiwanych przez wyszukiwarkę językach.

Kod: Zaznacz cały
<Language>pl-PL</Language>
<Language>en-EN</Language>
<Language>de</Language>

Domyślną wartością jest *, która oznacza, że wyszukiwarka nie ogranicza się do któregokolwiek języka.

Można też poinformować aplikację kliencką, że wyniki wyszukiwania mogą zawierać treści dla dorosłych. Domyślną wartością jest false.

Kod: Zaznacz cały
<AdultContent>true</AdultContent>

Ostatni ze znaczników, który omówimy, to SyndicationRight, który informuje aplikację kliencką o jej prawach w zarządzaniu wynikami wyszukiwania. Zdefiniowane są 4 przypadki

  1. open
    • aplikacja kliencka może wysłać żądanie o wyniki wyszukiwania
    • aplikacja kliencka może pokazać wyniki użytkownikowi końcowemu
    • aplikacja kliencka może przekazać wyniki dalej, do innych klientów wyszukiwania

  2. limited
    • aplikacja kliencka może wysłać żądanie o wyniki wyszukiwania
    • aplikacja kliencka może pokazać wyniki użytkownikowi końcowemu
    • aplikacja kliencka nie może przekazać wyników do innych klientów wyszukiwania

  3. private
    • aplikacja kliencka może wysłać żądanie o wyniki wyszukiwania
    • aplikacja kliencka nie może pokazać wyników użytkownikowi końcowemu
    • aplikacja kliencka nie może przekazać wyników do innych klientów wyszukiwania

  4. closed
    • aplikacja kliencja nie ma żadnych praw

Domyślną wartością jest open. Przykład użycia:

Kod: Zaznacz cały
<SyndicationRight>limited</SyndicationRight>

Informacja dla przeglądarki i użytkownika

Mamy gotową wtyczkę wyszukiwarki. Kolejnym etapem jest poinformowanie przeglądarki internetowej, że nasza strona takową oferuje.

W sekcji head strony wstawiamy poniższy fragment kodu.

Kod: Zaznacz cały
<link rel="search" type="application/opensearchdescription+xml" title="WH | JavaScript" href="http://example.com/sciezka/do/pliku/wtyczki.xml" />

Dodatkowo, w wybranych przeglądarkach możemy wstawić na stronę przycisk instalujący w przeglądarce użytkownika wtyczkę. Wystarczy dodać poniższy kod do strony.

Kod: Zaznacz cały
if (window.external && window.external.AddSearchProvider) {
    jQuery(function ($) {
        $('<button/>')
            .attr('type', 'button')
            .text('Dodaj wyszukiwarkę')
            .click(function () {
                window.external.AddSearchProvider('http://example.com/sciezka/do/pliku/wtyczki.xml');
                return false;
            })
            .appendTo('body'); // zamiast selektora 'body' zdefiniuj własny element gdzie przycisk ma się znaleźć
    });
}

Podsumowanie

Tyle tytułem wstępu. W późniejszym czasie zajmiemy się rozszerzeniami specyfikacji, obsługiwanymi przez niektóre przeglądarki. Między innymi opisany zostanie sposób dostarczania podpowiedzi do wyszukiwania.

Masz pytania lub wątpliwości? Odwiedź nasze forum dyskusyjne.

Rafał Kukawski

Programista, webmaster. Szczególnie upodobał sobie JavaScript i technologie klienckie, choć strona serwera i bazy danych nie stanowią tajemnicy. Tworzy też aplikacje na urządzenia mobilne. kukawski.pl.


Komentarze


HTML CSS JavaScript PHP bazy danych MySQL Flash grafika framework hosting domeny pozycjonowanie wordpress Facebook