>> ~- [[http://wikkawiki.org/OpenSearchForWikka#hn_What_is_OpenSearch | What is OpenSearch?]] ~- [[http://wikkawiki.org/OpenSearchForWikka#hn_Who_uses_OpenSearch | Who uses OpenSearch?]] ~~- [[http://wikkawiki.org/OpenSearchForWikka#hn_Search_engines | Search engines]] ~~- [[http://wikkawiki.org/OpenSearchForWikka#hn_Search_clients | Search clients]] ~- [[http://wikkawiki.org/OpenSearchForWikka#hn_Enter_Wikka | Enter Wikka]] ~~- [[http://wikkawiki.org/OpenSearchForWikka#hn_Create_a_description_file | Create a description file]] ~~- [[http://wikkawiki.org/OpenSearchForWikka#hn_Provide_for_autodiscovery | Provide for autodiscovery]] ~- [[http://wikkawiki.org/OpenSearchForWikka#hn_Over_to_the_browser | Over to the browser]] >>=====""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 and retrieve the results. Or, According to the ""OpenSearch.org"" official website: ~''**""OpenSearch"" is a collection of simple formats for the sharing of search results.**'' 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. >>See also... ==From the horse's mouth:== ~- [[http://www.opensearch.org/Home | OpenSearch]] ~- [[http://www.opensearch.org/Specifications/OpenSearch/1.1 | OpenSearch 1.1 current draft]] ~- [[http://www.opensearch.org/Community/OpenSearch_search_clients | OpenSearch search clients]] ~- [[http://www.opensearch.org/Community/OpenSearch_search_engine_directories | OpenSearch search engine directories]] ~- [[http://www.opensearch.org/Community/OpenSearch_software | OpenSearch software]] ==Elsewhere:== ~- [[http://en.wikipedia.org/wiki/Opensearch | Wikipedia's page on OpenSearch]] ~- [[http://15seconds.com/issue/071109.htm | 15 Seconds: An Introduction to OpenSearch]] >>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 #### tag in the ##
## 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//. A **search client** application can be a desktop application (such as a browser: both Internet Explorer 7+ and [[http://wikkawiki.org/OpenSearchForWikka#hn_Footnotes | Firefox 2+]] ""1)"" 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 [[http://www.opensearch.org/Home | 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 [[http://blog.wikkawiki.org/ | blog]], and **[[http://wush.net/trac/wikka/ | Trac]]** for our issue tracking. And did you notice there's a wiki site in that list? Wikipedia is a major one (Mediawiki has a plugin for that), but not the only one. For more see [[http://www.opensearch.org/Community/OpenSearch_software | OpenSearch software]]. >>Many major search engines already support ""OpenSearch"": [[http://amazon.com/ | 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 [[http://wikipedia.org/ | WikiPedia]] (in all languages), [[http://wordpress.org/ | WordPress]] (via a [[http://www.williamsburger.com/wb/archives/opensearch-v-1-1 | plugin]]), [[http://trac.edgewall.org/ | Trac]], [[http://www.youtube.com/ | Youtube]], and [[https://addons.mozilla.org/ | Mozilla Add-ons]]. More ""OpenSearch"" providers can be found here (just a start): ~- [[http://www.opensearch.org/Community/OpenSearch_search_engine_directories | OpenSearch search engine directories]] (a list of lists) ~- [[http://tredosoft.com/internet_explorer_7_search_providers | Tredosoft's list of search providers]] (don't be confused by the reference to IE7: it works equally well with Firefox!) ~- [[https://addons.mozilla.org/en-US/firefox/browse/type:4/cat:all?sort=name | 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, several browsers have built-in support for ""OpenSearch"" and autodiscovery, allowing you to add extra search engines to the list of engines you can use: ~- **Firefox 3** (see [[http://wikkawiki.org/OpenSearchForWikka#hn_Footnotes | the footnotes]] ""1)""); there is also a [[https://addons.mozilla.org/en-US/seamonkey/addon/552 | plugin]] that works with **Firefox 1.0-3.0** as well as **Seamonkey** ~- **Internet Explorer 7** (and later - see [[http://wikkawiki.org/OpenSearchForWikka#hn_Footnotes | the footnotes]] ""2)"") ~- **Camino** ([[http://caminobrowser.org/features/ | since version 1.6]]) ~- it also //seems// that the Google **Chrome** browser (just in beta) also supports it, (it will actually //automatically// add a search engine once you've used it - which provides the user with rather less control than the other browsers do; it's possible it uses autodiscovery for this, without explicitly mentioning it) There are also web-based search aggregation sites. For details, see: [[http://www.opensearch.org/Community/OpenSearch_search_clients | 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"". While the usual format of an OpenSearch result is a feed (Atom or RSS), the specification also provides for search results in the form of HTML pages - and that's exactly what Wikka already does in its search functionality. This means that **any Wikka installation can be an ""OpenSearch"" search provider** - all it takes is two steps: ~1) Create and upload an XML description file ~2) Enable autodiscovery with two simple additions to the #### section You do not even need to edit any scripts! Ready? Let's go! ===Create a description file=== >> You can read the details of the syntax of the description file here: ~- [[http://www.opensearch.org/Specifications/OpenSearch/1.1#OpenSearch_description_document | OpenSearch description document]] ~- [[http://www.opensearch.org/Specifications/OpenSearch/1.1#OpenSearch_URL_template_syntax | OpenSearch URL template syntax]]>>First, a little preparation: ~1) 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! ~1) You also need a description of your search engine: up to 1024 plaintext characters - no markup allowed! ~1) 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 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]]); ~~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. ~~- A 64x64 image of type "image/jpeg" or "image/png" ~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, as well as any other encoding. ~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 should provide a description in the title attribute, that describes what an end user would be adding to their browser. Although this isn't part of the specification, the content of this title attribute should actually **match** the ""ShortName"": browser implementations of autodiscovery will compare the text of the title attribute to the ""ShortName"" of already-installed search engines: if there is no match, the browser will still offer to add it, even if it has been added already. (That is because it cannot be detected until the description file has been loaded - for autodiscovery a browser only looks at the #### tag itself.) After that preparation, you're ready to create your XML description file. First, grab the following template: **search description template** %%(xml;1)