Create a possibility to refresh a layer every N seconds: OpenLayers.Strategy.Refresh, excellent patch by krisgeus, r=me (closes #2317)

git-svn-id: http://svn.openlayers.org/trunk/openlayers@9790 dc9f47b5-9b13-0410-9fdd-eb0c1a62fdaf

lib/OpenLayers.js

@@ -194,6 +194,7 @@
             "OpenLayers/Strategy/Paging.js",
             "OpenLayers/Strategy/BBOX.js",
             "OpenLayers/Strategy/Save.js",
+            "OpenLayers/Strategy/Refresh.js",
             "OpenLayers/Protocol.js",
             "OpenLayers/Protocol/HTTP.js",
             "OpenLayers/Protocol/SQL.js",

lib/OpenLayers/Strategy/Refresh.js

@@ -0,0 +1,139 @@
+/* Copyright (c) 2006-2009 MetaCarta, Inc., published under the Clear BSD
+ * license.  See http://svn.openlayers.org/trunk/openlayers/license.txt for the
+ * full text of the license. */
+
+/**
+ * @requires OpenLayers/Strategy.js
+ */
+
+/**
+ * Class: OpenLayers.Strategy.Refresh
+ * A strategy that refreshes the layer. By default the strategy waits for a
+ *     call to <refresh> before refreshing.  By configuring the strategy with 
+ *     the <interval> option, refreshing can take place automatically.
+ *
+ * Inherits from:
+ *  - <OpenLayers.Strategy>
+ */
+OpenLayers.Strategy.Refresh = OpenLayers.Class(OpenLayers.Strategy, {
+    
+    /**
+     * Property: force
+     * {Boolean} Force a refresh on the layer. Default is false.
+     */
+    force: false,
+
+    /**
+     * Property: interval
+     * {Number} Auto-refresh. Default is 0.  If > 0, layer will be refreshed 
+     *     every N milliseconds.
+     */
+    interval: 0,
+    
+    /**
+     * Property: timer
+     * {Number} The id of the timer.
+     */
+    timer: null,
+
+    /**
+     * Constructor: OpenLayers.Strategy.Refresh
+     * Create a new Refresh strategy.
+     *
+     * Parameters:
+     * options - {Object} Optional object whose properties will be set on the
+     *     instance.
+     */
+    initialize: function(options) {
+        OpenLayers.Strategy.prototype.initialize.apply(this, [options]);
+    },
+   
+    /**
+     * APIMethod: activate
+     * Activate the strategy. Register any listeners, do appropriate setup.
+     * 
+     * Returns:
+     * {Boolean} True if the strategy was successfully activated.
+     */
+    activate: function() {
+        var activated = OpenLayers.Strategy.prototype.activate.call(this);
+        if(activated) {
+            if(this.layer.visibility === true) {
+                this.start();
+            } 
+            this.layer.events.on({
+                "visibilitychanged": this.reset,
+                scope: this
+            });
+        }
+        return activated;
+    },
+    
+    /**
+     * APIMethod: deactivate
+     * Deactivate the strategy. Unregister any listeners, do appropriate
+     *     tear-down.
+     * 
+     * Returns:
+     * {Boolean} True if the strategy was successfully deactivated.
+     */
+    deactivate: function() {
+        var deactivated = OpenLayers.Strategy.prototype.deactivate.call(this);
+        if(deactivated) {
+            this.stop();
+        }
+        return deactivated;
+    },
+    
+    /**
+     * Method: reset
+     * Start or cancel the refresh interval depending on the visibility of 
+     *     the layer.
+     */
+    reset: function() {
+        if(this.layer.visibility === true) {
+            this.start();
+        } else {
+            this.stop();
+        }
+    },
+    
+    /**
+     * Method: start
+     * Start the refresh interval. 
+     */
+    start: function() {
+        if(this.interval && typeof this.interval === "number" && 
+            this.interval > 0) {
+
+            this.timer = window.setInterval(
+                OpenLayers.Function.bind(this.refresh, this),
+                this.interval);
+        }
+    },
+    
+    /**
+     * APIMethod: refresh
+     * Tell the strategy to refresh which will refresh the layer.
+     */
+    refresh: function() {
+        if (this.layer && this.layer.refresh && 
+            typeof this.layer.refresh == "function") {
+
+            this.layer.refresh({force: this.force});
+        }
+    },
+   
+    /**
+     * Method: stop
+     * Cancels the refresh interval. 
+     */
+    stop: function() {
+        if(this.timer !== null) {
+            window.clearInterval(this.timer);
+            this.timer = null;
+        }
+    },
+    
+    CLASS_NAME: "OpenLayers.Strategy.Refresh" 
+});

tests/Strategy/Refresh.html

@@ -0,0 +1,162 @@
+<html>
+<head>
+  <script src="../../lib/OpenLayers.js"></script>
+  <script type="text/javascript">
+
+    var interval = 5000;
+    
+    function test_initialize(t) {
+        t.plan(2);
+
+        var s = new OpenLayers.Strategy.Refresh({interval: interval});
+        t.ok(typeof s.interval === "number", "interval must be a number");
+        t.eq(s.interval, interval, "ctor sets interval");
+    }
+
+    function test_activate(t) {
+        t.plan(4);
+
+        var l = new OpenLayers.Layer.Vector();
+        l.setVisibility(false);
+        var s = new OpenLayers.Strategy.Refresh();
+        s.setLayer(l);
+
+        t.eq(s.active, false, "not active after construction");
+
+        var activated = s.activate();
+        t.eq(activated, true, "activate returns true");
+        t.eq(s.active, true, "activated after activate");
+        t.ok(l.events.listeners.visibilitychanged[0].obj == s &&
+            l.events.listeners.visibilitychanged[0].func == s.reset,
+            "activates registers visibilitychanged listener");
+    }
+
+    function test_activateWithVisibleLayer(t) {
+        t.plan(5);
+
+        var l = new OpenLayers.Layer.Vector();
+        l.setVisibility(true);
+        var s = new OpenLayers.Strategy.Refresh({interval: interval});
+        s.setLayer(l);
+
+        t.eq(s.active, false, "not active after construction");
+
+        var activated = s.activate();
+        t.eq(activated, true, "activate returns true");
+        t.eq(s.active, true, "activated after activate");
+        t.ok(l.events.listeners.visibilitychanged[0].obj == s &&
+            l.events.listeners.visibilitychanged[0].func == s.reset,
+            "activates registers visibilitychanged listener");
+        t.ok(s.timer !== null, "timer should be set on activate if layer is visible");
+
+        // reset the timer!!
+        s.stop();
+    }
+
+    function test_events(t) {
+        
+        t.plan(1);
+        var log = {
+            visibilitychanged: 0
+        };
+
+        var map = new OpenLayers.Map("map");
+        var layer = new OpenLayers.Layer.Vector(null, {
+            strategies: [new OpenLayers.Strategy.Refresh({interval: interval})],
+            protocol: new OpenLayers.Protocol({
+                read: function(config) {
+                    config.callback.call(config.scope, {});
+                }
+            }),
+            isBaseLayer: true,
+            eventListeners: {
+                visibilitychanged: function() {
+                    ++log.visibilitychanged;
+                }
+            }            
+        });
+        map.addLayer(layer);
+
+        layer.setVisibility(false);
+        t.eq(log.visibilitychanged, 1, "visibilitychanged triggered");
+        
+        map.destroy();
+        
+    }
+
+    function test_refreshWithNormalProgress(t) {
+        
+        t.plan(1);
+        var log = {
+            refreshcalled: 0
+        };
+
+        var map = new OpenLayers.Map("map");
+        var layer = new OpenLayers.Layer.Vector(null, {
+            strategies: [new OpenLayers.Strategy.Refresh({
+                interval: interval,
+                refresh: function() {
+                    if (this.layer && this.layer.refresh) {
+                        ++log.refreshcalled;
+                    }
+                }
+            })],
+            protocol: new OpenLayers.Protocol({
+                read: function(config) {
+                    config.callback.call(config.scope, {});
+                }
+            }),
+            isBaseLayer: true
+        });
+        map.addLayer(layer);
+
+        t.delay_call((5 * (interval / 1000)) + 0.5, function() { 
+            t.eq(log.refreshcalled, 5, "number of refreshes");
+            map.destroy();
+        });
+        
+    }
+
+    function test_refreshWithSwitchingVisibility(t) {
+        
+        t.plan(1);
+        var log = {
+            refreshcalled: 0
+        };
+
+        var map = new OpenLayers.Map("map");
+        var layer = new OpenLayers.Layer.Vector(null, {
+            strategies: [new OpenLayers.Strategy.Refresh({
+                interval: interval,
+                refresh: function() {
+                    if (this.layer && this.layer.refresh) {
+                        ++log.refreshcalled;
+                    }
+                }
+            })],
+            protocol: new OpenLayers.Protocol({
+                read: function(config) {
+                    config.callback.call(config.scope, {});
+                }
+            }),
+            isBaseLayer: true
+        });
+        map.addLayer(layer);
+
+        window.setTimeout(function() {
+            layer.setVisibility(false);
+        }, 2.5 * interval);
+        
+        t.delay_call((5 * (interval / 1000)) + 0.5, function() { 
+            t.eq(log.refreshcalled, 2, "number of refreshes");
+            map.destroy();
+        });
+        
+    }
+
+    </script>
+</head>
+<body>
+    <div id="map" style="width: 400px; height: 200px;"></div>
+</body>
+</html>

tests/list-tests.html

@@ -166,6 +166,7 @@
     <li>Strategy/Fixed.html</li>
     <li>Strategy/Paging.html</li>
     <li>Strategy/Save.html</li>
+    <li>Strategy/Refresh.html</li>
     <li>Style.html</li>
     <li>StyleMap.html</li>
     <li>Tile.html</li>