Rixstep
	`About \| ACP \| Buy \| Industry Watch \| Learning Curve \| News \| Products \| Search \| Substack`

Home » Learning Curve

One Thousand Two Hundred?

Actually more. One thousand two hundred ten currently. And counting. And here's how to use them.

Get It

Try It

'Sharky Pooh' writes to question whether Rixstep's ACP Web Services can truly tally over one thousand two hundred. 'A fanciful number at best', writes the arrogant twit. Now if one had been describing his IQ at '50' then the description definitely holds.

The number of web services available to ACP subscribers broke the thousand mark almost three years ago.

Here's a list of the services from a year or two back. This page already has nine hundred seventy web services. Users of the free version thus have at least nine hundred seventy; ACP users as stated have over one thousand two hundred. Swallow that, Sharky, if it's not too big for your mouth.

http://rixstep.com/acp/aws/catalogues.shtml

That page lists only nine hundred seventy; the downloads cited below have one thousand two hundred ten and ACP subscribers currently have one thousand two hundred eighty two. With a few more on the way in the next few weeks.

Be that as it may, let's move beyond the puerile ignorance and arrogance of Sharky and concentrate on what the ACP web services are, how they work, and how you use them.

What They Are

The ACP Web Services are a way to get contextual search (or other) results from selected text almost anywhere on your desktop. The results come through your web browser. And all you have to do is select text somewhere. Almost anywhere. And this thanks to the pervasive NSText system used in OS X.

Think of them as invisible 'widgets': all you see is your application's menu. They're on the menu of every application you run. And because you don't have to fire up another application you can work right from the application you're currently using. They pick things up 'contextually' and the results come up in your web browser.

You can select text:

Right here in your browser. Right now. On this page. Double click any word. Yes on this page. Or drag a selection across several words. On one or several lines. For example: select an address and scoot to Google Maps. It's that easy.
Select text in any text editor/word processor/whatever and you're ready to go.
Select text in any text input field. Such as in a save as dialog. Or a web form in your web browser. Anywhere.

You don't have to be able to edit the text - just select it. If you can select it the OS X text system takes care of the rest.

At the end of the day the web is more powerful than any constellation of applications you can conceivably use. More powerful than Watson or Sherlock or any of that. Yes you can get up a dictionary tool locally; but you can't get dictionary and thesaurus services and search services and whatnot to the tune of one thousand two hundred such features. Your hard drive can't handle storage or performance like that. But the powerful servers of the web can.

And it's fully tantamount to doing your 'crunching' on remote and super powerful servers. And with today's broadband speeds you get results as fast too. That's exactly what you're doing.

And your interface is the web browser you already have.

So if you need to know things and search for things you can either:

Do nothing until the right widget comes around (if ever) and then switch programs and then type in your search criteria - and your widget just accesses a web server anyway but it's not as easy as that for then it has to deconstruct the HTML and then reconstruct it again. Talk about stupid. And this wastes a lot of time and CPU too; or
Fire up your web browser, find the right bookmark, surf to it, wait for it to load, then type in your search criteria; or
Select some text locally and select the appropriate ACP Web Services menu item and off you go.

You'll run into trouble with apps that aren't 'native' OS X apps - using Carbon or other 'outdated' technologies. Some parts of Firefox or Camino for example. They might not be using the text system native to OS X. But most applications you use - Safari, TextEdit, Mail, ordinary file dialogs, text fields in web forms, etc etc - they'll all work.

Where To Get

The ACP Web Services can be found here. They're free.

http://rixstep.com/aws

You basically need three components and the 'resources' themselves. You need the service module, the service menu editor, and the resource browser. And then the resource catalogues.

Here's the direct download. 446 KB.

ftp://rixstep.com/aws/aws.bz2

There are four modules within.

browser.bz2 - the resource browser. Save until later.
catalogues.bz2 - the resource catalogues. Used with the browser. Later.
manager.bz2 - the services menu editor. Save until later.
service.bz2 - the service module itself. Open this one now.

So double click service.bz2 now and open it. Inside in addition to the EULA and the README you'll find the AWS.service bundle. Move this to ~/Library/Services. [If you don't have this directory then certainly you have the directory ~/Library - so scoot there and create the subdirectory Services - and then move AWS.service to it.]

[A service module gets installed on your computer in one of a number of standard locations. Either /Library/Services or ~/Library/Services. The latter is infinitely preferred as services provided at the former location appear on everyone's menu and you can't customise without interfering with other people's configurations. So you put the module in your own directory - at ~/Library/Services - and then they only run for you.]

Now if you go right away to your Services menu - it's on the application menu of any Cocoa application - you won't see anything yet. The system doesn't know they exist yet. Normally you have to log out and in again or reboot for the system to notice them. But there are ways around that.

NeXTSTEP used to have a standalone program to reactivate services. The API is still in the system; it's used in the ACP Web Services menu editor found in manager.bz2.

You couldn't run the menu editor before you had the service module in place as it would otherwise burp and say there's nothing to do and then exit. But now that you have the service module in place you can run it.

So double click manager.bz2. You'll see a similar EULA and README and the AWSManager.app bundle. You can put this app anywhere you want or just run it where it is for now. Either way: move it if you want and then run it right away. When it's open go straight away to the application menu and choose 'Update Services' (⌘S). This will trigger the system to update the system services. When you go back to your application menu again and then to your Services menu you should see the beginnings of your own ACP Web Services there.

The services you find now are only a default setup. They are mostly generic search services. Services such as Accoona, Ask, Clusty, Dogpile, half a dozen Googles, two Yahoos. What you want to do at this point is add some more services you like. So now you double click browser.bz2.

Again you'll find a EULA and a README and you'll also find the AWSBrowser.app bundle. You do the same thing with this you did with AWSManager.app. You move it if you want to but then you run it. You won't see a window pop up but you'll notice the menu bar changes. That's OK. You need to open a catalogue file now. So now you double click catalogues.bz2.

You'll find seventeen (17) catalogue files: #base.aws, Amazon(CA).aws, Amazon(DE).aws, Amazon(FR).aws, Amazon(JP).aws, Amazon(UK).aws, Amazon(US).aws, Google-intl-phrase.aws, Google-intl.aws, Google.aws, Hollywood.com.aws, Network-Tools.aws, search.aws, Slashdot.aws, thefreedictionary.aws, translations.aws, World-News-Network.aws.

All told there are 1,210 [one thousand two hundred ten] resources within. So pick one and double click it.

#base.aws might be a good place to start.

Resource browser windows come up as tidy small things with an extended 'drawer' at the bottom. Actually there are two drawers there. You hit ⌘/ (command-slash) to switch between them.

In the top part of the window you see a list of the resources in the file; in the first drawer you see a description of the resource, a small icon identifying the resource, and an empty text entry field. You use this text entry field to test your resource: just type something in and hit enter and your browser should scoot to get your search results.

Now hit ⌘/ to switch drawers; you'll find the actual configuration data: the menu item for the service, its menu subitem, and the actual query string that will be used to get your search results. You can edit these now but if the resource is working OK at this point you can defer until you have the item on your menu. At which point you can use AWSManager instead.

When you find something you like you export it. Exporting puts the item 'as is' on your services menu. The 'export' command is on your File menu. You can also use the shortcut ⇧⌘E.

And how the new Services menu item looks is determined by the fields 'Menu Item' and 'Menu Subitem': services can namely handle one - but only one - level of hierarchy. Non native apps like Finder have previously suffered from programming errors and seemed to allow more but didn't - those were just programming bloopers.

The menu item and menu subitem are namely concatenated together with a slash ('/') character in the Info.plist file. The complete string is deconstructed by the system at runtime. The service browser constructs this string and inserts it into your list of services. When the system sees the string [and it expects only one string] it looks for the slash and then creates the top item and the submenu item from that.

Your web services are stored in the service module bundle. In Info.plist - they're under the key 'NSServices' ('NeXTSTEP Services'). You use your menu editor to modify them once they're in place. That's the idea. And 'saving' changes not only updates your Info.plist but also triggers the system to refresh your Services menu.

The Search Strings

ACP Web Service search strings are eminently straightforward. They - and the AWS technology - take advantage of a configuration capability in the services that's never before been used in this fashion. Programmatically the interface looks like this.

-(void)fubar:(NSPasteboard *)pb userData:(NSString *)data error:(NSString **)error;

'fubar' is the 'receiver': it's defined in Info.plist. This is the entry point in the service module the system will use.

The receiver is sent a pointer to a pasteboard (clipboard - NSPasteboard). And a pointer to 'user data' (userData). And the address of a pointer where the module can set an diagnostic string should an error occur.

The secret is in the 'user data': this field isn't needed to activate services. Put simply: 'it's for anything you want'.

What the ACP Web Services want is your 'query string' sent as this function argument. And what the ACP Web Services do at that point is get your text selection off the special pasteboard with that pointer they were sent and catenate that string to the 'query string'.

So if the query string for 'Amazon UK' is the following.

amazon.co.uk/exec/obidos/search-handle-url/field-keywords=

And you've selected the word 'fubar' almost anywhere possible in your computer you'll get the following string as a result.

amazon.co.uk/exec/obidos/search-handle-url/field-keywords=fubar

The ACP Web Services will then prepend 'http://' to the string so it looks like the following.

http://amazon.co.uk/exec/obidos/search-handle-url/field-keywords=fubar

And then the ACP Web Services will kick start your browser and have it surf to that address.

The great majority of online search services namely operate with this type of URL to specify search terms. Google's standard search looks like the following.

http://www.google.com/search?q=

All one thousand two hundred ACP Web Services (as well as Watson/Sherlock/Dashboard 'widgets') work the same way.

Deconstructing

And as most online search services work in the same way so you can turn them into ACP Web Services. You can tell pretty quickly by visiting their sites and testing their searches - your search key has to turn up somewhere in their URLs.

And all you have to do if that's the case is extract the search key, reorder everything if necessary, and then put it on your Services menu. Piece of cake basically. A bit of savvy and intelligence and it's done. Let's deconstruct an Amazon URL to see how it works.

First we surf to amazon.co.uk; then we choose a category - let's choose 'DVD'; then let's decide what DVD we want to search for - let's search for 'Matrix'! The URL we get back is the following. Looks like a mess, doesn't it? Relax!

http://amazon.co.uk/s/ref=nb_ss_w_h_/203-8520316-4634311?url=search-alias%3Ddvd&field-keywords=Matrix&Go.x=9&Go.y=11&Go=Go

Now let's whittle away at this monster URL and see how far we can go and still get the same results. There are a lot of things in there we don't need. Let's remove them carefully. First step is to 'unescape' the string. This is admittedly easier with the ACP Text Services ('Undo Escapes') but any of those percent signs together with their two hex digit sequence immediately following can (and should) be changed back into a single character. You can also use an ASCII table with hex values.

http://amazon.co.uk/s/ref=nb_ss_w_h_/203-8520316-4634311?url=search-alias=dvd&field-keywords=Matrix&Go.x=9&Go.y=11&Go=Go

And we can now see more clearly what's going on. We see the field 'url=search-alias=dvd' is very important as that's our search category. Before it was unescaped it was 'url=search-alias%3Ddvd'; the second equals sign ('=') had to be escaped so the receiver code didn't misinterpret it. At any rate: that stays in.

The field 'ref=nb_ss_w_h_' doesn't look too important; let's try removing it.

http://amazon.co.uk/s/203-8520316-4634311?url=search-alias=dvd&field-keywords=Matrix&Go.x=9&Go.y=11&Go=Go

Yep: still works. So let's now remove the '&Go.x=9', the '&Go.y=11, and the '&Go=Go'. That 'Go' is defined as 'Go' seems pretty obvious; it's probably a default.

http://amazon.co.uk/s/203-8520316-4634311?url=search-alias=dvd&field-keywords=Matrix

Yep - that works too! So one more attempt: that big number '203-8520316-4634311' looks suspect - let's try to remove it.

http://amazon.co.uk/s/?url=search-alias=dvd&field-keywords=Matrix

Yep - that works too! Removing the '/s/' probably will not work as it's likely the 's' directory contains search code. [And if you try it you'll see.]

So that's pretty easy. And if you look again you'll see your actual search string happily occurs at the end. Remove it now and you have an ACP Web Service ready for export.

amazon.co.uk/s/?url=search-alias=dvd&field-keywords=

[Remember: you don't need the 'http://' scheme - it's automatically prepended.]

Now if you add that service to your system, update your services, double click the following word right here in your browser, and then select the new service on your 'Services' menu, you should scoot to the correct Amazon page. Try it. Now.

Matrix

Did it work? Congratulations in such case are in order.

But what would have happened if you got the arguments in the wrong order? Try the following string and you'll see it still gets you to the same place. Click the line below and see.

amazon.co.uk/s/?field-keywords=Matrix&url=search-alias=dvd

But in this case the search key's stuck in the middle of the URL and the web services want it at the end.

So what do you do? Punt? No. You deconstruct the URL.

Scheme	`http://`
World Wide Web Domain	`amazon.co.uk`
Relative Resource Locator (RRL)	`s/`
Argument	`field-keywords=`
Argument	`url=search-alias=`

The scheme is prepended automatically; we add a slash to the end of the domain; we separate the final URL from the arguments with a question mark; and we separate the arguments from each other with ampersands.

We can thus reconstruct the URL with the arguments in any order we want.

Scheme	`http://`
World Wide Web Domain	`amazon.co.uk`
Relative Resource Locator (RRL)	`s/`
Argument	`url=search-alias=`
Argument	`field-keywords=`

http:// + amazon.co.uk + / + s/ + ? + url=search-alias=dvd + & + field-keywords=Matrix: put it all together.

[Does a directory really parse the RRL? No of course not. But remember there's always a 'default file' for directories on web servers, and its name can be configured. So it's that file in such case that contains the code.

[Questions about running the ACP Web Services? Write to aws@rixstep.com.]