home » filterJSON : A jQuery Plugin

filterJSON : A jQuery Plugin

I’m pleased to announce the release of a new jQuery plugin that I’ve been working on for the last few days, called “filterJSON.”

What It Does

Imagine that you have a JSON file, and need an easy way to filter through and display its contents on the page. If you’re using a helpful JavaScript library like jQuery, you could use .getJSON() to load and parse the file; however, you’re then left with a huge clump of data to sort through.

Wouldn’t it be easier if there was a way to, in a sense, allow for pagination through these objects? Wouldn’t it be easier if we could set the number of items to display on the page at any given time? That’s exactly what this plugin does.

Twitter Example

In this example, we’re going to reference a JSON file containing my most recent twenty tweets. Twitter offers a JSON feed that we can use… 

http://twitter.com/status/user_timeline/yourUsername.json?count=DesiredCount

Simply substitute your personal username and desired count, and then paste it into the address bar. This will provide a download link for the JSON file. (Note – in a real world situation, you would probably use a CRON job to automatically do this X times per day.)

Step 2

Next create a new folder called “Twitter,” and add an index.html, the filterJson.js plugin, and the JSON file you just downloaded.

Within your index file, reference jQuery and filterJSON just before the closing body tag. 

<!DOCTYPE html>

<html lang="en">
<head>
	<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
	<title>Twitter - filterJSON Example</title>
</head>
<body>

<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js" type="text/javascript"></script>
<script src="filterJson.js" type="text/javascript"></script>
</body>
</html>

Step 3

Now – we can simply call the filterJson() plugin, pass in our JSON file, and set our desired options. 

<script type="text/javascript">
	$('body').filterJson({

	});
</script>

The code above attaches the filterJson plugin to the ‘body’ element, or the element which will contain the returned data. Please note that in an actual website, you would probably use something MUCH more specific, like an unordered list.

filterJSON requires two parameters to function correctly: “data” and “complete.”

  1. data : – A path to the JSON file, relative to the current page.
  2. complete : – Allows you to use the returned data in any way that you like. 
<script type="text/javascript">
	$('body').filterJson({
		data : 'nettuts.json',

		complete : function(i, r) {
			$('body').append('<p>' + r[i].text + '</p>');
		}
	})
</script>

The “complete” function requires a bit of explanation. It comes with two parameters that you can work with: the index (i), and the JSON file’s contents, represented here by “r.” You’re free to name these as you wish. To access each object within the JSON file, we first reference the contents, “r,” and then the index, “i”… or r[i].

To determine what information to display on the page, we have to take a look at the JSON file we downloaded from Twitter.

Twitter JSON Example

A quick glance brings a plethora of properties which are available to us, including “text” which contains – as you would guess – the text for that particular iteration’s tweet. To display that on the page, we simply, within the complete function, append r[i].text.

This process will then repeat itself, increasing “i” by one each time – which, in effect, moves the focus on to the next tweet (or object).

Example

By default, filterJSON assumes a limit of five items. It then appends “More” and “Previous” links accordingly to allow one to filter through each set. If we’d instead prefer to display only one at a time, we add “limit : 1.”

	$('body').filterJson({
		data : 'nettuts.json',
		limit : 1,

		complete : function(i, r) {
			$('body').append('<p>' + r[i].text + '</p>')
		}
	})
Example

Step 4: Customize 

	$('body').filterJson({
		data : 'nettuts.json',
		limit : 4,
		anchorWrap : '<h2>',
		nextText : 'See More',
		prevText : 'Go Back',
		transition: 'fade',
		delay : 1000,

		complete : function(i, r) {
			$('body').append('<p>' + r[i].text + '</p>')
		}
	})

Download the Source Code for this Example.

Available Properties

Required

  1. data : null – Must add a path to desired JSON file. (’js/example-json.json’)
  2. complete : function(index, json) – This is where you add the contents to your page. It accepts an index and json parameter. To cycle through your file, simply use json[i].desiredPropertyNameFromJSONFile. Please note that “index” and “json” can be renamed as you see fit.

Optional

  1. limit : 5 – default is 5. This corresponds to the number of items to display at a time.
  2. delay : 400 – default is 400 (about a half a second). Corresponds to the delay between transitions.
  3. transition : fade, slide – type of transition.
  4. anchorWrap : <p> – What to wrap the “next” and “previous” links in.
  5. prevText : – The value for the prev link.
  6. nextText : – The value for the next link.
  7. prevId : – The id for the prev link.
  8. nextId : – The id for the next link.

Known Issues

I just released this (October 29, 2009), so I’m certain that there are bugs and lines of code that could be cleaned up. :) Here are some that I’m aware of:

  1. There’s a slight flickr when using the “slide” transition.
  2. 100% reliant upon JavaScript being enabled; will be allowing for more graceful degradation with a future update.
  3. In IE6, the text has some opacity issues during fading.

Compliance

filterJSON has been tested in the following browsers:

  1. IE6
  2. IE7
  3. IE8
  4. Firefox
  5. Safari
  6. Chrome