Before we dig into the details of the Photos Utilities script library, let’s discuss scripting folders and albums.
Folders and Albums
In the scripting implementation for Photos, albums and folders are not only elements of other containers (folders and albums are considered containers themselves), but they are also elements of the application itself.
In other words, a folder can “belong to” or be “contained in” another folder, and would then be addressed by its containment hierarchy, like this:
--> folder id "XBUnURnAR0K27giMD7533w" of folder id "ZHeENHAqRyCUvST2W3J9ig" of folder id "3NL0t3v4T8S8RsktrcDg9g" of application "Photos"
05
end tell
Notice that the resulting reference to the folder, lists each container in the chain of ownership from the bottom of the chain to the top, using the possessive “of” to indicate containment (⬆ see above )
But, folders are also an element of the Photos application, and so you can address them directly, without having to acknowledge their containment hierarchy, like this:
Folder as an element of the Photos application
01
-- ELEMENT OF THE APPLICATION
02
tellapplication "Photos"
03
getfolder "Sub-sub Folder"
04
--> folder id "XBUnURnAR0K27giMD7533w" of application "Photos"
05
end tell
Notice that the resulting reference to the folder, lists the Photos application as being the “parent” of the folder (⬆ see above )
Having the ability to directly address a container without having to know its hierarchy is very convenient. It means that a script doesn’t have to know where a folder is located in your Photos library, in order to work with it.
But, as with most things, there are some scenarios where this dual ownership may cause issues that require special handling:
If the Photos library contains more than one folder or album named the same name.
If the folder or album is located on the “top-level” of the library.
If the Photos library contains multiple folders or albums named the same name, a script will need to address the folder or album by either specifying its containment hierarchy, or by using its unique identifier (ID), such as:
folderid "XBUnURnAR0K27giMD7533w"
And for a script to determine what folders and albums are located at the top-level of the library involves a complex process, requiring examining the containment hierarchy of all folders or albums.
But here’s the good news: the Photos Utilities script library contains commands that make dealing with top-level and multiple-named folders and albums, a much easier process.
“Suites” are Sweet!
The commands comprising the Photos Utilities script library are grouped into collections called “suites.” Each suite contains a set of related commands. The first suite “Photos Utility Suite” contains commands for working with top-level containers, and the second suite “Photos Export Suite” contains commands for exporting images from Photos to files and to each of the iWork applications.
The following are the commands from the Photos Utility Suite.
location in libraryv : The path to the referenced album or folder
location in library
forobject reference : A reference to the album or folder whose path is to be derived
[ appending IDboolean ] : Should the library path end with the ID of the target item? Default value is false.
[ delimiter stringtext ] : The text to place between path items. The default value is: “ > ”
→ text : A text string denoting the names of the chain of parent containers. For example: Top-level folder name > Next folder name > Next folder name > Target album name
top level foldersv : Returns a list of the top level folders
top level folders
→ list of object references : A list of references to the top level folders
top level albumsv : Returns a list of the top level albums
top level albums
→ list of object references : A list of references to the top level albums
names of top level foldersv : Returns a list of the names of top-level folders
names of top level folders
→ list of strings : A list of folder names
names of top level albumsv : Returns a list of the names of top-level albums
names of top level albums
→ list of strings : A list of albums names
top level folderv : Returns reference to top level folder whose name matches the provided string
top level folder
namedtext : The name of the folder to reference
→ object reference : A reference to the matched top level folder
top level albumv : Returns reference to top level album whose name matches the provided string
top level album
namedtext : The name of the album to reference
→ object reference : A reference to the matched top level album
containment treev : This command returns a list of object references for the chain of containing folders (from the top to the bottom) of an album or folder.
containment tree
forobject reference : An object reference to the album or folder whose containment hierarchy is to be derived.
→ list of object references : A list of object references (from the top to the bottom) outlining the chain of containing folders. An empty list {} means the object is at the top-level.
wait for Photosv : This routine will wait for Photos to launch
wait for Photos
[ timeout durationinteger ] : The maximum number of seconds to wait for Photos to complete launching. Minimum and default value is 300 (5 minutes).
→ boolean : A value of “true” when Photos has finished launching
Dealing with Multiple Folders Named the Same Name
As you can see in the screen capture shown on the left, the example Photos library contains folder hierarchies that are identical except for the name of their top-level parent folders. In this example, the Photos library contains three folders named “Structure.”
So if a script had to locate a specific one of the folders named “Structure,” it would have to either: present a list of the same-named folders to the user for them to select from, or use the containment tree command to get the name of the parent folder of each folder, and the name of its parent folder, etc.
Fortunately, the location in library command provides and easy way to generate delimited item location strings representing where a folder or album is located within the library. These “paths” are perfect for displaying to users.
Also, the command has an optional appending ID parameter that when used, will add the folder or album’s unique ID to the end of the path string. This ID can then be extracted from a selected path, to reconstitute an object reference to the target folder or album, as demonstrated in the example script below.
NOTE: If a “use clause” is included in a script, and you plan to include commands from the Standard Additions scripting addition (such as display dialog, choose folder, etc.) in your script, then support for the scripting additions must be declared via a “use scripting additions” statement added at the top of your script. (⬇ see below )
Locating Folder by Name
01
usescript "Photos Utilities"
02
usescripting additions
03
04
tellapplication "Photos"
05
activate
06
setfolderNameto "Structure"
07
settheseFoldersto every folder whose name isfolderName
08
setfolderCountto thecountoftheseFolders
09
if thefolderCountis 0 then
10
error "No folder named “" & folderName & "“ exists in this library."
11
else if thefolderCountis 1 then
12
set thetargetFoldertoitem 1 oftheseFolders
13
else
14
settheseFolderLocationsto ¬
15
location in libraryfortheseFolderswithappending ID
16
setdialogPromptto ¬
17
"Multile folders named “" & folderName & "” exist. Choose the one to use:"
18
setchosenFolderLocationto ¬
19
(choose from listtheseFolderLocationswith promptdialogPrompt)
Unless the location of a container is specified, all folders and albums created using the make command will be placed at the top-level of the library. The following script demonstrates how to create and delete top-level folders or albums.
display notification "The folders have been deleted." with title "Create|Delete Photos Folders"
30
end if
31
end tell
Creating Folders within a Top-Level Folder
Use the techniques outlined in the following example to add a folder within a top-level folder, if the name of the top-level folder in the Photos library occurs more than once as a folder name.
For those interested in creating and writing scripts and script libraries, the Photos Utilities Script Library is written in AppleScriptObj-C, a dynamic fusion of the AppleScript and Objective-C programming languages. The source code of the library can be viewed in a script editing application.
Comprehensive 3rd-party documentation and tools for writing and deploying AppleScriptObj-C applications, scripts, and script libraries are available from Myriad Communications.
DISCLAIMER
THIS WEBSITE IS NOT HOSTED BY APPLE INC.
Mention of third-party websites and products is for informational purposes only and constitutes neither an endorsement nor a recommendation. PHOTOSAUTOMATION.COM assumes no responsibility with regard to the selection, performance or use of information or products found at third-party websites. PHOTOSAUTOMATION.COM provides this only as a convenience to our users. PHOTOSAUTOMATION.COM has not tested the information found on these sites and makes no representations regarding its accuracy or reliability. There are risks inherent in the use of any information or products found on the Internet, and PHOTOSAUTOMATION.COM assumes no responsibility in this regard. Please understand that a third-party site is independent from PHOTOSAUTOMATION.COM and that PHOTOSAUTOMATION.COM has no control over the content on that website. Please contact the vendor for additional information.