CityDesk 2.0-Documentation
Linking to Previous and Next Articles

When your site contains a sequence of articles which are logically read one after the other, you may want to provide a "Next" link on each page which goes to the next article in the sequence, and, possibly, a "Previous" link which goes back to the previous article. This allows your visitors to read the articles one after the other instead of being forced to goback to the home page after each article.

Creating Next and Previous links is easy with CityDesk, and can be completely automated by including CityScript in the article's template.

Before you can create a Next or Previous link, you have to decide which articles to include in the sequence. For example, consider this site:

In this site, it would make sense to provide "Next" and "Previous" links in each chapter of the book. For example when you are reading Chapter 2, there would be a Previous link to Chapter 1 and a Next link to Chapter 3. However, you probably don't want the "Previous" link from Chapter 1 to link to the misspelled article about alligators in the Articles folder, because that is not really a part of the book sequence.

To accomplish this, when you create a Next or Previous link, you must specify the exact set of articles you want to include in the sequence, and their sort order. This is done using exactly the same syntax as the forEach statement. For Next links:

{$ nextLink n var in (condition) sort-order $}
.... link body ....
{$ end $}

For Previous links, simply use the keyword previousLink instead:

{$ previousLink n var in (condition) sort-order $}
.... link body ....
{$ end $}

Notice that this looks almost exactly like a forEach statement:

n is an optional number, greater than zero, indicating the maximum number of articles that you want included in the sequence. If omitted, all articles that match condition are included in the sequence. For example, if your home page contents only lists the ten most recent articles, you may decide that the Next and Previous links on each of those pages should only navigate between the ten most recent articles.

var is a variable name, for example, x, which should start with a letter or underscore and must consist entirely of letters, underscores, and digits. Inside the body of the nextLink/previousLink section, this variable will be assigned to the next or previous article.

condition is a clause which determines which articles to include in the sequence. It must be in parentheses. You can simply use (all), which returns all the articles in your site. To include a subset of all the articles in your site, seeDetermining Which Articles To Include.

sort-order is optional. It can be either sortAscendBy .field or sortDescendBy .field.

Here is an example that could be used in the book chapter template to provide previous and next links to other chapters in the book:

{$ nextLink n in (folder "Book") $}
    <a href="{$n.Link$}">Next</a>
{$ end $}
{$ previousLink p in (folder "Book") $}
    <a href="{$p.Link$}">Previous</a>
{$ end $}

Inside the body of nextLink and previousLink we can put anything we want. We can even pull out fields from the next (previous) article such as the headline. Here's an example showing the headline as well:

{$ nextLink n in (folder "Book") $}
    <a href="{$n.Link$}">Next</a>: {$ n.Headline $}
{$ end $}
{$ previousLink p in (folder "Book") $}
    <a href="{$p.Link$}">Previous</a>: {$ p.Headline $}
{$ end $}

When there is no next or previous article according to the sequence you specified, nothing is printed. However, you can use the else clause to provide alternate text that will appear when there is no next or previous article:

{$ nextLink n in (folder "Book") $}
    <a href="{$n.Link$}">Next</a>
{$ else $}
    The End
{$ end $}
{$ previousLink p in (folder "Book") $}
    <a href="{$p.Link$}">Previous</a>
{$ end $}

That example will print Next links where available, and Previous links where available. On the last article, when there is no next article, it will print The End instead.

As you can see, nextLink and previousLink work very much like forEach. You can think of them as a variety of forEach that magically includes only one article, the next one or the previous one, as offset from the current article. In fact the easiest way to create a Next or Previous link is to copy the forEach loop from your index page verbatim and replace the keyword forEach with nextLink or previousLink, then replace the keyword next with end.

CityDesk Documentation -  Home

---

©Copyright 2001-2003 Fog Creek Software, Inc. All Rights Reserved.