Archives

For some types of templates, like blog and news, it is useful to archive the cloned pages by certain time periods e.g. group together pages by years, months or days.
Archives tag is used to find out all the past time periods (years, months and days) during which atleast one page has been published.

The following snippet will simply list all the monthly periods that contain alleast one published page -

<cms:archives masterpage='blog.php'>
    <cms:date k_archive_date format='F Y' /><br>
</cms:archives>

By default the archives tag will group together pages by month. You can set the type parameter to either yearly, monthly or daily to specify the desired grouping. For example, the following snippet will create yearly archives of pages -

<cms:archives masterpage='blog.php' type='yearly'>
    <cms:date k_archive_date format='F Y' /><br>
</cms:archives>

Variables set by archives tag

The following variables are set for each time period as it is iterated -

k_archive_date

Denotes the beginning of the time period.

k_next_archive_date

Denotes the end of the time period.

k_archive_link

Link to the archive-view of the template.
A listing of all pages that belong to this period can be done here (see below).

k_archive_count

The number of published pages in this period.

k_count

Count of the current iteration.
Starts by default from '1' but this can be modified by the startcount parameter.

Using the variables that get set for each time period, the following snippet could be used to create a side-bar menu that lists the latest 6 available monthly archives along with the count of pages in each period. Each entry is also hyperlinked to it's archive-view page that should list all the contained pages.

<ul>
<cms:archives limit='6'>
    <li>
    <a href="<cms:show k_archive_link/>"><cms:date k_archive_date format='F Y' /></a>
    (<cms:show k_archive_count />)
    </li>
</cms:archives>
</ul>

The archives tag is only the first step in arranging your pages in archives as it merely delineates the archive periods for us.
To list the pages belonging to any of these periods, we'll have to use the pages tag which we have already discussed.

If you recall the pages tag, pages belonging to a particular time period can be easily fetched by setting the start_on and stop_before parameters.
If we set these two parameters to the start and the end of an archive time period, a list of pages that were published during that period can be created.
We can use the k_archive_date and k_next_archive_date variables set at each iteration of the archives tag to do so.

<ul>
<cms:archives masterpage='property.php'>
    <li>
    <b><cms:date k_archive_date format='F Y' /></b> (<cms:show k_archive_count />)
    <ul>
    <cms:pages masterpage='property.php' start_on=k_archive_date stop_before=k_next_archive_date>
        <li>
        <a href="<cms:show k_page_link />"><cms:show k_page_title /></a>
        <i><cms:date k_page_date /></i>
        </li>
    </cms:pages>
    </ul>
    </li>
</cms:archives>
</ul>

The snippet given above is great for listing out on one single page all the monthly archive periods along with the pages belonging to them (like in a site-map).

You can also create separate pages for each archive period.
In fact, Couch already does this for you.
You might recall that Couch supports a view of any clonable template that is dedicated to listing out pages belonging to a time period - the archive-view.
The k_archive_link variable set by the archives tag points to this view for each time period.
Thus for a monthly period of July, 2010, the link of the archive-view of blog.php could be -
http://www.yoursite.com/blog/2010/07/

For an yearly period of 2010, the same link would be -
http://www.yoursite.com/blog/2010/

While for a daily period, the link would be -
http://www.yoursite.com/blog/2010/07/31/

By pointing your browser to these urls, you'll be accessing your blog.php template in archive-view (see: Views).
In this view, apart from other variables that you normally find set, Couch sets the k_archive_date and k_next_archive_date variables (see: Variables available in Views).
It shouldn't be difficult to set up the pages tag to list pages belonging the archive period by using these variables (see: Listing Pages).