Revision history for OpenSearchForWikka


Revision [23377]

Last edited on 2016-05-20 07:38:47 by NilsLindenberg [Replaces old-style internal links with new pipe-split links.]
Additions:
~- [[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]]
~- [[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]]
~- [[http://en.wikipedia.org/wiki/Opensearch | Wikipedia's page on OpenSearch]]
~- [[http://15seconds.com/issue/071109.htm | 15 Seconds: An Introduction to OpenSearch]]
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+]] ""<sup>1)</sup>"" 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]].
>>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]].
~- [[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!)
~- **Firefox 3** (see [[http://wikkawiki.org/OpenSearchForWikka#hn_Footnotes | the footnotes]] ""<sup>1)</sup>""); 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]] ""<sup>2)</sup>"")
~- **Camino** ([[http://caminobrowser.org/features/ | since version 1.6]])
There are also web-based search aggregation sites. For details, see: [[http://www.opensearch.org/Community/OpenSearch_search_clients | OpenSearch search clients]].
~- [[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:
~~- 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]]);
~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.
<ShortName>[[your | ShortName]]</ShortName>
<LongName>[[**your | LongName]]</LongName>
<Description>[[a | description, up to 1024 characters of plain text, no markup]]</Description>
<Contact>[[**your | Contact email]]</Contact>
template="[[your | base_url]]TextSearch[[separator ?|&]]phrase={searchTerms}"/>
<Image height="16" width="16" type="image/vnd.microsoft.icon">[[**path | to a 16x16 icon]]</Image>
<InputEncoding>[[**encoding | if not UTF-8]]</InputEncoding>
<OutputEncoding>[[**encoding | if not UTF-8]]</OutputEncoding>
This is conformant with the latest version of the specification, the [[http://www.opensearch.org/Specifications/OpenSearch/1.1 | OpenSearch 1.1 current draft]].
~- [[http://www.opensearch.org/Specifications/OpenSearch/1.1#The_.22OpenSearchDescription.22_element | OpenSearchDescription]] **required**: the root element
~- [[http://www.opensearch.org/Specifications/OpenSearch/1.1#The_.22ShortName.22_element | ShortName]] **required**: fill in your short name here
~- [[http://www.opensearch.org/Specifications/OpenSearch/1.1#The_.22LongName.22_element | LongName]] optional: if you don't have a long name, leave out this whole line
~- [[http://www.opensearch.org/Specifications/OpenSearch/1.1#The_.22Description.22_element | Description]] **required**: fill in your search engine description here
~- [[http://www.opensearch.org/Specifications/OpenSearch/1.1#The_.22Contact.22_element | Contact]] optional: your contact email, if you provide one; otherwise leave out the whole line
~- [[http://www.opensearch.org/Specifications/OpenSearch/1.1#The_.22Url.22_element | Url]] **required**: this is the template the search client will use to search your site. Fill in your base URL (the base_url value from your ##wikka.config.php## file. The next bit is """TextSearch""" for the basic search; if you want to provide an interface to the expanded search instead, use """TextSearchExpanded""". Then a separator: **##?##** if you use URL rewriting (##rewrite_mode## 1 in ##wikka.config.php##), **##&##** if you do not
~- [[http://www.opensearch.org/Specifications/OpenSearch/1.1#The_.22Image.22_element | Image]] optional: 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)
~- [[http://www.opensearch.org/Specifications/OpenSearch/1.1#The_.22Query.22_element | Query]] optional: this 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
~- [[http://www.opensearch.org/Specifications/OpenSearch/1.1#The_.22SyndicationRight.22_element | 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
~- [[http://www.opensearch.org/Specifications/OpenSearch/1.1#The_.22Language.22_element | Language]] optional: one element for each language that your search engine supports (in RFC 3066 format); the default is "*" for "any language"
~- [[http://www.opensearch.org/Specifications/OpenSearch/1.1#The_.22InputEncoding.22_element | InputEncoding]] optional: must match the character set your site is encoded in (ISO-8859-1 for a standard Wikka install); default is UTF-8
~- [[http://www.opensearch.org/Specifications/OpenSearch/1.1#The_.22OutputEncoding.22_element | OutputEncoding]] optional: must match the character set your site is encoded in (ISO-8859-1 for a standard Wikka install); default is UTF-8
<ShortName>[[your | ShortName]]</ShortName>
<Description>[[a | description, up to 1024 characters of plain text, no markup]]</Description>
template="[[your | base_url]]TextSearch[[separator ?|&]]phrase={searchTerms}"/>
Make sure that your title attribute matches the ""ShortName"" in your description file. Although the [[http://www.opensearch.org/Specifications/OpenSearch/1.1#Autodiscovery_in_HTML.2FXHTML | OpenSearch specification states]] only "The "title" attribute may contain a human-readable plain text string describing the search engine", in practice the strings should match so as not to confuse browsers (they compare the title attribute with the ""ShortName"" of already-installed search engines to decide whether of not to offer to install a new one).
~1) Actually, Firefox 2 did not really support the ""OpenSearch"" specification, but a [[http://developer.mozilla.org/En/Creating_MozSearch_plugins | proprietary variant]].
~~- While that document suggests that "the only difference is the root element and XML namespace" that is certainly not the case in comparison with the //current// ""OpenSearch"" 1.1 draft version. Also, [[http://developer.mozilla.org/en/Creating_OpenSearch_plugins_for_Firefox | Creating OpenSearch plugins for Firefox]] suggests that the **Param** elements they use are an ""OpenSearch"" extension, but the document they link to actually describes a **[[http://www.opensearch.org/Specifications/OpenSearch/Extensions/Parameter/1.0 | Parameter element]]** as an extension: there is no Param element in ""OpenSearch"".
~~- An extra complication is that adding these Mozilla-specific elements, attributes and namespace to an ""OpenSearch"" description (as illustrated on WikkaOpenSearch and the [[http://developer.mozilla.org/en/Creating_OpenSearch_plugins_for_Firefox | Mozilla documentation]]) will make it **[[http://developer.mozilla.org/Talk:en/Creating_OpenSearch_plugins_for_Firefox#What%27s_wrong_here.3f | no longer work with Internet Explorer]]**: the document is no longer conformant (and no longer "open")!
Deletions:
~- [[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]]
~- [[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]]
~- [[http://en.wikipedia.org/wiki/Opensearch Wikipedia's page on OpenSearch]]
~- [[http://15seconds.com/issue/071109.htm 15 Seconds: An Introduction to OpenSearch]]
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+]] ""<sup>1)</sup>"" 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]].
>>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]].
~- [[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!)
~- **Firefox 3** (see [[http://wikkawiki.org/OpenSearchForWikka#hn_Footnotes the footnotes]] ""<sup>1)</sup>""); 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]] ""<sup>2)</sup>"")
~- **Camino** ([[http://caminobrowser.org/features/ since version 1.6]])
There are also web-based search aggregation sites. For details, see: [[http://www.opensearch.org/Community/OpenSearch_search_clients OpenSearch search clients]].
~- [[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:
~~- 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]]);
~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.
<ShortName>[[your ShortName]]</ShortName>
<LongName>[[**your LongName]]</LongName>
<Description>[[a description, up to 1024 characters of plain text, no markup]]</Description>
<Contact>[[**your Contact email]]</Contact>
template="[[your base_url]]TextSearch[[separator ?|&]]phrase={searchTerms}"/>
<Image height="16" width="16" type="image/vnd.microsoft.icon">[[**path to a 16x16 icon]]</Image>
<InputEncoding>[[**encoding if not UTF-8]]</InputEncoding>
<OutputEncoding>[[**encoding if not UTF-8]]</OutputEncoding>
This is conformant with the latest version of the specification, the [[http://www.opensearch.org/Specifications/OpenSearch/1.1 OpenSearch 1.1 current draft]].
~- [[http://www.opensearch.org/Specifications/OpenSearch/1.1#The_.22OpenSearchDescription.22_element OpenSearchDescription]] **required**: the root element
~- [[http://www.opensearch.org/Specifications/OpenSearch/1.1#The_.22ShortName.22_element ShortName]] **required**: fill in your short name here
~- [[http://www.opensearch.org/Specifications/OpenSearch/1.1#The_.22LongName.22_element LongName]] optional: if you don't have a long name, leave out this whole line
~- [[http://www.opensearch.org/Specifications/OpenSearch/1.1#The_.22Description.22_element Description]] **required**: fill in your search engine description here
~- [[http://www.opensearch.org/Specifications/OpenSearch/1.1#The_.22Contact.22_element Contact]] optional: your contact email, if you provide one; otherwise leave out the whole line
~- [[http://www.opensearch.org/Specifications/OpenSearch/1.1#The_.22Url.22_element Url]] **required**: this is the template the search client will use to search your site. Fill in your base URL (the base_url value from your ##wikka.config.php## file. The next bit is """TextSearch""" for the basic search; if you want to provide an interface to the expanded search instead, use """TextSearchExpanded""". Then a separator: **##?##** if you use URL rewriting (##rewrite_mode## 1 in ##wikka.config.php##), **##&##** if you do not
~- [[http://www.opensearch.org/Specifications/OpenSearch/1.1#The_.22Image.22_element Image]] optional: 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)
~- [[http://www.opensearch.org/Specifications/OpenSearch/1.1#The_.22Query.22_element Query]] optional: this 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
~- [[http://www.opensearch.org/Specifications/OpenSearch/1.1#The_.22SyndicationRight.22_element 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
~- [[http://www.opensearch.org/Specifications/OpenSearch/1.1#The_.22Language.22_element Language]] optional: one element for each language that your search engine supports (in RFC 3066 format); the default is "*" for "any language"
~- [[http://www.opensearch.org/Specifications/OpenSearch/1.1#The_.22InputEncoding.22_element InputEncoding]] optional: must match the character set your site is encoded in (ISO-8859-1 for a standard Wikka install); default is UTF-8
~- [[http://www.opensearch.org/Specifications/OpenSearch/1.1#The_.22OutputEncoding.22_element OutputEncoding]] optional: must match the character set your site is encoded in (ISO-8859-1 for a standard Wikka install); default is UTF-8
<ShortName>[[your ShortName]]</ShortName>
<Description>[[a description, up to 1024 characters of plain text, no markup]]</Description>
template="[[your base_url]]TextSearch[[separator ?|&]]phrase={searchTerms}"/>
Make sure that your title attribute matches the ""ShortName"" in your description file. Although the [[http://www.opensearch.org/Specifications/OpenSearch/1.1#Autodiscovery_in_HTML.2FXHTML OpenSearch specification states]] only "The "title" attribute may contain a human-readable plain text string describing the search engine", in practice the strings should match so as not to confuse browsers (they compare the title attribute with the ""ShortName"" of already-installed search engines to decide whether of not to offer to install a new one).
~1) Actually, Firefox 2 did not really support the ""OpenSearch"" specification, but a [[http://developer.mozilla.org/En/Creating_MozSearch_plugins proprietary variant]].
~~- While that document suggests that "the only difference is the root element and XML namespace" that is certainly not the case in comparison with the //current// ""OpenSearch"" 1.1 draft version. Also, [[http://developer.mozilla.org/en/Creating_OpenSearch_plugins_for_Firefox Creating OpenSearch plugins for Firefox]] suggests that the **Param** elements they use are an ""OpenSearch"" extension, but the document they link to actually describes a **[[http://www.opensearch.org/Specifications/OpenSearch/Extensions/Parameter/1.0 Parameter element]]** as an extension: there is no Param element in ""OpenSearch"".
~~- An extra complication is that adding these Mozilla-specific elements, attributes and namespace to an ""OpenSearch"" description (as illustrated on WikkaOpenSearch and the [[http://developer.mozilla.org/en/Creating_OpenSearch_plugins_for_Firefox Mozilla documentation]]) will make it **[[http://developer.mozilla.org/Talk:en/Creating_OpenSearch_plugins_for_Firefox#What%27s_wrong_here.3f no longer work with Internet Explorer]]**: the document is no longer conformant (and no longer "open")!

Revision [20236]

Edited on 2008-09-13 08:29:29 by NilsLindenberg [(m)]

No Differences

Revision [20206]

Edited on 2008-09-05 13:42:50 by JavaWoman [oops double echo]
Additions:
~1) For each of your XML description files, **insert** a ##link## tag that indicates its location, for instance just before the ##link## tags for the favicon; the ##href## attribute must point to the location of your XML file. You can use variables, too. For instance like this for (plain) ""TextSearch"": %%(html4strict;18) <link rel="search" type="application/opensearchdescription+xml" href="<?php echo $site_base;?>libs/opensearch/TextSearch.xml" title="<?php echo $this->GetConfigValue('wakka_name');?> Text Search"/>%%
Deletions:
~1) For each of your XML description files, **insert** a ##link## tag that indicates its location, for instance just before the ##link## tags for the favicon; the ##href## attribute must point to the location of your XML file. You can use variables, too. For instance like this for (plain) ""TextSearch"": %%(html4strict;18) <link rel="search" type="application/opensearchdescription+xml" href="<?php echo <?php echo $site_base;?>libs/opensearch/TextSearch.xml" title="<?php echo $this->GetConfigValue('wakka_name');?> Text Search"/>%%

Revision [20205]

Edited on 2008-09-05 12:51:03 by JavaWoman [more "what is"]
Additions:
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.
Deletions:
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.

Revision [20204]

Edited on 2008-09-05 12:44:49 by JavaWoman [fleshing out the 'see also' box a bit]
Additions:
>>See also...
==From the horse's mouth:==
==Elsewhere:==
~- [[http://en.wikipedia.org/wiki/Opensearch Wikipedia's page on OpenSearch]]
~- [[http://15seconds.com/issue/071109.htm 15 Seconds: An Introduction to OpenSearch]]
Deletions:
>>See also:

Revision [20203]

Edited on 2008-09-05 12:40:37 by JavaWoman [Over to the browser - preparing for adding screenshots]
Additions:
~- [[http://wikkawiki.org/OpenSearchForWikka#hn_Over_to_the_browser Over to the browser]]
====Over to the browser====
//This section is still a stub - expect some screenshots here later.//
Deletions:
~~- [[http://wikkawiki.org/OpenSearchForWikka#hn_Test Test!]]
===Test!===

Revision [20202]

Edited on 2008-09-05 12:19:24 by JavaWoman [update search clients]
Additions:
~- **Firefox 3** (see [[http://wikkawiki.org/OpenSearchForWikka#hn_Footnotes the footnotes]] ""<sup>1)</sup>""); 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**
Deletions:
~- **Firefox 3** (see [[http://wikkawiki.org/OpenSearchForWikka#hn_Footnotes the footnotes]] ""<sup>1)</sup>"")

Revision [20201]

Edited on 2008-09-05 06:07:22 by JavaWoman [reworking footnotes]
Additions:
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+]] ""<sup>1)</sup>"" 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.
~- **Firefox 3** (see [[http://wikkawiki.org/OpenSearchForWikka#hn_Footnotes the footnotes]] ""<sup>1)</sup>"")
~- **Internet Explorer 7** (and later - see [[http://wikkawiki.org/OpenSearchForWikka#hn_Footnotes the footnotes]] ""<sup>2)</sup>"")
~1) Actually, Firefox 2 did not really support the ""OpenSearch"" specification, but a [[http://developer.mozilla.org/En/Creating_MozSearch_plugins proprietary variant]].
~~- While that document suggests that "the only difference is the root element and XML namespace" that is certainly not the case in comparison with the //current// ""OpenSearch"" 1.1 draft version. Also, [[http://developer.mozilla.org/en/Creating_OpenSearch_plugins_for_Firefox Creating OpenSearch plugins for Firefox]] suggests that the **Param** elements they use are an ""OpenSearch"" extension, but the document they link to actually describes a **[[http://www.opensearch.org/Specifications/OpenSearch/Extensions/Parameter/1.0 Parameter element]]** as an extension: there is no Param element in ""OpenSearch"".
~~- An extra complication is that adding these Mozilla-specific elements, attributes and namespace to an ""OpenSearch"" description (as illustrated on WikkaOpenSearch and the [[http://developer.mozilla.org/en/Creating_OpenSearch_plugins_for_Firefox Mozilla documentation]]) will make it **[[http://developer.mozilla.org/Talk:en/Creating_OpenSearch_plugins_for_Firefox#What%27s_wrong_here.3f no longer work with Internet Explorer]]**: the document is no longer conformant (and no longer "open")!
~~- Meanwhile, Firefox 3 does support the actual OpenSearch specification, and the definition file (template) provided on this page works without a hitch in Firefox 3.
~~- The upshot is that if you wanted to provide backwards compatibility with Firefox 2, you'd have to provide a compliant ""OpenSearch"" description file **as well as** a Firefox proprietary (i.e., not-open) description file - and then indicate the difference in the only 16 characters you have for your ""ShortName"" and autodiscovery title attribute...
Deletions:
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+]] 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.
~- **Internet Explorer 7** (and later)
~- **Firefox 3** (see [[http://wikkawiki.org/OpenSearchForWikka#hn_Footnotes the footnotes]])
~1) Actually, Firefox 2 did not really support the OpenSearch specification, but a [[http://developer.mozilla.org/En/Creating_MozSearch_plugins proprietary variant]]. While that document suggests that "the only difference is the root element and XML namespace" that is certainly not the case in comparison with the //current// ""OpenSearch"" 1.1 draft version.
~1) An extra complication is that adding the Mozilla-specific elements, attributes and namespace to an ""OpenSearch"" description (as illustrated on WikkaOpenSearch) will make it **[[http://developer.mozilla.org/Talk:en/Creating_OpenSearch_plugins_for_Firefox#What%27s_wrong_here.3f no longer work with Internet Explorer]]**: the document is no longer conformant (and no longer "open")!
~1) Meanwhile, Firefox 3 does support the actual OpenSearch specification, and the definition file given above works without a hitch in Firefox 3.
~1) The upshot is that if you wanted to provide backwards compatibility with Firefox 2, you'd have to provide a compliant ""OpenSearch"" description file **as well as** a Firefox proprietary (no-open) description file.

Revision [20200]

Edited on 2008-09-05 05:43:25 by JavaWoman [adding a minimal description template]
Additions:
~- [[http://www.opensearch.org/Specifications/OpenSearch/1.1#The_.22Query.22_element Query]] optional: this 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
A minimal description file, with only the required tags, would look like this:
**minimal description template**
Make sure you understand what the defaults are though - for most Wikka installs you will at least need to override the default UTF-8 for ""InputEncoding"" and ""OutputEncoding"".
Deletions:
~- [[http://www.opensearch.org/Specifications/OpenSearch/1.1#The_.22Query.22_element Query]]optional: this 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

Revision [20199]

Edited on 2008-09-05 05:35:41 by JavaWoman [constraints for autodiscovery title attribute]
Additions:
~1) You also need a description of your search engine: up to 1024 plaintext characters - no markup allowed!
~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) 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 ##<link>## tag itself.)
Make sure that your title attribute matches the ""ShortName"" in your description file. Although the [[http://www.opensearch.org/Specifications/OpenSearch/1.1#Autodiscovery_in_HTML.2FXHTML OpenSearch specification states]] only "The "title" attribute may contain a human-readable plain text string describing the search engine", in practice the strings should match so as not to confuse browsers (they compare the title attribute with the ""ShortName"" of already-installed search engines to decide whether of not to offer to install a new one).
Deletions:
~1) Optional: A description is also possible: up to 1024 plaintext characters - no markup!
~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) 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!

Revision [20198]

Edited on 2008-09-05 05:13:42 by JavaWoman [rewriting Search clients, Camino added]
Additions:
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:
~- **Internet Explorer 7** (and later)
~- **Firefox 3** (see [[http://wikkawiki.org/OpenSearchForWikka#hn_Footnotes the footnotes]])
~- **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]].
Deletions:
As I've already hinted, Both **Internet Explorer 7** (and later) and **Firefox 3** (see [[http://wikkawiki.org/OpenSearchForWikka#hn_Footnotes the footnotes]]) 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: [[http://www.opensearch.org/Community/OpenSearch_search_clients OpenSearch search clients]].

Revision [20197]

Edited on 2008-09-05 01:34:56 by JavaWoman [correction for the link tag (oops)]
Additions:
~1) For each of your XML description files, **insert** a ##link## tag that indicates its location, for instance just before the ##link## tags for the favicon; the ##href## attribute must point to the location of your XML file. You can use variables, too. For instance like this for (plain) ""TextSearch"": %%(html4strict;18) <link rel="search" type="application/opensearchdescription+xml" href="<?php echo <?php echo $site_base;?>libs/opensearch/TextSearch.xml" title="<?php echo $this->GetConfigValue('wakka_name');?> Text Search"/>%%
Deletions:
~1) For each of your XML description files, **insert** a ##link## tag that indicates its location, for instance just before the ##link## tags for the favicon; the ##href## attribute must point to the location of your XML file. You can use variables, too. For instance like this for (plain) ""TextSearch"": %%(html4strict;18) <link rel="search" type="application/opensearchdescription+xml" href="<?php echo <?php echo $site_base ?>;?>libs/opensearch/TextSearch.xml" title="<?php echo $this->GetConfigValue('wakka_name');?> Text Search"/>%%

Revision [20196]

Edited on 2008-09-04 18:38:44 by JavaWoman [information about Firefox 2's non-compliant implementation]
Additions:
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+]] 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.
As I've already hinted, Both **Internet Explorer 7** (and later) and **Firefox 3** (see [[http://wikkawiki.org/OpenSearchForWikka#hn_Footnotes the footnotes]]) 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: [[http://www.opensearch.org/Community/OpenSearch_search_clients OpenSearch search clients]].
That's it - it's easier than it looks: just go through the steps carefully, you can't really go wrong. Name the file after the type of search it describes, like ##""TextSearch.xml""## or ##""TextSearchExpanded.xml""## (you can have both).
---
----
==Footnotes==
~1) Actually, Firefox 2 did not really support the OpenSearch specification, but a [[http://developer.mozilla.org/En/Creating_MozSearch_plugins proprietary variant]]. While that document suggests that "the only difference is the root element and XML namespace" that is certainly not the case in comparison with the //current// ""OpenSearch"" 1.1 draft version.
~1) An extra complication is that adding the Mozilla-specific elements, attributes and namespace to an ""OpenSearch"" description (as illustrated on WikkaOpenSearch) will make it **[[http://developer.mozilla.org/Talk:en/Creating_OpenSearch_plugins_for_Firefox#What%27s_wrong_here.3f no longer work with Internet Explorer]]**: the document is no longer conformant (and no longer "open")!
~1) Meanwhile, Firefox 3 does support the actual OpenSearch specification, and the definition file given above works without a hitch in Firefox 3.
~1) The upshot is that if you wanted to provide backwards compatibility with Firefox 2, you'd have to provide a compliant ""OpenSearch"" description file **as well as** a Firefox proprietary (no-open) description file.
~1) Since I don't have access to Internet Explorer 7, I'm hoping for someone to test the instructions in this page (or a proof of concept implementation of it), and report the result here!
Deletions:
A **search client** application can be a desktop application (such as 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.
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: [[http://www.opensearch.org/Community/OpenSearch_search_clients OpenSearch search clients]].
That's it - it's easier than it looks: just go through the steps carefully, you can't really go wrong. Name the file after the type of search it describes, like ##TextSearch.xml## or ##TextSearchExpanded.xml## (you can have both).

Revision [20195]

Edited on 2008-09-04 18:06:18 by JavaWoman [a few smallish corrections]
Additions:
~- [[http://www.opensearch.org/Specifications/OpenSearch/1.1 OpenSearch 1.1 current draft]]
This is conformant with the latest version of the specification, the [[http://www.opensearch.org/Specifications/OpenSearch/1.1 OpenSearch 1.1 current draft]].
Now you can edit it; the bits you need to fill in are enclosed in ""[[...]]"". If it starts with ""**"", it is optional: leave out the whole tag if you do not provide a value. The elements you absolutely **must** provide are ""ShortName"", Description and Url; and of course the ""OpenSearchDescription"" root element. ""ShortName"" and Description are described above; Url is the search URL "template" the browser will use to construct a search from the user's input. Let's go through it line by line (elements are linked to the official description):
Deletions:
Now you can edit it; the bits you need to fill in are enclosed in ""[[...]]"". If it starts with ""**"", it is optional: leave out the whole tag if you do not provide a value. The elements you absolutely **must** provide are ""ShortName"", Description and Url; the first two are described above,is how your search will be shown in a browser, the second is the search URL "template" the browser will use to construct a search from the user's input. Let's go through it line by line (elements are linked to the official description):

Revision [20194]

Edited on 2008-09-04 13:52:30 by JavaWoman [struggle with nested lists]
Additions:
~~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.
Deletions:
~ 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.

Revision [20193]

Edited on 2008-09-04 13:25:13 by JavaWoman [nearly done - screenshots later!]
Additions:
~- [[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_Test Test!]]
>>=====""OpenSearch"" for Wikka=====
~- [[http://www.opensearch.org/Community/OpenSearch_software OpenSearch software]]
>>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//.
A **search client** application can be a desktop application (such as 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.
>>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]].
====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:
===Create a description file===
%%(xml;1)
~1) **copy** the .htaccess file you find in the ##images## or ##css## directory to your ##opensearch## directory (without this, a browser won't be able to download the XML file!)
===Provide for autodiscovery===
~1) Find the section where the start of the HTML is produced (in 1.1.6.5 this starts on line 7); two lines below that is the ##<head>## element; change it from %%(html4strict;9)<head>%% to %%(html4strict;9)<head profile="http://a9.com/-/spec/opensearch/1.1/">%%
~1) For each of your XML description files, **insert** a ##link## tag that indicates its location, for instance just before the ##link## tags for the favicon; the ##href## attribute must point to the location of your XML file. You can use variables, too. For instance like this for (plain) ""TextSearch"": %%(html4strict;18) <link rel="search" type="application/opensearchdescription+xml" href="<?php echo <?php echo $site_base ?>;?>libs/opensearch/TextSearch.xml" title="<?php echo $this->GetConfigValue('wakka_name');?> Text Search"/>%%
===Test!===
Now, if you go to your wiki with a browser like Firefox, you'll note that the dropdown button for the search box get a blue "glow" around its down arrow. Click it, and you'll see an option to add your own search engine(s) to the list. All you need to do is click that menu item, and from then on you can search your site directly from the browser, without going to the site first. **And any of your visitors can do the same.**
Deletions:
=====""OpenSearch"" for Wikka=====
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.
>>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, but not the only one.
>>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]], [[http://trac.edgewall.org/ Trac]], [[http://www.youtube.com/ Youtube]], and [[https://addons.mozilla.org/ Mozilla Add-ons]].
===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 a description file==
%%(xml;1;TextSearch.xml)
==Provide for autodiscovery==
~1) Find the section where the start of the HTML is produced (in 1.1.6.5 this starts on line 7); two lines below that is the ##<head>## element; change it from %%(html)<head>%% to %%(html)<head profile="http://a9.com/-/spec/opensearch/1.1/">%%
~1) For each of your XML description files, create a ##link## tag that indicates its location, for instance just before the ##link## tags for the favicon; the ##href## attribute must point to the location of your XML file. You can use variables, too. For instance like this for (plain) ""TextSearch"": %%(html) <link rel="search" type="application/opensearchdescription+xml" href="<?php echo <?php echo $site_base ?>;?>libs/opensearch/TextSearch.xml" title="<?php echo $this->GetConfigValue('wakka_name');?> Text Search"/>%%
==Test!==

Revision [20192]

Edited on 2008-09-04 12:38:56 by JavaWoman [nearly there...]
Additions:
**search description template**
Now you can edit it; the bits you need to fill in are enclosed in ""[[...]]"". If it starts with ""**"", it is optional: leave out the whole tag if you do not provide a value. The elements you absolutely **must** provide are ""ShortName"", Description and Url; the first two are described above,is how your search will be shown in a browser, the second is the search URL "template" the browser will use to construct a search from the user's input. Let's go through it line by line (elements are linked to the official description):
~- [[http://www.opensearch.org/Specifications/OpenSearch/1.1#The_.22OpenSearchDescription.22_element OpenSearchDescription]] **required**: the root element
~- [[http://www.opensearch.org/Specifications/OpenSearch/1.1#The_.22ShortName.22_element ShortName]] **required**: fill in your short name here
~- [[http://www.opensearch.org/Specifications/OpenSearch/1.1#The_.22LongName.22_element LongName]] optional: if you don't have a long name, leave out this whole line
~- [[http://www.opensearch.org/Specifications/OpenSearch/1.1#The_.22Description.22_element Description]] **required**: fill in your search engine description here
~- [[http://www.opensearch.org/Specifications/OpenSearch/1.1#The_.22Contact.22_element Contact]] optional: your contact email, if you provide one; otherwise leave out the whole line
~- [[http://www.opensearch.org/Specifications/OpenSearch/1.1#The_.22Url.22_element Url]] **required**: this is the template the search client will use to search your site. Fill in your base URL (the base_url value from your ##wikka.config.php## file. The next bit is """TextSearch""" for the basic search; if you want to provide an interface to the expanded search instead, use """TextSearchExpanded""". Then a separator: **##?##** if you use URL rewriting (##rewrite_mode## 1 in ##wikka.config.php##), **##&##** if you do not
~- [[http://www.opensearch.org/Specifications/OpenSearch/1.1#The_.22Image.22_element Image]] optional: 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)
~- [[http://www.opensearch.org/Specifications/OpenSearch/1.1#The_.22Query.22_element Query]]optional: this 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
~- [[http://www.opensearch.org/Specifications/OpenSearch/1.1#The_.22SyndicationRight.22_element 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
~- [[http://www.opensearch.org/Specifications/OpenSearch/1.1#The_.22Language.22_element Language]] optional: one element for each language that your search engine supports (in RFC 3066 format); the default is "*" for "any language"
~- [[http://www.opensearch.org/Specifications/OpenSearch/1.1#The_.22InputEncoding.22_element InputEncoding]] optional: must match the character set your site is encoded in (ISO-8859-1 for a standard Wikka install); default is UTF-8
~- [[http://www.opensearch.org/Specifications/OpenSearch/1.1#The_.22OutputEncoding.22_element OutputEncoding]] optional: must match the character set your site is encoded in (ISO-8859-1 for a standard Wikka install); default is UTF-8
That's it - it's easier than it looks: just go through the steps carefully, you can't really go wrong. Name the file after the type of search it describes, like ##TextSearch.xml## or ##TextSearchExpanded.xml## (you can have both).
To install these file(s) in your Wikka installation you need to:
~1) create a ##opensearch## directory under the ##libs## directory in your installation path (if you run an old version of Wikka and don't have a ##libs## directory, simply create that first);
~1) upload your XML description file(s) into ##[yourpath]/libs/opensearch##.
==Provide for autodiscovery==
For this, you'll need to edit the file ##header.php##. Depending on the version of your Wikka installation, it's either in the ##templates## directory (version 1.1.6.4 or later), or the ##actions## directory (earlier versions). The process is the same, regardless of where it is located.
Open (a local copy of) the file in a text editor, and make the following changes:
~1) Find the section where the start of the HTML is produced (in 1.1.6.5 this starts on line 7); two lines below that is the ##<head>## element; change it from %%(html)<head>%% to %%(html)<head profile="http://a9.com/-/spec/opensearch/1.1/">%%
~1) For each of your XML description files, create a ##link## tag that indicates its location, for instance just before the ##link## tags for the favicon; the ##href## attribute must point to the location of your XML file. You can use variables, too. For instance like this for (plain) ""TextSearch"": %%(html) <link rel="search" type="application/opensearchdescription+xml" href="<?php echo <?php echo $site_base ?>;?>libs/opensearch/TextSearch.xml" title="<?php echo $this->GetConfigValue('wakka_name');?> Text Search"/>%%
If you have done this locally, upload your modified ##header.php## to your server again.
==Test!==
Deletions:
Now you can edit it; the bits you need to fill in are enclosed in ""[[...]]"". If it starts with ""**"", it is optional: leave out the whole tag if you do not provide a value. The elements you absolutely **must** provide are ""ShortName"", Description and Url; the first two are described above,is how your search will be shown in a browser, the second is the search URL "template" the browser will use to construct a search from the user's input. Let's go through it line by line:
~- [[http://www.opensearch.org/Specifications/OpenSearch/1.1#The_.22OpenSearchDescription.22_element OpenSearchDescription]] is the root element: **required**
~- [[http://www.opensearch.org/Specifications/OpenSearch/1.1#The_.22ShortName.22_element ShortName]]: fill in your short name here: **required**
~- [[http://www.opensearch.org/Specifications/OpenSearch/1.1#The_.22LongName.22_element LongName]]: if you don't have a long name, leave out this whole line
~- [[http://www.opensearch.org/Specifications/OpenSearch/1.1#The_.22Description.22_element Description]]: fill in your search engine description here: **required**
~- [[http://www.opensearch.org/Specifications/OpenSearch/1.1#The_.22Contact.22_element Contact]]: your contact email, if you provide one; otherwise leave out the whole line
~- [[http://www.opensearch.org/Specifications/OpenSearch/1.1#The_.22Url.22_element Url]]: this is the template the search client will use to search your site. Fill in your base URL (the base_url value from your ##wikka.config.php## file. The next bit is """TextSearch""" for the basic search; if you want to provide an interface to the expanded search instead, use ""TextSearchExpanded"". Then a separator: ##?## if you use URL rewriting (##rewrite_mode## 1 in ##wikka.config.php##), ##&## if you do not
~- [[http://www.opensearch.org/Specifications/OpenSearch/1.1#The_.22Image.22_element 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)
~- [[http://www.opensearch.org/Specifications/OpenSearch/1.1#The_.22Query.22_element 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
~- [[http://www.opensearch.org/Specifications/OpenSearch/1.1#The_.22SyndicationRight.22_element 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
~- [[http://www.opensearch.org/Specifications/OpenSearch/1.1#The_.22Language.22_element Language]]: optional, one element for each language that your search engine supports (in RFC 3066 format); the default is "*" for "any language"
~- [[http://www.opensearch.org/Specifications/OpenSearch/1.1#The_.22InputEncoding.22_element InputEncoding]]: optional, must match the character set your site is encoded in (ISO-8859-1 for a standard Wikka install); default is UTF-8
~- [[http://www.opensearch.org/Specifications/OpenSearch/1.1#The_.22OutputEncoding.22_element OutputEncoding]]: optional, must match the character set your site is encoded in (ISO-8859-1 for a standard Wikka install); default is UTF-8

Revision [20191]

Edited on 2008-09-04 11:53:18 by JavaWoman [markup corrected]
Additions:
~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.)
Deletions:
~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.)

Revision [20190]

Edited on 2008-09-04 11:50:41 by JavaWoman [more data added, wondering why preview shows a mess...]
Additions:
~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) 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!
<Description>[[a description, up to 1024 characters of plain text, no markup]]</Description>
template="[[your base_url]]TextSearch[[separator ?|&]]phrase={searchTerms}"/>
Now you can edit it; the bits you need to fill in are enclosed in ""[[...]]"". If it starts with ""**"", it is optional: leave out the whole tag if you do not provide a value. The elements you absolutely **must** provide are ""ShortName"", Description and Url; the first two are described above,is how your search will be shown in a browser, the second is the search URL "template" the browser will use to construct a search from the user's input. Let's go through it line by line:
~- <?xml... ?> is the processing instruction: **required**
~- [[http://www.opensearch.org/Specifications/OpenSearch/1.1#The_.22OpenSearchDescription.22_element OpenSearchDescription]] is the root element: **required**
~- [[http://www.opensearch.org/Specifications/OpenSearch/1.1#The_.22ShortName.22_element ShortName]]: fill in your short name here: **required**
~- [[http://www.opensearch.org/Specifications/OpenSearch/1.1#The_.22LongName.22_element LongName]]: if you don't have a long name, leave out this whole line
~- [[http://www.opensearch.org/Specifications/OpenSearch/1.1#The_.22Description.22_element Description]]: fill in your search engine description here: **required**
~- [[http://www.opensearch.org/Specifications/OpenSearch/1.1#The_.22Contact.22_element Contact]]: your contact email, if you provide one; otherwise leave out the whole line
~- [[http://www.opensearch.org/Specifications/OpenSearch/1.1#The_.22Url.22_element Url]]: this is the template the search client will use to search your site. Fill in your base URL (the base_url value from your ##wikka.config.php## file. The next bit is """TextSearch""" for the basic search; if you want to provide an interface to the expanded search instead, use ""TextSearchExpanded"". Then a separator: ##?## if you use URL rewriting (##rewrite_mode## 1 in ##wikka.config.php##), ##&## if you do not
~- [[http://www.opensearch.org/Specifications/OpenSearch/1.1#The_.22Image.22_element 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)
~- [[http://www.opensearch.org/Specifications/OpenSearch/1.1#The_.22Query.22_element 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
~- [[http://www.opensearch.org/Specifications/OpenSearch/1.1#The_.22SyndicationRight.22_element 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
~- [[http://www.opensearch.org/Specifications/OpenSearch/1.1#The_.22Language.22_element Language]]: optional, one element for each language that your search engine supports (in RFC 3066 format); the default is "*" for "any language"
~- [[http://www.opensearch.org/Specifications/OpenSearch/1.1#The_.22InputEncoding.22_element InputEncoding]]: optional, must match the character set your site is encoded in (ISO-8859-1 for a standard Wikka install); default is UTF-8
~- [[http://www.opensearch.org/Specifications/OpenSearch/1.1#The_.22OutputEncoding.22_element OutputEncoding]]: optional, must match the character set your site is encoded in (ISO-8859-1 for a standard Wikka install); default is UTF-8
Deletions:
~1) For the autodiscovery you can provide a longer description, 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!
~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 woudl need to specify.
<Description>[[**a description, up to 1024 characters of plain text, no markup]]</Description>
template="[[your base_url, ending in a slash]]TextSearch?phrase={searchTerms}"/>
<Attribution>[[copyright for your search data]]</Attribution>
<AdultContent>false</AdultContent>

Revision [20189]

The oldest known version of this page was created on 2008-09-04 10:54:27 by JavaWoman [more data added, wondering why preview shows a mess...]
Valid XHTML :: Valid CSS: :: Powered by WikkaWiki