Add the findOnce() function

7 files changed, 70 insertions, 8 deletions

diff --git a/HISTORY.md b/HISTORY.md
index 4bae44c..be799e1 100644
--- a/HISTORY.md
+++ b/HISTORY.md
@@ -1,5 +1,8 @@
 # History
 
+## v2.0.0-alpha.5 October 5, 2014
+- Added findOnce() to allow filtering once'd elements
+
 ## v2.0.0-alpha.4 October 4, 2014
 - Updated documentation
 
diff --git a/README.md b/README.md
index ce0bfa1..1324085 100644
--- a/README.md
+++ b/README.md
@@ -83,6 +83,15 @@ $('div.calendar').once(function() {
 });
 ```
 
+To find once'd elements later on, use the `.findOnce()` function:
+
+``` javascript
+$('div.calendar').findOnce('calendar', function() {
+  // This function is called for each element that was already called "once"
+  // with the "calendar" ID.
+});
+```
+
 
 ## Development
 
@@ -152,5 +161,3 @@ These amazing people have contributed code to this project:
 [Become a contributor!](https://github.com/RobLoach/jquery-once/blob/master/CONTRIBUTING.md#files)
 
 <!-- /BACKERS -->
-
-
diff --git a/jquery.once.js b/jquery.once.js
index 143a835..9ec9479 100644
--- a/jquery.once.js
+++ b/jquery.once.js
@@ -1,5 +1,5 @@
 /*!
- * jQuery Once Plugin 2.0.0-alpha.4
+ * jQuery Once Plugin 2.0.0-alpha.5
  * http://github.com/robloach/jquery-once
  *
  * Dual licensed under the MIT and GPL licenses:
@@ -66,7 +66,34 @@
   };
 
   /**
-   * Filters elements that have been processed once already.
+   * Removes the once data from the given elements, based on the given ID.
+   *
+   * @param id
+   *   A required string representing the name of the data id which should be used
+   *   when filtering the elements. This only filters elements that have already
+   *   been processed by the once function. The id should be the same id that
+   *   was originally passed to the once() function.
+   * @param fn
+   *   (Optional) If given, this function will be called for each element that
+   *   whose element's once data was removed. The function's return value
+   *   follows the same logic as $.each(). Returning true will continue to the
+   *   next matched element in the set, while returning false will entirely
+   *   break the iteration.
+   *
+   * @api public
+   */
+  $.fn.removeOnce = function (id, fn) {
+    // Filter through the elements to find the once'd elements.
+    var elements = this.findOnce(id);
+
+    // Remove the once data from the elements.
+    elements.removeData('jquery-once-' + id);
+
+    return $.isFunction(fn) ? elements.each(fn) : elements;
+  };
+
+  /**
+   * Filters elements that have already been processed once.
    *
    * @param id
    *   A required string representing the name of the data id which should be used
@@ -82,12 +109,12 @@
    *
    * @api public
    */
-  $.fn.removeOnce = function (id, fn) {
+  $.fn.findOnce = function (id, fn) {
     // Filter the elements by which do have the data.
     var name = 'jquery-once-' + id;
     var elements = this.filter(function() {
       return $(this).data(name) === true;
-    }).removeData(name);
+    });
 
     return $.isFunction(fn) ? elements.each(fn) : elements;
   };
diff --git a/once.jquery.json b/once.jquery.json
index cc76ad1..f8c39ab 100644
--- a/once.jquery.json
+++ b/once.jquery.json
@@ -6,7 +6,7 @@
         "jquery",
         "once"
     ],
-    "version": "2.0.0-alpha.4",
+    "version": "2.0.0-alpha.5",
     "author": {
         "name": "Rob Loach",
         "url": "http://robloach.net"
diff --git a/package.json b/package.json
index f19c87e..d10985e 100644
--- a/package.json
+++ b/package.json
@@ -2,7 +2,7 @@
   "name": "jquery-once",
   "title": "jQuery Once",
   "description": "Act on jQuery elements only once.",
-  "version": "2.0.0-alpha.4",
+  "version": "2.0.0-alpha.5",
   "keywords": [
     "jquery"
   ],
diff --git a/test/index.html b/test/index.html
index 887b696..038db22 100644
--- a/test/index.html
+++ b/test/index.html
@@ -24,6 +24,11 @@
       <p>This is <span>Test 4</span>.</p>
     </div>
 
+    <div id="test5">
+      <p>This is <span>Test 5</span>.</p>
+      <p>This is <span>Test 5 #2</span>.</p>
+    </div>
+
   </div>
 
   <script src="http://code.jquery.com/jquery-2.1.1.js"></script>
diff --git a/test/test.js b/test/test.js
index a0c3d58..6e6353f 100644
--- a/test/test.js
+++ b/test/test.js
@@ -59,3 +59,23 @@ test("Remove the value from attribute correctly", function() {
   hasData = $('#test4 span').data('jquery-once-test4');
   ok(!hasData, 'The value is properly removed when called removeOnce().');
 });
+
+test("Finding elements correctly through findOnce()", function() {
+  // Create one once() call.
+  $('#test5 span').once('test5', function() {
+    // Do nothing.
+  });
+
+  // Find the once'd element through the callback.
+  var elements = $('span').findOnce('test5', function() {
+    var hasData = $(this).data('jquery-once-test5');
+    ok(hasData, 'Finding the correct span element after once() through callback.');
+  });
+
+  // Find the once'd element without the callback.
+  elements = $('span').findOnce('test5');
+  elements.each(function() {
+    var hasData = $(this).data('jquery-once-test5');
+    ok(hasData, 'Finding the correct span element after once().');
+  });
+});