PithHelmet

Links and Downloads

General Information
Screen Shots

Latest News

PithHelmet Bugs
PithHelmet FAQ
PithHelmet Features
PithHelmet Installation
PithHelmet Localization

PithHelmet-0.7.3.tbz (Panther only)
PithHelmet-0.7.1.tgz (v85.x only)
PithHelmet-0.6.1.tgz (v74 only)

PithHelmet-src-0.7.2.tgz (source only)

Pith Helmet Logo
Enjoy PithHelmet?

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

1.0 Feeling Lucky?

If you are a brave soul, you can try the PithHelmet v2.0 Beta.

1.1 What It Does

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

This is just a series of hacks on top of Apple's WebKit framework, but it seems to work rather effectively.

Due to the manner in which PithHelmet blocks ad content, most types of advertising content can be caught in the filter - this includes images, javascript, css, text, iframes, popups and popunders.

1.2 More Detailed Information

Progress reports are regularly written to the PithHelmet Development section of my development log. One of these days I will get around to hosting the source somewhere, but for now, inquiring minds can send me a quick email and get the latest branch.

2.1 Installing and Upgrading

PithHelmet is a plugin for SIMBL. This keeps PithHelmet from unintentionally interfering with other applications, such as the screen saver.

As of v0.6.3, PithHelmet is distributed as a metapackage and installed by Apple's Installer.app. The PithHelmet.mpkg file will automatically update or install the lastest version of SIMBL and the PithHelmet plugin. The installed components are listed below.

The actual PithHelmet.bundle will now be installed in the /Library/Application Supports/SIMBL/Plugins folder.

If you have added you own rules, they will get saved in a backup file in ~/Library/Application Support/PithHelmet before they are automatically upgraded.

Note: Some older versions (pre-v0.5) of PithHelmet will prevent the package from installing properly. There are a few useful error messages that will inform you of files that are in the way. If you remove these files, either by moving them or trashing them, the install should proceed. There are several potential directories to remove, but eventually, things should install correctly.

For additional installation information and trouble shooting, check PithHelmet Installation Notes. These notes are updated more frequently than the main site.

2.2 Uninstalling PithHelmet

Removing (trashing) the PithHelment.bundle from /Library/Application Support/SIMBL/Plugins folder will effectively remove PithHelmet from Safari.

2.3 Installed Files and Folders

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.
Hide 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.
Hide Ad-Sized Images
Causes images (and iframes too) matching common advertisement sizes to be blocked. This is only valid if Hide Blocked Content is enabled as well.
Hide Links To Blocked Content
Causes content linked to URLs matching the Block rules to be hidden. This is surprisingly time consuming and usually accounts for any slowness related to PithHelmet. This is only valid if Hide 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.
GIF Animations
This can alter the number of times GIF animations play - Alway (default), Once (the entire animation will play only once) or Never (the first frame of the animation will be shown, but there will be no animation).
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
Rules Types:
  • 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
Rule Groups:
Block
Content matching these patterns are blocked.
Allow
An Allow rule will override a block rule. It also overrides images size blocking.
Exempt Sites
Disables all PithHelmet features for any sites matching these patterns. This is helpful for trusted sites.
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 Images from this Server (contextual menu)
Right-Click (Control-Click) on Image
adds a new Block rule for the server hosting the current image
Never Block Content from this Server (contextual menu)
Right-Click (Control-Click) on Page background (not an Image or a Link)
adds a new Exempt Site rule for the domain name of the current site
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
Revert To Factory Rules...
Deletes all user-added rules and restores them to the latest version of the factory rules
Report Bug...
see above
Send Donation...
see above
Help
Links to a few helpful sites and PithHelmet ReadMe
About PithHelmet...
Loads this document in a new browser window

I told you it was quick.

4.1 Caveats

  1. 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.8

  1. Cookie filtering/mangling - I swear I'll work on it!
  2. 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. There are also a number of pages on the PithHelmet section of my collaborative web site, Wikir.

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.7.3 - released 2004-07-02

v0.7.2b - re-released 2004-06-06

v0.7.2a - re-released 2004-02-03

v0.7.2 - released 2003-11-16

v0.7.1 - released 2003-10-20

v0.7 - released 2003-08-26

v0.6.3 - released 2003-06-26

v0.6.2 - released 2003-06-23

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