Not Rated!

jQuery Spy : Jquery Plugin

Following many requests, I have upgraded the jQuery spy code to support multiple items returned from the AJAX response and custom timestamp functions – so that requests can be completely tailored.

Import the plug-in, and call the code on the spy container div (assuming you’ve imported jQuery already).

<script type="text/javascript" src="spy.js"></script>
<script type="text/javascript">
  $(function() {
    /* returns a selection of HTML DIVs to be inserted in to
        the #spyContainer in a spy-style */
    $('#spyContainer').spy({'ajax': '/ajax/news.php'});
  });
</script>
<div id="spyContainer"></div>

Usage
Simple Parameters

* ajax – required – the URL to server side script that will return the content
* limit – default 10 – the total number of rows to show
* fadeLast – default 5 – the number of rows to fade out, i.e. the last 5 rows
* fadeInSpeed – default ’slow’ (600) – the speed, in milliseconds to use for the first row to fade in with
* timeout – default 3000 (3 seconds) – the time in milliseconds between showing a new row
* method – default to HTML – should be the AJAX response type, valid values are: HTML or JSON

For example:

$(function() {
  $('#spyContainer').spy({
      'ajax': '/jquery_spy/out.php',  // return type is HTML
      'fadeInSpeed': '1400', // crawl
      'timeout': 2000 // new item every 2 seconds
  });
});

Custom Functionality

* push – custom push on function, this must be customised if using JSON
* timestamp – custom timestamp function, defaults to return seconds from 1978.
* isDupe – custom duplicate check function. This will work if not specified for HTML, but not JSON.
* pushTimeout – control the time between individual items being pushed on to the spy stack.

Custom Push

If you don’t want to return HTML to the spy, you can write your own push method.

Your custom method will have access to ‘this’ which is the DOM element (i.e. the contain div) and ‘response’ which is the response in plain text.

Here is an example using JSON:

$(function() {
  $('#spyContainer').spy({
    'ajax': '/jquery_spy/out_json.php',
    'push': custom_push });
});

function custom_push(response) {
  eval("var json = " + response); // convert to JSON

  // I'm being lazy here, but you get the idea:
  // Build the HTML
  var html = '<div style="display:none">'
  html += '<span class="ctr">' + json.num;
  html += '</span><span class="content">';
  html += json.string + '</span></div>';
  // Prepend the HTML inside the container
  $('#' + this.id).prepend(html);
}

Custom timestamp

Most developers have their own system for tracking the latest items, so I had this in to it’s own pass in function. The example should explain the usage. The return value from the ‘timestamp’ value will be what is passed in to the AJAX request via the ‘timestamp’ posted value.

$(function() {
  $('#spyContainer').spy({
    'limit': 25,
    'fadeLast': 3,
    'ajax': '/jquery_spy/out.php',
    'fadeInSpeed': 'slow',
    'timeout': 3000,
    'timestamp' : myTimestamp };
});

function myTimestamp() {
  var d = new Date();
  // formated as yyyy-mm-dd HH:MM:ss
  return d.getFullYear() + '-' +
    pad(d.getMonth()+1) + '-' + // because month starts at zero
    pad(d.getDate()) + ' ' +
    pad(d.getHours()) + ':' +
    pad(d.getMinutes()) + ':' +
    pad(d.getSeconds());
}

function pad(n) {
  n = n.toString();
  return n.length == 1 ? '0' + n : n;
}

Custom isDupe

This function allows you compare the latest item against the last item to flag for a duplicate. This customisation really comes in to it’s own if you’re using JSON. If give the JSON object an ID, then you can compare the ID between the latest and the last items and chose not to show it.

Continuing in the Digg spy fashion, this spy does allow duplicates to appear in the list, but not next to each other.

If the return value is true the latest item is not shown. If the return value is false, the item is shown.

The function takes two parameters: latest item and last item.

Here’s an example using JSON (assuming our JSON output object has an ID attribute):

$(function() {
  $('#spyContainer').spy({
    'limit': 25,
    'fadeLast': 3,
    'ajax': '/jquery_spy/out_json.php',
    'fadeInSpeed': 'slow',
    'timeout': 3000,
    'method': 'json',   // JSON output
    'isDupe': myIsDupe };
});

function myIsDupe(latest, last) {
  return !!(latest.id == last.id); // return boolean
}

Custom pushTimeout

The custom pustTimeout is particularly useful if you want to show all the items returned from the Ajax call to be pushed on to the stack straight away (rather than evenly one at a time).

The best way to do this is:

$(function () {
  $('spyContainer').spy({
    ... normal settings ...
    'pushTimeout': 1 // gives the appearance of all coming in at once
  });
});

Pause and Play Buttons

Included in the plug-in are pause: pauseSpy() and play: playSpy() functions.

These will, as the digg spy does, pause the flow of new content and start it up again. You can see these in use in the simple example
Usability

I touched on this before, but I would strongly recommend that you think about those users that will have JavaScript disabled for whatever reason. Your spy page should still work.

Here’s what I would recommend:

1. Pre-populate the page. If you are going to limit to 10 items in the spy, start off with 10 items on the page.
2. Use a meta refresh in a tag to automatically have the page reload.

Here’s an example:

<script type="text/javascript">
  // the index starts at zero - so fade down all
  // the divs after the 5th one
  $(function() {
  $('#spyContainer > div:gt(4)').fadeEachDown(); // initial fade
  $('#spyContainer').spy({
    'limit': 8,
    'fadeLast': 3,
    'ajax': '/jquery_spy/out.php',
    'fadeInSpeed': 1400,
    'timeout': 3500 };
  });
</script>

</noscript><noscript>
   <meta http-equiv="refresh" content="60" />
</noscript>

Demo: http://leftlogic.com/jquery/spy.html

Source: http://leftlogic.com/jquery/spy.html

Related Listings:

1. Jquery Spy Script Following many requests, I have upgraded the jQuery spy code…
2. Jquery Add To List Script A very customisable plugin that hooks into select lists. An…
3. jQuery Address – Deep linking plugin This is a jQuery plugin to allow users to select…