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.
/Developer/Applications/Property List Editor
- Create a new document (Command-N)
- Click the New Root button
- Click the New Child button
- Double click the name and enter
- Double click the value and enter
- Save the file as
environment.plist in your home directory and quit Property List Editor
- Open up Terminal from the /Applications/Utilities directory
mv environment.plist .MacOSX/
Creating a New Channel
- After installing the latest Developer Tools, open
- Choose File -> New Project
- Under "Standard Apple Plug-ins" choose "Sherlock Channel" and click "Next"
- For the Project Directory, choose ~/Sites
- 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"
- 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 email@example.com your identifier would be
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
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
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.
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
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