pagesjs 0.0.5 → 0.1.0

data/ChangeLog

@@ -1,3 +1,10 @@
+== 0.1 (Ignacy Hryniewiecki)
+* Add API to redefine work with URL.
+* Rename Pages.pagesSelector to Pages.selector.
+* Simpler API in Pages.animating.
+* Abort previous page loading, when start to load new one.
+* Decrease files size (by compressible code and UnglifyJS 2).
+
 == 0.0.5 (Pyotr Kakhovsky)
 * Add data.from with URL changing source.
 * Pages.open() will change URL if it necessary.

data/README.md

@@ -76,7 +76,9 @@ For Ruby on Rails you can use gem for Assets Pipeline.
 
 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/pages.js/downloads>.
+Take it from: [github.com/ai/pages.js/downloads].
+
+[github.com/ai/pages.js/downloads]: https://github.com/ai/pages.js/downloads
 
 ## Usage
 
@@ -118,7 +120,7 @@ Callbacks get three arguments:
 * `$`: jQuery.
 * `$$`: jQuery finder only in current page (a little bit faster and more safely
   than `$`). For example `$$('a')` is equal to `$('a', page)`.
-* `page`: jQuery-nodes of selected pages.
+* `page`: jQuery-nodes of selected page.
 
 You can pass `load` as second argument without other options:
 
@@ -165,7 +167,7 @@ You can create you own animation, just add object with `animate` function.
 When animation ends, you *must* call `done` argument.
 
 ```js
-Pages.animation.cool = {
+Pages.animations.cool = {
   animate: function(prev, next, done, data) {
     prev.coolHiding();
     next.coolShowing(function() {
@@ -185,7 +187,7 @@ Argument `data` contains merged page and link data attributes:
 ```
 
 ```js
-Pages.animation.slide = {
+Pages.animations.slide = {
   animate: function(prev, next, done, data) {
     prev.slideHide(data.direction);
     next.slideShow(data.direction, function() {
@@ -222,6 +224,42 @@ $(document).load(function() {
 });
 ```
 
+### History API support
+
+I prefer graceful degradation and think, that old browsers should reload full
+page by old way. But if you want to add page changes animation to old browser,
+you can redefine `Pages.isSupported`, `Pages.getURL`, `Pages.setURL`,
+`Pages.watchURL` and `Pages.unwatchURL` methods to support any of History API
+polyffils.
+
+### URL Methods
+
+You can redefine way, that Pages.js use to get/set current page URL.
+For example, to synchronize open page between different tabs by Session Storage,
+or to support one page sites:
+
+```js
+Pages.isSupported = function() {
+  return true;
+};
+
+Pages.setURL = function(url) {
+  location.hash = url;
+};
+
+Pages.getURL = function() {
+  return location.hash;
+};
+
+Pages.watchURL = function(callback) {
+  $(window).on('hashchange.pages', callback);
+};
+
+Pages.unwatchURL = function() {
+  $(window).off('hashchange.pages');
+};
+```
+
 ## Contributing
 
 1. To run tests you need node.js and npm. For example, in Ubuntu run:
@@ -239,9 +277,12 @@ $(document).load(function() {
 3. Run test server:
 
    ```sh
-   ./node_modules/.bin/cake test
+   ./node_modules/.bin/cake server
    ```
 
-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:
-   <localhost:8000/integration>.
+   [localhost:8000/integration].
+
+[localhost:8000]: http://localhost:8000
+[localhost:8000/integration]: http://localhost:8000/integration

data/lib/assets/javascripts/pages.js

@@ -16,7 +16,7 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
-;(function($) {
+;(function($, undefined) {
   "use strict";
 
   // Pages.js is a framework for History pushState. It allow you to manage
@@ -30,7 +30,7 @@
   //    page content without layout. Just check `HTTP_X_REQUESTED_WITH`
   //    HTTP header to equal `"XMLHttpRequest"`.
   // 3. Load jQuery before Pages.js.
-  window.Pages = {
+  var self = window.Pages = {
 
     // Is history management disabled.
     disabled: false,
@@ -45,8 +45,8 @@
     //
     // Be default it is `article.page` (`article` tag with `page` class).
     //
-    //  Pages.pagesSelector = '.page';
-    pagesSelector: 'article.page',
+    //  Pages.selector = '.page';
+    selector: 'article.page',
 
     // Current animation name. For some page or link you can set
     // custom animation by `data-page-animation` attribute.
@@ -71,7 +71,31 @@
     //     }
     //   };
     //   Pages.animation = 'slideUpDown';
-    animations: { },
+    animations: {
+      // The simplest “animation”. Just immediately hide/show pages
+      // by CSS display property.
+      immediately: {
+        animate: function(prev, next, done, data) {
+          prev.hide();
+          next.show();
+          done();
+        }
+      },
+
+      // Simple fade in/out animation.
+      fade: {
+        // Animation duration in milliseconds.
+        duration: 300,
+
+        animate: function(prev, next, done, data) {
+          var half = this.duration / 2;
+          prev.fadeOut(half, function() {
+            next.fadeIn(half, done);
+          });
+        }
+      },
+
+    },
 
     // Add description for page with `selector`. Allow options:
     // * `load`: `function ($, $$, page)` which is called, when page is loaded
@@ -122,24 +146,24 @@
     //     });
     //   });
     add: function(selector, options) {
-      if ( typeof(options) == 'undefined' ) {
-        this._liveCallbacks.push(selector);
+      if ( options == undefined ) {
+        self._liveCallbacks.push(selector);
       } else {
         if ( typeof(options) == 'function' ) {
           options = { load: options };
         }
         options.selector = selector;
-        this._pages.push(options);
+        self._pages.push(options);
       }
     },
 
     // Run Pages.js. It’s called automatically on document ready.
     // It’s used for tests.
     init: function() {
-      this._enlive($(this._document));
-      var current = this._findCurrent();
+      self._enlive($(self._doc));
+      var current = self._findCurrent();
       if ( current.length ) {
-        this._setCurrent(current);
+        self._setCurrent(current);
       }
     },
 
@@ -148,6 +172,13 @@
     //   if ( !Pages.isSupported() ) {
     //     $('.old-browser-notice').show();
     //   }
+    //
+    // If you rewrite `setURL` and other URL methods, you maybe need
+    // to override this method too:
+    //
+    //   Pages.isSupported = function() {
+    //     return true;
+    //   };
     isSupported: function() {
       return !!(window.history && history.pushState);
     },
@@ -155,20 +186,20 @@
     // Start session history management. It’s called automatically on
     // document ready. You can use it manually after `Pages.disable` calling.
     enable: function() {
-      if ( this._events || !this.isSupported() ) {
+      if ( self._events || !self.isSupported() ) {
         return false;
       }
-      this.disabled = false;
-      this._events = true;
+      self.disabled = false;
+      self._events  = true;
 
-      $(window).on('popstate.pages', function() {
-        if ( Pages._lastUrl != location.pathname ) {
-          Pages.open(location.pathname, { from: 'popstate' });
+      self.watchURL(function() {
+        if ( self._lastUrl != self.getURL() ) {
+          self.open(self.getURL(), { from: 'popstate' });
         }
       });
 
-      $(this._document).on('click.pages', 'a', function() {
-        return Pages._openLink($(this));
+      $(self._doc).on('click.pages', 'a', function() {
+        return self._openLink($(this));
       });
 
       return true;
@@ -177,10 +208,10 @@
     // Disable session history management. Pages.js will load by default browser
     // way without AJAX and animations.
     disable: function() {
-      $(this._document).off('click.pages', 'a');
-      $(window).off('popstate.pages');
-      this.disabled = true;
-      this._events = false;
+      $(self._doc).off('click.pages', 'a');
+      self.unwatchURL();
+      self.disabled = true;
+      self._events = false;
     },
 
     // Show page by `url` with overrided page `data`. Return true if page is
@@ -190,29 +221,29 @@
     //     Pages.open('/gameover');
     //   }, 5000);
     open: function(url, data) {
-      if ( location.pathname != url ) {
-        history.pushState({ }, '', url);
+      if ( self.getURL() != url ) {
+        self.setURL(url);
       }
 
-      if ( typeof(data) == 'undefined' ) {
+      if ( data == undefined ) {
         data = { };
       }
-      if ( typeof(data.from) == 'undefined' ) {
+      if ( data.from == undefined ) {
         data.from = 'js';
       }
       data.url = url;
-      Pages._lastUrl = url;
+      self._lastUrl = url;
 
-      var page = this.page(url);
+      var page = self.page(url);
       if ( page.length ) {
-        this._openPage(page, data);
+        self._openPage(page, data);
         return true;
       } else {
-        this._loadPages(url, data, function(nodes) {
+        self._loadPages(url, data, function(nodes) {
           nodes.hide();
-          page = Pages.page(url, nodes);
+          page = self.page(url, nodes);
           if ( page.length ) {
-            Pages._openPage(page, data);
+            self._openPage(page, data);
           }
         });
         return false;
@@ -220,16 +251,16 @@
     },
 
     // Find loaded page by URL in `data-url` attribute.
-    // It use `Pages.pagesSelector` to detect pages tags.
+    // It use `Pages.selector` to detect pages tags.
     //
     //   if ( Pages.page('/comments').length ) {
     //     // Comment page is loaded to DOM
     //   }
     page: function(url, base) {
       if ( !base ) {
-        base = $(this._document);
+        base = $(self._doc);
       }
-      var selector = this.pagesSelector + '[data-url="' + url + '"]';
+      var selector = self.selector + '[data-url="' + url + '"]';
       return base.filter(selector).add(base.find(selector));
     },
 
@@ -247,10 +278,24 @@
     // from AJAX (but `HTTP_X_REQUESTED_WITH` is better way):
     //
     //   Page.load = function(url, data, callbacks) {
-    //     $.get(url + '?no_layout=1', callback);
+    //     return $.get(url + '?no_layout=1', callback);
     //   };
+    //
+    // It must return some AJAX request object or ID to use it in `stopLoading`.
+    // If you use non-jQuery AJAX, you need also override `stopLoading`.
     load: function(url, data, callback) {
-      $.get(url, callback);
+      return $.get(url, callback);
+    },
+
+    // Stop current AJAX page loading. It just abort jQuery AJAX, but allow you
+    // to override it.
+    //
+    // It will get as argument, what `load` was return.
+    //
+    // You need to override this method, only if your `load` override, don’t
+    // return jQuery jqXHR object (`$.get` and `$.post` return correct jqXHR).
+    stopLoading: function(loading) {
+      loading.abort();
     },
 
     // Change document title. It is internal method, used by `Pages.open`,
@@ -268,17 +313,59 @@
     //
     //   Pages.preload('/posts/all');
     preload: function(url) {
-      this._loadPages(url, { }, function(nodes) {
+      self._loadPages(url, { }, function(nodes) {
         nodes.hide();
       })
     },
 
+    // Change document URL to `url`. By default it will use
+    // `history.pushState`, but you can change it to support
+    // your history library or some hacks.
+    //
+    //   Pages.setURL = function(url) {
+    //     location.hash = url;
+    //   };
+    setURL: function(url) {
+      history.pushState({ }, '', url);
+    },
+
+    // Get current page URL. By default it will use `location.pathname`,
+    // but you can change it to support your history library or some hacks.
+    //
+    //   Pages.getURL = function() {
+    //     return location.hash;
+    //   };
+    getURL: function() {
+      return location.pathname;
+    },
+
+    // Set `callback` to watch for current page URL changes.
+    // By default it will bind to `popstate` event, but you can change it
+    // to support your history library or some hacks.
+    //
+    //   Pages.watchURL = function(callback) {
+    //     $(window).on('hashchange.pages', callback);
+    //   };
+    watchURL: function(callback) {
+      $(window).on('popstate.pages', callback);
+    },
+
+    // Disable listening, which was set by `watchURL`.
+    // By default it will unbind from `popstate` event, but you can change it
+    // to support your history library or some hacks.
+    //
+    //   Pages.unwatchURL = function() {
+    //     $(window).off('hashchange.pages');
+    //   };
+    unwatchURL: function() {
+      $(window).off('popstate.pages');
+    },
+
     // Internal API to wait previous animation, before start new one.
     //
-    //   Pages.animating.wait(function() {
-    //     Pages.animating.start();
+    //   Pages.animating.run(function(done) {
     //     // Animation code
-    //     Pages.animating.end();
+    //     done();
     //   });
     animating: {
 
@@ -288,9 +375,14 @@
       // True if some animation is played now.
       waiting: false,
 
-      // Mark, that we start animation.
-      start: function() {
-        this.waiting = true;
+      // If there isn’t animation now, `callback` will be executed now.
+      // Else `callback` will wait, until previous animation will call `end`.
+      wait: function(callback) {
+        if ( this.waiting ) {
+          this._waiters.push(callback);
+        } else {
+          callback();
+        }
       },
 
       // Mark, that current animation is ended.
@@ -302,20 +394,27 @@
         }
       },
 
-      // If there isn’t animation now, `callback` will be executed now.
-      // Else `callback` will wait, until previous animation will call `end`.
-      wait: function(callback) {
-        if ( this.waiting ) {
-          this._waiters.push(callback);
-        } else {
-          callback();
-        }
+      // Wait for previous animation end, execute `callback` and run another
+      // animations, only after `callback` will execute it first argument.
+      //
+      //   Pages.animating.run(function(done) {
+      //     // Animation code
+      //     done();
+      //   });
+      run: function(callback) {
+        var animating = this;
+        animating.wait(function() {
+          animating.waiting = true;
+          callback(function() {
+            animating.end();
+          });
+        });
       }
 
     },
 
     // Link to current `window.document`. It is used for tests.
-    _document: document,
+    _doc: document,
 
     // Arra of added pages options.
     _pages: [],
@@ -331,19 +430,22 @@
 
     // Find first current page.
     _findCurrent: function() {
-      return $(this.pagesSelector + ':visible:first', this._document)
+      return $(self.selector + ':visible:first', self._doc)
     },
 
+    // AJAX request, if some page is loading now.
+    _loading: null,
+
     // Find pages in new content, set caches and trigger load event on them.
     _enlive: function(nodes) {
-      var args = this._callbackArgs(divs)
-      for (var i = 0; i < this._liveCallbacks.length; i++) {
-        this._liveCallbacks[i].apply(nodes, args);
+      var args = self._callbackArgs(divs)
+      for (var i = 0; i < self._liveCallbacks.length; i++) {
+        self._liveCallbacks[i].apply(nodes, args);
       }
 
       var page, pages;
-      for (var i = 0; i < this._pages.length; i++) {
-        page = this._pages[i];
+      for (var i = 0; i < self._pages.length; i++) {
+        page = self._pages[i];
         var divs = nodes.filter(page.selector);
         divs = divs.add( nodes.find(page.selector) );
         if ( divs.length ) {
@@ -354,7 +456,7 @@
             divs.data('pages', [page]);
           }
           if ( page.load ) {
-            page.load.apply(divs, this._callbackArgs(divs));
+            page.load.apply(divs, self._callbackArgs(divs));
           }
         }
       }
@@ -382,7 +484,7 @@
       for (var i = 0; i < pages.length; i++) {
         page = pages[i];
         if ( page[type] ) {
-          page[type].apply(div, this._callbackArgs(div));
+          page[type].apply(div, self._callbackArgs(div));
         }
       }
     },
@@ -390,11 +492,11 @@
     // Find page descriptions for current and next page and fire `close` and
     // `open` events.
     _setCurrent: function(next) {
-      if ( this.current ) {
-        this._callback(this.current, 'close');
+      if ( self.current ) {
+        self._callback(self.current, 'close');
       }
-      this._callback(next, 'open');
-      this.current = next;
+      self._callback(next, 'open');
+      self.current = next;
     },
 
     // Open URL from link.
@@ -403,7 +505,7 @@
       if ( !href || href[0] != '/' ) {
         return true;
       }
-      if ( typeof(link.data('pagesDisable')) != 'undefined' ) {
+      if ( link.data().pagesDisable != undefined ) {
         return true;
       }
 
@@ -415,7 +517,7 @@
       var path = href[0];
       var hash = href[1];
 
-      this.open(path, data);
+      self.open(path, data);
       if ( hash && location.hash != hash ) {
         location.hash = hash;
       }
@@ -424,8 +526,8 @@
 
     // Open loaded page.
     _openPage: function(page, data) {
-      if ( page[0] == Pages.current[0] ) {
-        Pages._setCurrent(page);
+      if ( page[0] == self.current[0] ) {
+        self._setCurrent(page);
         return;
       }
 
@@ -442,38 +544,43 @@
           }
         }
         if ( pageAnimation ) {
-          anim = pageAnimation(this.current);
+          anim = pageAnimation(self.current);
         }
       }
-      anim = anim || Pages.animation;
+      anim = anim || self.animation;
 
-      this.animating.wait(function() {
-        if ( typeof(data.title) != 'undefined' ) {
-          Pages.title(data.title);
+      self.animating.run(function(done) {
+        if ( data.title != undefined ) {
+          self.title(data.title);
         }
-        Pages.animating.start();
-        Pages.animations[anim].animate(Pages.current, page, function() {
-          Pages.animating.end();
-          Pages._setCurrent(page);
+        self.animations[anim].animate(self.current, page, function() {
+          done();
+          self._setCurrent(page);
         }, data);
       });
     },
 
     // Internal method to load pages. Used in `open` and `preload`.
     _loadPages: function(url, data, callback) {
-      var body = $('body', Pages._document).addClass('page-loading');
+      var body = $('body', self._doc).addClass('page-loading');
         body.trigger('page-loading', data);
         if ( data.link ) {
           data.link.addClass('page-loading');
           data.link.trigger('page-loading', data);
         }
 
-        this.load(url, data, function(html) {
+        if ( self._loading ) {
+          self.stopLoading(self._loading);
+        }
+
+        self._loading = self.load(url, data, function(html) {
+          self._loading = null;
+
           var nodes = $(html);
-          if ( Pages.current.length ) {
-            nodes = nodes.insertAfter(Pages.current);
+          if ( self.current.length ) {
+            self.current.after(nodes);
           } else {
-            nodes = nodes.appendTo(Pages._document.body);
+            $(self._doc.body).append(nodes);
           }
 
           body.removeClass('page-loading');
@@ -483,41 +590,19 @@
             data.link.trigger('page-loaded', data);
           }
 
-          Pages._enlive(nodes);
+          self._enlive(nodes);
           callback(nodes);
         });
     }
 
   };
 
-  // The simplest “animation”. Just immediately hide/show pages
-  // by CSS display property.
-  Pages.animations.immediately = {
-    animate: function(prev, next, done, data) {
-      prev.hide();
-      next.show();
-      done();
-    }
-  };
-
-  // Simple fade in/out animation.
-  Pages.animations.fade = {
-    // Animation duration in milliseconds.
-    duration: 300,
-
-    animate: function(prev, next, done, data) {
-      var half = this.duration / 2;
-      prev.fadeOut(half, function() {
-        next.fadeIn(half, done);
-      });
-    }
-  };
-
   $(document).ready(function() {
-    Pages._lastUrl = location.pathname;
-    Pages.init();
-    if ( !Pages.disabled ) {
-      Pages.enable();
+    self._lastUrl = self.getURL();
+    self.init();
+    if ( !self.disabled ) {
+      self.enable();
     }
   });
-}).call(this, jQuery);
+
+})(jQuery);

metadata

@@ -1,32 +1,32 @@
 --- !ruby/object:Gem::Specification
 name: pagesjs
 version: !ruby/object:Gem::Version
-  version: 0.0.5
   prerelease: 
+  version: 0.1.0
 platform: ruby
 authors:
 - Andrey "A.I." Sitnik
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-10-22 00:00:00.000000000 Z
+date: 2012-11-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
+  type: :runtime
   name: sprockets
+  prerelease: false
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '2'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
     none: false
+  version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '2'
+    none: false
 description: Pages.js allow you to manage pages JS code and forget about low-level
   History API.
 email:
@@ -50,17 +50,17 @@ rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
-required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
+required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
+  none: false
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.23