Smart Lists: Prototype Extension - 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 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)
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]:
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
|
|
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 (Fuller) Example
Here's another example that illustrates a few more of its configurable options. To keep it as simple as possible, it's in a separate page containing only the necessary JS & HTML. If you're still hazy on precisely what the script adds, try disabling javascript on the page - that should clear things up!
This example is included in the downloadable zipfile for your reference.
Setting up your Smart List
Here's the basic HTML/JS needed to set up your Smart List with Prototype.
<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 special, required 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).
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.
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.
<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:
new SmartList(); // Prototype
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", "" pageChangeDuration: 0.5, // seconds for Prototype numItemsPerPage: 10, paginationLeft: "\u00ab", paginationRight: "\u00bb", maxPaginationLinks: 20, defaultDropdownOptText: "All items", defaultDropdown2OptText: "All items", dd2Flags: [] // an array. See note below });
Most of the settings are clear, but these deserve special mention:
- dd2Flags: this setting is only required if you are require a second dropdown. If you do, you can enter the flag names in this setting (it's an array of strings) and they will appear in the second dropdown instead of the first.
- showFlagCount: this shows the number of the flags in parentheses in the the dropdown(s), after the flag name.
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, #sl-pagination2 | The pagination elements |
| #sl-flag-dropdown select, #sl-flag-dropdown2 select | The flag dropdowns |
| .sl-pagination-selected, .sl-pagination2-selected | The current page in the paginations |
| .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
Click the link below to download the script. The file includes all required Scriptaculous and Prototype files, an example page, and a basic configuration page to help you get started.
As always, if you encounter any bugs or have feature suggestions, please post in this thread.
