Form Resources in WannaBe (Deprecated)

Since WannaBe does not yet support HTML forms, which are used to access search engines (among other things), WannaBe needs a way to do web searches. WannaBe now uses Sherlock-compatible search plug-ins for this purpose. Before these were supported, WannaBe used a specially-configured 'STR#' resource to do searches. These form resources are still supported, but won't be for long, so their use is deprecated. Nevertheless, this page describes how to add form resources to WannaBe, by editing the WannaBe application file's resource fork. Each additional search/form entry requires 3 steps to be enabled:

Step 1: Modify the MENU resource

To MENU resource ID 230, add a new menu item with the name of the search/form as you would like it to appear in WannaBe's Search submenu. The name must be unique and not match any menu item already in the submenu.

Step 2: Modify the Mcmd resource

To Mcmd resource ID 230, add a new command number mapping with value "-1". If you don't own CodeWarrior or haven't installed the Mcmd template for ResEdit, you append 8 F's and increase the count in the first 2 bytes by one. For instance, the Hex editor for the 'Mcmd' resource id 230 *as shipped* with WannaBe 1.0a3 will show:

0005 FFFF FFFF FFFF
FFFF FFFF FFFF FFFF
FFFF FFFF FFFF

To add a single entry, change this to:

0006 FFFF FFFF FFFF
FFFF FFFF FFFF FFFF
FFFF FFFF FFFF FFFF
FFFF

(If you *do* own Codewarrior and *have* installed the Mcmd template into ResEdit, the above step can be performed by clicking on the asterisks in the template window and then selecting "Insert New Field(s)" from ResEdit's resource menu. Since all values should be "-1", it doesn't matter if you add it at the top or bottom, as long as the number of entries matches the number of menu items in MENU resource ID 230.)

Step 3: Add a new STR# resource

The 3rd step is the hardest and most complex. It helps if you understand how URLs are formed from HTML form data.

Part 3a: Create the resource

You need to create a new 'STR#' resource. The resource ID doesn't matter, but WannaBe will be using 'STR#' IDs in the range 3300-3399 for its own web form resources. I will reserve IDs in the range 3400-3599 for your own use. This will aid in transferring resources to new WannaBe versions when you upgrade. While the ID doesn't matter, the name does. The name must match *exactly* the string for the menu item added in step 1. Be careful not to accidentally add trailing spaces, etc.

Part 3b: Number of strings

The string list resource must have 12 strings. Any more than 12 are ignored, but if the resource has less than 12, WannaBe will not create a window from the resource.

Part 3c: Content of the Strings

The content of each string is as follows. String list resource ID 3300 is a template which also explains each string briefly:

1st string: name of the form/search window. This does not need to match the name of the resource/menu item, but it will probably be similar, perhaps with "Search" prepended.

2nd string: The action URL of the HTML form which the window is based on.

3rd: The form method. At this time, only "GET" is supported. Anything else will raise a signal.

4th: reserved. This string is currently ignored, like some others to follow. To be safe, just leave the string "reserved" as its value, or blank, as in "". In the future, if I add features which use these fields, I will interpret "reserved" or "" as the default value.

5th: a string of hidden data values. This is perhaps the most complex, but it is really not that difficult to figure out. As of right now, the WannaBe form window can only interpret one text INPUT field to place in the window along with a submission button. Many forms require more fields, however. These can be added by default, via this 5th string. The string should consist of the appropriate <name>=<value> pairs separated by '&'. For instance:

search=web&format=textonly&listings=20

Such a string can be constructed by looking at the HTML for the form you wish to use and choosing the values for the various input fields that won't be shown. If you do not wish any extra hidden data to be added in this way, be sure to leave the field blank, without any spaces whatsoever.

6th: number of input fields. At this time, only "1" is supported. Anything else will raise a signal.

7th: label for the first input field. This could be something like: "Enter query:"

8th: type for the first input field. At this time, only "text" is supported.

9th: name for the first input field. This should be the value of the "name" attribute of the INPUT tag for the HTML form you wish to emulate.

10th: initial value for the first input field. This is the initial text you wish to appear in the edit box. Typically blank.

11th: reserved

12th: reserved

Remember to be careful about not adding extra spaces, as they may screw up the generation of a proper URL to be sent to a server. You may also want to keep a copy of your custom 'STR#' resources in a separate resource file to make it easier to transfer them to updated versions of WannaBe.

Back to WannaBe Documentation.

Part of the WannaBe website, by David T. Pierson, <dtp@mindstory.com>. This page was last modified on 8/1/99; 7:24:00 PM.