This first tutorial should give you answers to:

1. How do I install scripts and use the Scripts menu?
   
2. How can I use a function script in a spreadsheet?
   
   

This tutorial lesson only uses prepared scripts, without opening them or exposing any of the inner workings. So, even if you never want to type a line of “code”, this lesson is for you. Upcoming tutorial lessons will look at the code in prewritten scripts, and then cover the script development process so you can create your own scripts from scratch.

You do not have to write any code to use an existing script, so do not fear that AppleScript’s amazing powers are only for programmers. Installing a script is a simple drag and drop operation.

A script can be executed in a number of ways. For now we’ll focus on using scripts in an application’s Scripts menu. Many scriptable applications (such as Mail, AppleWorks, Outlook Express and Interarchy) have a Scripts menu. The Scripts menu generally appears just to the left of “Help” in the menu bar, as an icon that looks like a paper scroll (see Figure 1).

	Figure 1: The Scripts Menu

The Scripts menu is a convenient place to store your scripts, written by yourself or others. It lists the contents of a corresponding scripts folder. You can add, delete or rename script files in that folder to change the menu items. You can change the folder structure to alter the corresponding structure of the menu, as each sub-folder creates a sub-menu.

AppleWorks 5 dynamically updates the Scripts menu when the contents of Scripts folder is altered. Unfortunately, AppleWorks 6 requires a relaunch to update its Scripts menu.

Exercise 1: Installing “Enhancement Pack” Scripts

Let’s install some scripts to add some menu items to AppleWorks. If you have previously installed the Enhancement Pack, skip this exercise. Otherwise, follow these steps, which copy some scripts into AppleWorks’ Scripts folder, so they appear in its Scripts menu:

1. If you have not already done so, download the Enhancement Pack for AppleWorks.
   
2. Confirm that the “Enhancement Pack” folder is decompressed (ie it is a folder that you can open). If it is still a .sit file, decompress it by dragging it onto Stuffit Expander.
   
3. The uncompressed “Enhancement Pack” folder should contain an “Installer” application. Open it (eg by double clicking).
   
4. The installer should display an information dialog. Click its “Run” button.
   
5. If it asks you to locate your copy of AppleWorks. Do so.
   
6. The installer should take a short while to install the scripts then display a dialog to tell you that it was successful.
   
7. If AppleWorks 6 was running when you installed the scripts, then you need to quit and relaunch it to refresh the Scripts menu.
   
8. If you have any trouble, refer to the ReadMe document in the Enhancement Pack folder and the Troubleshooting page.
   
   

Exercise 2: Showing Installed Scripts

Let’s look at the installed scripts.

1. Open your AppleWorks Scripts folder. The easiest way to do this is to launch AppleWorks and select “Open Scripts Folder” in the Scripts menu, as shown in Figure 1.
   
2. Locate the “Small Caps” script file in the AppleWorks “Scripts” folder (AppleWorks 5’s Scripts folder is instead named “AppleWorks Scripts”). You may need to expand the “Text” folder to see the Small Caps file, as shown in Figure 2. Don’t open it, just check that it’s there.
   
   

   	Figure 2: A Script in AppleWorks’ Scripts Folder.

   
   
   

Every script you install in the Scripts folder adds a menu item to the Scripts menu. You can select this new menu item like any other, effectively using a new application feature.

Exercise 3: Running Small Caps in the Scripts Menu

Try this exercise that uses the Small Caps script to format some text.

1. Switch back to AppleWorks. Create a word processing document and type a sentence. (The effects will be best shown if you use a large font size, such as 18 or 24 point.)
   
2. Select a series of words in the text.
   
3. In the Scripts menu, select “Small Caps” (see Figure 3).
   
   

   	Figure 3: Select Small Caps in the Scripts Menu

   
   
   

4. Check that the script formats the selected text as small caps, similar to Figure 4. Each lowercase letter is converted to a smaller font size, but in uppercase (capitals), “small caps”.
   
   

   	Figure 4: Results of Small Caps Script

   
   
   

The previous examples showed how you can attach a script to a menu (the Scripts menu), where the script is initiated whenever you activate its menu item. Some applications allow you to attach a script to user interface elements other than menus. For instance, in AppleWorks you can also attach a script to a calculation, so that the script runs whenever the calculation is performed. The calculation might be part of a spreadsheet cell or database field formula. It can simply produce a numeric or text result for display in the cell or field, or the script can display an alert, draw a line, move a file or any other task. At this stage, we’ll look at the simplest purpose of a script function, performing a calculation and returning a numeric result.

A script attached to a formula is called a script function or custom function. In AppleWorks, a script function is called from the built in “MACRO” function (which, confusingly, has nothing to do with macros in this context). The general form of the MACRO function to call a script is:

MACRO("Script File Name", 2, "handler name", parameter1, parameter2, ...)

Thankfully, the Enhancement Pack can write out this function for us, so I won’t explain the inner workings at this stage, just how to attach a script to a calculation.

Exercise 4: Using the “Rank” Script Function

AppleWorks’ list of built in spreadsheet functions includes many statistical calculations, but lacks a function to give the rank of a given value in a data set. For instance, in a set of scores, if a score ranked 5th, means that it has the 5th incremental value, a rank of 1 means the lowest value.

In this exercise, we’ll use a “Rank” custom function that uses an attached script to calculate the result.

1. Create a new AppleWorks spreadsheet and enter the data in Figure 5.
   
   

   	Figure 5: Spreadsheet with Sample Data

   
   
   

2. In another cell (in our example, in cell C2), enter an “=” sign, and leave the cursor flashing (ie don’t hit Enter yet and don’t switch to another program until you’ve finished the formula).
   
3. In the Scripts menu, select “Function...”.
   
4. It will show you a list of functions. Choose the “Rank” function.
   
5. Check that the cursor is still flashing in the spreadsheet cell, containing an “=” sign. Paste in the Rank function (eg by selecting “Paste” in the “Edit” menu). But don’t hit Enter yet.
   
6. Select the parameter “valueToRank” (eg by double clicking it) and type the number 5 in its place.
   
7. Select the parameter “withinCellRange” (eg by double clicking it) and then select your previously entered data range (by dragging from the first to the last cell). It should replace the parameter with your data’s cell range (A2..A8 in our example. So your formula should look like this:
   
   =MACRO("Rank",2,"calculate",5,A2..A8)
   
   
8. Press the Enter key. AppleWorks will calculate the results using the attached script, and display 6 in the calculation cell (cell C2 in our example). See Figure 6. This indicates that the score of 5 was 6th incremental value (ie 6th when counting from lowest to highest value) in our sample data.
   
   

   	Figure 6: Raw Data and Linear Regression Results

   
   
   

Try these supplementary tasks:

1. Try changing the “valueToRank” value in the previous exercise, from 5 to any other number in the list of scores. Confirm that the calculation is what you expect.
   
2. Try adding another rank calculation, for a different value than the first.
   
3. Change one of the raw data scores (in column A in our example). That will force all the script functions to recalculate. AppleWorks reruns the Rank script for each occurrence in the spreadsheet. You should see that it runs fairly rapidly.
   
4. Open the “Script Function Samples” document provided with the Enhancement Pack. To locate it, select “About Enhancement Pack” from the Scripts menu, click the “Document” button, then the “Script Function Samples” link. (Or locate it directly in the Finder at: AppleWorks 6/ AppleWorks Essentials/ Scripts Support/ Documentation.) Experiment with some of the other script functions there.
   
5. Try using some of the other Enhancement Pack scripts, from the Scripts menu. For more information on each, read the detail in the “About Enhancement Pack” document (access from the Scripts menu) and its “Enhancement Features” link, or the web site.
   
   

As a script user, you only need to know what the script does and how to run it, such as selecting it in the Scripts menu or referring to it from a spreadsheet formula. Up to this point in the tutorial series, the exercises have covered using scripts. If you only want to use existing scripts without customizing, then you can stop this tutorial now. However, I suggest that you continue through this series to discover how to make AppleScript work for you by writing your own scripts.

---

Now, you can continue on to Tutorial 2, where we will open a script to see what makes it tick and customize it to work slightly differently. We will also save a script as an application that we can run just by double clicking in the Finder.

---