Listing Pages

Couch has a powerful tag named pages that can be used to list all pages belonging to a template.
For example -

<cms:pages masterpage='blog.php'>
     <!-- All the variables of each page cloned out of this template are available here -->
     <cms:show k_page_title /><br>
</cms:pages>

- the snippet given above will fetch all pages cloned out of blog.php template.
The masterpage parameter stands for the template's name. If this parameter is omitted, the name of the current template (i.e. the template this snippet is placed in) will be used.

This tag iterates through each of the fetched page and makes available all the data associated with the page as variables. The variables are exactly the same as those made available had the page been accessed discretly via its URL (i.e. in its page-view).

Pages tag supports a number of parameters that can be used to fine tune the actual pages that get fetched.
Please see the parameters section for a comprehensive list.

LISTING PAGES IN THE LIST-VIEWS (HOME-VIEW, FOLDER-VIEW AND ARCHIVE-VIEW)

As shown in the previous chapter, for clonable templates, Couch considers certain URLS as those meant for listing pages cloned out of the template being accessed.

For example:
http://www.mysite.com/blog/
- is considered to be a home-view and a list to all the pages cloned out of blog.php should be displayed in this view.

http://www.mysite.com/blog/hobbies/
- is considered to be a folder-view and a list of all the pages cloned out of blog.php that belong to 'hobbies' sub-folder should be displayed in this view.

http://www.mysite.com/blog/2010/05/
- is considered to be an archive-view and a list of all the pages cloned out of blog.php that have been published during the month of May in 2010 should be displayed in this view.

When a template is accessed using the URLs mentioned above, Couch recognizes the view and sets certain variables that can be used by you to list the pages as is expected for the particular view.
See: Variables available in views.
It is ultimately upto you whether or not you choose to list pages in the expected manner.

Handling home-view

The k_is_home variable can be used to recognize this view and then the pages tag can be used to list all pages cloned from the template being accessed.

<cms:if k_is_home >
    <cms:pages>
        <!-- All the variables of each page cloned out of this template are available here -->
    </cms:pages>
</cms:if>

Handling folder-view

The k_is_folder variable can be used to recognize this view. The k_folder_name variable made available by Couch in this view can then be used as a parameter of the pages tag to list pages belonging to that folder -

<cms:if k_is_folder >
    <cms:pages folder=k_folder_name include_subfolders='1' >
        <!-- All the variables of each page in this folder are available here -->
    </cms:pages>
</cms:if>

Handling archive-view

The k_is_archive can be used to recognize this view. In this view, Couch makes available the k_archive_date and k_next_archive_date variables that denote the boundries of the archive's period. These two variables can then be used as parameters of the pages tag to list pages belonging to that time period -

<cms:if k_is_archive >
    <cms:pages start_on=k_archive_date stop_before=k_next_archive_date >
        <!-- All the variables of each page belonging to this archive period are available here -->
    </cms:pages>
</cms:if>

A unified way of handling all the listviews

The three list views can be handled separately if the way the pages and their contents are displayed differs between the views. However, if their is no difference in the way the list is displayed, the following is the preferred way of handling all the three list-views together -

<cms:if k_is_list >
    <cms:pages folder=k_folder_name include_subfolders='1' start_on=k_archive_date stop_before=k_next_archive_date >
        <!-- All the variables of each page belonging to this view are available here -->
    </cms:pages>
</cms:if>

The snippet given above can handle all the list-views because if the current view is a home-view, the k_folder_name, k_archive_date and k_next_archive_date will not be set and hence these parameters will have no effect on the pages fetched. Similarly in the folder-view the k_archive_date and k_next_archive_date will not be set and in the archive-view the k_folder_name will not be set.