Photos Utility Suite
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 as an element of a Container | ||
| 01 | -- ELEMENT OF A CONTAINER | |
| 02 | tell application "Photos" | |
| 03 | get folder "Sub-sub Folder" of folder "Sub-Folder" of folder "Top Level Folder" | |
| 04 | --> 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 | tell application "Photos" | |
| 03 | get folder "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:
folder id "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 library v : The path to the referenced album or folder
location in library
for object reference : A reference to the album or folder whose path is to be derived
[ appending ID boolean ] : Should the library path end with the ID of the target item? Default value is false.
[ delimiter string text ] : 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 folders v : 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 albums v : 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 folders v : 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 albums v : 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 folder v : Returns reference to top level folder whose name matches the provided string
top level folder
named text : The name of the folder to reference
→ object reference : A reference to the matched top level folder
top level album v : Returns reference to top level album whose name matches the provided string
top level album
named text : The name of the album to reference
→ object reference : A reference to the matched top level album
containment tree v : 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
for object 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 Photos v : This routine will wait for Photos to launch
wait for Photos
[ timeout duration integer ] : 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 )
Creating or Deleting Top-Level Folders
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.
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.
Next, we’ll examine the Photos Export Suite that contains specialized export commands for quickly exporting images to disk or the iWork applications.
