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: bluefrog@shaw.wave.ca
<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: bluefrog@shaw.wave.ca
|
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 every time 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
AppleScript's
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.
