BenjaminKeen.com - Smart Lists

Smart Lists: jQuery Plugin - v1.0.3

What it Does

Smart Lists is light-weight (8KB) script that lets you convert "flat" HTML lists of information into categorized, paginated lists. In essence, it's a presentation layer for improving the readability of related information, without requiring a database or server-side script. It's extremely browser friendly and supports Firefox 2, IE6+, Safari 2+ and Opera 9+.

Smart Lists is available as both a Scriptaculous-Prototype and a jQuery extension. This page documents the jQuery version.

Configurable options:

Choice for the item hide/show effect (Blind, Fade/Appear, Grow/Shrink, none)
Choice for changing page effect (Blind, Fade/Appear, Grow/Shrink, none)
Control over speed at which effects occur
Number of items per page
Option to show/hide the number of items in each category
Complete control over CSS classes (to ensure compatibility with any webpage)
Downgrades gracefully (i.e. if JS not enabled)

An Example >>

An Example

For a live usage of this script, see my Software page - but here's another example with a little commentary.

Imagine you wanted to put the following list of recipes on your webpage [it's wrapped it in an overflowed div because the list was rather long]:

Recipes

White Bread [More...]

A basic white bread recipe. Difficulty Level: easy

Rat a la Tart [More...]

This delicious recipe converts the nasty, smelly rat you found dead in the drainpipe to a sumptuous meal, guaranteed to delight your guests! Difficulty level: medium

Brown Bread [More...]

A basic brown bread recipe. Difficulty Level: medium

Barbecue Cat Sandwiches [More...]

Put your cat to a good use: in a sandwich! Cheap and simple. Difficulty Level: easy

Peanut Butter Cookies [More...]

A favorite to bake and to eat, chocolate chip cookies come in many variations. Difficulty Level: medium

Cake Mix Cookies [More...]

Never heard of 'em? Everything from caramel brownies to hamentaschen and bonbons can be made from cake mixes. Difficulty Level: medium

Beer Bread [More...]

Bread made with beer instead of water! More disgusting than you'd expect! Difficulty Level: hard

Chicken Wings [More...]

Often overlooked, chicken wings are full of flavor. Try them as Buffalo wings, with Thai spices, BBQ sauce and more. Difficulty Level: medium

Greek Eggplant Salad [More...]

Warning! Eggplant is not edible. Ignore all recipes that include eggplant - they're only kidding. Difficulty Level: easy

Chicken Pasta [More...]

Chicken and pasta are two family pleasing staples that come together in this recipe collection. Difficulty Level: hard

Meat Stew [More...]

Possibly the most disgusting thing I've ever eaten, now faithfully reproduced on paper. Guaranteed to open up the sluices at both ends. Difficulty Level: medium

Cereal [More...]

Ah, cereal. Where would we be without cereal? Difficulty Level: easy

Fish Pie [More...]

A fish. In a pie. Difficulty Level: hard

Greek Salad [More...]

Torn Iceburg lettuce, peeled and sliced cucumbers chunks of fresh tomatoes with crumbled feta cheese. Yum! Difficulty Level: medium

Chocolate Sorbet [More...]

A delicious chocolate sorbet - always a delight for the kids! Warning: you need at least a PhD to even *attempt* to create this meal. I tried and failed. THIRTY TIMES. Difficulty Level: hard

Pink Bread [More...]

White bread recipe with a dash of red food dye added for good measure. Difficulty Level: hard

Pretty straightforward, but what if your user wants to search for bread recipes or only simple recipes? They'd have to manually look through each item. With shorter lists this may be feasible, but the larger the list the bigger the pain.

So with a few minor changes to your HTML, here's the same list using the Smart List script:

Recipes

White Bread [More...]

A basic white bread recipe. Flags: Easy Bread

Rat a la Tart [More...]

This delicious recipe converts the nasty, smelly rat you found dead in the drainpipe to a sumptuous meal, guaranteed to delight your guests! Flags: Medium Meat

Brown Bread [More...]

A basic brown bread recipe. Flags: Medium Bread

Barbecue Cat Sandwiches [More...]

Put your cat to a good use: in a sandwich! Cheap and simple. Flags: Easy Meat Snack

Peanut Butter Cookies [More...]

A favorite to bake and to eat, chocolate chip cookies come in many variations. Flags: Medium Snack

Cake Mix Cookies [More...]

Never heard of 'em? Everything from caramel brownies to hamentaschen and bonbons can be made from cake mixes. Flags: Medium Snack

Beer Bread [More...]

Bread made with beer instead of water! More disgusting than you'd expect! Flags: Hard Bread Beer

Chicken Wings [More...]

Often overlooked, chicken wings are full of flavor. Try them as Buffalo wings, with Thai spices, beer, BBQ sauce and more. Flags: Medium Beer Snack

Greek Eggplant Salad [More...]

Warning! Eggplant is not edible. Ignore all recipes that include eggplant - they're only kidding. Flags: Easy Salad

Chicken Pasta [More...]

Chicken and pasta are two family pleasing staples that come together in this recipe collection. Flags: Hard Meat Pasta

Meat Stew [More...]

Possibly the most disgusting thing I've ever eaten, now faithfully reproduced on paper. Guaranteed to open up the sluices at both ends. Flags: Medium Meat

Cereal [More...]

Ah, cereal. Where would we be without cereal? Flags: Easy

Fish Pie [More...]

A fish. In a pie. Flags: Hard Meat

Greek Salad [More...]

Torn Iceburg lettuce, peeled and sliced cucumbers chunks of fresh tomatoes with crumbled feta cheese. Yum! Flags: Medium Salad

Chocolate Sorbet [More...]

A delicious chocolate sorbet - always a delight for the kids! Warning: you need at least a PhD to even *attempt* to create this meal. I tried and failed. THIRTY TIMES. Flags: Hard Snack

Pink Bread [More...]

White bread recipe with a dash of red food dye added for good measure. Flags: Hard Bread

Some functionality to note:

Clicking on a flag or selecting an option from the dropdown filters the list by that flag, hiding all others.
The pagination (<< 1 2 3 >>) only appears if the number of results for a particular flag is greater than the number allowed on a page (in this case 5).
Clicking on a separate page fades out the old page and fades in the new.

From an HTML point of view, other than some superficial styles all I did was identify appropriate flags for each element. It seemed like the difficulty level and recipe type would be logical ways to catalog the information. Then, I added an HTML element within each item node (a div) which listied its flags, like so: <span class="flags">Bread Easy</span>. When the page loads, the script dynamically reads these strings and converts them to comma-delimited links. It also adds an alphabetized dropdown list containing your flags (and, optionally, the flag count) and some links for viewing the items by page.

Whenever you select a flag by clicking on the link or selecting it from the dropdown list, it filters the visible items to only those that contain the selected flag. Hey presto!

Another example >>

Setting up your Smart List

Here's the basic HTML/JS needed to set up your Smart List with jQuery.

<html>
<head>
  <script type="text/javascript" src="jquery.js"></script>
  <script type="text/javascript" src="jquery.smartlists.js"></script>
 
  <script type="text/javascript">
  $(document).ready(function() { $.smartlist(); });
  </script>
 
  <style type="text/css">
  #sl-pagination span { padding-left: 2px; padding-right: 2px; }
  .sl-pagination-selected { border: 1px solid #336699; background-color: #E5F3FE; font-weight: bold; padding: 2px; }
  .sl-pagination-selected a:link, .sl-pagination-selected a:visited { text-decoration: none; color: #0099FF }
  </style>
 
</head>
<body>
 
  <div id="sl-flag-dropdown"></div>
  <div id="sl-pagination"></div>
 
  <div id="sl">
    <div class="item"><span class="flags">Chicken Rat Elephant</span></div>
    <div class="item"><span class="flags">Rat Bird Spam</span></div>
    <div class="item"><span class="flags">Elephant Chicken</span></div>
  </div>
 
</body>
</html>

The three special page elements have these id's:

sl-flag-dropdown - the flag dropdown will be inserted here.
sl-pagination - the << 1 2 3 >> pagination will be inserted here
sl - this contains your entire list. Each item has a class of "item", and each of the item flags have a class of "flags" (though these CSS rules are customizable).

Configuration Options >>

Configuration Options

Smart Lists are initialized with the following JS code:

new SmartList(); // Prototype
$.smartlist(); // jquery

The above initializes them with the default options. Here's how you initialize one with custom options. This lists all options available:

// PROTOTYPE
new SmartList({
  baseName:               "sl",
  itemClass:              "item",
  showFlagCount:          false,
  itemFlagClass:          "flags",
  itemFlagSeparator:      ", ",
  itemChangeEffect:       "Blind", // "FadeAppear", "Blind", "ShrinkGrow", ""
  itemChangeDuration:     0.5, // seconds for Prototype
  pageChangeEffect:       "FadeAppear", // "FadeAppear", "Blind", "ShrinkGrow", "" (ShrinkGrow not available for jQuery extension)
  pageChangeDuration:     0.5, // seconds for Prototype
  numItemsPerPage:        10,
  paginationLeft:         "\u00ab",
  paginationRight:        "\u00bb",
  maxPaginationLinks:     20,
  defaultDropdownOptText: "All items"
});
 
// JQUERY
$.smartlist({
  baseName:               "sl",
  itemClass:              "item",
  showFlagCount:          false,
  itemFlagClass:          "flags",
  itemFlagSeparator:      ", ",
  itemChangeEffect:       "Blind", // "FadeAppear", "Blind", ""
  itemChangeDuration:     500, // ms for jQuery
  pageChangeEffect:       "FadeAppear", // "FadeAppear", "Blind", ""
  pageChangeDuration:     500, // ms for jQuery
  numItemsPerPage:        10,
  paginationLeft:         "\u00ab",
  paginationRight:        "\u00bb",
  maxPaginationLinks:     20,
  defaultDropdownOptText: "All items"
});

CSS Reference >>