Description of AdBlock source code files

[Michael Gundlach]

Pao asked for an overview of what each file in trunk/ does.  Here it is for all to benefit :)  If anyone would like to clean this up and put explanatory comments at the top of each source file, please do!

Info.plist: Safari's equivalent of manifest.json.

Settings.plist: Safari file needed to give Safari users access to AdBlock's options from the Safari menu -> Preferences -> Extensions.

_locales/*/messages.json: localization (translation) files for all strings AdBlock uses into various languages.  Used by chrome.i18n.getMessage().

adblock_start_common.js: content script loaded on every page.  Its 2 main goals are to inject a <style> tag onto the page to hide ads, and to get rid of elements whose resources have been blocked from downloading, so that the user doesn't see broken image icons or iframes with errors in them.

adblock_start_chrome.js: Chrome-specific functionality that adblock_start_common.js uses.  The elementPurger object listens for messages from the background about blocked requests, finds the element on the page that made the request, and removes it from view.

adblock_start_safari.js: Safari-specific functionality that adblock_start_common.js uses.  AdBlock listens for "beforeload" events from  Safari every time a DOM element is loaded on the page, calls the background page to see if the element's resource may load, and if not, cancels the load and removes the element from view.

background.js: The main background page script, containing many helper functions called by various parts of AdBlock, plus stores the filter engine, runs code in Chrome to check each request for ads, sets up context menus, etc etc etc.

background_safari.html: Chrome doesn't require a specific .html file to load all your background scripts -- you just list the scripts in manifest.json.  Safari needs a .html file, which is listed in Info.plist.

bandaids.js: A content script containing site-specific hacks.  adblock_start_common calls its run_bandaids() function

functions.js: common utility functions loaded by every part of AdBlock -- the background, the content scripts, the toolbar button, the options page.  Included is localizePage() which finds all i18n message IDs on a web page and fills in the appropriate messages using chrome.i18n.getMessage().  Also included is BGcall(), which lets any part of AdBlock call one of the functions defined in background.js and get a return value back asynchronously.

idlehandler.js: Class that helps AdBlock wait until the user is idle before doing intensive work.

manifest.json: The starting point for Chrome.

port.js: Chrome-to-Safari porting library.  It gives Safari all the chrome.* API functions that Chrome normally defines.  Each of the chrome.* functions it defines in turn call various safari.* API functions to accomplish the same task.

safari_bg.js: Safari-specific background code -- e.g. handling the toolbar button, and listening for requests from adblock_start_safari.js's beforeload event handler.

stats.js: Logging class so that AdBlock can send anonymized messages to a central server, e.g. weekly pings reporting that a user still has AdBlock installed.

button/*: The page that appears when you click the AdBlock toolbar button in Chrome.

filters/adblock_custom.txt: The "AdBlock Custom" filter list, which I upload periodically to the URL from where users download it.

img/, jquery/: images and libraries used by AdBlock. 

Special case: jquery/css/override-page.css: this is CSS applied to webpages when we inject the blacklist wizard, so that the page's own CSS doesn't mess up how our wizard looks.

options/*: Options page and individual Options tabs.

pages/adreport.*: The "Report an ad" advanced toolbar button menu entry

pages/install/*: shown at installation

pages/resourceblock.*: The "Show the Resource List" advanced toolbar button menu entry

pages/subscribe.*: Shown when a user clicks an abp:subscribe link on the web (e.g. on this page: http://adblockplus.org/en/subscriptions )

tools/: not shipped with AdBlock.  Unit tests, a localization tool hosted at chromeadblock.com/l10n , and a program used to verify translations.

uiscripts/*: Scripts for showing the "Block an ad", "Block an ad on this page", and "Don't run on pages on this domain" wizards from the toolbar button menu

filtering/*: The filter engine.  This, along with background.js and adblock_start_*.js, make up the most important parts of AdBlock for blocking ads.

filtering/filtertypes.js: Defines the Filter class and subclasses, which respresent a single ad blocking filter.  Filter.matches() tells us if the filter applies to a given URL.

filtering/filterset.js: Defines the FilterSet class, which is basically a big list of Filters.  FilterSet.matches() tells us if any of its Filter's apply to a given URL.

filtering/myfilters.js: Defines the MyFilters class, which stores the user's subscribed filter lists, fetches updates, and stores the official list URLs.  background.js says "_myfilters = new MyFilters()" at startup.

filtering/filteroptions.js: A few helpful enumerations.

filtering/filternormalizer.js: Reads textual filters (e.g. "ad$third-party,domain=google.com") and makes sure they are well-formatted, ignoring the ones that are broken.

filtering/fifocache.js: A caching utility class... it looks like I'm even using this anymore.  Oops.

filtering/domainset.js: Each Filter has a ._domains property showing what domains it applies to (e.g. "all domains except for google.com and yahoo.com").  A DomainSet represents those domains.

filtering/stylesheetregistrar.js: Safari-only class that uses an experimental more efficient API for hiding ads.  Instead of injecting <style> tags on pages, AdBlock just tells Safari what CSS sheets should be applied on what domains, and Safari takes care of the rest.

[Paolo Anchoriz]

This is really helpful :)