If you haven't customized anything in version 2.x, then you don't have anything to do. And if you've only done a bit of customizing, it's probably easiest to just start over with version 3.

Assuming you have heavily customized the shortcuts, though, and don't want to lose your work, here's what you need to do. Note that the process isn't automatic, and you may have to do some editing after it's all done, depending on your customizations. (But going forward, you shouldn't ever have to do this again.)

1. Install the new macro, but do not delete the old macro—just disable it.

2. Open the old macro's user-Shortcuts macro, and find the green List shortcuts to be removed from the default list here box:

   

   Take a screenshot of the box, or leave the window open, or copy-and-paste the entries somewhere, just so you know what they were.

3. Launch the new macro then click the Manage box. In the Shortcut Manager window, select Remove one or more shortcuts.

4. Using the Shift and/or Command keys, click on each entry in the list that matches a shortcut from the old version of the macro. To remove the selected shortcuts, double-click on one that's currently selected.

5. Return to the old version of the macro again, and this time, find the green box in the user-Shortcuts macro labeled List shortcuts to be added to the list here. Select everything in that box and copy it:

   

   Once everything's copied to the clipboard, launch the new macro, click the Manage button again, then select Add many custom shortcuts (batch) from the Shortcut Manager. This will open a new large text input box onscreen; paste the copied data into the box:

   

   Click OK, and hopefully all your shortcuts will be added—but if not, you'll see a box explaining exactly what's wrong, and the input window will reopen with your pasted text. Edit as necessary, then click OK again.

That should be all the work required to upgrade. However, you may want to explore the Shortcut Manager some more, as you can now do much more than you could before—you can easily change a predefined shortcut's shortcut keys (or description or URL), for example, and you can choose from a list of 80+ sites to add to your shortcuts.

This is the heart of Web Search via Shortcuts 3.0, and the key to making future upgrades completely trivial. All work with shortcuts should go through the shortcut manager.

On first use

The very first time you launch the new macro, you'll be asked to answer some questions that the macro in general—and the Shortcut Manager in particular—need in order to work correctly. Two of the questions are relatively trivial—your preferred dialog style and default "no shortcut" search site—but the last is critically important.

The last question asks you to select a folder where a Websearch folder will reside. In this folder, the macro uses two files (ws_adds.txt and ws_deletes.txt) to track your customizations. This is the key to easy upgradeability—when you install a new version of the macro, it will automatically find those files and read the data into the macro.

If you use more than one Mac, select a folder on a cloud drive to hold your Websearch folder, and you'll be able to use your customized list from any Mac you use.

The Shortcut Manager's menu

You access the Shortcut Manager by clicking the Manage button (or pressing ⌘M) in the input dialog window. You'll then see the main Shortcut Manager window:

The name explains what each option does, but here's how to use each one…

Add shortcuts from bundled list

Web Search via Shortcuts includes a list of 80+ pre-configured sites, ready for your use. All you need to do is activate them, and you do that through this menu item. When selected, a new window opens showing all the optional shortcuts, organized into rough categories:

You can type to select, if you wish, but if you're planning on adding more than one, use the Shift and/or Command keys to make multiple selections. Once you've selected the ones you'd like to activate, double-click the mouse on one of the selected items (or just press Return) to move to the next step.

After making your selections, you'll see a dialog for each selected shortcut, asking you what shortcut you'd like to use:

The dialog will insure that each shortcut is unique (and doesn't contain any spaces), then proceed to the next site you selected.

Add one custom shortcut

Use this option when you want to add a new custom shortcut of your own; it presents an input box for you to complete:

Pay close attention to the listed rules, as you won't be allowed out of the dialog box until your entries meet those restrictions—no spaces or duplicates in the shortcut, and a valid URL that also contains the {SEARCH} placeholder. Click OK when done, and your new shortcut is added and active.

Modify a shortcut's settings

This powerful feature lets you change anything about any of your active shortcuts—the activation keys, the description, and the URL. You'll first be shown a list of your active shortcuts; select one from the list, and it will appear in a dialog box, with its current values filled in:

Change whatever values you wish, then click OK. (Unfortunately, I have no control over the text box width, so you won't be able to see the full URL; copy and paste into a text editor if you want to edit the URL, then paste it back in.) The macro will make sure it's not a dupe, and requires the URL to be valid and include the {SEARCH} placeholder.

Remove one or more shortcuts

Use this menu item to remove shortcuts—custom ones you added, ones you added from the optional list, or even the default built-in shortcuts. You can choose one or more from the pop-up list that appears:

Note: If you remove default or optional shortcuts, you can easily add them back, as they're stored in the macro. If you remove a custom shortcut, though, it's gone for good and you'll have to re-add it from scratch.

Restore a removed built-in shortcut

If you remove one of the built-in shortcuts, then decide you'd like to have it back, this is the menu to use. (This menu item only appears if there are removed built-in shortcuts.) Just pick one or more shortcuts to restore from the menu that appears:

Note: To restore a removed optional shortcut, use the Add shortcuts from bundled list entry in the Shortcut Manager.

List shortcuts

This is more of a "future" feature than a "now" feature, but you can use it and see how it looks. It opens a window showing your active shortcuts, along with any available (hidden or inactive) built-in and optional shortcuts:

You can sort the tables using the arrows in the headers. Eventually, this will (hopefully) be a window from which you can visually add and remove shortcuts with a click. For now, it's a list that includes the ability to test each site in the list by clicking the "test" link—this will literally search for "test" on the selected site.

Preferences and tools

This menu item launches a new menu, with a few additional options on it:

The first three entries let you change the settings you made during initial setup. The View Websearch folder contents will open your Websearch folder in Finder. Finally, the Reset the macro menu item will do just that: It's a total reset of the macro, removing all your files, customizations, and global variables.If you run the macro after using reset, it will act as though you'd never run it before.

You really shouldn't have to use this, and if you do, I'd appreciate hearing from you, as it's there only as a measure of last resort.

Version 3 of the Web Search via Shortcuts macro works entirely differently than any of its predecessors. The older versions stored all your modifications in a macro, user-Shortcuts, within the macro itself. This worked reasonably well, but it had two main issues.

First, the list had to be recreated each time you invoked the macro, as there was otherwise no way to tell if you'd changed any shortcuts. This caused a slight but noticeable delay before the input dialog appeared. The second issue was that upgrading was a real pain—you had to install the new macro, then copy-and-paste values between the old and new versions of each macro's user-Shortcuts macro.

Version 3 fixes both these issues by storing your customizations in two files on your hard drive. It creates a new folder, Websearch, in a location of your choosing, and then writes ws_adds.txt and ws_deletes.txt files into that folder. As these files can be read at any time, this allowed me to save the shortcut list in a global variable, and only update it at certain times (see below). The end result is that the input dialog appears nearly instantaneously, and future upgrades should require zero work on your part—the new macro will read the existing files the first time you launch it, and you'll be up and running.

Follow these usage tips to get the most out of the new Web Search via Shortcuts 3.0 macro…

• Make all changes through the Shortcut Manager. Even though you could edit the text files on the drive, this is not the recommended approach. By using the Shortcut Manager, your list will automatically be kept up to date.

• Take advantage of the long list of optional shortcuts. The macro now includes a list of 80+ nearly ready-to-use searchable sites. The Shortcut Manager will let you easily add as many as you like in one pass—all you'll have to do is assign each one a new shortcut.

• Customize the shortcuts. New in this version is the ability to easily customize any existing shortcut, including the built-in (default) shortcuts. You can change the shortcut keys, description, and the URL. These changes are written to the files on your disk, so they'll persist through upgrades.

• Check for updates in the Shortcut Manager. There's also a timed routine, in the Update Related section of the macro. If you prefer, you can disable its timed trigger, and just manually check from the Shortcut Manager.

So how is the macro list kept current, if the files reside on the drive and it's not updated before each use? Given that all changes happen within the Shortcut Manager, that's when the list is updated—simply opening the Shortcut Manager will refresh the list. It's also refreshed, hopefully obviously, whenever you make a change within the Shortcut Manager. But the mere act of opening it will refresh the list.

There's also a timed routine in the Update Related section of the macro to refresh the list every six hours, in case you haven't opened the Shortcut Manager and (gasp!) edited the files directly on the hard drive. You can also disable this timed macro's trigger if you prefer, as long as you occasionally open the Shortcut Manager.

Permanent variables: In order to work how it does now, Web Search via Shortcuts has to use a few permanent variables:

1. rg_Websearch_activelist: Holds the current list of active shortcuts, and explains the speed increase in this version: Instead of rebuilding the list every launch, the list is just displayed from the variable. You'll notice, if you look, that there are codes in front of each type of shortcut, which enables the various management tasks for each type of shortcut.

2. rg_Websearch_folderloc: Stores the location of your Websearch folder. It needs to be in a permanent variable, otherwise the macro would have to ask you each time you run it where the folder can be found.

3. rg_Websearch_pref_default: Stores your chosen default search site, i.e. the one you'll search if you enter search terms without a shortcut.

4. rg_Websearch_pref_style: Stores your preferred dialog style, brief or verbose.

If you delete any of these variables, they will be recreated—rg_Websearch_activelist rebuilds automatically the next time you launch the macro, while the other three will require you to walk through a dialog box to set their values. So, really, just don't delete them.

Bugs and glitches:

Version 3 is a major rewrite, and I expect there are issues that I haven't found in testing—so please, let me know if you run into any problems!