JQuery with ZetaBoards: The Basics

This documentation will walk you through the basics of jQuery as it applies to ZetaBoards. If you have not already, I suggest you browse through the jQuery Tutorials available from the jQuery website. This walkthrough is not a substitute, but rather, a ZetaBoards-specific example of how to use jQuery. Once you understand the basics here, the more general tutorials will help you write more complicated code.

This walkthrough will show you how to create a code that will turn any URLs in a custom profile field into a link in the details next to a user's post.

First you will need to set up a custom profile field that is meant to contain a URL. For this tutorial we'll call it InvisionFree URL, but it can be anything you want.

Create a test topic and make some posts in it. For the best results, use multiple accounts so you can test your code on topics with several different URLs in that field.

The code will go into the JavaScript section of your Board Template.

Developing jQuery is much easier with Firebug. It is not required–you can simply put this code into your Board Template and edit it as you go–but it will make things faster, and its built-in error console helps you figure out why your codes are not functioning properly. If you're using Firebug, you don't need the <script> tags in the below examples. This walkthrough will assume you do not have Firebug, however, and that you're pasting this code directly into your board template.

JQuery uses the Document.ready() construct to make sure your code doesn't run until the page has been completely loaded. The simplest way to use this with jQuery is like so:

<script type="text/javascript">
$(function () {
  // All code goes here
  // It will not run until the page is done loading.
});
</script>

$(function () { }); is a shortcut for the document.ready() construct.

The true power of jQuery lies in its Selectors, which allow you to select and manipulate any element on the page. First, however, you have to determine which elements we want to select.

View the page source of the test topic you created. Locate a definition list with the user_info class–this is where each user's profile details show up in topics. You want to select every definition item (the <dd> element) within every definition list that has the user_info class in it.

With jQuery, the simplest way to select elements is to use a CSS-like syntax–so if you know CSS, you're already halfway there! In this case, you will be selecting dl.user_info dd. You pass this to the jQuery() function, or $() for short.

But wait, there's more. To save even more coding, you can select only those definition items that contain a URL. Here's how:

<script type="text/javascript">
$(function () {
  $("dl.user_profile dd:contains('http://')");
});
</script>

The :contains selector lets you match only those that contain http://.

Now that you have selected the definitions, you need to to loop through each of them. Without jQuery, this would usually involve some sort of for() loop. In jQuery, just use the .each() function:

<script type="text/javascript">
$(function () {
  $("dl.user_profile dd:contains('http://')").each(function () {
    // All code inside this function
    // will be executed for _each_ definition element.
    // It's like a loop, only easier to write.
  });
});
</script>

Use .html() to get the contents of the definition item:

<script type="text/javascript">
$(function () {
  $("dl.user_profile dd:contains('http://')").each(function () {
    var item = $(this).html();
  });
});
</script>

$(this) refers to the current matched element–in this case, the definition item in the current iteration of the .each() function. The item variable contains whatever the content of the field is–in this case, it would be a URL, such as http://google.com/.

The .html() method does more than retrieve HTML, however. You can use it to set the HTML content of an element, which is what you must do next:

<script type="text/javascript">
$(function () {
  $("dl.user_profile dd:contains('http://')").each(function () {
    var item = $(this).html();
    $(this).html('<a href="' + item + '">' + item + '</a>');
  });
});
</script>

This just uses basic string concatenation to set the content of the definition item to <a href="http://google.com/">http://google.com/</a>.

This is a very simple example, intended to demonstrate the convenience of jQuery selectors and how to use .each() to iterate through those elements that you have selected. It does not demonstrate other nifty jQuery features, however, such as chainability, animations and effects, and even Ajax.

• How jQuery Works by John Resig
• Getting Started with jQuery by Jörn Zaefferer
• JQuery for Designers by Mark Panay
• How to Get Anything You Want by Karl Swedberg