O'Reilly Mac OS X Innovators Contest
Innovators Contest. Mac DevCenter. Mac OS X Conference.
  Contest Rules     Entry Form     Contest Prizes  

Web Services
Macintosh/OS X
Open Source
Game Development
Enterprise Development 
The Missing Manuals

Creating Sherlock Channels

by Harold Martin

Editor's Note: In this first of a two-part series, Harold Martin shows you how to get started with creating Sherlock channels by walking you through the process of creating a channel to search, browse, and display articles from the MacOSXHints.com site. Along with Apple's Sherlock documentation (those documents should be installed on your hard drive at /Developer/Documentation/Sherlock), you can begin to explore the world of developing for Sherlock.

This article is included on the Mac OS X Innovators contest site as an example of the many development opportunities that the Mac platform offers programmers and hobbyists alike.

Sherlock was first introduced by Apple with Mac OS 8.5 in 1998. With the introduction of Mac OS 9 in 1999, a new version was released, Sherlock 2. At that time it received a user interface overhaul, even though the underlying channel structure stayed the same for the most part. Now, with the introduction of Mac OS X 10.2 Jaguar, Sherlock is completely overhauled both internally and externally and becomes Sherlock 3. For the first time, Sherlock developers are able to create complete user interfaces that take full advantage of Aqua and Mac OS X. With the increased power also comes new challenges when developing channels: there was a dearth of documentation to help developers create a channel from start to finish. That is, until now.

What You'll Need

  • Mac OS X 10.2 Jaguar, preferably the latest version.

  • The Apple Developer Tools. These are on the gray CD that came with Jaguar. You'll also need to download and install the December 2002 update from the Apple Development Tools site.

  • The Sherlock 3 Developer Channels. These are channels themselves that we'll use later on.

Setting Up Sherlock to Run in Developer Mode

In order for this channel to run in developer mode, which allows us to, among other things, reload a channel without restarting Sherlock, we need to set the SHERLOCK_DEBUG_CHANNELS environment variable.

  1. Open /Developer/Applications/Property List Editor
  2. Create a new document (Command-N)
  3. Click the New Root button
  4. Click the New Child button
  5. Double click the name and enter SHERLOCK_DEBUG_CHANNELS
  6. Double click the value and enter 1
  7. Save the file as environment.plist in your home directory and quit Property List Editor
  8. Open up Terminal from the /Applications/Utilities directory
  9. Type
    mkdir .MacOSX
    mv environment.plist .MacOSX/

Creating a New Channel

  1. After installing the latest Developer Tools, open /Developer/Applications/Project Builder
  2. Choose File -> New Project
  3. Under "Standard Apple Plug-ins" choose "Sherlock Channel" and click "Next"
  4. For the Project Directory, choose ~/Sites
  5. Enter the name of the project. Since we're creating a channel for Mac OS X Hints, let's name it, logically enough, "macosxhints". The Project Directory should now show "~/Sites/macosxhints"
  6. Click "Finish"

You now have a Sherlock Channel just waiting to be developed! You may be wondering why you should create it in ~/Sites, but we'll get to that in a minute.

Setting the Channel Identifier and Name

The first thing to do after you have created your channel is to give it a unique identifier. This way Sherlock never gets confused between channels, even if they have the same name. In Project Builder (PB) lick on the file "SherlockChannel.xml". This is where all the basic information about your channel will be stored. You should see a line like


Change this to reflect your Web site, or if you don't have one, your email address. So if your email is stevej@mac.com your identifier would be com.mac.stevej.macosxhints.

After you change the identifier, we'll want to name our channel. Note: When I mention files and their paths (unless I state otherwise) I'm referring to the Project Builder structure, not the Finder file structure. Under the folder Channel/LocalizedResources.plist/ choose the file en. You'll see

<string>Sherlock Channel</string>

Let's change "Sherlock Channel" to "Mac OS X Hints".

Now you're ready to launch Sherlock in developer mode. Make sure Sherlock isn't running. In PB click the icon with the hammer over the monitor, or press Command-R. Sherlock will open up, but you won't see your channel because you haven't subscribed to it yet. First make sure Personal Web Sharing is on in the Sharing System Preferences pane. Now, open a browser and type


replacing stevej with your username. Now you see that the reason the channel was saved in ~/Sites is because everything in ~/Public will be available on the internet when you start the Web server, which was done in the Sharing preference pane.

Now let's pick apart the URL: sherlock:// is how all channels are opened, localhost means to get them from your computer, ~stevej is to get the channels from stevej's Sites folder, "macosxhints" is the folder within the Sites folder to get the channel, SherlockChannel.xml is the file where Sherlock gets the initial information about the channel (it's the same file we edited the channel identifier in earlier), and ?action=add tells Sherlock to keep that channel on your toolbar.

Overview of Channel Programming

In this section, we'll step back and take a look at the concepts and languages you'll use to start writing the channel.

The Languages

One of the most difficult part of writing channel is that you have to use two languages, JavaScript and XQuery. Even though it is theoretically possible to use only one, it's practically impossible. So let's look at the two and see how they are used together in writing a Sherlock channel.


Related Reading

JavaScript: The Definitive Guide
By David Flanagan

The Web page designer's friend (and the language that drives you nuts with rollovers and pop-ups), JavaScript it a rather easy-to-learn language that is ideal for retrieving and setting values in the DataStore (we'll get to that in a minute) and opening up external URLs, as well as some other things. I would highly recommend you read through (at least) the first six chapters of JavaScript: The Definitive Guide 4th ed.


XQuery, a newer language, is designed to parse XML (that's where the "X" come from). Although it has less documentation than JavaScript, XQuery will do many important things for our channel We'll use it for retrieving web pages and other files over the internet and parsing those file to get the information our channel needs out of them. Apple has added numerous extensions, particularly in the area of making http requests.

This article is too short to teach either of these languages in depth, but because of the Sherlock specific extensions and the limited documentation, more focus will be given to XQuery.

Triggers, DataStore, and Paths

These concepts are fundamental to writing channels, so pay attention! Triggers are the pieces of code (written in XQuery or JavaScript) that respond to events in the DataStore. The DataStore is the mostly invisible "glue" of a channel, where our code connects to our interface, and our interface connects to our code. Paths (in this context, these are not related to XPath) are how the DataStore knows where to find the interface widgets and the corresponding code.

Here's an example: when the user clicks on the "Search" button in the channel it will let the DataStore know it has been clicked. The button's name is "SearchButton" and the name of the top level view (the whole window) is "Internet" so the button's complete path is "Internet.SearchButton". Which means the DataStore will look for the path "Internet.SearchButton.action" in the code when the button is clicked, and execute the proper code. The code could then use a path to insert text into a text field. I don't want to get you bogged down in all the details right now, but keep this in mind, we'll look at it more later when we start coding.

The Channel Interface

There are also a few things you need to know about creating the interface. The first it that the interfaces widgets you'll use are Object Oriented (OO). OO means different things to different people, but for the interfaces we'll create it means that widgets can inherit properties and methods from their parents.

For example: the SearchButton is an instance (which means it's an actual use of) the NSButton object. NSButton inherits the "action" property (among others) from NSControl. An important reason to remember this is that Apple's Sherlock reference, which you'll come to rely on, only lists the methods specific to that object, assuming that you'll remember to look at the object's parent(s) to see it's other methods and properties. And in case you're wondering what the NS in front of each class is for it's a relic from NextStep, the OS from which Mac OS X is derived.

Pages: 1, 2

Next Pagearrow

Copyright © 2000-2006 O’Reilly Media, Inc. All Rights Reserved.
All trademarks and registered trademarks appearing on the O'Reilly Network are the property of their respective owners.
For problems or assistance with this site, email