visibilityjs 0.5 → 0.6

data/ChangeLog

@@ -1,3 +1,7 @@
+== 0.6 (Luna 1, Mechta)
+* Methods onVisible and afterPrerendering return listener ID (by mcfedr).
+* Fix documentation (by Erwann Mest).
+
 == 0.5 (SCORE, communication)
 * Split library to core and timers modules.
 * Allow to unbind change listener.

data/README.md

@@ -1,7 +1,7 @@
 # Visibility.js – a wrapper for the Page Visibility API
 
-Visibility.js allow you to determine whether your web page is visible to an
-user, is hidden in background tab or is prerendering. It allows you use the page
+Visibility.js allows you to determine whether your web page is visible to a
+user, is hidden in background tab or is prerendering. It allows you to use the page
 visibility state in JavaScript logic and improve browser performance by
 disabling unnecessary timers and AJAX requests, or improve user interface
 experience (for example, by stopping video playback or slideshow when user
@@ -22,10 +22,9 @@ assume that the page is visible all the time, and your logic will still work
 correctly, albeit less effective in some cases.
 
 Page Visibility API is natively supported by Google Chrome, Firefox and IE 10.
-You can add support for old Firefox (5–9 versions) by [MozVisibility] hack
-(include it before Visibility.js). For others browsers you can use
-`lib/visibility.fallback.js` with focus/blur hack (note that this hack have
-some issue, see falllback documentation).
+For others browsers you can use `lib/visibility.fallback.js` with focus/blur
+hack (note that this hack have issue, that document become to be hidden,
+when browser just lose focus, but still visible for user).
 
 Sponsored by [Evil Martians].
 
@@ -217,19 +216,51 @@ Visibility.change(function (e, state) {
 });
 ```
 
+Method `change` returns listener ID. You can use it to unbind listener by
+`Visibility.unbind(id)`:
+
+```js
+var listener = Visibility.change(function (e, state) {
+    if ( !Visibility.hidden() ) {
+       VideoPlayer.pause();
+    }
+});
+
+VideoPlayer.onFinish(function () {
+    Visibility.unbind(listener);
+});
+```
+
+Methods `onVisible` and `afterPrerendering` will also return listener ID,
+if they wait visibility state changes. If they execute callback immediately,
+they return `true` if Page Visibility API is supported and `false`
+if they can’t detect visibility state.
+
+```js
+var listener = Visibility.onVisible(function () {
+    notification.takeAttention();
+});
+
+notification.onOutOfDate(function () {
+    if ( typeof(listener) == 'number' ) {
+        Visibility.unbind(listener);
+    }
+});
+```
+
 ## Installing
 
 ### Packages
 
-Visibility.js shipped with 4 files:
+Visibility.js is shipped with 4 files:
 
 * `visibility.core` – core module.
 * `visibility.timers` – `every` and `stop` methods to set `setTimeout` depend
   on visibility state.
 * `visibility` – `visibility.core` and `visibility.timers` together.
 * `visibility.fallback` – fallback for browser without Page Visibility API.
-  It use document `focus`/`blur` events, so it say, that document in hidden,
-  when browser just lose focus.
+  It use document `focus`/`blur` events, so document become to be hidden,
+  when browser just lose focus, but still visible for user.
 
 ### Ruby on Rails
 
@@ -247,29 +278,35 @@ For Ruby on Rails you can use gem for Assets Pipeline.
    bundle install
    ```
 
-3. Include Visibility.js to your `application.js.coffee`:
+3. Include Visibility.js in your `application.js.coffee`:
 
    ```coffee
    #= require visibility
    ```
 
-   If you didn’t use `every` method, you can reduce library size, by including
+   If you willn’t use `every` method, you can reduce library size by including
    only core module:
 
    ```coffee
    #= require visibility.core
    ```
 
-### Other
+### CDN
 
-If you don’t use any assets packaging manager (it’s very bad idea), you can use
-already minified version of the library.
-Take it from: <https://github.com/ai/visibility.js/downloads>.
+If you don’t use any assets packaging manager use [CDNJS]. Add to your site:
 
-## Alternatives
+```html
+<script src="//cdnjs.cloudflare.com/ajax/libs/visibility.js/0.6/visibility.min.js"></script>
+```
 
-If you need smaller and simpler wrapper (for example, just to hide vendor
-prefixes), you can use [visibly.js](https://github.com/addyosmani/visibly.js).
+[CDNJS]: http://cdnjs.com/
+
+### Other
+
+If you need just a files, you can take already minified packages from
+[github.com/ai/visibility.js/downloads].
+
+[github.com/ai/visibility.js/downloads]: https://github.com/ai/visibility.js/downloads
 
 ## Contributing
 
@@ -291,6 +328,8 @@ prefixes), you can use [visibly.js](https://github.com/addyosmani/visibly.js).
    ./node_modules/.bin/cake test
    ```
 
-4. Open tests in browser: <localhost:8000>.
+4. Open tests in browser: [localhost:8000].
 5. Also you can see real usage example in integration test
    `test/integration.html`.
+
+[localhost:8000]: http://localhost:8000

data/lib/assets/javascripts/visibility.core.js

@@ -33,7 +33,9 @@
         // call it now if page is visible now or Page Visibility API
         // doesn’t supported.
         //
-        // Return true if callback if called now.
+        // Return false if API isn’t supported, true if page is already visible
+        // or listener ID (you can use it in `unbind` method) if page isn’t
+        // visible now.
         //
         //   Visibility.onVisible(function () {
         //       Notification.animateNotice("Hello");
@@ -41,7 +43,7 @@
         onVisible: function (callback) {
             if ( !this.isSupported() || !this.hidden() ) {
                 callback();
-                return true;
+                return this.isSupported();
             }
 
             var listener = this.change(function (e, state) {
@@ -50,6 +52,7 @@
                     callback();
                 }
             });
+            return listener;
         },
 
         // Call callback when visibility will be changed. First argument for
@@ -92,13 +95,17 @@
         // If Page Visibility API doesn’t supported, it will call `callback`
         // immediately.
         //
+        // Return false if API isn’t supported, true if page is already after
+        // prerendering or listener ID (you can use it in `unbind` method)
+        // if page is prerended now.
+        //
         //   Visibility.afterPrerendering(function () {
         //       Statistics.countVisitor();
         //   });
         afterPrerendering: function (callback) {
             if ( !this.isSupported() || 'prerender' != this.state() ) {
                 callback();
-                return true;
+                return this.isSupported();
             }
 
             var listener = this.change(function (e, state) {
@@ -107,6 +114,7 @@
                     callback();
                 }
             });
+            return listener;
         },
 
         // Return true if page now isn’t visible to user.

data/lib/assets/javascripts/visibility.js

@@ -33,7 +33,9 @@
         // call it now if page is visible now or Page Visibility API
         // doesn’t supported.
         //
-        // Return true if callback if called now.
+        // Return false if API isn’t supported, true if page is already visible
+        // or listener ID (you can use it in `unbind` method) if page isn’t
+        // visible now.
         //
         //   Visibility.onVisible(function () {
         //       Notification.animateNotice("Hello");
@@ -41,7 +43,7 @@
         onVisible: function (callback) {
             if ( !this.isSupported() || !this.hidden() ) {
                 callback();
-                return true;
+                return this.isSupported();
             }
 
             var listener = this.change(function (e, state) {
@@ -50,6 +52,7 @@
                     callback();
                 }
             });
+            return listener;
         },
 
         // Call callback when visibility will be changed. First argument for
@@ -92,13 +95,17 @@
         // If Page Visibility API doesn’t supported, it will call `callback`
         // immediately.
         //
+        // Return false if API isn’t supported, true if page is already after
+        // prerendering or listener ID (you can use it in `unbind` method)
+        // if page is prerended now.
+        //
         //   Visibility.afterPrerendering(function () {
         //       Statistics.countVisitor();
         //   });
         afterPrerendering: function (callback) {
             if ( !this.isSupported() || 'prerender' != this.state() ) {
                 callback();
-                return true;
+                return this.isSupported();
             }
 
             var listener = this.change(function (e, state) {
@@ -107,6 +114,7 @@
                     callback();
                 }
             });
+            return listener;
         },
 
         // Return true if page now isn’t visible to user.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: visibilityjs
 version: !ruby/object:Gem::Version
-  version: '0.5'
+  version: '0.6'
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-07-06 00:00:00.000000000 Z
+date: 2012-09-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sprockets