Script a File

Script-A-File User Guide

Software and documentation by Danny Goodman

Š1994 by Danny Goodman and Ziff-Davis Publications. All Rights Reserved.

Thanks to Greg Quinn for permission to include the GTQ OSAXen (scripting additions) with this product.
============================================================
COPYRIGHT, WARRANTY, AND LICENSES

This utility is copyrighted. Distribution is limited to Ziff Communications online services and electronic publishing projects. You may not post this utility to any other online service, network, or bulletin board. Making copies for any commercial purpose is prohibited. This utility is NOT public domain or shareware.

The following provisions apply to the FaceSpan runtime code contained in the Script-A-File application. This runtime code is (c) copyright 1994 Software Designs Unlimited, Inc.

This software contains copyrighted material, trade secrets and other
proprietary material. You may not decompile, reverse engineer or
disassemble this software.

You expressly acknowledge and agree that use of this software is at your sole risk. The software is provided "AS IS" and without warranty of any kind. Danny Goodman, Ziff Communications, Apple Computer, Inc., and Software Designs Unlimited, Inc. expressly disclaim all warranties, express or implied. They do not warrant that the functions contained in the software will meet your requirements, that the operation of the software will be uninterrupted or error-free, or that defects in the software will be corrected. Furthermore, they do not warrant or make any representations regarding the use or the results of the use of the software in terms of its correctness, accuracy, reliability or otherwise.

Under no circumstances, including negligence, shall Danny Goodman, Ziff-Davis Publications, Apple, or Software Designs Unlimited be liable for any incidental, special or consequential damages that result from the use or inability to use the software, even if they have been informed of the possibility of such damages.
=============================================================

Table of Contents:
OVERVIEW
KNOWN INCOMPATIBILITIES
SYSTEM REQUIREMENTS
COMPONENT FILES AND INSTALLATION
QUICK TOUR
TIPS AND TECHNIQUES
REFERENCE
TROUBLESHOOTING
FOR FURTHER EXPLORATION
HOW SCRIPT-A-FILE WORKS

OVERVIEW
Script-A-File is a utility program that puts the power of AppleScript to work for you without you having to write a word of AppleScript. Script-A-File creates dropletž applications that modify Finder-level characteristics of whatever files and/or folders you drop onto them. You determine the behavior of these modifications by way of the Script-A-File application, in which you click on various settings.

For example, you can instruct the droplet to create aliases in the Apple Menu Items folder for any item(s) you drag onto the droplet. Other types of operations include file or folder copying, moving, renaming (including searching and replacing file name characters and prepending or appending text or dates), and, with the scriptable Finder, setting Finder comments, file type and creator, and application memory partition sizes.

IMPORTANT: As with using any file management utility program, you are advised to maintain current and complete backup copies of your hard disks before using any Script-A-File droplet. Read the Copyright, Warranty, and Licenses section, above.

KNOWN INCOMPATIBILITIES
We have made every effort to test Script-A-File with a variety of hardware and software configurations. The only known conflict with the scriptable Finder routines in Script-A-File is with a utility called CopyDoubler, which processes Finder file copying as a background process. If you use Script-A-File to generate droplets that move files, copy files, or create aliases via the scriptable Finder, turn off CopyDoubler prior to dropping items on the droplet.

SYSTEM REQUIREMENTS
Macintosh running System 7.1 or higher
AppleScript version 1.1 runtime software
GTQ Scripting Library 1.2 (included)
(Optional) Scriptable Finder*

*(Consists of Finder 7.1.3 or later and Finder Scripting Extension)

AppleScript 1.1 runtime software is available from a number of sources. It is packaged with Apple's System 7 Pro retail package of system software. AppleScript runtime software also comes with a number of software programs that support AppleScript, such as HyperCard 2.2. Runtime software is also available as part of Apple's AppleScript Scripters Kit (available from retail and mail order dealers) and the AppleScript Developer's Kit (available from APDA). The software is also on the disk accompanying the 2nd printing of The Complete AppleScript Handbookž by Danny Goodman ($35.00 from Random House, ISBN 0-679-79148-5).

The optional scriptable Finder is available now only as part of the AppleScript Developer's Kit (APDA). Current plans from Apple are for all AppleScript runtime and scriptable Finder software to be part of the next release of system software (version 7.5). You can use Script-A-File today without scriptable Finder, and later use Script-A-File with the scriptable Finder when it is installed in your Mac.

COMPONENT FILES AND INSTALLATION
Script-A-File consists of numerous files, most of which are installed out of harm's way. In the unstuffed folder are the following items:

Script-A-File application
Droplet Template
User Guide (the file you're reading)
GTQLibrary

The Script-A-File application is where you'll be doing all your work to specify the actions of droplets. When you finish specifying the behavior of a droplet, Script-A-File peels off a copy of the Droplet Template and saves it wherever you wish. The Droplet Template file is never modified, and it should be located in the same folder as Script-A-File.

If you are not now using the scriptable Finder, we recommend that you manually move or copy a file named finderLibž from the Scripting the Finder folder (inside the AppleScript Utilities folder) to the Scripting Additions folder (inside the Extensions folder). This will prevent droplets from asking you to locate the finderLib file the first time they run.

Before using Script-A-File, you must install the scripting additions from the GTQ Scripting Library.* Open the folder GTQScriptingLibrary1.2ž inside GTQLibrary,ž select all of the files within and drag them into your Scripting Additions folder, which is located inside your Extensions folder.

Script-A-File uses this collection of scripting additions, created by Gregory T. Quinn, for many of its operations. These scripting additions have been licensed by Gregory Quinn to ZiffNet/Mac for distribution with Script-A-File. They may be re-distributed only in the same form in which they appear here, complete with documentation and sample scripts. For more information, see the enclosed documentation or contact Gregory Quinn (e-mail address: gregq@gordian.com).

*(A scripting addition, or OSAX, is a file which AppleScript uses to expand its vocabulary.)

QUICK TOUR
In this quick tour, we will create a droplet whose job is to create an alias file on the desktop for any folder that is dropped onto it.

1. Start Script-A-File.
The Script-A-File window appears. You may turn on Balloon Help at any time to help you learn the functions of any button or field in this window.

2. (Optional) If you have the scriptable Finder installed in your system, choose Scriptable Finder from the File menu.
The item will be checked in the menu, and some additional items that are normally dimmed in the window become active (because they are available only with scriptable Finder).

3. Click the Folders Only radio button.
We want this droplet to work only with folders, so we can narrow the behavior of the droplet with the choices at the top of the Script-A-File window. Since this droplet is to work only on the folder we drop on it, and not its contents, we'll leave the top checkbox about nested items unchecked.

4. Click on the latch icon to the right of the Move/Copy/Alias checkbox.
The Script-A-File window opens to reveal more settings that apply to moving, copying, and aliasing files.

5. Click the Aliasž radio button in the Action column.

6. Click the Desktopž radio button in the group of buttons signifying possible destinations.

7. Check the Move/Copy/Alias checkbox to tell Script-A-File that you want the actions detailed below to become part of the droplet's behavior.

8. Click the latch icon to the right of the Renamež checkbox.
The items for Move/Copy/Alias disappear, and a new set of choices for renaming files appear. In this droplet, we want to remove the word aliasž from the name of alias file.

9. Check the Replace Stringž checkbox.
The items beneath the checkbox become active.

10. Into the Replace:ž field, type a space and the word aliasž (without the quote marks).
Because we want to replace this text with nothing, leave the With:ž field blank.

11. Check the Rename checkbox near the latch to tell Script-A-File to include the Rename specifications in the droplet.
You may click the latch icon to close up the window, but it is not necessary.

12. Either click on the Save Droplet As...ž button or choose Save Droplet As...ž from the File menu to start the droplet building process.

13. Use standard file dialog navigation to reach a folder level where you'd like your new droplet to appear.

14. Enter a name for the droplet, such as Alias Folder to Desktop.ž
Because you may eventually create many of these droplets throughout your system, it is important that you provide a name that sufficiently describes what the droplet does so you can identify it later in the Finder.

15. Choose Quit from the File menu.

16. Drag a folder of your choice to the Alias Folder to Desktopž droplet you just created.
The droplet will place an alias to the item on the desktop. You may have to close or move Finder windows to see the alias.

TIPS AND TECHNIQUES
1. When defining the behavior of a droplet, think through carefully about the types of files and/or folders you wish your droplet to process. Beyond decisions about files or folders and whether the droplet should process items nested within a dropped folder, click the Set...ž button to make additional choices to narrow the behavior of the droplet, if appropriate. For example, to limit actions to just applications, click the Set...ž button to reveal the Selection Criteria window. To limit actions to an application, first click the Type isž checkbox; then click the Same As...ž button to help you locate any other application; Script-A-File then fills in the four-character file type (APPL) for you; click the OKž button, and see how the definition applies to the droplet under construction.

2. When multiple actions are selected (e.g., Copying and Renaming), all operations are performed in a very specific sequence to help you plan the outcome of the droplet's actions. Here, in the order in which actions are carried out, is the complete sequence if all possible checkbox actions were engaged:

Move/Copy/Alias
Rename: Replace String
Rename: Insert at Start
Rename: Append to End
Set Attributes: Set File Comments
Set Attributes: Set file Type
Set Attributes: Set file Creator
Set Attributes: Set Application Memory Partitions

The primary implications are in the renaming processes, particularly when name insertions or appendages would cause the filename to be longer than the allowed 31 characters (see Rename in the Reference section for more information).
Additional implications include the fact that each action works only on the items that resulted from the previous action. For example, if your droplet first copies all items from a dropped folder to the System Folder, the renaming steps that follow apply to the copies of the files now in the System Folder (not the originals).

3. You can use Script-A-File to create droplets that other users can put to work on their Macs (but be careful not to invoke options that call for specific folder names, which will probably be different on someone else's Mac). In fact, if you don't have the scriptable Finder installed in your Mac, you can direct Script-A-File to build a droplet that utilizes the scriptable Finder. When you build the droplet, Script-A-File detects that you are specifying Scriptable Finder in the File menu, but you don't have it installed on your Mac. You may instruct Script-A-File to continue building the droplet to work with the scriptable Finder. Other users of a droplet who don't have scriptable Finder must have the AppleScript runtime software and the GTQ OSAX files installed on their Macintoshes.

4. You may open an existing droplet file to make modifications or alternate versions as you see fit. To open an existing droplet, start Script-A-File, and choose Open...ž from the File menu. Droplets are real applications and are therefore not truly documents belonging to Script-A-File.

REFERENCE
In this reference section, we first detail the functions of menus, followed by description of each button (or button group) and text entry field.

File Menu/New
Returns all settings in the Script-A-File window to their default, empty settings. After choosing this menu item, the window's titlebar reads Script-A-File.ž You need to use this command only if you have opened or just built a droplet, and wish to define a new droplet.

File Menu/Open...
Lets you open an existing droplet file of your own creation. When a droplet is open, its name appears in the window's titlebar. To edit an existing droplet, make whatever changes you like to the settings, choose Save Droplet As from the File menu, and replace the old droplet with the new one of the same name.

File Menu/Scriptable Finder
Toggles between whether the next droplet you build is to work with a scriptable Finder. You don't have to be running scriptable Finder to build a droplet for someone else who has scriptable Finder: simply choose this menu item until it has a checkmark next to it. When building the droplet, you will be advised again that you don't have scriptable Finder installed in your machine, and you are about to build a droplet that requires scriptable Finder. Conversely, if you have scriptable Finder installed on your machine, you may create droplets that don't use scriptable Finder by unchecking this menu item.

File Menu/Save Droplet As...
The same as the Save Droplet As button in the window, this leads to a standard Save As file dialog, letting you name the droplet and determine where the droplet should be saved.

File Menu/Quit
Quits Script-A-File.

Edit Menu/Cut, Copy, and Paste
Behave as you'd expect for editing text inside text entry fields within Script-A-File.

Process Buttons (Files Only; Folders Only; Files & Folders)
Here you instruct the droplet what kinds of items to act upon. Because you may drop a folder containing any combination of files and folders, you can elect to limit the droplet's actions to one of these types of items. If you drop a group of files upon a droplet whose actions are designated for folders only, an alert advises you that no items were selected for processing.

Process Checkbox (Items Nested in Folders)
In the event you drop a folder of items onto your droplet, and that folder itself contains other folders, you may wish the droplet to drill downž through the nested folders in search of items to process. If so, check this box. When you turn on this option, Script-A-File builds a list of items all the way to the bottom of the most deeply nested file. In other words, the folder hierarchy is not maintained in this mode--all items are treated as equal citizens for all operations. If you uncheck this box, and you choose to move or copy a folder, Script-A-File moves or copies the folder and its contents, just as if you were moving or copying manually in the Finder. Subsequent operations in the same droplet (e.g., renaming, setting attributes) affect only the moved or copied folder, not their contents.

If an Itemĺs...ž Field
This field displays in plain language the results of choices made in the Selection Criteria window, which is triggered by clicking the Set... button to the right. The default value is to work on all items that are dropped onto the droplet, within the confines of the files/folders choices made with the Process radio buttons, above.

Set... Button
Displays the Selection Criteria dialog box, which allows you to instruct the droplet to narrow its action by one or more of the following criteria:
File Type
Creator Signature
Name
Creation Date
Modification Date

In the Selection Criteria window, each of these criteria is preceded by a checkbox. You may check one or more items to narrow the choices.

For File Type and Creator, four-character identifiers are required. If you don't know these identifiers, click the Same As... button to the right of the field to locate a file of the Type or Creator you wish the droplet to process; the four-character identifiers will be filled in for you.

To designate a file name, choose first from the pop-up list of how the wording you type in the right-hand field appears in the actual files or folders (Is or Contains). For example, to work only on items that have aliasž in their names, choose Contains in the pop-up list, and type aliasž into the field to the right.

For Creation and Modification dates, first choose whether the items' dates are the same as, before, or after the date you enter into the field to the right. Enter the desired date in the SHORT DATE format based on your Date & Time control panel setting. In the U.S., this is usually mm/dd/yy. For example, to work on items whose modifications dates are after September 11, 1994, choose Is After in the pop-up list, and enter 9/11/94 into the text field.

Click the OK button in the Selection Criteria window to apply the settings to the droplet under construction. Click Cancel to ignore any changes you may have made in the window. To edit these settings later, click the Set button in the Script-A-File window.

Move/Copy/Alias Checkbox and Latch
When the checkbox is checked, any settings in the Move/Copy/Alias settings panel (described next) are applied to the next droplet you build. No matter what settings you make below, they will be built into the droplet ONLY if this checkbox is checked prior to building the droplet.

The Latch is like the one in the Alarm Clock desk accessory. Click it once to lower the latch. The Script-A-File window expands to reveal choices available for moving, copying, and creating aliases for items dropped onto the droplet.

Move/Copy/Alias Item(s): Action buttons
Choose the action to be carried out upon items that survive the filtering of the Process buttons and Selection Criteria window. You may choose only one of the three possible actions in this group. You may move items only on the same hard disk volume. Copying works across mounted disk volumes (or servers). When the droplet creates an alias, its default behavior is to create the alias with the original name of the item plus the word alias,ž just as the Finder does, even if you direct the droplet to create the alias in another folder than the original (but see the example in the Quick Tour about how to program the droplet to remove the alias word). As with the Finder, if adding the word aliasž to an item name would exceed the 31-character name limit, the droplet removes enough characters from the end of the original name to accommodate the aliasž appendage.

Move/Copy/Alias Item(s): To Folder buttons
For each move, copy, or alias creation, the droplet requires a destination. Radio buttons provide shortcuts to common places around the Mac desktop and System Folder. To specify a folder of your own, click the Other button; a folder dialog appears, allowing you to specify the destination folder, whose pathname appears in the field at the bottom right of the window. To change the custom folder, click on other destination button first, and then re-click on the Other radio button.

Rename Checkbox and Latch
When the checkbox is checked, any settings in the Rename settings panel (described next) are applied to the next droplet you build. No matter what settings you make below, they will be built into the droplet ONLY if this checkbox is checked prior to building the droplet.

The Latch is like the one in the Alarm Clock desk accessory. Click it once to lower the latch. The Script-A-File window expands to reveal choices available for renaming items dropped onto the droplet.

Rename Item(s): Replace String
When this checkbox is checked, the text fields immediately below become active. You may specify a single search string and (optionally) a single replace string per droplet. For example, to replace all left bracket characters with a left curly brace: check the Replace String checkbox; type [ into the Replace field; and type { into the With field. To remove a string from all items that may contain it, enter that string in the Replace field, and leave the With field empty. Be aware of spaces that may affect your search and replace operation, as well as the 31-character item name limit.

Replace operations are performed prior to Insert and Append operations when the droplet is built with these items active. See item two in the Tips and Techniques section, above.

Rename Item(s): Insert at Start of Name
When this checkbox is checked, the radio button choices immediately below become active. You may have the droplet insert: a) any fixed text of your choice (check the String radio button, and enter the text into the field to its right); b) the short date (separated by a space); c) the name of the folder holding the item (enclosed between the ´ and Ş symbols); or d) any text entered by droplet user in response to a prompt for each item (whose name appears in the prompt dialog).

Exercise care in specifying text to be inserted before an item name. You are limited to 31 characters total. If necessary, Script-A-File droplets remove characters from the end of the item name to accommodate any inserted text.

Rename Item(s): Append at End of Name
When this checkbox is checked, the radio button choices immediately below become active. You may have the droplet append: a) any fixed text of your choice (check the String radio button, and enter the text into the field to its right); b) the short date (separated by a space); c) the name of the folder holding the item (enclosed between the ´ and Ş symbols); or d) any text entered by droplet user in response to a prompt for each item (whose name appears in the prompt dialog).

Exercise care in specifying text to be appended after an item name. You are limited to 31 characters total. If necessary, Script-A-File droplets remove characters from the end of the item name prior to accommodating any appended text.

Set Attributes Checkbox and Latch (Scriptable Finder only)
When Scriptable Finder is unchecked in the File menu, this checkbox is not available. Items in this grouping work only with the Scriptable Finder menu item checked (whether or not you have scriptable Finder installed on your Mac). When the checkbox is checked, any settings in the Set Attributes settings panel (described next) are applied to the next droplet you build. No matter what settings you make below, they will be built into the droplet ONLY if this checkbox is checked prior to building the droplet.

The Latch is like the one in the Alarm Clock desk accessory. Click it once to lower the latch. The Script-A-File window expands to reveal choices available for setting attributes for items dropped onto the droplet.

Set Attribute Item(s): Set File Comments To
When this checkbox is checked, the radio button choices immediately below become active. You may instruct the droplet to fill in the Comments field of each item's Get Info window with any one of the following items: a) today's date in short format; b) the name of the item; c) the name of the folder holding the item; d) any string entered by the user as the droplet runs (the prompt displays the name of the item); and e) any fixed text, which you enter into the field at the bottom of the list.

Remember: Get Info comments are erased whenever you rebuild your desktop.

Set Attribute Item(s): Set Finder Info
When this checkbox is checked, the fields and buttons immediately below become active. These fields are for the four-character identifiers that the Finder uses to manage relationships among documents, applications, and their desktop icons.

If you don't know the four-character identifier of the desired file, click the Same As... button and select a file of the same type and creator to which you'd like the droplet to change dragged items. For document files you wish to change, always select an existing document file of the desired type and creator for BOTH settings (don't choose the program, itself, for the Creator field--you want the same Creator as another document generated by that product). For example, to change a folder full of plain text files to Microsoft Word 4, click the Same As... buttons for each setting, and select an existing MS-Word 4 document file both times to show the droplet what to do (the Type and Creator fields would be WDBNž and MSWD,ž respectively).

Set Attribute Item(s): Application Memory
When this checkbox is checked, the items immediately below become active. This choice lets the droplet adjust the two memory partition settings for applications dropped onto the droplet (normally adjusted in the Get Info window). These values are in kilobytes, just as they are in the Get Info window. The Preferred Size value must be THE SAME OR LARGER than the Minimum Size value.

For example, if you want all HyperCard standalone applications you create to have sufficient memory assigned to them to run color, enter 2000 into both of these fields and build the droplet. Then, each time you create a HyperCard standalone, drag the new file to this droplet to adjust its memory sizes. Droplets with this action built in automatically ignore any item that is not an application.

TROUBLESHOOTING
Problem Building a Droplet
Always keep the Droplet Template file in the same folder as Script-A-File. Script-A-File expects it to be there for building any other droplet (no matter where you save the new droplet). Also, droplets occupy approximately 120K of disk space. Be sure you have enough disk space for the droplet you're trying to build.

The scriptable Finder version of Script-A-File and its droplets are incompatible with a utility called CopyDoubler. Temporarily disable CopyDoubler before creating or running a droplet.

Problem Running a Droplet
If the droplet won't run, there is a possibility it needs more memory to function. Since a droplet is an application, you can adjust its memory partition in the Get Info window in the Finder. Remember that if your Mac is running low on memory when you run the droplet, it will give the droplet as much memory as is available between the Minimum Size and Preferred Size. In other words, assigning 1024K as Minimum and 1500K as Preferred doesn't guarantee the droplet will get all 1500K--only if there is a block of that size or larger available.

FOR FURTHER EXPLORATION
Script-A-File is written with FaceSpan, the AppleScript interface builder that comes with Apple's AppleScript Scripters Kit (a retail product) and AppleScript Developer Kit (from APDA only). If you have FaceSpan (or the original version, called FrontMost), you may open up Script-A-File as a project to look inside its objects and scripts.

The Droplet Template is written with Apple's Script Editor, which comes with AppleScript runtime software. You may open the template with Script Editor or third party editor (e.g., Full Moon Software's ScriptWizardĹ) to view its script. Do this only with a copy, however, because any changes you make to the template may make the template inoperable.

HOW SCRIPT-A-FILE WORKS
Script-A-File requires the Droplet Template file, because AppleScript cannot create a droplet style of script from another script (i.e., the scripts running in Script-A-File). Therefore, the solution we chose for this release was to create a template that has the power to perform absolutely every action you can set in Script-A-File--both with scriptable Finder and without (using the GTQ OSAXes and finderLib). As you make choices and entries in the Script-A-File window, it writes the settings to properties stored temporarily in Script-A-File. When you build the droplet, Script-A-File makes a copy of Droplet Template, names it with the name you assigned it, and sets the template-copy's properties to the temporary ones in Script-A-File. The droplet's behavior is shaped by the settings in its own properties--it doesn't need Script-A-File at all.

Unfortunately, this all-in-one-template solution makes for a mighty hairy and scary-looking AppleScript script (although it's nicely compartmentalized into handlers for specific actions). If you like this version of Script-A-File, we will revise it in the future so that it writes just as much script in the droplets as is needed for the actions specified in Script-A-File. This will help scripting newcomers better understand AppleScript and, especially, the scriptable Finder, which will soon be in wide distribution.

Let us know what you think about Script-A-File.

Enjoy!