Create Custom Dictionaries For Mac OSX

Over the last couple of months I’ve been chipping away at creating an add-on dictionary for the Dictionary application on Mac. I wanted to create a dictionary for CFWheels.

Information on how to create such dictionaries was not all that easy to find. So I thought I’d share what I found in case it helps some else.

Apple’s Dictionary Services Programming Tutorial

First up, have a look at this tutorial on Dictionary Services Programming over at It provides all the information one needs to get started. You can also download a PDF of this tutorial.

Template Files for Dictionary

One thing that the tutorial assumes is that you have the template files for dictionary development are. First challenge was to figure out where they were. I found that they are installed with XCode at: /Developer/Examples/Dictionary Development Kit. If you don’t have XCode installed, then you can download the this zip file that contains the Dictionary Development Kit.

The Make Command

Before you customize anything in these files, simply run ‘make’ command in directory where you unzip these files. It should create a dictionary called “My Dictionary”. If you move this dictionary to /Library/Dictionaries or ~/Library/Dictionaries, it will start showing up i the Dictionary app.

There are a couple of other things that the make command can do:

  • make clean : cleans older builds
  • make install : installs the created dictionary to ~/Library/Dictionaries folder
  • make : creates the dictionary

Change the XML and Info.plist

Now add the stuff you want in the XML that will be used to create the dictionary. You will have to generate the XML with the appropriate structure and content. Also modify the plist file as required. Run “make” to create your dictionary.

A Big Gotcha – Cached Dictionaries

On thing that really had me flummoxed was that despite making a new dictionary, the Dictionary app was not reliably showing all the changes I expected.

This took a while to figure. There is a bunch of caching that comes into play if you are creating new builds of the dictionary. Cached versions show up and throw you off the track.

So I had to write this shell script to clean Dictionary app cache. Make sure that you

  • make the script executable before running it, and
  • quit the Dictionary app before you run

I found that I had run this each time I made a change to the XML file.

A downside to doing this is that it resets all Dictionary preferences. So when you start the Dictionary app after running this script, you have go to Preferences and turn on the dictionary you are working on. A bit painful, but not such a biggie.

My Development Workflow

So as I was making changes to the XML file with data, I was running the following commands:

  • ./ (cleans out all dictionary caches)
  • make clean (cleans out older builds of the dictionary)
  • make (makes the dictionary)
  • make install (installs the dictionary)

Example Dictionary: CFWheels

If you want to see an example of the dictionary that I created, check out:

Look at the XML and Info.plist files.

That’s it… go and have fun creating dictionaries now!

CFWheels Dictionary for Mac OS X

Working with any framework involves learning many things like file structure, information flow, etc. One of the most critical aspects of being proficient in a framework is how well one has learned the API. And this holds true of CFWheels as well.

CFWheels provides a simple API that one has to refer to time and again as one learns and develops with it. The CFWheels website has a great section on documentation which lists various API calls. And this helps the process of learning/working with the framework. But…

There were a couple of occasions when I was offline and a few when my connectivity not too good. Under those circumstances it was proving a little slow to figure out various API calls.

So I was browsing around a few months back and came across the ColdFusion 9 dictionary for Mac. That got me thinking that I should probably do something like that for CFWheels. The nice thing about a dictionary is that it is a desktop application, so it is very quick, has a very nice search, and most importantly, integrates very well with native Mac apps.

So here it is!

Download: CFWheels Dictionary for Mac

Installation is simple.

  • Unzip the zip file
  • Copy CFWheels.dictionary to either /Library/Dictionaries OR ~/Library/Dictionaries.

Fire up the Dictionary app, and you should see the CFWheels dictionary in the list of dictionaries available.

A few tips:

  • Once the CFWheels dictionary is installed, you can search for the word “api” and it lists a page where all CFWheels API calls are available. You can select what you want.
  • If you use a native Mac app like Panic’s Coda or TextMate the Mac dictionary service integrates beautifully with them. What that means is that you can select a word and right-click it and then “Look Up in Dictionary”. It opens dictionary and information about the text you selected.
  • Setup a keyboard shortcut (through System Preferences > Keyboards > Keyboard Shortcuts) for “Look Up in Dictionary” so that you can fire it up through keyboard.
  • If you want you can enable/disable various dictionaries through the Preferences menu of the Dictionary app. I find that to be quite handy.

Have fun! And do drop me a line if you like it! Or if you find any bugs/issues.

Update: Source Available on GitHub

The source for the dictionary is now on GitHub:

My CFWheels Presentation at CFObjective ANZ

Had a great time at CFObjective ANZ down in Melbourne.

I presented on CFWheels, a beautiful ColdFusion framework, inspired by Ruby on Rails.

Mine was the first presentation on day one, and in a way it worked nicely as I could then enjoy others with full attention. This is what I covered in the presenation.

CFWheels is a new-ish ColdFusion (CF) framework inspired by Ruby on Rails.

With its emphasis on convention over configuration, simple code organizing principles, a beautiful Model-View-Controller (MVC) architecture, and a pretty neat Object Relational Mapping (ORM) framework, CFWheels brings agility into applications written in CF.

In this talk, Indy takes you through the building blocks of a CFWheels application. He then shares his experience of learning and developing with CFWheels — an experience he thinks every CF developer should go through.

Come, have a listen, and see how CFWheels brings agility into CF development. And how you end up writing beautiful code, while having loads of fun as you develop.

I’ve added the presentation to Slideshare. Have a look.

CFWheels – Rediscovering beauty in CF Code

I haven’t been blogging much of late. Lots of traveling and work kept me away.

During this time, however, I have somehow managed to find time to play with Wheels. And I must say it has been a pleasure working with it.

I’ve dabbled with Ruby on Rails and Grails in the past and have always lamented about the fact that the frameworks in CF do not possess the same beauty and elegance.

Well, CFWheels changes all that.

If you ask me, I’d say that all CF developers should at least try it out to once to see all that it has to offer.

Personally, I like they way the MVC architecture is implemented in CFWheels — pretty much like Rails/Grails. Plus domain modeling and  URL rewriting using routes — leading to very nice, readable URL. And not to mention time-saver features like view helpers that let you build nice views and forms and add validation to them. And also the plugins… And also the provision for different environment like design/development/test/production.

I’ve tried it on Railo and it is blazing fast. I’m sure it would be as quick on CF9.

I could go on and on. But it is simpler for you to simply head over CFWheels to discover the magic.

Apache Rewrites for Subfolder Install of CFWheels

By default the CFWheels framework and application is installed in the webroot.

But if you want to install it in a subfolder in the webroot, you need to change the rewrites slightly.

I use the following and it works quite well.

In the example below, I have a server called hello.cfwheels.local, and it points to a folder under the webroot called hello.

ServerName hello.cfwheels.local

RewriteEngine On
RewriteOptions Inherit

RewriteCond %{REQUEST_URI} ^.*/(flashservices|flex2gateway|railo-context|robots.txt)($|/.*$) [NC]
RewriteRule ^(.*)$$1 [P,L]

RewriteCond %{REQUEST_URI} ^.*/(files|images|javascripts|miscellaneous|stylesheets|plugins|sitemap.xml|rewrite.cfm)($|/.*$) [NC]
RewriteRule ^(.*)$$1 [P,L]

RewriteRule ^(.*)$$1 [P,L]

RewriteRule ^/(.*)$$1 [P,L]
ProxyPassReverse /

ProxyPreserveHost on

If you think there is a better way to accomplish this, please drop in a line.