Link Lists Overview

Last edited: 1/24/2011

Link Lists are a very easy way to manage and organize a collection of links. Whether you're building a "quicklinks" sidebar or a blog roll of your favorite digital authors, Link Lists provide a flexible solution that allow for modification without having to wade through markup.

There are two methods of displaying the links of a Link List: as a hierarchical list that retains its structure, or as a flat list.

Example list

For the purpose of example, consider the following Link List:

  • Favorite search engines
    • Google
    • Yahoo!
    • Ask.com
  • Favorite news sites
    • World
      • Drudge Report
      • Fox News
    • Sports
      • ESPN.com
  • My brother's site
  • Mom's favorite picture of me

Display hierarchical list

The following getContent will display all of the above Link List, keeping hierarchy intact:

getContent(
"linklist",
"display:links",
"find:example-list",
"level1:<p>__name__</p>",
"level2:<p>   __name__</p>",
"level3:<p>      __name__</p>",
);

To display only a single level of the hierarchy, such as the first level, remove the level2 and level3 tags, leaving only the level1 tags.

Display flat list

If you simply want to output a flat listing, without having to worry about levels or hierarchy, try the following getContent:

getContent(
"linklist",
"display:links",
"find:example-list",
"show:<img src="__imageurl__" />",
"show:<a href="__url__">",
"show:__name__",
"show:</a>",
"show:<p>__description__</p>"
);

As you can see, show is used instead of the level number to display a flat listing.

Start list at different parent

By default, Link Lists are returned through the API with the parent set to root; that is, the entire list is returned. But what if you only want to display your favorite news sites on the current page? Like so:

  • World
    • Drudge Report
    • Fox News
  • Sports
    • ESPN.com

The parent parameter allows for this, as the following getContent demonstrates:

getContent(
"linklist",
"display:links",
"find:example-list",
"parent:favorite-news-sites",
"show:<img src="__imageurl__" />",
"show:<a href="__url__">",
"show:__name__",
"show:</a>",
"show:<p>__description__</p>"
);

parent can be used with either show or level# tags.

Open link in a new window

When adding or editing a link in the backend, there is a checkbox to "Open link in a new window." This does not magically make the link open in a new window, however; a few easy getContent changes are necessary to implement this option. Consider the following:

getContent(
"linklist",
"display:links",
"find:example-list",
"show:<img src="__imageurl__" />",
"show:<a href="__url__",
"show:__ifnewwindow__target="_blank"",
"show:>",
"show:__name__",
"show:</a>",
"show:<p>__description__</p>"
);

Notice the __ifnewwindow__ tag on its own show line. (This also works with level#.) Here's how it works: If a link is specified to "Open in a new window" in the backend, this tag will return with an empty space (" "); if not, nothing will be returned and the entire show/level# line will not be output. Think of it as a conditional: If "Open in a new window" is checked, a space will be output along with anything else on the line. Here we add target="_blank" to the anchor tag, but you could output rel="external", some class name, or whatever else you use to open a link in a new window. And remember, if "Open in a new window" is not checked, the entire show/level# line will not be output.