Transfer mode set to Awesome http://transfermodeawesome.posterous.com Dorkly bits on Exchange, Windows, software and whatever else I can think of. posterous.com Mon, 26 Apr 2010 16:10:00 -0700 Adding an OpenSearch provider for Redmine http://transfermodeawesome.posterous.com/2010/04/adding-opensearch-provider-to-redmine.html http://transfermodeawesome.posterous.com/2010/04/adding-opensearch-provider-to-redmine.html

Update: An OpenSearch plugin for Redmine has been created based on the work here.  I recommend you use that instead.  It is available at:

http://dev.holgerjust.de/projects/redmine-opensearch/wiki

Thanks to Holger for quickly turning this around.  Now, back to the original article:

Have you ever used your browser’s built-in search window?  Don’t answer that.

Internet Explorer and Firefox both allow search providers to be added to the built-in search window, so you can change which search the window actually performs.  By default my Firefox search comes with providers such as Google, Wikipedia, Answers.com, Amazon, etc.

I don’t actually use the feature much.  I’m used to typing Google searches in that box and don’t really think about anything else.  If I want to search Amazon, I go to Amazon.  But it is a convenience for Google.  The only way I might use it for something else were if there were another site I searched more often.

While it is arguable, I do search Redmine a lot for tickets, wiki info, etc.  As an experiment I wanted to switch my search box to Redmine.  I thought this would be a difficult task, perhaps involving coding.  Turns out is was much easier than I thought.  However, there was a lack of clear, simple steps to do so, so I’m sharing the process through which I went.

First of all, the search provider protocol, so to speak, is specified by OpenSearch.org.  I didn’t get a lot of help there.

I did, however, get help from a couple of sites if you just google “opensearch tutorial”.  While I still wasn’t sure exactly how to accomplish it, they made it a lot more comprehensible.

I also posted a discussion on the Redmine.org website, which landed me a key piece of help.  I thought I would have difficulty adapting the examples I was given, because I wanted to search an internal website not available on the web-at-large.  However, it wasn’t a problem after all.  I just couldn’t use the example on one web site that tried to use Google site search as the search provider.

The only caveat is that my implementation uses the most generic redmine search, which searches all projects.  More specific searches can be done after the first search.

There are two pieces you need:

  1. An opensearch description file available on your Redmine server
  2. A search provider notification link added to the template for Redmine’s html files, the one that includes the head tag

Here is the opensearch description file provided by another Redmine enthusiast, adapted for my site:

<?xml version="1.0" encoding="UTF-8"?>
<OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/">

    <ShortName>Redmine Search</ShortName>
    <Description>Search Redmine</Description>
    <Url template="http://redmine/search?q={searchTerms}"

         type="text/html" method="GET" />
    <Image height="16" width="16" type="image/vnd.microsoft.icon">http://redmine/favicon.ico</Image>
    <OutputEncoding>UTF-8</OutputEncoding>
    <InputEncoding>UTF-8</InputEncoding>
</OpenSearchDescription>

The reason for the edit above is that I previously posted another version of this file which turned out to be Firefox-specific, meaning it wouldn't work with IE.  This version works with both IE and Firefox.

As you can see, my server url is just http://redmine.  This won’t work for you, so you need to substitute your own.

You need to specify the template search string as well.  In the case of the general search, it’s simply your Redmine root url plus “/search”.  There are more specific project searches that include “/search/index/project-name”, where project-name is your project’s name, but that was too specific for my purposes.  You also want to tailor your search description.

Once that is customized, I needed to place it in the public directory on my Redmine server, which for me is c:\program files\bitnami redmine stack\apps\redmine\public.  Yours may be different.  I saved it as opensearchdescription.xml, which needs to be referenced elsewhere, so remember the name of yours.

Finally for this step, I wanted an icon associated with the search.  Unfortunately, Redmine hasn’t settled on a favicon as of my version, 0.8.4.  I couldn’t find a good one that is Redmine-specific, so I stole the one from ruby.org.  I also put this in the public directory, replacing the empty one there.

The other piece you need is a way to notify your browser that there is a search provider available.  This is done by a link present in the header of all of your pages on your site.  That requires modification of the base html template used by Redmine (other solutions are welcome, I don’t like customizing core Redmine files).

I added the following to apps/redmine/app/views/layout/base.rhtml, presented here in diff form:

<%= call_hook :view_layouts_base_html_head %>
<!-- page specific tags -->
<%= yield :header_tags -%>
+<link rel="search" href="http://redmine/opensearchdescription.xml"
+      type="application/opensearchdescription+xml"
+      title="Redmine" />
</head>
<body>
<div id="wrapper">

This is a link which I added right before the </head> tag.  It refers to the opensearchdescription.xml file I added earlier.

I also had to restart Redmine and clear my browser cache for everything to show up properly.

Once done, point your browser at your Redmine install and look for the “Add Redmine” entry in your search provider dropdown.  Once you add it, you still need to select the “Redmine” search provider entry.  This should do it.

Permalink | Leave a comment  »

]]>