Smart Lists is light-weight 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.

Smart Lists is available as both a Scriptaculous-Prototype and a jQuery extension. This page documents the Prototype 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
  • Cross-reference your data in two ways, with 2 flag dropdowns
  • 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)

Demo / Example

You can find the demo here.

Setting up your Smart List

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
<html>
<head>
  <script type="text/javascript" src="prototype.js"></script>
  <script type="text/javascript" src="effects.js"></script>
  <script type="text/javascript" src="smartlists.js"></script>
 
  <script type="text/javascript">
  Event.observe(window, 'load', function() { new 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-num-results"></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>
 
  <div id="sl-pagination2"></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).

A setup with 2 dropdowns, for cross-referencing the data

Conceptually, to understand what the second dropdown gives you – functionally speaking – I’d strongly recommend taking a look at the demo. In short, it lets you flag your data in two ways, letting users pinpoint precisely what they wish to see.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
<html>
<head>
  <script type="text/javascript" src="prototype.js"></script>
  <script type="text/javascript" src="effects.js"></script>
  <script type="text/javascript" src="smartlists.js"></script>
 
  <script type="text/javascript">
  Event.observe(window, 'load', function() {
    new SmartList({
      dd2Flags:  ["Chicken", "Bird"]
    });
  });
  </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-flag-dropdown2"></div>
  <div id="sl-pagination"></div>
  <div id="sl-num-results"></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>
 
  <div id="sl-no-results" style="display:none">No results found.</div>
 
  <div id="sl-pagination2"></div>
 
</body>
</html>

In this example, since you’re requiring two dropdowns, the special required page elements have these id’s:

  • sl-flag-dropdown – the flag dropdown will be inserted here.
  • sl-flag-dropdown2 – 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).
  • sl-no-results – since it is now possible to return no results, by choosing flags in the two dropdowns of which
    no Smart List item has both, you need to include an element with this ID. It is hidden / shown depending on the number of results.

The optional page elements are:

  • sl-pagination2 – a second pagination will be inserted here. This is helpful for the user if your Smart List may have a
    large height, since it lets them choose a new page without having to scroll to the top first.
  • sl-num-results – the number of results currently being viewed is inserted into this page element.

Configuration Options

Smart Lists are initialized with the following JS code:

1
new SmartList();

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// 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"
});

CSS Reference

For convenience, this page lists all the CSS classes / ids used by the Smart List. All classes are customizable via the configuration options, mentioned in the previous page. Notably: the main smart list (default: #sl) can be changed, which acts as a prefix for all the other classes and IDs.

#sl The Smart List
#sl-pagination The pagination element
#sl-flag-dropdown select The flag dropdown
.sl-pagination-selected The current page in the pagination
.sl-page-previous The previous page link
.sl-page-next The next page link
#sl .item A Smart List item
#sl .item .flags One or more flags that categorizes your Smart List item

Download

You can download the code from github. Just click the “download this repository as a Zip file” button. Click here to view the uncompressed source code.