Creating your own OpenSearch plugin for Firefox

Personally, I liked the search bar feature which is now a staple for all major web browsers already. However there are times when you found out that people may not have created a search plugin for that one site you frequent? For my case, I needed a search plugin for BitEx, a Chinese-Japanese dictionary but I can't find it at Mycroft. (the default place which Firefox points for users to find custom search plugins)

So basically you can either write it manually using a normal text editor or the automated way provided by Mycroft.

To do it automatically (Recommended!), you can use Mycroft's Submit plugins link, which will show you a simple form for you to fill up. The more important part is to fill in the "Search URL" field. Basically you can either view the HTML source or just do a normal search in order for you to get the search string being used, and then replace the parameters containing your keywords into {searchTerms}.

For instance, after I submitted a search at BitEx, the address bar now shows "http://www.bitex-cn.com/search_result.php?deal_type=jp2cn&keywords=%E6%97%A5%E6%9C%AC". Knowing that the "keyword" parameter is used for my search term, the "Search URL" field should be filled as "http://www.bitex-cn.com/search_result.php?deal_type=jp2cn&keywords={searchTerms}".

Now, make sure you put a meaningful plugin name and description and make sure what encoding that the webpage is using, especially if you are dealing with sites that was in a foreign language. Some of them aren't using Unicode yet so it's important to make sure that it's set correctly or your search plugin may be rendered useless.

Now, once everything is done, press the "Generate plugin" button and the textfield below will show the xml code of your plugin. I greatly recommend that you test your plugin once by saving the xml as a normal xml file and copy it to your search plugin folder. In Linux, it'd typically be stored in "~/.mozilla/firefox/[some random string]/searchplugins" folder. Note that [some random string] differs from each user profile. Restart your Firefox browser and test your plugin. Once confirmed that it's working, please do others a favour by submitting it to Mycroft. That'd be extremely helpful to other users.

To do it manually, you can refer to the "Creating OpenSearch plugins for Firefox" tutorial at Mozilla Development Center. Here are the steps that I used:

1. Open a new xml file, which in this case I named it as bitex.xml
   
2. Copy the template from the tutorial above
   
3. (Optional) Download the icon file from BitEx and edit it. The reason for me doing that because the icon file is extremely large, so I have to trim the fat myself before proceeding to the next step
   
4. Using the data: URI kitchen, get the xml data representation of the icon. Remember to tick the base64 checkbox located on top of the form, right next to "Title" text field. Then you either input the URL of the icon or upload your own (if you have edited one yourself) and press the "Generate" button. Copy the link which is presented to you and paste it between the <Image> tags. (see template)
   
5. Now, substitute all necessary fields shown in bold in the template file. Here's my quick explanation of how to fill in the values:
   • engineName: The name of the search engine
     
   • engineDescription: Your description of the search engine
   • inputEncoding: The input encoding used, typically UTF-8
   • imageData: The image data that you have generated in the previous step
   • method: Either GET or POST. Typically GET
   • searchURL: The base URL of the search engine, its the same as my previous example (see "To do it automatically" section)
   • (Not required) paramNameN and paramValueN: Used to pass parameters in the search requests. Typically not required unless the engine uses the POST method, in which you have to fill in such data
   • (Not required) suggestionURL: If the search engine supports the suggestion feature ala Google Suggest, then it'd be nice to fill this in
   • searchFormURL: The link to the search page, useful if users want to access the search page directly
     
6. Once you are done, save the xml file and copy it into your search plugins folder (see "To do it automatically" section)