PUC has been designed to allow you to develop so-called "Checkers" to look for specific changes within websites. These Checkers can be general (As we the "Filter" checker, which uses regular expressions) or it can be specific, such as the Ebay Bid Price Checker.

If you develop a checker that you think someone else might be able to use, feel free to share it on this wiki (see Update Checkers). If you feel you can elaborate on this guide, feel free to modify it. Just sign your changes.

Simple Checkers

A checker is a fragment of javascript code that modifies (overloads) PUC's checker class.

Overloading the following function changes how PUC determines whether a page has been updated:

  this.checkForUpdates(page); // Returns true if there is an update

It is called each time PUC checks for an update, immediately after it has downloaded a new page.

Information about the page to be checked is available in the page object passed to the checkForUpdates function.

The page object holds information about the page, including page.url, page.title, page.newSource, and page.oldSource. page.newSource and page.oldSource are the source code (in html) of the previously downloaded and most recently downloaded webpage. Many types of comparrison can be performed using various string/regular expression functions in javascript.

A basic checker

The following code is a complete (albeit simple) checker:

  this.checkForUpdates = function(page) {
    return (page.newSource != page.oldSource);
  }

Advanced Checkers

User Properties (Checker Banks)

PUC uses "Banks" to allow for user customization and extra data storing. When the User selects a checker and clicks "Checker Properties," they begin editing the Checker Bank. The default Bank can be edited by the Developer in the developer tab. If the default bank changes, then then the existing pages can reload the default bank by clicking "load defaults" in the properties window.

The bank is composed of keys, each of which has an associated array of values. For example, the Filter checker has a key called "Filters," which has an array of Labels for Filters. It also has a key called "Filter Definitions" which has an array of Regular Expressions. The index of each filter label corresponds to the index of each filter definition.

  var bank = page.getBank();

will return the bank corresponding to the current Checker. The following functions may be used to retrieve and set information about banks:

  // Gets the array of values associated with the string key
  bank.getValuesFromKey(key)   

  // gets the array of booleans of the same length specifying 
  // which values are selected by the user
  bank.getSelectedFromKey(key) 

  // Sets the values of a key to a whole new array
  bank.setValuesFromKey(key, newValueArray)      

  // Sets an array of booleans to specifiy which values 
  // should be selected
  bank.setSelectedFromKey(key, newSelectedArray) 

Once retrieved, the values array can be manipulated by reference as a normal Javascript array, for example:

  var vals = bank.getValuesFromKey("Filters");
  // Display all the names of the filters
  for(var i = 0; i < vals.length; i++)
    alert(vals[i]);

PUC remembers banks for checkers even when the user selects a different checker.

TO ADD: How to re-define the bank Add, Edit, and Remove functions.

"Show me what changed"

PUC provides the ability to visualize what has changed in the webpage. Your checker can provide its own difference using this function:

  this.showDiff(page, oldSource, newSource);

showDiff returns the string to be parsed as HTML code by Firefox. In the following basic example, the built-in diffString function is used, along with a filter that removes scripts.

  this.showDiff = function(page, oldSource, newSource) {
    return diffString(this.removeScripts(oldSource), this.removeScripts(newSource));
  }

The visualization can be more succinct, as with this sample, which displays the prices of an Ebay item:

  this.showDiff = function(page, oldSource, newSource) {
    var retval = "";
    retval += '<p><b>Ebay Item Price Changed:</b></p>';
    retval += '<p>New Price: ' + this.getPrice(newSource) + '</p>';
    retval += '<p>Old Price: ' + this.getPrice(oldSource) + '</p>';
    return retval;
  }

Overloadable Functions

This is a listing of the various functions that you can overload when creating an update checker. The only critical function is checkForUpdates. All the other functions do not need to be overloaded for basic functionality.

  // returns true if a change is detected, false otherwise
  this.checkForUpdates(page);

  // When the user is in the properties dialogue box 
  // and they click the "New" button, this function is 
  // called to prompt the user what new data should be added.
  // The return value is the data to be added to the property.
  // By returning null the new data will not be added at all.
  this.onUserCreateNew(bank, key);

  // When the user clicks "Edit" in the properties dialogue
  // the following function is called to determine how to ask
  // the user what to change the value to.
  this.onUserEdit(bank, key, valueIndex);

  // When the user clicks "Remove" in the properties dialoge
  // Returning true will allow the page be remove,
  // returning false will not
  this.onUserRemove(bank, key, valueIndex);

  // When the user clicks "Show me what changed" this function
  // is called.  It returns html that shows the user
  // what has changed in a web page.
  this.showDiff(page, oldSource, newSource);

  // You can create helper functions as desired
  this.helperfunction(param); 

Huh?

It might be easier to comprehend just by purusing the code for the Checker class itself in PUC. As long as you have PUC installed and are using Firefox, you can browse the code directly by putting this in your address bar: chrome://puc/content/pucChecker.js

You can also explore the latest code for PUC on the CVS repository website:

http://www.mozdev.org/source/browse/pageupdatechecker/src/chrome/content/puc/