jquery.anchoring: A JavaScript repository from gleuch

jQuery.anchoring

------------------------------------------------------------------------------------------------------

A jQuery plugin to allow AJAX permalinking with anchoring tags.

Released by Greg Leuch <http://gleuch.com>, originally for Magma <http://mag.ma>.

------------------------------------------------------------------------------------------------------

Easy to use:

  1. Add jquery.anchoring.js to the page.
  2. Add rel="anchor fn_name" to links, where "fn_name" is the name of the callback function.
  3. Add the initalizer and callback function(s):
      $(document).ready(

        // Add callback function 'fn_name'
        $.anchoring.addFunc('fn_name', function(href, data) {
          $.anchoring.retrieve({url: href, success : function() {
            -- return success callback --
            }
          });
        });
        
        // Initializer
        $('a[rel=^anchor]').anchoring({--additional settings--});
      });

  4. Start clicking away.

------------------------------------------------------------------------------------------------------

Examples:

Doing a custom AJAX request with fallback function.

  JavaScript:

  $(document).ready(function() {
    // Adding special function
    $.anchoring.addFunc('search', function(item) {
      var url = (item && item.href && item.href != '' ? item.href : item);

      if (item) $.anchoring.set(url);

      if (url) {
        $.anchoring.retrieve({
          dataType:'HTML',
          url : url,
          success : function(response) {
            $('#example').html(response);
          }
        }
      });
    });

    // Initializing with fallback function (which evals our function previously added above.
    $('a[rel^=anchor').anchoring({
      fallback : function(item) {
        $.anchoring.funcs.search(item ? item : $.anchoring.settings.location);
      }
    });
  });


  And some HTML:

  <p><a href="/search?q=rails" rel="anchor search">Search for 'rails'</a></p>
  <p><a href="/search?q=jQuery" rel="anchor search">Search for 'jQuery'</a></p>
  <div id="example">
    Search results will be replaced in this area.
  </div>



Or do custom functions based on HTML elements. These anchors will be defined by /#tagName.id

  JavaScript:

  $(document).ready(function() {
    // Adding special function for tabbing
    $.anchoring.addFunc('tab', function(item, data) {

      // Use the setElement function instead of the set function
      $.anchoring.setElement(item);

      // Tab effects
      $('#tabs .tab').removeClass('current');
      $('#tabs #tab_'+data).addClass('current');

      // Tab Area affects
      $('#areas .area').hide();
      $('#areas #area_'+data).show();
    });

    // Initialize and set fallback action.
    $('a[rel^=anchor tab]').anchoring({
      fallback : function() {
        // Always enable the first tab.
        $('#tab .tab:eq(0)').click();
      }
    });
  });


  And some HTML using the expansion of the rel attribute for more data:

  <div id="tabs">
    <a id="tab_rails" href="/search?q=rails" rel="anchor tab rails">Info about 'rails'</a>
    <a id="tab_jQuery" href="/search?q=jQuery" rel="anchor tab jQuery">Info about 'jQuery'</a>
  </div>
  <div id="areas">
   <p id="area_rails">This would be more info about 'rails'.</p>
   <p id="area_jQuery">This would be more info about 'rails'.</p>
  </div>


------------------------------------------------------------------------------------------------------

Tested and works in the following browsers:
  - Firefox 2.*, 3.* (and 3.5b)
  - Safari 3.* & 4 beta
  - Internet Explorer 8
  
Works with known issues in the following browsers:
  - Internet Explorer 6 & 7

******************************************************************************************************
NOTE: IE 6 & 7 only allows forward & back button to navigate between actual pages, not anchors.
      jQuery.anchoring does detect and load based on anchor tabs, but if a user clicks their
      back or forward button in their browser, it will take to to the previous page they were on.
******************************************************************************************************
  


Upcoming Features

  - Using JSOND as the default callback method (instead of initial function with an AJAX success 
    function() as the callback).
  - Optimization and testing in older browsers.
  - Demo code and demo page.

------------------------------------------------------------------------------------------------------


Changelog

  - Allowing shortened urls if requested URL base is same as current page URL base.
      - i.e. converts  /videos/#/videos/?page=2  into  /videos/#?page=2
  - Renaming 'default' to 'fallback' due to reserve word in WebKit/Safari.
  - Moving certain vars into settings object and added default function.
  - Removing cache:false from jQuery AJAX and forcing cache only if anchored url is the called url 
    (primarily first request).
gleuch/jquery.anchoring
