Photo Album

This report extensions shows all multimedia objects in a document as a grid of thumbnails, sorted by date, and grouped by century.

What it does

This extension opens a report window for the front document. The report displays every multimedia object in a grid similar to the one in Apple's Photos app. Each century has its own section, and objects that have no date are in a final section called Undated.

Size slider. The toolbar at the top has a slider that changes the size of all tiles in all sections at once. The toolbar and each section heading stay at the top of the window as you scroll.
Click a tile to open the multimedia record in its record window.
Hover over a tile to see its date along the bottom edge. The pop-up text (tooltip) shows the record's name, where the date came from, and the date.

Running the extension

Open a document and choose Photo Album from the Extensions menu. The script first looks for a date for each object. A progress message appears percentage processed while it does that, and a document with many multimedia objects may take a few moments. The report opens when the script is done.

How dates are found

Many multimedia records have no date of their own, so the script looks for a date in this order and uses the first one it finds:

The date recorded in the multimedia record itself.
Dates in the records that link to the object. For an individual, the script uses the birth date, then the death date, then the first event that has a date. For a family, it uses the marriage date, then the first event that has a date.

If several linked records have dates, the earliest date is used. For example, a photo linked to both a grandfather and his grandson is placed by the grandfather's date. Objects for which no date can be found are placed in the Undated section. Links to records that are not individuals or families (such as sources or notes) are not used to find dates.

Each tile's tooltip tells you which of these rules supplied the date, for example "Birth of Smith, John (linked record)".

The century sections are labeled by their years (for example "19th century 1801 - 1900"). Dates before year 1 (BC dates) are not supported.

Tiles that are not pictures

Some multimedia records do not point to an image the report can show. Those tiles display a symbol and the record's name instead of a picture. They still open the record when clicked.

	Meaning
❓	The file was not found. Check the multimedia record's file link and your multimedia folder.
🔗	The record links to a web address that is not an image. (Web addresses are tried as images first.)
✉️	The record is an email link (`mailto:`). The email address is shown as the caption.
📄	The file exists but could not be displayed as an image (for example, a PDF or sound file). The tooltip ends with the exact address that was tried.
🖼️	The file has special characters in its path (see below) and the temporary copy could not be made.

Files with special characters in their names

A report is a web page, and pictures are loaded using a web address. The characters &, ?, #, and % have special meanings in web addresses, so a picture whose file name (or whose folder name anywhere along the path) contains one of them cannot be loaded directly. The script works around the problem by making a temporary copy of such a file under a safe name and showing the copy. Your original files are never changed.

The temporary copies are made in a folder named GEDitCOMGrid. In GEDitCOM II this folder is in /tmp; in GEDitCOM it is in the genealogy workspace folder. A new numbered folder is created each time the script runs and old ones are not deleted by the script. They are safe to delete at any time and the system removes folders in /tmp on its own.

The "Files to fix" block

If any object needed a temporary copy, the script adds a final section at the end of the report called Files to fix. It has two parts:

A second grid that repeats the tiles of all those objects, so you can see them together.
A list of links, one for each of those records, followed by the full path of its file. Click a name to open the multimedia record, and use the path to find the file in the Finder.

The tooltip of each of these tiles also shows the full path.

Recommendation. Avoid &, ?, #, and % in the names of multimedia files and of the folders that contain them. Spaces and most other characters are fine. Using names without these four characters is good practice generally, because they can also cause problems for other software, web sites, and file transfers.

To fix a file

Scroll to the Files to fix block at the end of the report.
Click each link to open that multimedia object's record.
Hold down the option key and then select Tree→Move Multimedia Object To... menu command and use standard Mac methods to save under a new name.

The new version will be saved and the one with old name will be deleted. Typcially you move to the same folder as before and this action is then equivalent to renaming the file. The link to the file will in your genealogy docunent will be updated for the new name. When all files are fixed, re-run this extension to verify the new name work well.

Notes and limits

The report shows the full image file for each tile, resized by the window. A document with a very large number of big pictures may take longer to display.
Pictures load as you scroll, so tiles lower in the report may appear a moment after you reach them.
The script only reads your data. It does not change any records. The only things it writes are the temporary copies (when needed) described above.
The grid does not use the thumbnails stored in the document. It loads the image files themselves, so a record whose file cannot be found shows as ❓ even if the document has a stored thumbnail.