Learn how to write simple WOX plugins, with code examples.

In this blog post I'm, hopefully, going to learn you why WOX is so great and how easy it is to write your own WOX plugins.

I use both Mac OS and Windows. And probably the app I use the most on my Mac is Alfred. It's a productivity app, a bit similar to Apples Spotlight. But WAY more advanced.

A couple of months ago I started to use Windows more regularly. And with another OS comes the problem with finding substitutes for your favorite applications.

Finally I found a windows version of Alfred, kind of!

Luckily, most applications nowadays exist on both Mac OS and on Windows. But there are a few exceptions. Like Alfred. And I've tried every similar option I've found every since I started to use Windows on a daily basis. Without any luck. Sure, some options have been pretty good. One of them was Launchy. But when you're used to Alfred it's hard to settle with something that's not quite as good.

But finally I found a open software alternative called WOX.

WOX logotype
WOX logotype

What do I use Alfred and WOX for?

Here's a short list with some examples to give you an idea. This is no where near everything I use these two applications for though.

  • Launch programs super fast
  • Find files, and open them
  • As a calculator
  • Search for things on Internet using any of the search engines
  • Find the best price for things on Prisjakt
  • Find GitHub repos
  • And much much more…

Skeleton of a WOX plugin

It's super easy to write your own plugins for WOX. In this blog post I'm going to explain the basics and also show you two basic plugins I've written.

First, you can write plugins using either C# or Python. This blog post is going to focus on C#.

Every plugin need to have a few things to be able to work as a plugin. As I'm using C# in this tutorial I'm going to use Visual Studio to write my plugins.

  1. Create a folder for your plugin, choose a nice name that describes what your plugin does.
  2. Start Visual Studio and create a new Class Library project in your folder.
  3. Add a Nuget package called WOX.Plugin.
  4. Make sure you have a class called Main that inherits from the interface IPlugin
  5. Implement the interface, it adds two methods to your class. The first one is called Init and the other is called Query. (I'll explain later what each method is used for)
  6. That's actually all that is needed for a WOX skeleton plugin. Of course, this plugin isn't doing anything yet. But you have what you need to get started coding.

Example of an empty plugin

Take a look at my GitHub gist. It's a completely empty plugin, but a good starting point. If you followed the steps above you should have something similar.

Two plugins that's useful for me

So far I haven't had the time to build that many plugins. But two plugins I've built that I use daily is one for a price search site called "Prisjakt". It's the biggest here in Sweden. And the other plugin is to get nice pictures from NASA. They have a service where you can get a picture based on date. You enter a date and press enter, your default browser opens a very high resolution picture that's perfect for nice backgrounds for your computer.

Prisjakt plugin

Each and every day I search for the price of some product. A lot of times just out of curiosity. Or before I'm going to buy something, to read reviews and find the best price.

The plugin is extremely simply both to use .

  1. Write the keyword, the default keyword is "pris" followed by the word or words you want to search for.
  2. Press Enter on your keyboard.
  3. The site Prisjakt opens and have done a search for your word / words.

You find the source code here. Feel free to do whatever you wan't with it.

NASA Plugin

The other plugin is based on the same principle. But with a twist.

The NASA service I use is called APoD, "Astronomy picture of the day". The twist is that their API requires a correct date.

Here is the source code on GitHub as a gist.

First you'll find different variables, an API-key, the URL to the API and some other variables so we don't have to create a new instance of WebClient each time for example.

When a Query happens, I first make sure if the length of the string can be a valid date. So I simply check if the query is between 8 and 10 characters. If it isn't I return an empty list, a.k.a no result.

If the query have the correct length I try to parse the date. If the parsing goes well and I have a valid DateTime object i format the date the way NASA prefers it.

date.ToString("yyyy-MM-dd");

Now it's only a matter of formatting the correct API URL. Example,
https://api.nasa.gov/planetary/apod?date=2018-10-14&api_key=DEMO_KEY

As you might notice, I use their demo API key. It has some limits. But for this use case it's more than enough!

The result we get back is in json. So we need to parse it. As we're using C#, it's very convenient to use Newtonsoft Json.NET.

When we've reached this far it's only a matter of creating a Result (a WOX Plugin class) and use the json result to get the Title, the Explanation and the image URL.

How to publish a plugin to the WOX plugin library

WOX has a plugin library where everyone can publish their plugins.

Currently (at the time of the writing) it's 183 plugins published. You find the library here, http://www.wox.one/plugin Try to search for Prisjakt or NASA and you should be able to find my plugins.

First of all, you need an account. So go ahead and create an account and login. Then visit the Plugin section and press Upload.

At the next screen you need you enter some information and upload the plugin file. What I had most problem with was to have the correct structure in the folder. And also to create a valid json file with some meta data for your plugin.

WOX has some documentation about plugins, but nothing really of how to publish a plugin. So it was some trial and error.

Anyway, the correct structure in your folder should look something like this,

The Images folder only contains the image (logo) I use when displaying the result. The file plugin.json is the meta data I wrote about earlier. Here is some documentation about the contents.

When you have the correct file structure, go ahead and zip the folder but one last important step is to rename the file. Change the file type from zip to wox.

Now it only to upload and image, the wox plugin and fill in some optional information.

The first times I tried I got different errors. That was what I meant by trial and error. But hopefully my blog post have helped you to avoid errors.

Summary

WOX isn't as good as Alfred, but it's the best Window alternativt I've found. And that it's super easy to write plugins makes it only more fun to use.

If you're a Windows user, I really think you should give WOX a try. Give it a few weeks, after a while you'll probably get addicted as I got.

Just to have a calculator very easy to open (alt+enter) makes it worth it.

Don't hesitate to ask me any question, I'm more that happy to answer all types of questions. Or maybe you have a great idea for a plugin but doesn't know how to code, contact me. Maybe I also think it's a great idea.

Source code of my WOX plugins

You find the full source code on GitHub.

Prisjakt: https://github.com/Yodapp/WOX.Prisjakt
NASA: https://github.com/Yodapp/WOX.Nasa.APOD

Posted in

Daniel

Just another developer and a true code monkey! I enjoy working will web, mobile and system development. I've been a developer for all my life (or at least since I was six years old) and have ~15 years work experience.

Leave a Comment

Your email address will not be published. Required fields are marked *

Hope you like cookies, if not. Too bad for you! ;-)

Scroll to Top