Quick Start Guide
This guide will help you get started with running Dashboard Widgets on your macOS device.
Download
First, you need to download the app. The only official source is the GitHub repository at https://github.com/nikolan123/WidgetPortingToolkit.
First Launch
Double-click the downloaded DMG and drag the app into your Applications folder.
Since this app has not been notarized by Apple (costs a lot of money), there are extra steps required to open it. To open it:
- macOS Ventura (13) and later: System Settings → Privacy & Security → scroll down and click "Open Anyway". Authenticate if prompted.
- macOS Monterey (12) and earlier: System Preferences → Security & Privacy → click "Open Anyway". Authenticate if prompted.
- Alternative method (Sonoma 14 and earlier): Right-click the app → Open → Open Anyway.
- Terminal method (any version):
xattr -d com.apple.quarantine /Applications/Widget\ Porting\ Toolkit.app
You can then open the app normally.
Initial Setup
You need a folder containing various shared resources the widgets use called WidgetResources. You can either get it yourself or use this one provided by me:
If you decided to use my zip, extract it.
Go into Options > Install Support Directory and choose your WidgetResources folder. This copies the provided WidgetResources folder to the app's directory. You only need to do this once.
How to use
First off, you need widgets. You can check out the guide on where to get widgets from:
Once you have some widgets, you can drag them to the application's main window. This will open a window where you have to confirm the installation. To skip the window (and also silence installation errors and permission prompts), you can enable Silent Mode from the options menu.
To go into the full-screen dashboard recreation, maximize the main app window.
Each installed widget has a unique identifier used to store its preferences and to allow multiple of the same widget to be installed. These identifiers can be seen next to the widget's name.
Widget Tweaks
There are a number of tweaks that help old widgets run. The default should work for most widgets. You can modify this list by clicking the settings icon for a widget or option-clicking in the plus menu in the fullscreen view.
There are 2 types of tweaks - Runtime and Preprocessing.
Runtime Tweaks
are applied when the widget is loaded. They can be toggled on and off at any time and apply the next time you close and reopen the widget.
- Recreate Dashboard API - Recreates the original Dashboard API. Includes stuff such as system command execution, persistant data, animations, and more.
- Inject Helper CSS - Helps make the widgets feel like native apps - disables dragging images and native browser scroll.
- Proxy XMLHttpRequest - Overwrite the XMLHttpRequest and make the requests from Swift instead. Sometimes helps with CORS issues.
- Transparent Background - Without this, the widget background will be white instead of transparent.
- Use native window shadow - macOS Tahoe broke shadows. This should be disabled on Sequoia and earlier, unless you prefer custom shadows.
Preprocessing Tweaks
are applied when the widget is installed. To change these, you need reinstall the widget and choose your desired tweaks from the install window.
- Replace appropriate file paths - Fix hardcoded paths to system directories and widget resources.
- Copy Support Directory - Lets the widget use shared resources. Without this, many will be broken.
- Fix self-closing <script /> tags - Fixes the old weird self-closing script tags. Fixes a small amount of widgets.
- Add a blank localizedStrings.js if it doesn't exist - This does almost nothing and just prevents a console error which annoys me.