Non-Scripter's Guide to Using Downloaded AppleScripts

One of the frustrations for a non-scripter is to find one in a scriptable application’s forums, on the MacScripter Forums (bbs.applescript.net) or Apple’s own AppleScript Discussions that does precisely what they are looking for, but not know how to use it. I answer a lot of mails from folks like that. This tutorial is addressed to them, so if you’re an accomplished or even occasional scripter, you probably know most of this.

Assuming that you (the reader) don’t have time to learn AppleScript right now, but that you really want to use a script’s function immediately, let’s start with a script. Suppose you knew that you had hurriedly entered a person’s name and number in your address book sometime in the previous month, but didn’t now recall their name. That never happens to me, of course, but it’s ridiculously easy to do when on the phone – who was that guy? Combing through all of your Address Book entries is a bit tedious, particularly if you had, in your haste, not assigned it to a group, so you Google around and find this simple script to do it. I just wrote it, so you won’t find it if you look. It not only shows all the names recently entered (you are asked to define “recently”) but also returns the phone number or numbers by label (work, home, etc.) for the a name you recognize and pick from a list:

-- Get the required time span counting back from today
set {T, B} to {text returned, button returned} of (display dialog "How far back in time?" & return & "Enter a guess in weeks" default answer "5" buttons {"Cancel", "Entry Date", "Last Changed"} default button 3)
set tDate to (current date) - (T * weeks)
-- Query the Address Book for names
tell application "Address Book"
	if B is "Entry Date" then
		set tNames to name of every person whose creation date > tDate
	else
		set tNames to name of every person whose modification date > tDate
	end if
	-- Offer a choice from those found in the span
	set Who to choose from list tNames with prompt "Choose a name or cancel"
	-- Use the name chosen to get the phone number or numbers by label
	set Ph to {label, value} of phones of (first person whose name is Who as string)
	-- Build a message to me
	set Msg to "Phone Numbers" & return & return
		repeat with k from 1 to count item 1 of Ph
		set Msg to Msg & item k of item 1 of Ph & ": " & item k of item 2 of Ph & return
	end repeat
	-- Tell me
	display dialog Msg
end tell

Steps to Use the Scripts

  • 1) [b]Find your Script Editor Application:[/b]

    If you don’t already know where it is, then in Tiger use spotlight to to search for it and select it there to open it. If you are an earlier system, find a folder named “AppleScript” in your Application folder and within it, double click the Script Editor.app.

  • 2) [b]Move the Script to the Script Editor[/b]
    • * If the script is in the window of a browser that supports drag and drop, you can select the whole thing and drag it to the Script Editor's top pane.
    • * If the script won't drag, you can copy the entire text of the script and paste it into the upper pane of the Script Editor window open on your desktop.
    • * If you find the script in [url=http://bbs.applescript.net]bbs.applescript.net[/url], it will be enclosed in a box at the top of which you'll find an orange right angle bracket ( [b]>[/b] ), followed by a link in blue that says: "Open this Scriptlet in your Editor". Click on it, and the link will open your script editor for you and with your permission, load the script into the top pane of the Script Editor window.
  • 3) [b]Compile the Script[/b]

    Click the compile button in the toolbar of the Script Editor window and the script should colorize (called “pretty printing”) if all is well. If it does not then either it’s a bad script, or it hasn’t been correctly copied. There may be a pause while the Script Editor opens any application to which the script sends instructions that is not currently running on your machine. This will always happen because the script must first get the scripting dictionary from the application in order to compile the script’s instructions to that application.

  • 4) [b]Test the Script for Function[/b]

    With the application set up to do what you expect of the script (in the case of the one above, you don’t have to do anything), click the run button in the toolbar of the Script Editor window to be certain that the script does indeed do what you wanted. If it is satisfactory, save it. (described in more detail in next item).

  • 5) [b]Save the Script[/b]

    In the Library folder of your Home folder, you’ll find a folder named “Scripts”. The easiest way to get there in the Finder is to press Shift-Command-G to open the “Go to Folder” window, and in it enter “~/Library/Scripts/” (where the tilde~” is found under the escape key on most keyboards). “tilde-slash” is Unix shorthand for your Home folder.

    • * Some applications support a Scripts menu (looks like the script icon you see in the Script Editor application icon: ) in their menu bar (the Address Book does not). The next section describes how to set up a Script Menu and have it reveal scripts only when the Application they apply to is active.
    • * There is also a system-wide script menu that displays all the scripts in your Scripts folders, including any that occur in the system-wide Library's Scripts folder (at /Library/Scripts, for Go to Folder). Scripts placed in /Library/Scripts are available to any user of the machine while those in your users library scripts folder are yours alone. The next section of this tutorial deals with showing and organizing the contents of those menus.
[b]Showing the Script Menu in Your Menu Bar[/b]

If you don’t have a script menu in your menu bar (it looks like this : and will appear in the right-hand set of icons on your menu bar inward from the spotlight icon and time/date display if it shows) then you can get one by going to the AppleScript folder in your Applications folder and running the application called “AppleScript Utility” (icon shown below) and in its window checking “Show Script Menu in menu bar”.

[i]The AppleScript Utility Application Icon[/i]

If at this point, you don’t have any other scripts in your ~/Library/Scripts folder, you can either organize it yourself, or let Apple do it for you by downloading and running the scriptlet obtained by clicking this link {Setup Script Menu.app} to download it. If you run this with some scripts already in your Scripts folder, then move them as necessary to the new folders this applet created for you.

If you prefer to organize your own script menu, the process the scriptlet helps with is as follows:

  • 1) Go to /Users/Username/Library/Scripts/ and check for a folder called "Applications". If it doesn't already exist, create it.
  • 2) In this Scripts folder "Applications" folder, create a subfolder called "Address Book" (the subfolder's name should be spelled exactly the same as the application).
  • 3) Finally, place your Address Book script(s) (like the one above) in this Address Book folder.
  • 4) Repeat steps (2) & (3) for any other applications for which you have application-specific scripts.

What Have We Wrought?

At this point, assuming you’ve done as outlined here, you’re ready to use scripts that you find for tasks you’d like to do but can’t script. AppleScripts are fairly easy to read, so I recommend that you read them before trying them. In particular, pay attention to scripts that contain the phrase do shell script followed by stuff you don’t understand. In particular, do shell script “rm …” is a script to irretreavably delete something. Don’t go there if you don’t understand what’s going to happen – you have the power in a script you run to delete your own home folder.

Finally, if you’ve organized your Scripts folder as outlined, then when you look in the Script menu with Address Book running, you’ll see it’s folder, and this script. After you’ve seen what scripting for you, you might consider learning to write them (or modify those by others) yourself. Here’s a set of links to tutorials in MacScripter.net/unScripted/ by Craig Smith, one of the Principals of MacScripter, which read in the order below are an excellent place to start:

  • [url=http://macscripter.net/articles/415_0_10_0_C/]AppleScript Tutorial for Beginners I - Getting Started & Script Editor[/url]
  • [url=http://macscripter.net/articles/428_0_10_0_C/]AppleScript Tutorial for Beginners II - Variables and Dictionaries[/url]
  • [url=http://macscripter.net/articles/434_0_10_0_C/]AppleScript Tutorial for Beginners III - The Power of Lists[/url]
  • [url=http://macscripter.net/articles/445_0_10_0_C/]AppleScript Tutorial for Beginners IV - Records & Repeats[/url]
  • [url=http://macscripter.net/articles/452_0_10_0_C/]AppleScript Tutorial for Beginners V - Testing & Shorthand[/url]
  • [url=http://macscripter.net/articles/458_0_10_0_C/]AppleScript Tutorial for Beginners VI - User Interaction[/url]
  • [url=http://macscripter.net/articles/463_0_10_0_C/]AppleScript Tutorial for Beginners VII - Errors[/url]
  • [url=http://macscripter.net/articles/467_0_10_0_C/]AppleScript Tutorial for Beginners VIII - Getting the Drop on Droplets[/url]

Happy Scripting