kworks: Using AppleScript for AppleWorks 6

As many users are uncomfortable with AppleScripts, I wrote this note.
Thanks to those who give me help or advices.

Some of them are Dale Gillard, Gene Von Troyer, Barbara Brundage and Niel Lambert who re-read the last version.

Yvan KOENIG (from FRANCE)

-+-+-+-+-+-+-

AppleScript and AppleWorks

As you certainly know, when it was modified to become compatible with Mac OS X, AppleWorks 6 lost its macro feature. So, some of us decided to use the other tool allowing one to automate some actions, I'm speaking of AppleScript.

The macros were beloved by many users because one may create some of them without any kind of learning process.
AppleScript is often more powerful but one must learn a language to write the wanted script.

Happily, some authors write scripts and make them available for free. So, many users just have to know how they may use available scripts.

I met four kinds of scripts that we may have to interface with AppleWorks.

A -- The first ones are scripts which are used mainly as enhancements to AppleWorks, like my "WP TOC" one.

You just have to paste the source file in a new script window in the Apple's Script editor, and click the button "compile."

Then go to the menu "File > Save as..." and choose the format "Compiled script" or "Application" more often with the two available checkboxes UNCHECKED.

It's boring but the Apple's "Script Editor" available under Mac OS X 10.2.x generates "compiled scripts" which are not usable by AppleWorks.
One must generate "compiled scripts" from Mac OS 9 or use a FREE third party editor named SMILE which allows us to choose the format of the generated "compiled scripts".

You may also save the scripts as "applications".

Even if it is not absolutely required, it's of good practice to store these scripts in the AppleWorks's dedicated folder: "AppleWorks 6:AppleWorks Essentials:Scripts". You may create subfolders in this folder. My own setting is made of subfolders: "WP", "SS", "DB", "DR" for scripts related to WP, SS, DB or DR documents. No need for "PR" or "PT" as AppleScript is unable to deal with these kinds of documents.

When stored in these folders or subfolders, scripts are available from the AppleWorks's script menu, the one with a small icon.

One may also link a script to a keyboard shortcut or to a function key.

One may also link one to a button for the button bar.

B -- The second ones are scripts called from the spreadsheets by the MACRO() function. I apologize but Apple guys removed the help about them from the help files available under OS X. I put it at the end of this document.
I already posted scripts of this kind here and there ("mediane" is one of them).

They are saved and stored as the first ones, but a detail changes.

If they are stored in the "AppleWorks 6:AppleWorks Essentials:Scripts" folder, the calling syntax is something like: =MACRO("mediane",2,"boulot",firstCell..lastCell) but, if as I make, you want to put them in a subfolder, the syntax must looks like:
=MACRO(":subfolder:mediane",2,"boulot",firstCell..lastCell) (DON'T FORGET the 1st colon).

C -- The third ones are scripts which one uses exactly as a standard application.

You just have to paste the source file in a new script window in Apple's Script Editor, and click the button "compile."

Then go to the menu "File > Save as..." and choose the format "Application" more often with the two available check boxes UNCHECKED.

When one wants to use one of these scripts, he just have to double-click its icon or, sometimes, to drag and drop the icon of the object on which the script will apply on the script's icon.

D -- The fourth ones are "folder action scripts" working for AppleWorks.
One of them is my own "Trash Recent Items AW".

As their use is slightly more complex, I will explain it for each operating system separately.

-+-+-+- From Mac OS 8.6 to 9.2.2

Just compile in the AppleScript Editor and store as "compiled script" in the "System Folder.:Folder Action Scripts" folder.

To attach the script to a folder, AW's "Recent Items"'s one for instance,
click the "Recent Items" icon while holding down the Control key, and the Contextual Menu that opens should display "Attach a Folder Action".

Select that to link the script to the "Recent Items" folder.

With these "old" operating systems, an action script won't work if the
folder is closed. You can collapse the folder window to just the Title
Bar.

You may also search for a 16K extension file named "Folder Actions Plus" which allows folder scripts to work on closed folders.
<http://macscripter.net/tools.html#t9>

-+-+-+- Under Mac OS X (10.2 ... )

Just compile in the AppleScript Editor and store it as "compiled script" in the Folder Action Scripts folder located in "Library:Scripts:Folder Action Scripts".

If you don't have the "Scripts Menu" installed, go to "Applications:AppleScript:Script Menu.menu" and double-click "Script Menu.menu" to install the Menu Bar script menu icon.

To attach the script to a folder, AW's "Recent Items"'s one for instance, go to the menu "Script Menu > Folder Actions > Attach Script to Folder". A dialog box opens allowing you to select a script that you want to attach to a folder. A second dialog box will open allowing you to select the target folder.

-+-+-+- Under Mac OS X (10.3 ... )

Just compile in the AppleScript Editor and store it as "compiled script" or as "application" in the Folder Action Scripts folder located in "Library:Scripts:Folder Action Scripts".

Control + click on folder's icon. You will get a contextual menu.
Select "Enable Folder Actions" item to activate the Folder Actions feature.

Select "Configure Folder Actions" item to attach the script to the folder.

-+-+-+-

It may be useful to read "AppleScript Usage Notes" delivered with AppleWorks.

Yvan Koenig

Addenda:

1 -- was in the "Late-breaking news" file:

AppleScript issues

Using AppleScript with AppleWorks
You can use AppleScript to automate and extend many AppleWorks features. AppleWorks 6 includes several useful scripts. These scripts, and information about how to use them, are in the Scripts folder within the AppleWorks 6 folder.

Using the Activate command in the Script Editor
When working with AppleScripts, avoid running a script from within the Script Editor application if the script includes a command to activate AppleWorks.

For best results, run the script
¥ from the Script Editor, but send events to AppleWorks in the background (avoid the Activate command)
¥ from within AppleWorks using, for example, a Button Bar button or the AppleScript menu
¥ as a standalone AppleScript applet

2 -- MACRO (the missing OS X help)

Use MACRO to

¥ execute a button (the same as clicking it)
A button can play a macro, open a document, start another application, go to a specific page on the World Wide Web, or execute a script.
¥ execute an AppleScript or any script that complies with the Open Scripting Architecture (OSA)

Format:
¥ for buttons: =MACRO(name,type)
¥ for scripts: =MACRO(name,type,subroutine,...)

Arguments:
¥ name: the exact name (case-sensitive) of the button, or script, enclosed in quotation marks
¥ type : a number that indicates what to execute
¥ 1: execute a button
¥ 2: execute a script
¥ subroutine: the name of the subroutine to execute, followed by required parameters. Separate additional parameters with commas.

MACRO returns a value indicating the result:

For MACRO returns When
Buttons 0 AppleWorks executes the button
#N/A! AppleWorks can't find a button by that name

Scripts the result of the AppleWorks executes the
script script
#N/A! AppleWorks can't find a script by that name
#SCRIPT! AppleWorks encounters an error executing the script
#USER! the script returns an error value

Example: =IF(D7>65, MACRO("Pass",1), MACRO("Fail",1))

If the value in cell D7 is 65 or greater, this formula executes a button called "Pass." If the value in cell D7 is 64 or less, the formula executes a button called "Fail."

Tips:

¥ To see the names of buttons, choose Preferences from the Edit menu, then choose Button Bar. Type the button name exactly as you see it in the list.

CAUTION

Sometimes it may be interesting to put the script in the System's Script menu.

This is mainly useful for some using GUIscripting which fails when launched from the AppleWorks own Scripts menu.
When installing in this menu, use Compiled Scripts because Applications ones are scanned by the system which try (and fail) to prebind them.