Jack of All Widgets



When I first heard of Apple's Dashboard Widgets the two things that went through my mind were 1) this could be really cool and 2) My screen is going to get cluttered really, really quickly. And it didn't take long for developers to make more widgets than one could fit on the screen at once, even if you have a dozen cinema displays. I guessed that developers would end up making lots of single-purpose widgets for similar tasks: search Amazon, search Google, search the Yellow Pages, etc. If I wanted to have quick search functionality for lots of different sites, I'd have to leave open a widget for each one, cluttering up the screen. OR, I could write a single widget which executed a search function for lots of different sites. So that's what I did.

What JackWidget Does

JackWidget is a multi-website search tool. It provides quick access to dozens of commonly used web searches. It has a search field and a popup menu. The search field, of course, is for typing in the search terms. The popup menu is for selecting which site or sites to search. Some of the popup items actually send your search to several websites at once. It's as easy as choosing a search from the popup menu, typing in some search terms, and hitting return. The widget activates Safari and executes the search(es). It also supports command line interface style usage, allowing the user to bypass the popup menu. It has over two dozen searches built in, and is infinitely customizable (if you know how to open a widget package and edit XML files).

How to Use It

The simplest way to use it is to select a search from the popup menu, type in some search terms and hit return. The different sites often have different formats for their search terms, so when you choose a specific search from the popup menu a hint appears in the search field, like "zip code" or "city, state". (The hints don't appear if there's already something in the search field, but you will still get a tooltip if you mouse over the field.) You don't have to select the search from the popup first, but to execute the search you do have to hit return when the cursor is in the search field. If you type your search first and then choose from the popup, you won't get the format hint.

Searched Websites

  • Accuweather
  • Acronymfinder
  • AirborneExpress/DHL (package tracking)
  • Amazon
  • Barnes and Noble
  • Bizrate
  • Borders
  • Bugmenot
  • Citysearch
  • eBay
  • Epinions
  • Federal Express (package tracking)
  • Foldoc (Free online dictionary of computing)
  • Froogle (Google's product search)
  • Geocoder (Find the latitude and longitude of an address)
  • Google (general, finance, movies, user video)
  • Infospace
  • Internet Movie Database (IMDB)
  • jux2 (searches google, yahoo and msn simultaneously)
  • Law.com - legal dictionary
  • Lyrictracker
  • MacUpdate
  • Mapquest (find address, find latitude/longitude)
  • MelissaData
  • Merriam-Webster (Dictionary, Thesaurus, Medical Terms)
  • NOAA (Weather)
  • Pricegrabber
  • Superpages.com
  • Shopping.com
  • Ultimate-Guitar.com (Tab)
  • UPS (package tracking)
  • USPS (find zipcode)
  • USPS (package tracking)
  • VersionTracker
  • Weather.com
  • Webopedia (computer terms)
  • Whitepages.com
  • Wikipedia
  • WiFi-HotSpotList.com
  • Yahoo (maps, movies, real estate, stock prices)
  • Zabasearch

Rules for Interpreting the Hints

Separate fields with a forward slash ("/")
Some website searches require info in several fields. The reverse address search is one example. The hint for this search is something like "number/street/city/state". In order for the search to work correctly, the search terms have to be separated with forward slashes. So the search *must* look like this to work: 1234/ elm st./ anytown/ ST
Note that in this case the city and state names are in separate fields. Other websites will accept them in a single field, like "Walla Walla, WA" or sometimes it will accept "Walla Walla WA" (no comma). Pay attention to the hints for clues on where to place commas, if necessary. If you put extra "/"s, the text in the extra fields will be ignored. For example, if you put "1234/Elm St./Walla Walla/WA/ Hi / There", "Hi" and "There" will be ignored.

Optional terms are enclosed in parentheses
If a search term is optional and you want to leave it out, just put two slashes together. (Or, if you want to leave out the first term, start with a slash.) For instance, in the SuperPages search there's a field for both a keyword and a business name, but you don't have to do both, you could search for "/kinko's/kalamazoo mi" or "copy shops//needles ca" (Note that I didn't separate the city and state with a comma, because it's not required here, but watch the hint for guidance.)

Quotation marks in the hints are only to group items, don't include them in your actual search string
For example, the hint '"city, state" or zip code' means you either put "kalamazoo, mi" OR the zip code. I use the quotes here to avoid confusion: 'city, state or zip code' looks like it accepts either "kalamazoo, mi" or "kalamazoo, 22222", but the latter one won't work.

"Advanced" Operation

The default search in JackWidget is called "Query" and operates a little differently from the other searches. Query allows you to do a predefined search without having to select it from the popup menu. If you look at the searches defined in the popup you'll see some of them have a short string in square brackets at the end, like "Amazon: Books [ama]". The "ama" means that you can execute this search in the default "Query" mode without having to select the item in the popup. To do this, simply type "ama " (remember the space!) and then your search terms. For example, "ama Harry Potter" will search Amazon for Harry Potter books.

In fact, you don't have to be in "Query" mode to use a query string. If you preface your string with a question mark ("?") like so: "?ama Red Dwarf" you can run the general Amazon search, regardless of which search popup is selected! This will work in "query" mode as well, although you don't need to put the question mark.

Customization.

JackWidget is very customizable, but it's not easy. All of the searches in JackWidget are defined in two xml files in the widget package: "urls.xml" and "searches.xml". To get at them you have to either "Show Package Contents" of the widget by right/control clicking on it, OR change the widget package to a folder by removing the ".wdgt" extension from the name. This should only be done on a copy of the widget, not the one installed in your user ~/Library folder. After you're done editing, you'll need to reinstall/restart the widget by double clicking on it.

DANGER, Will Robinson! It is very easy to mess up one or both of the xml files to the point where the program no longer works correctly, or at all. I know because I've done this myself several times. That's why it's important to work on a copy and always have a backup in case you mess up the original!

The file "urls.xml" contains definitions for individual websites. It basically shows how to construct a query for that website. The file "searches.xml" defines the items chooseable in the popup menu. Each search in "searches.xml" specifies one or more urls to be searched. To add a website, you need to first add an entry in "urls.xml" specifying the url, then an entry or entries in "searches.xml". The entries in "searches.xml" are parsed in order, so where you put it matters. You can figure out the basic format from looking at the default files provided with JackWidget.

A couple features deserve special mention. Some urls require only one field and some require multiple fields. If you don't put any "fields" tags in basically the program just concatenates the url string with the search string. If you put fields tags in, the program concatenates the url string with string pairs made out of the field names and individual search terms. It's up to you to figure out how to construct the url string and encode it into the XML definition.

Some websites use a special way of handling searches, called the "post" method. You can identify these by the "method=post" option in their form tag. These are identified in the urls.xml file with the following option in the url tag: type="post". URLs whose type is "post" are treated differently than regular URLs. Basically what Jack Widget does is construct a simple html file consisting of only the form and the elements needed to make the form work. The elements come from the "field" tags. The string contained between a pair of field tags is used to name a form element. If the pair of field tags is immediately followed by a pair of value tags, the form is constructed with that value as the default value. If the pair of field tags has no corresponding value tags, the program assumes that the value will be supplied by the user.

Really the only way to understand the method="post" URLs is to look at the examples. The first two websites I included are gaspricewatch.com, and the USPS.com package tracking site. To see what the program does, first look at the definitions in the urls.xml file. Then run a search in the widget in one of the two "post" examples. It doesn't matter which one. After running a search, look in the /tmp directory. (Yeah, it's at the root, and no, you can't see it using the finder, you have to use terminal to "cd /tmp", "ls", then "cat jacktemp0.html"). When you submit a "post" search, the program generates this file and then tells Safari to open it. The javascript embedded in the file automagically submits itself. You should see the search terms you entered embedded in the form elements.

Some websites replace spaces with characters other than the standard "%20" string. You can specify what to replace spaces with in the XML file, using the "replacespacewith" tag. You can also specify nothing, by putting nothing between the open and close tags. "Nothing" should be translated into "%20". As of the current version of JackWidget, however, nothing is translated into "+" because of a bug in Apple's version of JavaScript which doesn't handle URLs with spaces in them. Also, some websites require that the search be parsed into several fields. The reverse address search is one example and you can see how this is handled in "urls.xml".

Remember, be careful editing the file! If you make an error it generally disables everything that comes after the error, so a lot of the searches could stop working even if there's nothing wrong with them. Even the smallest error can cause a problem. For example, I couldn't figure out for the life of me why some of my searches weren't working, until I discovered that I had left out the "/" in a closing "</field>" tag. All the searches defined after that error in the file were broken.

Oh yeah, one more thing, if you add your own URLs, be sure to use "&amp;" instead of just "&" or else it won't work. But if you're savvy enough to alter the xml files to do this, you probably already knew that.

A note about country localization: Right now, Jack of All Widgets is biased towards American users. All the searches assume you're in the US. This is because that is where I live and those are the websites I go to. In many cases it is quite easy to alter the search URLs so it accepts country as a parameter. In other cases it probably wouldn't be too hard to find the alternative URL for the site for that country. I can't guarantee that this is always possible, though. I welcome modifications and customizations to the URL list to accommodate international users, and if enough sites are converted I would consider hosting different localized URL lists. I may in the future do an international version which accepts country as a parameter where possible (i.e. it doesn't assume "US").

Enjoy!
(C) 2005-2011 Dave Richmond.
Copyleft under GNU GPL