JQueryLiveQuery < System

---+ %TOPIC%
%JQPLUGINS{"livequery"
  format="
    Homepage: $homepage <br />
    Author(s): $author <br />
    Version: $version
  "
}%

%TOC%

---++ How to use it

%STARTSECTION{"summary"}%
Live Query utilizes the power of jQuery selectors by firing callbacks for
matched elements auto-magically, even after the page has been loaded and the
DOM updated.
%ENDSECTION{"summary"}%

Live Query fires a function (callback) when it matches a new element and
another function (callback) for when an element is no longer matched. This
provides ultimate flexibility and untold use-cases. For example the following
code uses a function based Live Query to implement the jQuery hover helper
method and remove it when the element is no longer matched.

<verbatim class="js">
$('li') 
    .livequery(function(){ 
    // use the helper function hover to bind a mouseover and mouseout event 
        $(this) 
            .hover(function() { 
                $(this).addClass('hover'); 
            }, function() { 
                $(this).removeClass('hover'); 
            }); 
    }, function() { 
        // unbind the mouseover and mouseout events 
        $(this) 
            .unbind('mouseover') 
            .unbind('mouseout'); 
    }); 
</verbatim>

---++ API

---+++ =livequery= signatures

The =livequery= method has 2 different signatures or ways to call it.

Pass one or two functions to =livequery=. Doing this, =livequery= will call the
first passed function when an element is newly matched and will call the second
passed function when an element is removed or no longer matched. The second
function is optional. The =this= or context of the first function will be the
newly matched element. For the second function it will be the element that is
no longer matched.

<verbatim class="js">
// matchedFn: the function to execute when a new element is matched
$(selector).livequery( matchedFn );

// matchedFn: the function to execute when a new element is matched
// unmatchedFn: the function to execute when an element is no longer matched
$(selector).livequery( matchedFn, unmatchFn );
</verbatim>

---+++ =expire= signatures

The =expire= method has 3 different signatures or ways to call it.

The first way will stop/expire all live queries associated with the selector.

<verbatim class="js">
$(selector).expire();
</verbatim>

The second way will stop/expire all live queries associated with the selector and matchedFn.

<verbatim class="js">
// matchedFn: the function to execute when a new element is matched
$(selector).expire( matchedFn );
</verbatim>

The third way will stop/expire all live queries associated with the selector, matchedFn, and unmatchedFn.

<verbatim class="js">
// matchedFn: the function to execute when a new element is matched
// unmatchedFn: the function to execute when an element is no longer matched
$(selector).expire( matchedFn, unmatchFn );
</verbatim>

---++ For Plugin Developers

If your plugin modifies the DOM without using the built-in DOM Modification methods (append, addClass, etc), you can register your plugin with Live Query like this.

<verbatim class="js">
if (jQuery.livequery) 
    jQuery.livequery.registerPlugin("pluginMethodName"); 
</verbatim>

You can register several plugin methods at once by just passing them as additional arguments to the registerPlugin method.

<verbatim class="js">
if (jQuery.livequery) 
    jQuery.livequery.registerPlugin("method1", "method2", "method3"); 
</verbatim>

---++ Example

%JQREQUIRE{"loader, livequery"}%

This is the =livequery= code to prepare the page to process any dom element of class =trigger= when no matter when it appears.

<verbatim class="js">
%STARTSECTION{"javascript"}% <litreral>
<script>

jQuery(function($) {
  $(".trigger").livequery(
    function() {
      var $this = $(this);

      $this.css({
        color:'#fff',
        background:'#b20000',
        display:'inline-block',
        padding:'0.5em'
      });

      //alert("there's a new trigger");
    },
    function() {
      //alert("there's a trigger going offline");
    }
  );

  // adds the refresh behavior
  $(".refresh").click(function() {
    $("#loader").trigger("refresh");
    return false;
  });
});


</script>
</literal> %ENDSECTION{"javascript"}%
</verbatim>

%ADDTOZONE{
  "script"
  section="javascript"
  requires="JQUERYPLUGIN::LIVEQUERY"
}%

This is the content to be loaded asynchronously. It contains a div element with a =trigger= class. This div will be 
processed by an event handler registered using =livequery=.

<verbatim class="tml">
%STARTSECTION{"loadme"}% <div class="trigger">hello world</div> %ENDSECTION{"loadme"}%
</verbatim>


This is a JQueryLoader that will load the content of the =loadme= section below one with a delay of two second.

<div id="loader" class="jqLoader {section:'loadme', delay:2000}">
%ICON{"processing"}%
</div>

Click <a href="#" class="refresh">refresh</a> to do it again.
This topic: System > JQueryPlugin > JQueryLiveQuery
Topic revision: revision 1 (raw view)
Copyright &© by the contributing authors. All material on this site is the property of the contributing authors.
Ideas, requests, problems regarding BACCHUS Wiki? Send feedback