Writing a Sherlock Plugin
Writing a Sherlock Plugin
- Subject: Writing a Sherlock Plugin
- From: Larry Walker <email@hidden>
- Date: Sun, 10 Dec 2000 18:43:55 -0800
<!doctype html public "-//W3C//DTD W3 HTML//EN"> This is the kind of
stuff I like to find, Simple.
Here's the address;
http://www.apple-donuts.com/sherlocksearch/howto.html
If anyone comes across other cool stuff like this please forward it to
me.
email@hidden
Writing a sherlock plugin
By: Gord Lacey
Intro:
I've been asked by numerous people about how to write an .src file. I
decided to write this step by step guide to help those that asked and
others that might want to learn as well. If you have a few mins to learn,
and more time to test it out, writing .src files is easy. Before we
start.....the limitations of Sherlock.
Limitations:
1. Sherlock can't search pages without search engines. Sherlock is an
interface or bridge between your computer and the search engine; you
can't build a bridge without having some place to put the other side, and
you can't search a site without a search engine.
2. Sherlock uses linked text as the name when returning results. A
good example of this is the Version Tracker .src file (which has been
removed, see note). If you do a search using it, your results will be a
bunch of numbers; the version numbers of the programs. Because Version
Tracker uses the version number as the link, this is what Sherlock
returns as the name. It sucks, but that's life, you can't do anything
about it (unless it's your site).
Tools used:
Text Editor (I use BBEdit), ResEdit, Sherlock (comes with OS 8.5), some
time and basic knowledge of HTML.
Getting Started:
You should go to the page you want to make the .src file for and save the
search page as source from your Browser. The run a search and save the
results. Note: I've found that NS 4.0 sometimes returns "No Matching
Results" from search sites when saving the results. I've found that NS
3.0 works most of the time, and that's what I usually use for saving my
sites as source.
Open an existing Apple-provided (or a 3rd party) .src file in your text
editor. I'll use the .src file I created for WebCrawler as an example.
The text from the file is below. All this
# Created by Apple-Donuts - Gord Lacey
# Visit www.apple-donuts.com
# e-mail: email@hidden
<search
name = "Web Crawler"
method = get
action = "
http://www.webcrawler.com/cgi-bin/WebQuery";
update = "
http://www.apple-donuts.com/sherlock/WebCrawler.src.hqx";
updateCheckDays = 3
>
<INPUT NAME="searchText" user>
<interpret
resultListStart = "for these results."
resultListEnd = "</table>"
resultItemStart = "<BR>"
bannerStart="</FORM>"
bannerEnd="</B></FONT></CENTER></a>"
>
</search>
Break down of the text:
This is pretty straight-forward. It's just a bit of info I've added to
the plugin so someone who opens it knows who made it. You don't have to
put this in any of your files, but I'd suggest it if you want to
distribute it.
# Created by Apple-Donuts - Gord Lacey
# Visit www.apple-donuts.com
# e-mail: email@hidden
How Sherlock interfaces with the Search Engine:
<search
name = "Web Crawler"
method = get
action = "
http://www.webcrawler.com/cgi-bin/WebQuery";
update = "
http://www.apple-donuts.com/sherlock/WebCrawler.src.hqx";
updateCheckDays = 3
>
<INPUT NAME="searchText" user>
name = "Web Crawler"
Okay, now some important stuff. The name = "Web Crawler" tag tells
Sherlock what name to show. In the finder you could name the file
skdajhdflkajsh.src, but without changing this tag, it'll always show up
as "Web Crawler" in Sherlock.
method = get
This is the method the form uses. You can find this info in the source
code we saved from the site earlier. It's either get or post and can
appear with "" around it or not. method = get and method = "get" both
work. Here's the code taken from WebCrawler that shows "get" as the
method used: <FORM NAME=wcsearchform
ACTION=
http://www.webcrawler.com/cgi-bin/WebQuery METHOD=GET>
action = "
http://www.webcrawler.com/cgi-bin/WebQuery";
This is where Sherlock goes to contact the search engine. You get this
info from the source code and it's part of the FORM tag found there:
<FORM NAME=wcsearchform ACTION=
http://www.webcrawler.com/cgi-bin/WebQuery
METHOD=GET>
update = "
http://www.apple-donuts.com/sherlock/WebCrawler.src.hqx";
You only need this tag if you want to update the .src file for people. It
uses the directory I've created for updates, and when I update the Web
Crawler.src file it'll be named WebCrawler.src.hqx because that's the
name I choose and because it uses binhex for compression.
updateCheckDays = 3
This is how often Sherlock will look for new updates. 3 days sounds
reasonable to me, and it's also what Apple uses for their .src files.
<INPUT NAME="searchText" user>
This is one of the most important parts of an .src file. This is the
input box on WebCrawler that people put their search string in. The user
part is there because it tells Sherlock that this is the info to send to
the search engine. Note: There can be MANY <INPUT> tags on a web page.
Many are invisible, but they should still be included. I use GoLive
CyberStudio to quickly pick out any invisible tags. If there are pulldown
menus to select something on the search page, that should also be
included. Many pages have a "Number of Results" pulldown on the page.
You'll have to decide what these pulldown menus should be set to. If you
can't decide on something, maybe you should make more than one for a
site.
This section of the .src file interprets the data the search engine
returns.
<interpret
resultListStart = "for these results."
resultListEnd = "</table>"
resultItemStart = "<BR>"
bannerStart="</FORM>"
bannerEnd="</B></FONT></CENTER></a>"
>
</search>
resultListStart = "for these results."
This tells Sherlock where to start looking for results. It can be text
(like above) or it can be code. Sometimes it's good to find where the
results are and then find a good place for Sherlock to start from.
resultListEnd = "</table>"
This tells Sherlock where to stop looking for results. Anything below
this will be ignored.
resultItemStart = "<BR>"
This tells Sherlock that everytime it sees a <BR> tag that it should
count it as a new result. It'll only return <BR> tags that appear between
resultListStart and resultListEnd.
resultItemEnd = "<SOME CODE HERE>" Not Shown above
This tells Sherlock that the result has ended. This is good if there is
text between your current result, and the next one. This isn't needed for
every .src file, but for most of them it's good to include.
bannerStart="</FORM>"
This tells Sherlock where the banner starts. It's a good idea to include
this for any site that has banners. This is how some people support the
sites they run. Who knows, if everyone moved to Sherlock, and no one
loaded the banners, some of these great sites might shut down.
bannerEnd="</B></FONT></CENTER></a>"
This is where the banner ends.
skipLocal = true Not Shown
This will eliminate any results to local files. There was one search
engine I did that put a local link half way through the results. This is
the perfect place to use the skipLocal = true tag to get rid of that
result.
Wow...that's it. Now you can test it to see if it works.
Testing your new .src file:
The first thing to do is change the creator/file type of the text file to
match an .src file (Type:issp Creator:fndf). If you are not sure how to
change a files type and creator codes you can download one of our
applescripts to do it for you. If you have Sherlock open, quit it now.
Sherlock loads the .src files each time it starts up. You'll need to
restart Sherlock every time you change an .src file and want to test it.
Some bug testing tips:
* If you think you have the resultItemStart and resultItemEnd tags
correct, maybe it's your resultListStart and resultListEnd tags that are
too narrow. Change these to resultListStart="<html> and
resultListEnd="</html>" to make it search the entire document.
* If you still aren't getting any results, check the form info. You
may be sending Sherlock someplace other than the search engine.
* If you're getting more results that you expect you have a problem
with the resultListStart and resultListEnd tags. They may be used
somewhere else in the document.
* It could also be that Sherlock is returning some local files as
results. Try using the skipLocal = true tag.* You may have picked a
site that just doesn't work with Sherlock. I found Download.com didn't
like anything I tried.
Extending your Sherlock file with ResEdit:
If you want to have your plugin update over the net then you have to open
it in ResEdit and play with some resources. You should open an Apple .src
file and copy these resources: ftag, MPSR, MWBB (For an explanation of
these resources see below). If you open the ftag resource, you'll notice
that most of it is illegible, however, the part you can read should be
the name of the .src file in the finder. Edit the name of the Apple file
and change it to the same name of your .src file in the finder. You might
notice a date resource in the Apple .src file. This is the file that's
added to when Sherlock updates the .src file. You'll get a new date ID
every time you update the .src file. The first one is 128, the second 129
and so on.
Update - Info from Apple.
I received an e-mail from Brian Bechtel at Apple shortly after posting
this "how-to" guide. Here's his explanation of the resources found with
ResEdit:
"The ftag resource is used by Apple's software configuration management
group to keep track of items. Some items in system software may be
localized to non-Roman names. It can be difficult to keep track of all
the names if you're running a system with American English only installed
and you're trying to view a Kanji name. Therefore, Apple's software
configuration management group adds this harmless resource so they can
track all items in a build with Roman character names that tell them some
internal information about which build this piece was part of.
The MPSR resource is used by MPW, the Mac Programmer's Workbench. It's
documented in technote PT 570 at
<
http://devworld.apple.com/technotes/pt/pt_570.html>
The MWBB is a Metrowerks Codewarrior editor resource.
All three of these resources are harmless, and do NOT need to be added to
a new Sherlock .src file. They will not affect the functionality of a
.src file in any way. They are part of the build or development process."
Okay, you're totally done making your .src file. When you're happy with
it, send it to us and we'll put it on our site with your name beside it.
If you have any problems, or comments on this file, just send us mail and
we'll be glad to help.