Guides and Sample Code

Developer

Mac Automation Scripting Guide

On This Page

Processing Dropped Files and Folders

Droplets are applets configured to process dropped files and folders. A droplet is distinguishable from a normal applet because its icon includes a downward pointing arrow, as shown in Figure 17-1.

Figure 17-1A script droplet icon image: ../Art/icon_droplet_2x.png

To create an AppleScript droplet, include an open event handler in your script and save the script as an application. To create a JavaScript droplet, include an openDocuments function in your script and save the script as an application. The presence of this handler or function automatically renders the saved application as a droplet, allowing it to accept dropped files and folders in the Finder. The open handler and openDocuments function accept a single parameter—a list of dropped files or folders—which are passed to the handler when the script is activated by dropping something onto it. In AppleScript, these dropped files and folders are alias objects. In JavaScript, they’re Path objects. For more information about these types of objects, see Referencing Files and Folders.

An AppleScript open handler is formatted as shown in Listing 17-1.

APPLESCRIPT

Open in Script Editor

Listing 17-1AppleScript: Structure of an open handler
  1. on open theDroppedItems
  2. -- Process the dropped items here
  3. end open

A JavaScript openDocuments function is formatted as shown in Listing 17-2.

JAVASCRIPT

Open in Script Editor

Listing 17-2JavaScript: Structure of an openDocuments function
  1. function openDocuments(droppedItems) {
  2. // Process the dropped items here
  3. }

Typically, a droplet loops through items dropped onto it, processing them individually, as in Listing 17-3 and Listing 17-4.

APPLESCRIPT

Open in Script Editor

Listing 17-3AppleScript: An open handler that loops through dropped items
  1. on open theDroppedItems
  2. repeat with a from 1 to length of theDroppedItems
  3. set theCurrentDroppedItem to item a of theDroppedItems
  4. -- Process each dropped item here
  5. end repeat
  6. end open

JAVASCRIPT

Open in Script Editor

Listing 17-4JavaScript: An openDocuments function that loops through dropped items
  1. function openDocuments(droppedItems) {
  2. for (var item of droppedItems) {
  3. // Process each dropped item here
  4. }
  5. }

To run a droplet, drop files or folders onto it in the Finder. To test a droplet in Script Editor, add the following line(s) of code to the root level—the run handler portion—of the script. Listing 17-5 and Listing 17-6 prompt you to select a file and then passes it to the open handler or openDocuments function.

APPLESCRIPT

Open in Script Editor

Listing 17-5AppleScript: Calling the open handler to test a droplet within Script Editor
  1. open {choose file}

JAVASCRIPT

Open in Script Editor

Listing 17-6JavaScript: Calling the openDocuments handler to test a droplet within Script Editor
  1. var app = Application.currentApplication()
  2. app.includeStandardAdditions = true
  3. var file = app.chooseFile()
  4. openDocuments([file])

Creating an AppleScript Droplet from a Script Editor Template

Script Editor includes several preconfigured AppleScript droplet templates, which solve the majority of droplet use cases.

To create a droplet from a Script Editor template
  1. Launch Script Editor from /Applications/Utilities/.

  2. Select File > New from Template > Droplets.

  3. Choose a droplet template.

    Options include:

    • Droplet with Settable Properties—This template processes dropped files based on file type, extension, or type identifier. It also demonstrates how to include a user-configurable setting, which affects the behavior of the script.

    • Recursive File Processing Droplet—This template processes dropped files based on file type, extension, or type identifier. It is configured to detect files within dropped folders and their subfolders.

    • Recursive Image File Processing Droplet—This template processes image files matching specific file types, extensions, or type identifiers. It is configured to detect images within dropped folders and their subfolders.

    All of these templates are designed to serve as starting points for creating a droplet, and can be customized, as needed.

Creating a Droplet to Process Files

In Listing 17-7 and Listing 17-8, the open handler and openDocuments function process dropped files based on file type, extension, or type identifier. The file types, extensions, and type identifiers supported by the handler are configurable in properties at the top of the script. If a dropped file matches the criteria you configure, then the file is passed to the processItem() handler, where you can add custom file processing code. These examples are not configured to process dropped folders.

APPLESCRIPT

Open in Script Editor

Listing 17-7Handler that processes dropped files matching specific file types, extensions, or type identifiers
  1. property theFileTypesToProcess : {} -- For example: {"PICT", "JPEG", "TIFF", "GIFf"}
  2. property theExtensionsToProcess : {} -- For example: {"txt", "text", "jpg", "jpeg"}, NOT: {".txt", ".text", ".jpg", ".jpeg"}
  3. property theTypeIdentifiersToProcess : {} -- For example: {"public.jpeg", "public.tiff", "public.png"}
  4. on open theDroppedItems
  5. repeat with a from 1 to count of theDroppedItems
  6. set theCurrentItem to item a of theDroppedItems
  7. tell application "System Events"
  8. set theExtension to name extension of theCurrentItem
  9. set theFileType to file type of theCurrentItem
  10. set theTypeIdentifier to type identifier of theCurrentItem
  11. end tell
  12. if ((theFileTypesToProcess contains theFileType) or (theExtensionsToProcess contains theExtension) or (theTypeIdentifiersToProcess contains theTypeIdentifier)) then
  13. processItem(theCurrentItem)
  14. end if
  15. end repeat
  16. end open
  17. on processItem(theItem)
  18. -- NOTE: The variable theItem is a file reference in AppleScript alias format
  19. -- Add item processing code here
  20. end processItem

JAVASCRIPT

Open in Script Editor

Listing 17-8Function that processes dropped files matching specific file types, extensions, or type identifiers
  1. var SystemEvents = Application("System Events")
  2. var fileTypesToProcess = [] // For example: {"PICT", "JPEG", "TIFF", "GIFf"}
  3. var extensionsToProcess = [] // For example: {"txt", "text", "jpg", "jpeg"}, NOT: {".txt", ".text", ".jpg", ".jpeg"}
  4. var typeIdentifiersToProcess = [] // For example: {"public.jpeg", "public.tiff", "public.png"}
  5. function openDocuments(droppedItems) {
  6. for (var item of droppedItems) {
  7. var alias = SystemEvents.aliases.byName(item.toString())
  8. var extension = alias.nameExtension()
  9. var fileType = alias.fileType()
  10. var typeIdentifier = alias.typeIdentifier()
  11. if (fileTypesToProcess.includes(fileType) || extensionsToProcess.includes(extension) || typeIdentifiersToProcess.includes(typeIdentifier)) {
  12. processItem(item)
  13. }
  14. }
  15. }
  16. function processItem(item) {
  17. // NOTE: The variable item is an instance of the Path object
  18. // Add item processing code here
  19. }

Creating a Droplet to Process Files and Folders

In Listing 17-9 and Listing 17-10, the open handler and openDocuments function loop through any dropped files and folders.

For each dropped file, the script calls the processFile() handler, which determines whether the file matches specific file types, extensions, and type identifiers. The file types, extensions, and type identifiers supported by the handler are configurable in properties at the top of the script. If there’s a match, then any custom file processing code you add runs.

The script passes each dropped folder to the processFolder(), which retrieves a list of files and subfolders within the dropped folder. The processFolder() handler recursively calls itself to process any additional subfolders. It calls the processFile() handler to process any detected files. If necessary, you can add custom folder processing code to the processFolder() handler.

APPLESCRIPT

Open in Script Editor

Listing 17-9Handler that processes dropped folders and files
  1. property theFileTypesToProcess : {} -- I.e. {"PICT", "JPEG", "TIFF", "GIFf"}
  2. property theExtensionsToProcess : {} -- I.e. {"txt", "text", "jpg", "jpeg"}, NOT: {".txt", ".text", ".jpg", ".jpeg"}
  3. property theTypeIdentifiersToProcess : {} -- I.e. {"public.jpeg", "public.tiff", "public.png"}
  4. on open theDroppedItems
  5. repeat with a from 1 to count of theDroppedItems
  6. set theCurrentItem to item a of theDroppedItems
  7. tell application "Finder"
  8. set isFolder to folder (theCurrentItem as string) exists
  9. end tell
  10. -- Process a dropped folder
  11. if isFolder = true then
  12. processFolder(theCurrentItem)
  13. -- Process a dropped file
  14. else
  15. processFile(theCurrentItem)
  16. end if
  17. end repeat
  18. end open
  19. on processFolder(theFolder)
  20. -- NOTE: The variable theFolder is a folder reference in AppleScript alias format
  21. -- Retrieve a list of any visible items in the folder
  22. set theFolderItems to list folder theFolder without invisibles
  23. -- Loop through the visible folder items
  24. repeat with a from 1 to count of theFolderItems
  25. set theCurrentItem to ((theFolder as string) & (item a of theFolderItems)) as alias
  26. open {theCurrentItem}
  27. end repeat
  28. -- Add additional folder processing code here
  29. end processFolder
  30. on processFile(theItem)
  31. -- NOTE: variable theItem is a file reference in AppleScript alias format
  32. tell application "System Events"
  33. set theExtension to name extension of theItem
  34. set theFileType to file type of theItem
  35. set theTypeIdentifier to type identifier of theItem
  36. end tell
  37. if ((theFileTypesToProcess contains theFileType) or (theExtensionsToProcess contains theExtension) or (theTypeIdentifiersToProcess contains theTypeIdentifier)) then
  38. -- Add file processing code here
  39. display dialog theItem as string
  40. end if
  41. end processFile

JAVASCRIPT

Open in Script Editor

Listing 17-10Function that processes dropped folders and files
  1. var SystemEvents = Application("System Events")
  2. var fileManager = $.NSFileManager.defaultManager
  3. var currentApp = Application.currentApplication()
  4. currentApp.includeStandardAdditions = true
  5. var fileTypesToProcess = [] // For example: {"PICT", "JPEG", "TIFF", "GIFf"}
  6. var extensionsToProcess = [] // For example: {"txt", "text", "jpg", "jpeg"}, NOT: {".txt", ".text", ".jpg", ".jpeg"}
  7. var typeIdentifiersToProcess = [] // For example: {"public.jpeg", "public.tiff", "public.png"}
  8. function openDocuments(droppedItems) {
  9. for (var item of droppedItems) {
  10. var isDir = Ref()
  11. if (fileManager.fileExistsAtPathIsDirectory(item.toString(), isDir) && isDir[0]) {
  12. processFolder(item)
  13. }
  14. else {
  15. processFile(item)
  16. }
  17. }
  18. }
  19. function processFolder(folder) {
  20. // NOTE: The variable folder is an instance of the Path object
  21. var folderString = folder.toString()
  22. // Retrieve a list of any visible items in the folder
  23. var folderItems = currentApp.listFolder(folder, { invisibles: false })
  24. // Loop through the visible folder items
  25. for (var item of folderItems) {
  26. var currentItem = `${folderString}/${item}`
  27. openDocuments([currentItem])
  28. }
  29. // Add additional folder processing code here
  30. }
  31. function processFile(file) {
  32. // NOTE: The variable file is an instance of the Path object
  33. var fileString = file.toString()
  34. var alias = SystemEvents.aliases.byName(fileString)
  35. var extension = alias.nameExtension()
  36. var fileType = alias.fileType()
  37. var typeIdentifier = alias.typeIdentifier()
  38. if (fileTypesToProcess.includes(fileType) || extensionsToProcess.includes(extension) || typeIdentifiersToProcess.includes(typeIdentifier)) {
  39. // Add file processing code here
  40. }
  41. }