openlayers/lib/OpenLayers/Strategy/Paging.js

   1 /* Copyright (c) 2006-2008 MetaCarta, Inc., published under the Clear BSD
   2  * license.  See http://svn.openlayers.org/trunk/openlayers/license.txt for the
   3  * full text of the license. */
   4
   5 /**
   6  * @requires OpenLayers/Strategy.js
   7  */
   8
   9 /**
  10  * Class: OpenLayers.Strategy.Paging
  11  * Strategy for vector feature paging
  12  *
  13  * Inherits from:
  14  *  - <OpenLayers.Strategy>
  15  */
  16 OpenLayers.Strategy.Paging = OpenLayers.Class(OpenLayers.Strategy, {
  17
  18     /**
  19      * Property: features
  20      * {Array(<OpenLayers.Feature.Vector>)} Cached features.
  21      */
  22     features: null,
  23
  24     /**
  25      * Property: length
  26      * {Integer} Number of features per page.  Default is 10.
  27      */
  28     length: 10,
  29
  30     /**
  31      * Property: num
  32      * {Integer} The currently displayed page number.
  33      */
  34     num: null,
  35
  36     /**
  37      * Property: paging
  38      * {Boolean} The strategy is currently changing pages.
  39      */
  40     paging: false,
  41
  42     /**
  43      * Constructor: OpenLayers.Strategy.Paging
  44      * Create a new paging strategy.
  45      *
  46      * Parameters:
  47      * options - {Object} Optional object whose properties will be set on the
  48      *     instance.
  49      */
  50     initialize: function(options) {
  51         OpenLayers.Strategy.prototype.initialize.apply(this, [options]);
  52     },
  53
  54     /**
  55      * APIMethod: activate
  56      * Activate the strategy.  Register any listeners, do appropriate setup.
  57      *
  58      * Returns:
  59      * {Boolean} The strategy was successfully activated.
  60      */
  61     activate: function() {
  62         var activated = OpenLayers.Strategy.prototype.activate.call(this);
  63         if(activated) {
  64             this.layer.events.on({
  65                 "beforefeaturesadded": this.cacheFeatures,
  66                 scope: this
  67             });
  68         }
  69         return activated;
  70     },
  71
  72     /**
  73      * APIMethod: deactivate
  74      * Deactivate the strategy.  Unregister any listeners, do appropriate
  75      *     tear-down.
  76      *
  77      * Returns:
  78      * {Boolean} The strategy was successfully deactivated.
  79      */
  80     deactivate: function() {
  81         var deactivated = OpenLayers.Strategy.prototype.deactivate.call(this);
  82         if(deactivated) {
  83             this.clearCache();
  84             this.layer.events.un({
  85                 "beforefeaturesadded": this.cacheFeatures,
  86                 scope: this
  87             });
  88         }
  89         return deactivated;
  90     },
  91
  92     /**
  93      * Method: cacheFeatures
  94      * Cache features before they are added to the layer.
  95      *
  96      * Parameters:
  97      * event - {Object} The event that this was listening for.  This will come
  98      *     with a batch of features to be paged.
  99      */
 100     cacheFeatures: function(event) {
 101         if(!this.paging) {
 102             this.clearCache();
 103             this.features = event.features;
 104             this.pageNext(event);
 105         }
 106     },
 107
 108     /**
 109      * Method: clearCache
 110      * Clear out the cached features.  This destroys features, assuming
 111      *     nothing else has a reference.
 112      */
 113     clearCache: function() {
 114         if(this.features) {
 115             for(var i=0; i<this.features.length; ++i) {
 116                 this.features[i].destroy();
 117             }
 118         }
 119         this.features = null;
 120         this.num = null;
 121     },
 122
 123     /**
 124      * APIMethod: pageCount
 125      * Get the total count of pages given the current cache of features.
 126      *
 127      * Returns:
 128      * {Integer} The page count.
 129      */
 130     pageCount: function() {
 131         var numFeatures = this.features ? this.features.length : 0;
 132         return Math.ceil(numFeatures / this.length);
 133     },
 134
 135     /**
 136      * APIMethod: pageNum
 137      * Get the zero based page number.
 138      *
 139      * Returns:
 140      * {Integer} The current page number being displayed.
 141      */
 142     pageNum: function() {
 143         return this.num;
 144     },
 145
 146     /**
 147      * APIMethod: pageLength
 148      * Gets or sets page length.
 149      *
 150      * Parameters:
 151      * newLength: {Integer} Optional length to be set.
 152      *
 153      * Returns:
 154      * {Integer} The length of a page (number of features per page).
 155      */
 156     pageLength: function(newLength) {
 157         if(newLength && newLength > 0) {
 158             this.length = newLength;
 159         }
 160         return this.length;
 161     },
 162
 163     /**
 164      * APIMethod: pageNext
 165      * Display the next page of features.
 166      *
 167      * Returns:
 168      * {Boolean} A new page was displayed.
 169      */
 170     pageNext: function(event) {
 171         var changed = false;
 172         if(this.features) {
 173             if(this.num === null) {
 174                 this.num = -1;
 175             }
 176             var start = (this.num + 1) * this.length;
 177             changed = this.page(start, event);
 178         }
 179         return changed;
 180     },
 181
 182     /**
 183      * APIMethod: pagePrevious
 184      * Display the previous page of features.
 185      *
 186      * Returns:
 187      * {Boolean} A new page was displayed.
 188      */
 189     pagePrevious: function() {
 190         var changed = false;
 191         if(this.features) {
 192             if(this.num === null) {
 193                 this.num = this.pageCount();
 194             }
 195             var start = (this.num - 1) * this.length;
 196             changed = this.page(start);
 197         }
 198         return changed;
 199     },
 200
 201     /**
 202      * Method: page
 203      * Display the page starting at the given index from the cache.
 204      *
 205      * Returns:
 206      * {Boolean} A new page was displayed.
 207      */
 208     page: function(start, event) {
 209         var changed = false;
 210         if(this.features) {
 211             if(start >= 0 && start < this.features.length) {
 212                 var num = Math.floor(start / this.length);
 213                 if(num != this.num) {
 214                     this.paging = true;
 215                     var features = this.features.slice(start, start + this.length);
 216                     this.layer.removeFeatures(this.layer.features);
 217                     this.num = num;
 218                     // modify the event if any
 219                     if(event && event.features) {
 220                         // this.was called by an event listener
 221                         event.features = features;
 222                     } else {
 223                         // this was called directly on the strategy
 224                         this.layer.addFeatures(features);
 225                     }
 226                     this.paging = false;
 227                     changed = true;
 228                 }
 229             }
 230         }
 231         return changed;
 232     },
 233
 234     CLASS_NAME: "OpenLayers.Strategy.Paging"
 235 });