A few weeks back I had talked about the need to watch properties of an object and be able to take action when certain values changed. The need for this arose out of wanting to build generic components that could 'attach' themselves to other objects. One example is a drop shadow - if I add a shadow behavior to an object I want the shadow to be pinned to that object so when that object moves I also want the shadow to move with it, or when the panel is hidden the shadow should hide with it - automatically without having to explicitly hook up monitoring code to the panel.

For example, in my shadow plug-in I can now do something like this (where el is the element that has the shadow attached and sh is the shadow):

if (!exists) // if shadow was created 
    el.watch("left,top,width,height,display",
             function() {                         
                 if (el.is(":visible"))
                     $(this).shadow(opt);   // redraw
                 else
                     sh.hide();
             },
             100, "_shadowMove");

The code now monitors several properties and if any of them change the provided function is called. So when the target object is moved or hidden or resized the watcher function is called and the shadow can be redrawn or hidden in the case of visibility going away. So if you run any of the following code:

$("#box")
    .shadow()
    .draggable({ handle: ".blockheader" });
    
    
// drag around the box - shadow should follow

// hide the box - shadow should disappear with box
setTimeout(function() { $("#box").hide(); }, 4000);

// show the box - shadow should come back too
setTimeout(function() { $("#box").show(); }, 8000);

This can be very handy functionality when you're dealing with objects or operations that you need to track generically and there are no native events for them. For example, with a generic shadow object that attaches itself to any another element there's no way that I know of to track whether the object has been moved or hidden either via some UI operation (like dragging) or via code. While some UI operations like jQuery.ui.draggable would allow events to fire when the mouse is moved nothing of the sort exists if you modify locations in code. Even tracking the object in drag mode this is hardly generic behavior - a generic shadow implementation can't know when dragging is hooked up.

So the watcher provides an alternative that basically gives an Observer like pattern that notifies you when something you're interested in changes.

In the watcher hookup code (in the shadow() plugin) above  a check is made if the object is visible and if it is the shadow is redrawn. Otherwise the shadow is hidden. The first parameter is a list of CSS properties to be monitored followed by the function that is called. The function called receives this as the element that's been changed and receives two parameters: The array of watched objects with their current values, plus an index to the object that caused the change function to fire.

How does it work

When I wrote it about this last time I started out with a simple timer that would poll for changes at a fixed interval with setInterval(). A few folks commented that there are is a DOM API - DOMAttrmodified in Mozilla and propertychange in IE that allow notification whenever any property changes which is much more efficient and smooth than the setInterval approach I used previously. On browser that support these events (FireFox and IE basically - WebKit has the DOMAttrModified event but it doesn't appear to work) the shadow effect is instant - no 'drag behind' of the shadow. Running on a browser that doesn't support still uses setInterval() and the shadow movement is slightly delayed which looks sloppy.

There are a few additional changes to this code - it also supports monitoring multiple CSS properties now so a single object can monitor a host of CSS properties rather than one object per property which is easier to work with. For display purposes position, bounds and visibility will be common properties that are to be watched.

Here's what the new version looks like:

$.fn.watch = function (props, func, interval, id) {
        /// <summary>
        /// Allows you to monitor changes in a specific
        /// CSS property of an element by polling the value.
        /// when the value changes a function is called.
        /// The function called is called in the context
        /// of the selected element (ie. this)
        /// </summary>    
        /// <param name="prop" type="String">CSS Properties to watch sep. by commas</param>    
        /// <param name="func" type="Function">
        /// Function called when the value has changed.
        /// </param>    
        /// <param name="interval" type="Number">
        /// Optional interval for browsers that don't support DOMAttrModified or propertychange events.
        /// Determines the interval used for setInterval calls.
        /// </param>
        /// <param name="id" type="String">A unique ID that identifies this watch instance on this element</param>  
        /// <returns type="jQuery" /> 
        if (!interval)
            interval = 200;
        if (!id)
            id = "_watcher";

        return this.each(function () {
            var _t = this;
            var el$ = $(this);
            var fnc = function () { __watcher.call(_t, id) };
            var itId = null;

            var data = { id: id,
                props: props.split(","),
                func: func,
                vals: [props.split(",").length],
                fnc: fnc,
                origProps: props,
                interval: interval
            };
            $.each(data.props, function (i) { data.vals[i] = el$.css(data.props[i]); });
            el$.data(id, data);

            hookChange(el$, id, data.fnc);

        });

        function hookChange(el$, id, fnc) {
            el$.each(function () {
                var el = $(this);
                if (typeof (el.get(0).onpropertychange) == "object")
                    el.bind("propertychange." + id, fnc);
                else if ($.browser.mozilla)
                    el.bind("DOMAttrModified." + id, fnc);
                else
                    itId = setInterval(fnc, interval);
            });
        }
        function __watcher(id) {
            var el$ = $(this);
            var w = el$.data(id);
            if (!w) return;
            var _t = this;

            if (!w.func)
                return;

            // must unbind or else unwanted recursion may occur
            el$.unwatch(id);

            var changed = false;
            var i = 0;
            for (i; i < w.props.length; i++) {
                var newVal = el$.css(w.props[i]);
                if (w.vals[i] != newVal) {
                    w.vals[i] = newVal;
                    changed = true;
                    break;
                }
            }
            if (changed)
                w.func.call(_t, w, i);

            // rebind event
            hookChange(el$, id, w.fnc);
        }
    }
    $.fn.unwatch = function (id) {
        this.each(function () {
            var el = $(this);
            var fnc = el.data(id).fnc;
            try {
                if (typeof (this.onpropertychange) == "object")
                    el.unbind("propertychange." + id, fnc);
                else if ($.browser.mozilla)
                    el.unbind("DOMAttrModified." + id, fnc);
                else
                    clearInterval(id);
            }
            // ignore if element was already unbound
            catch (e) { }
        });
        return this;
    }

There are basically two jQuery functions - watch and unwatch.

jQuery.fn.watch(props,func,interval,id)

Starts watching an element for changes in the properties specified.

props
The CSS properties that are to be watched for changes. If any of the specified properties changes the function specified in the second parameter is fired.

func (watchData,index)
The function fired in response to a changed property. Receives this as the element changed and object that represents the watched properties and their respective values. The first parameter is passed in this structure:

   { id: itId, props: [], func: func, vals: [] };

A second parameter is the index of the changed property so data.props[i] or data.vals[i] gets the property value that has changed.

interval
The interval for setInterval() for those browsers that don't support property watching in the DOM. In milliseconds.

id
An optional id that identifies this watcher. Required only if multiple watchers might be hooked up to the same element. The default is _watcher if not specified.

jQuery.fn.unwatch(id)

Unhooks watching of the element by disconnecting the event handlers.

id
Optional watcher id that was specified in the call to watch. This value can be omitted to use the default value of _watcher.

You can also grab the latest version of the  code for this plug-in as well as the shadow in the full library at:
http://www.west-wind.com:8080/svn/jquery/trunk/jQueryControls/Resources/ww.jquery.js

watcher has no other dependencies although it lives in this larger library. The shadow plug-in depends on watcher.