added getNextHref, getInsertionPoint, dataFilter

jquery.jscroll.js

@@ -29,7 +29,104 @@
             nextSelector: 'a:last',
             contentSelector: '',
             pagingSelector: '',
-            callback: false
+            callback: false,
+            /* {{{
+            ```js 
+            callback: function() {
+                var $child, $internalRefsToTagName, $jscrollInner, $newSection, tagName;
+                $marker.remove();
+                $jscrollInner = $('.jscroll-inner');
+                $newSection = $(this);
+                $newSection.before($newSection.children('section'));
+                while (($child = $newSection.children().first()).length) {
+                    tagName = $child[0].tagName;
+                    $internalRefsToTagName = $newSection.find(tagName);
+                    $jscrollInner
+                    .find(tagName)
+                    .not($internalRefsToTagName)
+                    .last()
+                    .after($child);
+                }
+                $('.jscroll-added').not($newSection).remove();
+            },
+            ``` 
+            */ // }}}
+
+            getNextHref: false,
+            /* getNextHref: fn(); return href; // {{{
+                Allow hrefs to be returned by user function 
+
+                ```js
+                getNextHref: function() {
+                    var $next, $nextHref;
+                    $next = $('#page-nav a[href]').first();
+                    $nextHref = $next.attr('href');
+                    $next.attr('href', null);
+                    return $nextHref;
+                },
+                ```
+            */ // }}}
+
+            getInsertPoint: false,
+            /* getInsertPoint: fn($inner); return $(element)
+            // {{{
+                Allow user defined function to determine insert
+                point of new parts, part will be inserted
+                **before** returned point.  This allows for
+                inserts to take place within complex HTML
+                structures, eg:
+
+                ```html
+                <section id="initial part">
+                  <div>
+                    <p>
+                      <ol>
+                        <li>
+                          <!-- new parts insert here -->
+                          <div id="insert-point" />
+                 ```
+
+                 ```js
+                 jscroll({
+                   debug: true,
+                   getInsertPoint: function($inner) {
+                       return $marker = $inner.find('#m4rk3r');
+                   }
+                 });
+                 ```
+
+                 TODO: Allow function to perform insertion itself?
+                           This might cause issues with the existing jscroll-added
+                           based processing, but it may be possible to remove those
+                           DIVs if insertion is controlled externally.
+
+                       Conclusion: Modification of insertion points is is best 
+                           performed using the existing callback function.
+
+                 TODO: Combine `dataFilter` functionality?
+                           One wouldn't like to enforce the creation of a manual insert
+                           function, just to allow editing of new HTML.  The ease of
+                           use (minimal setup) of jScroll is a great feature, and
+                           should not be detracted from by overly complex requirements
+                           for user functions (or the need for any user functions at
+                           all). // }}}
+            */
+
+            dataFilter: false,
+            /* dataFilter: fn(html); return html         // {{{
+                Allow user function to modify raw HTML returned 
+                from $.ajax request
+
+            ```js
+              dataFilter: function(data, dataType) {
+                  var $data;
+                  data += '<div id="m4rk3r">';
+                  $data = processDocxAttributes($('<div>').html(data));
+                  return $data.html();
+              },
+            ``` 
+            */ // }}}
+
         }
     };
 
@@ -41,11 +138,11 @@
             _userOptions = (typeof options === 'function') ? { callback: options } : options,
             _options = $.extend({}, $.jscroll.defaults, _userOptions, _data || {}),
             _isWindow = ($e.css('overflow-y') === 'visible'),
-            _$next = $e.find(_options.nextSelector).first(),
+            _$next = _options.getNextHref ? false : $e.find(_options.nextSelector).first(),
             _$window = $(window),
             _$body = $('body'),
             _$scroll = _isWindow ? _$window : $e,
-            _nextHref = $.trim(_$next.attr('href') + ' ' + _options.contentSelector),
+            _nextHref = _options.getNextHref ? _options.getNextHref() : $.trim(_$next.attr('href') + ' ' + _options.contentSelector),
 
             // Check if a loading image is defined and preload
             _preloadImage = function() {
@@ -116,13 +213,13 @@
                 }
             },
 
-            _setBindings = function() {
+            _setBindings = function() { 
                 var $next = $e.find(_options.nextSelector).first();
-                if (!$next.length) {
+                if (!_options.getNextHref && !$next.length) {
                     return;
                 }
                 if (_options.autoTrigger && (_options.autoTriggerUntil === false || _options.autoTriggerUntil > 0)) {
-                    _nextWrap($next);
+                    if (!_options.getNextHref) _nextWrap($next);
                     if (_$body.height() <= _$window.height()) {
                         _observe();
                     }
@@ -134,6 +231,7 @@
                     }
                 } else {
                     _$scroll.unbind('.jscroll');
+                    if (!_options.getNextHref)
                     $next.bind('click.jscroll', function() {
                         _nextWrap($next);
                         _load();
@@ -142,24 +240,41 @@
                 }
             },
 
+            // A more versatile replacement for $.load
+            _get = function(element, url, callback) {
+                return $.ajax({
+                    url: url,
+                    dataType: 'html',
+                    dataFilter: _options.dataFilter,
+                    success: function(data, textStatus, jqXHR) {
+                        element.html(data);
+                        return callback.call(element, data, textStatus, jqXHR);
+                    }
+                });
+            };
+
             // Load the next set of content, if available
             _load = function() {
                 var $inner = $e.find('div.jscroll-inner').first(),
                     data = $e.data('jscroll');
 
                 data.waiting = true;
+                if (!_options.getInsertPoint) 
                 $inner.append('<div class="jscroll-added" />')
                     .children('.jscroll-added').last()
                     .html('<div class="jscroll-loading">' + _options.loadingHtml + '</div>');
-
+                else 
+                    _options.getInsertPoint($inner).before('<div class="jscroll-added" />')
+                        .children('.jscroll-added').last()
+                        .html('<div class="jscroll-loading">' + _options.loadingHtml + '</div>');
                 return $e.animate({scrollTop: $inner.outerHeight()}, 0, function() {
-                    $inner.find('div.jscroll-added').last().load(data.nextHref, function(r, status) {
+                    _get($inner.find('div.jscroll-added').last(), data.nextHref, function(r, status) {
                         if (status === 'error') {
                             return _destroy();
                         }
                         var $next = $(this).find(_options.nextSelector).first();
                         data.waiting = false;
-                        data.nextHref = $next.attr('href') ? $.trim($next.attr('href') + ' ' + _options.contentSelector) : false;
+                        data.nextHref = _options.getNextHref ? _options.getNextHref() : $next.attr('href') ? $.trim($next.attr('href') + ' ' + _options.contentSelector) : false;
                         $('.jscroll-next-parent', $e).remove(); // Remove the previous next link now that we have a new one
                         _checkNextHref();
                         if (_options.callback) {
@@ -216,4 +331,5 @@
         });
     };
 
-})(jQuery);
+})(jQuery);
+// vim: set ts=4 sts=4 sw=4 et: