View Guide with Images

Introduction

JavaScript Blocker (hereinafter "the extension") is a Safari extension which, despite it names, can block many different resources from loading. It will help keep you safe on the web by preventing tracking agencies, social networks, and generally bad places from loading. There are also some other features that can make your browsing experience more enjoyable. In this manual you will learn about every aspect of JavaScript Blocker.

A predefined set of rules—the whitelist and blacklist—is automatically installed to help with allowing or blocking "safe" or "bad" items. If you want to ignore either or both of these lists, you can do so via the extension's settings page.

Installation

You can install the extension from Apple's Safari Extension Gallery or from its website. Either way, once completed, you will see a new toolbar icon appear.

Click the toolbar icon to reveal the main window where everything takes place. If you are on the Safari Extensions Gallery, you will see a popup in the window telling you that while the installation was successful, it will not be able to function on that website. The reason for this is because Apple prevents extensions from running on the gallery for security reasons.

User Interface

Main Window

If this is the first install of the extension (i.e. you aren't updating from a previous version) you will see the initial blank window. You'll have to reload your open webpages in order for the window to become populated.

• Unlock lets you remove the restriction on the extra features of the extension. Once clicked, a popup will appear where you can input your email address for verification or unlock without contributing.

• Disable turns off all features of the extension until Safari is relaunched or you re-enable the extension.

• Help takes you to a webpage where you can solve any problems you may come across with the extension.

• Settings will open the extension's settings page in an overlay within the active tab.

• Rules opens a popup that lets you quickly manage the active temporary rules, show all your rules, or create a quick backup.

• Show Hidden will be enabled when there are hidden items in the window.

• JavaScript Blocker lets you access a console where errors will appear. It must be double clicked to open.

The page selector lets you gain access to the information contained within frames on the active webpage. You can use the frame switcher on the right to quickly navigate through them.

• Here you will see all of the items that have been allowed or blocked. Items may vary in style to let you know what's going on.

  • Text

  • • Black. A resource loaded using the non-secure HTTP protocol.
    • Brown or gold. A resource loaded using the secure HTTPS protocol.
    • Blue. A resource from a Safari extension.
    • Purple. A resource using the file transfer protocol.
    • Italic (and any color). The item cannot be blocked, typically for frames when a navigation event occurred.

  • Background Colors

  • • Transparent. The item was not affected by an existing rule.
    • Green. The item was allowed by a whitelist rule.
    • Red. The item was blocked by a blacklist rule.
    • Gray. The item was allowed or blocked by a user added rule or automatic rule.

The number next to the Allowed/Blocked headers is the total number of resources affected. It will also count any hidden items and therefore may not match the number of items displayed until clicking Show Hidden.

Each section can be collapsed by hovering over next to header (SCRIPTS, FRAMES, etc.) and clicking Hide.

You can also collapse the the Allowed/Blocked sections by clicking on its header.

The Block or Hide… buttons will reveal a popup which two choices: Some and All. Clicking on Some will reveal check boxes and select boxes so that you can select multiple items to block, allow, or hide all at once. Selecting All will show you check boxes with the type of item to block, allow, or hide (scripts, frames, etc.).

Simple Mode

The question mark next to each item will reveal up to two options.

• If the item is under OTHER, it will tell you exactly what the "other" is doing.

• Safety Info will be a button if the item was affected by a rule. Otherwise, it will open automatically with three choices to give you a better understanding of how safe the host is for that item.

• Show Matched Rules will appear if the item was affected by any type of rule. It will open a popup with the rules and their associated domain.

Expert Mode

The question mark next to each item will reveal an additional option alongside the ones above.

• View Script|Frame|Image Source? lets you view the source code of frames and scripts, and view images within the popover.

Features

The extension controls which resources are allowed or blocked based on the domain of the webpage and the source of the item in question. There are several blockers included to control almost anything on a webpage. Only the Script and Frame blockers are enabled by default. Each one has its own default action which can be configured from the settings page under Rules.

Methods of Action

Any rule created can be permanent or temporary. A temporary rule is one that will be automatically removed when Safari is restarted.

Rules can be created to always block scripts if they originate from a different hostname, from a different sub-domain, anywhere, or the blacklist only.

Let's say I choose to block rules if they come from a different hostname. Now, I navigate to example.org and it attempts to load a resource from example.com—a different hostname—a rule is created to block any resource originating from example.com on example.org. But if example.org tries loading a resource from sub.example.org, it will be allowed since it is a sub-domain of example.org. This is possible by selecting "Different hostnames" from the preferences for "Automatically block * from:".

If you wanted to allow resources only from the same originating hostname, choose "Different hosts & subdomains" instead. Then, even a resource from sub.example.org will be blocked.

If you wanted to block everything, select "Anywhere".

If you wanted to block only known bad scripts, select "Blacklist only".

Script Blocker

One of the most important aspects of the extension is its ability to block scripts. By default, the extension will block any script not originating from within the domain of the webpage you are visiting. This means that you are automatically protected from tracking agencies, advertisers, social networks, etc.

Scripts are considered to be any resource loaded using a <script> tag. Scripts that are not loaded from somewhere and are not using a data URI cannot be blocked. Unfortunately this is a limitation of Safari extensions. This is mostly not an issue as harmful/unwanted scripts will most likely be loaded from a file.

The following blockers are part of the extra features of the extension.

Frame Blocker

The extension can also prevent <frameset>s and <iframe>s from being loaded. These are often used to place ads or social networks on webpages because the frame itself will be from the host of the ad or social network. For example, if I go to www.example.com and they have a frame that loads Facebook, without the frame blocker, I would still see all of Facebook stuff and they can still track where you've been. By default, the frame blocker will only allow frames that originate within the same domain of the webpage you are visiting. A placeholder can be used to load a specific frame by clicking on it.

Embed and Object Blocker

<embed>s and <object>s can be things like Flash, Java, etc. By default, these elements are blocked regardless of where they originate from. A placeholder can be used to load a specific embed or object by clicking on it.

Video Blocker

This will block only HTML5 <video> elements. To block Flash videos, use the Embed and Object Blocker. All videos are blocked by default. A placeholder can be used to load a specific video by clicking on it.

DOM Image Blocker

Images will only be prevented from appearing on the webpage. Unfortunately they will still be downloaded, though you will never see them. This is a limitation of WebKit (Safari). All images are allowed by default regardless of where they are from. A placeholder can be used to load specific images by clicking on it.

Other Features

The extension can also help block some JavaScript annoyances and help with reading webpages. They can be enabled one-by-one under Other Features on the settings page. With the exception of the first three items, they act just like a blocker so you can create rules for them on a per-domain basis. If the feature is active, it will appear as a blocked item under OTHER in the main window. The text below appearing in bold will be the name of the item as it appears in the window.

• Prevent links on webpages from sending referrer information so the destination will not know where you are coming from.

• When navigating to a short URL, you can choose to see what the URL will expand into and confirm if you want to continue or not.

• An experimental feature to block all referrer information for GET requests in the main window when just preventing links from sending it isn't enough.

• Modal alert dialogs

  Alert dialogs can be displayed within the webpage instead of a standard modal dialog so they don't get in your way. Multiple alerts will stack and can be closed by swiping to the right or clicking the close button.

• Confirm dialogs

  Confirm dialogs can be automatically confirmed. If alert dialogs are suppressed by the above feature, the confirmed action will be displayed within the webpage.

• Context menu overrides

  Ensure that right-clicking on a webpage will always work as intended and that other extensions will not be able to fill up the context menu.

• Window resize functions

  Prevent webpages from changing the size of your browser window or opening a new window with a custom size.

  These functions are overwritten: resizeBy, resizeTo, moveTo, open.

• Autocomplete disablers

  Make sure forms are always able to autocomplete even if they set autocomplete="off".

• Default webpage font

  Force webpages to use a custom font so you'll always be able to read the content.

• Default webpage zoom level

  Automatically zoom in on webpages if you have trouble seeing them.

  Adds a zoom CSS property to the <body> element.

Snapshots

Snapshots is one of the extension's extra features that automatically creates backups of your rules any time they are modified. You can use it to recover from any accidental changes or to create different rule sets for different situations, such as when you're at home or in public.

You can access the snapshots UI from the rule list by clicking the time machine icon in the actions bar.

Once opened, you will see a summary of how many snapshots there are and how much space they are using. You can limit the amount of UNKEPT snapshots from the settings page.

When you first start off, there will only be snapshots under UNKEPT since they are not saved permanently by default. Clicking Create Snapshot will create a new, unnamed KEPT snapshot with the current date and time.

Snapshot Previews

You can preview a snapshot's rules (i.e. temporarily use them in place of the current rule set) by clicking Preview. This will take you back to the rule list where you will see see all of the rules in the snapshot. The active preview will be green in the snapshots UI.

You can browse around as you normally would to see the rules in action. You will not be able to create or remove any rules while the preview is in use—snapshots are read-only.

From the rule list, you can recover rules to place them in the current rule set by clicking the Recover button next to a rule, where Delete/Restore/Disable would normally be. You can also recover entire domain sets by switching to edit mode (click the little pencil icon in the actions bar). A Recover button will appear next to the domain name. Clicking it will reveal two options: Merge and Replace. Use Merge when you want append the current rules for that domain and Replace to use only the snapshot's version of the domain rules (the current rules for that domain will be removed).

Click the time machine icon again to reveal a popup with Merge Rules and Replace Rules. Use Merge when you want to append your current rule set with rules unique to the snapshot and Replace to turn the snapshot into the current rule set. You can also click Close Snapshot to revert back to the current rule set.

Snapshot Options

Click on a snapshot's name to reveal a popup.

• Name lets you give the snapshot a custom name. You cannot use the same name twice. Names are case sensitive so "Standard" is not the same as "standard".

• Compare opens a popup with three ways you can compare the snapshot to the current rule set. A comparison can be acted upon just like a preview, but unlike previews, they will last only until the rule list is closed. Until then, the rules resulting from the comparison will be used in place of the current rules.

• • Only in Snapshot will show rules in the snapshot that are not in the current rules.

  • Only in My Rules will show rules in the current rules which are not in the snapshot.

  • In Both will show rules that are in both the current rules and the snapshot.

• Keep saves the snapshot permanently; it will not be deleted as part of the automatic purge.

• Unkeep will allow the snapshot to be removed as part of the automatic purge.

• Delete permanently removes the snapshot.

FAQ

• I see "Error 0: error" when trying to verify my payment.

  Most likely you are unable to contact the verification server. Check you firewall and/or Little Snitch settings. You'll have to allow outbound connections to http://lion.toggleable.com:160. The verification server may also be temporarily offline.

• Animations are executing extremely slowly.

  The extension uses the shift key to slow down animations for people who enjoy that kind of thing. Sometimes it gets stuck in the down position so pressing it again should resolve the issue.

• Blocked/Allowed tells me that x resources were blocked/allowed, but I only see y items.

  This usually occurs when an item is affected by a whitelist or blacklist rule in simple mode and mostly for allowed items. If the webpage has some items that are whitelisted, they appear separately from the items that are allowed for a different reason. This is so you can see which rules are causing the items to be allowed. If that is not the case, there may be some hidden items. Click Show Hidden in the top bar of the main window to reveal them. Nothing is hidden by default.

• The toolbar icon looks like it has an "X" through it.

  This means that the extension is completely disabled. Either re-enable it manually or restart Safari.

• How do I uninstall the extension?

  Safari preferences > Extensions > JavaScript Blocker > Uninstall (on the right).