Customizing Reports#

Tailor the user interface elements of your exported PDF reports. You have the flexibility to modify the font, customize the header and footer text, and provide a company logo according to your preferences. See the sample PDF image below for an illustration of these customizable features.

Example PDF

See also

Configuring the date format is done at runtime by using the --date-format option. See date format for more information.

Setup#

When you first launch Patcher, a setup assistant will automatically create the necessary com.liquidzoo.patcher.plist file in the user’s Library Application Support directory, located at $HOME/Library/Application Support/Patcher. Once setup is completed successfully, the first_run_done key in the property list file will automatically be set to True:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Setup</key>
    <dict>
        <key>first_run_done</key>
        <true/>
    </dict>
</dict>
</plist>

Warning

Do not modify the first_run_done key in the Setup dictionary directly. Altering this key may cause Patcher to re-run the setup process. If you need to reset the initial setup state, use the --reset command instead. For more information, see resetting Patcher.

Modifying the Property List File#

The property list file contains the settings that control the appearance of the PDF reports. You can edit these values using /usr/libexec/PlistBuddy or a code editor of your choice (VSCode, BBEdit, CodeRunner, etc.).

Opening Property Lists in Xcode

If the plist file appears as a binary file when opened in VSCode or other editors, you can open it in Xcode instead. Xcode is available as a free download from the Mac App Store and fully supports editing plist files. This will prevent issues with binary formatting that some editors may encounter.

Using jappleseed as an example, the path to the property list file would be:

/Users/jappleseed/Library/Application Support/Patcher/com.liquidzoo.patcher.plist

Editing the Header & Footer Text#

Tip

Why not use defaults to edit the property list file? Unfortunately, the defaults binary in macOS lacks the ability to update keys nested within dictionaries. PlistBuddy is much better equipped to handle property lists with nested elements.

To modify the header and footer text using PlistBuddy, use the following commands:

$ /usr/libexec/PlistBuddy -c "Set :UI:HEADER_TEXT 'Your Custom Header Text'" ~/Library/Application\ Support/Patcher/com.liquidzoo.patcher.plist
$ /usr/libexec/PlistBuddy -c "Set :UI:FOOTER_TEXT 'Your Custom Footer Text'" ~/Library/Application\ Support/Patcher/com.liquidzoo.patcher.plist
$ /usr/libexec/PlistBuddy -c "Set :UI:LOGO_PATH 'path/to/your/company/logo.png'" ~/Library/Application\ Support/Patcher/com.liquidzoo.patcher.plist

These commands will correctly update the HEADER_TEXT, FOOTER_TEXT and LOGO_PATH keys within the UI dictionary.

Note

The footer text will automatically append a | character followed by the page number to the end of the specified footer text.

Customizing the Font#

To change the font, update the FONT_NAME, FONT_REGULAR_PATH and FONT_BOLD_PATH values in the UI dictionary.

$ /usr/libexec/PlistBuddy -c "Set :UI:FONT_NAME 'Helvetica'" ~/Library/Application\ Support/Patcher/com.liquidzoo.patcher.plist
$ /usr/libexec/PlistBuddy -c "Set :UI:FONT_REGULAR_PATH '/path/to/Helvetica-Regular.ttf'" ~/Library/Application\ Support/Patcher/com.liquidzoo.patcher.plist
$ /usr/libexec/PlistBuddy -c "Set :UI:FONT_BOLD_PATH '/path/to/Helvetica-Bold.ttf'" ~/Library/Application\ Support/Patcher/com.liquidzoo.patcher.plist

Important

The default font used in testing is Google’s Assistant Font. While you can specify a different font to match your organization’s branding, be aware that doing so may cause formatting or alignment issues in the exported PDF reports. It is recommended to test the PDF export functionality thoroughly after changing the font to ensure the new font does not adversely affect the document’s appearance.

Full Example Configuration#

Here is an example configuration with custom header, footer text, and a specified font:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Setup</key>
    <dict>
        <key>first_run_done</key>
        <true/>
    </dict>
    <key>UI</key>
    <dict>
        <key>HEADER_TEXT</key>
        <string>Confidential Report</string>
        <key>FOOTER_TEXT</key>
        <string>© 2024 Your Company</string>
        <key>FONT_NAME</key>
        <string>Helvetica</string>
        <key>FONT_REGULAR_PATH</key>
        <string>/path/to/Helvetica-Regular.ttf</string>
        <key>FONT_BOLD_PATH</key>
        <string>/path/to/Helvetica-Bold.ttf</string>
        <key>LOGO_PATH</key>
        <string>/Users/jappleseed/Library/Application Support/Patcher/logo.png</string>
    </dict>
</dict>
</plist>

The above example would result in a PDF report that looks identical to the example PDF image at the top of this page.