PithHelmet

Pith Helmet Logo
Problem:
I hate ads.
Solution:
Kill my television.
Better Solution:
Content filter my web pages...

1. What It Does

The PithHelmet adds some some basic but powerful content filtering to Apple's Safari browser. The basic purpose is to filter advertisements, but there are other potential uses as well (blocking Flash, Shockwave or horrible midi loops).

This is just a quick hack on top of Apple's basic framework, but it seems to work rather effectively.

2. Installing and Upgrading

As of version 0.4, PithHelmet has been redesigned to work as a plugin for SIMBL (Simple InputManager Bundle Loader). This should solve a few problems with PithHelmet unintentionally interfering with other applications, such as the screen saver. The actual PithHelmet.bundle will now be installed in the ~/Library/InputManager/SIMBL/Plugins folder.

If you are installing for the first time:

If you are upgrading from a previous version (v0.4.x or greater):

If you are upgrading from a previous version (v0.2):

3.1 How To Block A URL

Once you've installed the files, start Safari (restart it if it's been running during the install process). Try browsing a few sites and you should see markedly less advertisements. (I like cnn.com or msn.com for a good demo site)

If some undesirable content isn't blocked, you can add it to the "block list" in one of the following ways:

You can test the rules on a particular URL by clicking the "Test Rules" button. That will give you some information about whether or not the url was blocked or allowed, and for what reason. Once you close the preferences pane or click the Save button, the new rules will be active.

3.2 How To Allow A URL

If some desirable content is accidentally getting caught by the Block rules (a false positive), you can specifically allow content via an Allow rule. The method is similar to adding an Block rule, simply add the rule to the Allow group instead. Allow rules are applied only after an Block rule has been matched.

You can use the same testing method described in the previous section.

3.3 How To Build Better Blocking Rules

PithHelmet now has a test panel (accessibly via the PithHelmet preferences pane in Safari) which will give you an explanation of what exactly PithHelmet thinks about a specified URL.

In addition, the curious user can enable the PithHelmet.log file (from the preferences pane) and all urls matching a rule will be logged to this file. A side benefit of logging is that potentially, people can submit their logs to me for analysis, so I can prioritize the rules and make them both faster and more effective.

Additionally, a useful thing would be for people to mark items in the log which were matched unintentionally, so I can reduce accidental blocking. The best way to send the log files is via email attachment.

Also, feel free to send your custom Block/Allow rules back to me - I will make them available in any subsequent releases if they are widely applicable. If you do submit a rule, you might want to include a hint about which sites this rule is for - that way I can clean up the rule if necessary and also take some time to validate it myself.

3.4 Quick Explanation of the Preferences Pane

Bug Icon
Report a bug to me via email - this automatically fills out version info for Safari and PithHelmet
Plane Icon
Takes you to a PayPal page where you can send a donation to reward my development efforts
Enable Transmogrifier - (advanced users)
Enables you to transmogrify one url to another, similar, but different url.
Currently, the demo rule makes all New York Times Magazine pages go to the printer-friendly equivalent. You have to edit the PithHelmet.plist manually to make this work.
Collapse Blocked Content
Executes a Javascript function once a page finishes loading to remove content matching the Block rules. It also checks the location of links, and links to matching the Block rules are also expunged.
Collapse Ad-Sized Images
Causes images (and iframes too) matching common advertisement sizes to be blocked. This is only valid if Collapse Blocked Content is enabled as well.
Enable Logging
Writes all PithHelmet actions to a log file ~/Library/Application Support/PithHelmet/PithHelmet.log It can be useful to tell you which URL's PithHelmet is blocking - useful to me because I can generate prioritized rules based on how often a rule causes a block/allow action.
Enable Contextual Menu
Adds a contextual menu item to allow images to be blocked with a single click.
Enable Debug Menu
Somebody wrote an application that basically just turned on the built-in Safari menu and then demanded cash for it, something around $10. Needless to say, that is dumb. It rubbed me the wrong way, so I included this option to turn the Debug menu on/off. This requires you to restart Safari for the option to take effect.
Block All Cross-site Content
If this is turned on, all images, movies, etc. on a page that do not come from the same domain that appears in the location bar will be blocked. This is pretty drastic, but a few people requested it. I leave it off personally.
Plus Icon
Adds a new rule. You must have a group, or an existing rule already selected before you click.
Minus Icon
Removes the currently selected rule.
Rules Editor
Block (or Allow) Domain only filters the domain - not the rest of the url. It is an optimization to reduce the amount of time spent matching the rules. Each of the icons indicates a particular rule type:
  • Invalid Rule
  • Domain Match - suffix match the domain with the text
  • Regex Domain Match - regex match limited to the domain
  • Regex URL Match - regex match against the whole URL
Test Rules
Brings up a panel where you can type a URL and see the results of having PithHelmet run over it. It will tell you if it is allowed, blocked and why (which rule matches, etc.)
Reload
Reloads all rules from the PithHelmet.plist file - one might really call this revert. You will lose unsaved changes.
Save
Saves current rules to the PithHelmet.plist file.

3.5 Quick Explanation of Menu Items and Keyboard Shortcuts

Block Filtered Content (Safari menu)
Command-Shift-K
turns PithHelmet on/off
Reload Page Unfiltered (View menu)
Command-Shift-R
reloads the current url with PithHelmet disabled temporarily
Block Image from this Server (contextual menu)
Right-Click (Control-Click) on Image
adds a new Block Domain rule for the current image
Preferences Pane Contextual Menu
Add New Rule...
allows you to add a new rule of a particular type
Set Rule Type
allows you to change the type of a rule (see above)
Remove Rule
see above
Truncate Log
Deletes the PithHelmet log file if you feel it is getting too large
Report Bug...
see above
Send Donation...
see above
About PithHelmet...
Loads this document in a new browser window

I told you it was quick.

4.1 Caveats

  1. Limit .gif image loops. Chimera and OmniWeb have this - very handy. My initial investigations suggest that Apple may be implementing this themselves, so I have back-burnered this for now.
  2. This entire thing is based on private non-final APIs inside Safari. v0.6 works with Safari 1.0 v73 (Beta2) and is tested on Mac OS X 10.2.5 - I doubt it works on versions earlier than 10.2 and could very well break on the next release of Safari.

4.2 Possible Features for v0.7

  1. Cookie filtering/mangling
  2. Installer
  3. Collapse Flash content

5. Questions | Comments | Feedback

Please feel free to contact me via email - I'm interested to here your criticisms and thoughts.

You can always read about the latest PithHelmet status in my development journal.

If you are feeling especially appreciative, consider sending me a donation via PayPal.

6. Thanks

Nora G - for letting me test the early versions on her laptop.

Numerous folks have expressed their thanks for PithHelmet and provided substantial encouragement.

7. Revision History

v0.6.1 - released 2003-05-16

v0.6 - released 2003-05-01

v0.5 - released 2003-03-24

v0.4.3 - released 2003-03-08

v0.4.2 - released 2003-03-06

v0.4.1 - released 2003-02-10

v0.4 - released 2003-02-09

v0.3 - released 2003-02-01

v0.2 - released 2003-01-28

v0.1 - released 2003-01-15

©2003 Mike Solomon | XHTML 1.1 | CSS 2.0