Revision [20190]
This is an old revision of OpenSearchForWikka made by JavaWoman on 2008-09-04 11:50:41.
OpenSearch for Wikka
What is OpenSearch?
At its simplest, OpenSearch is an open specification that allows search engines to publish what the (HTTP) interface to their engine looks like, and search clients to use that specification to provide a compatible user interface to that search engine. Search engines may also use the specification to tell what the license for their search results is: an open license would allow search clients to create a single interface to multiple open-license search engines, much like today's "meta" search engines.All the search engine needs to do is publish a description file in XML format that specifies its interface; and to enable autodiscovery it can link to this description file via a <link> tag in the <head> section of its website. Any application that supports OpenSearch can thus find this description file, and use it to create an interface to using that search engine without requiring the end user to go to the search engine's website. (It gets better: since the description format is so simple, you could actually create your own description files for search engines that don't publish one, or create one for a customized search. )
A search client application can be a desktop application (like a browser: both Internet Explorer 7+ and Firefox 2+ support it) but it can also be a web-based application. An application needs to download the XML description file, and interpret it to provide a search interface for the search engine it belongs to.
For a more detailed description, see OpenSearch.
Who uses OpenSearch?
Even though the OpenSearch specification is officially still a draft (but quite stable), it is already widely supported.Search engines
Did you notice how two in that list are applications that the Wikka Wiki project itself is using? We use WordPress for our blog, and Trac for our issue tracking. And did you notice there's a wiki site in that list? Wikipedia is a major one, but not the only one.
Many major search engines already support OpenSearch: Amazon, of course, since they are the inventor, but also Yahoo!, Google, and may more. But any website or web publishing software that provides its own search function can be a search provider for OpenSearch as well. Notable examples are WikiPedia (in all languages), WordPress, Trac, Youtube, and Mozilla Add-ons.More OpenSearch providers can be found here (just a start):
- OpenSearch search engine directories (a list of lists)
- Tredosoft's list of search providers (don't be confused by the reference to IE7: it works equally well with Firefox!)
- Firefox Search Tools add-ons (although Firefox calls it "plugins", if you download from a link, what you get is the actual XML description file for the search engine: a nice way to study description files!)
Search clients
As I've already hinted, Both Internet Explorer 7 (and later) and Firefox 2 (and later) support OpenSearch, allowing you to add extra search engines to the list of engines you can use. (It seems that the Google Chrome browser (just in beta) also supports it, without explicitly mentioning it.)There are also web-based search aggregation sites. For details, see: OpenSearch search clients.
Enter Wikka
As you may have gathered by now, although the OpenSearch specification allows many variations, if you have a website that provides search functionality, it is actually very easy to enable that for OpenSearch. In fact, any Wikka installation can be an OpenSearch search provider - all it takes is two steps:- Create and upload an XML description file
- Enable autodiscovery with two simple additions to the <head> section
Ready? Let's go!
Create a description file
You can read the details of the syntax of the description file here:
First, a little preparation:
- This is possibly the hardest part of the exercise: You need to decide how your search function(s) will be known to the world, and you have only 16 or fewer characters of plain text available. That "ShortName" is what your search will be known by in the dropdown search menu of a supporting browser (unless you also provide a LongName, so make sure it is distinctive. If you want to support both the plain text search and the expanded text search you can, but your choice of "ShortName" becomes even harder!
- While the ShortName" element is required, you can also provide an optional LongName, for which you have //48 or fewer characters of plain text// available. It seems that Firefox will use the ShortName, even if a LongName is provided, in the search dropdown (I don't know how IE7 is handling this since I don't have access to it.)
~1) Optional: A description is also possible: up to 1024 plaintext characters - no markup!
~1) Optional: A Contact email; you could use your admin email address, but remember that it will be visible in cleartext. If you are not comfortable with that, create a special throw-away address for the purpose, or just do not provide a contact
~1) An icon would be nice, although it is not strictly necessary. Two formats are recommended (you can provide both):
~~- A 16x16 small icon - this can be type "image/x-icon" or "image/vnd.microsoft.icon" (the [[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwui/html/msdn_icons.asp Microsoft ICON format]]);
~~- A 64x64 image of type "image/jpeg" or "image/png"
~ If you already have a favicon for your site, you can simply use that, or you can create a special "search" variant if you like; if you create a special one, just upload it to you ##images## directory.
~1) The default "input format" for OpenSearch is UTF-8; if you've set up your site to use UTF-8, you won't need to specify anything, but the default for Wikka is ISO-8859-1, which you would need to specify.
~1) Finally, decide on a location for your XML description file. In a short discussion with DarTar on the [[TheLounge #wikka]] IRC channel, we agreed that ##libs/opensearch## would be a good location: while it is not a library in the sense of a set of routines in a programming language, you can provide a library if search description files here.
~1) For the autodiscovery you can provide a longer description in a title attribute, that describes what an end user would be adding to their browser. Just remember that once a search interface has been added, that description is no longer available: the ShortName (or LongName if provided) **must** be able to stand on its own, and not be confusable with other searches someone may have added!
After that preparation, you're ready to create your XML description file. First, grab the following template:
%%(xml;1;TextSearch.xml)
[[your ShortName]] [[**your LongName]] [[a description, up to 1024 characters of plain text, no markup]] [[**your Contact email]] [[**path to a 64x64 image [[**path to a 16x16 icon]] open en-us [[**encoding if not UTF-8]] [[**encoding if not UTF-8]]
- Image: you can have zero, one or two of these; fill in the (relative or absolute) path to the image(s) you prepared, and make sure the type attribute matches your image (see the type descriptions above)
- Query: this is optional, but can provide a search client with a way to test your search engine; "page" is a good search term to use as it will provide a result even on a fresh Wikka install
- SyndicationRight: optional, possible values are open|limited|private|closed; the default is "open". You'll probably want to use "open" (in which case you can leave out the whole line), but see the documentation for the precise semantics
- Language: optional, one element for each language that your search engine supports (in RFC 3066 format); the default is "*" for "any language"
- InputEncoding: optional, must match the character set your site is encoded in (ISO-8859-1 for a standard Wikka install); default is UTF-8
- OutputEncoding: optional, must match the character set your site is encoded in (ISO-8859-1 for a standard Wikka install); default is UTF-8
