Retired Documentation: You are using the documentation for version 1.7.3 which was retired in 2013. Go here for the latest version documentation or check here for your available upgrades to the latest version.
Weblog Category Archive Tag
This tag is designed to let you list all of your weblog entries and have them organized by category.
{exp:weblog:category_archive weblog="default_site" style="linear"}
{categories}
<h3>{category_name}</h3>
{if category_description}<p>{category_description}</p>{/if}
{/categories}
{entry_titles}
<a href="{path='SITE_INDEX'}">{title}</a><br />
{/entry_titles}
{/exp:weblog:category_archive}
This tag allows you to show your entry titles organized by category in a master archive that looks like this:
<h3>Category one</h3>
<p>Category one is our first category.</p>
<a href="www.mysite.com/1/">title one</a><br />
<a href="www.mysite.com/2/">title two</a><br />
<a href="www.mysite.com/3/">title three</a><br />
<a href="www.mysite.com/4/">title four</a><br />
<a href="www.mysite.com/5/">title five</a><br />
<h3>Category two</h3>
<p>This was our second category ever created.</p>
<a href="www.mysite.com/6/">title one</a><br />
<a href="www.mysite.com/7/">title two</a><br />
<a href="www.mysite.com/8/">title three</a><br />
<a href="www.mysite.com/9/">title four</a><br />
<a href="www.mysite.com/10/">title five</a><br />
etc...
It shows the name of each category, and the weblog entry titles assigned to them. Note: Once you have hundreds of weblog entries, it might become cumbersome to use this tag on your page.
Parameters
- backspace="6"
- class="my_custom_class"
- disable="category_fields"
- id="my_custom_id"
- orderby="date"
- show="4|7"
- show_empty="no"
- show_future_entries="yes"
- sort="asc"
- status="open"
- style="linear"
- weblog="news"
backspace=
backspace="6"
Backspacing removes characters from the last iteration of the loop. For example, if you put a <br /> tag after each listed entry you'll have this layout:
Category one
<a href="www.mysite.com/1/">title one</a><br />
<a href="www.mysite.com/2/">title two</a><br />
<a href="www.mysite.com/3/">title three</a><br />
<a href="www.mysite.com/4/">title four</a><br />
<a href="www.mysite.com/5/">title five</a><br />
Category two
<a href="www.mysite.com/6/">title one</a><br />
<a href="www.mysite.com/7/">title two</a><br />
You might, however, not want the <br /> tag after the final item in each set. By adding backspacing you can remove it. Simply count the number of characters and spaces in the item you want to remove and add it to the tag (do not include trailing spaces in your count). A <br /> tag has 6 characters, so you would do this:
{exp:weblog:category_archive weblog="default_site" backspace="6"}
{categories}
<h3>{category_name}</h3>
{/categories}
{entry_titles}
<a href="{path='SITE_INDEX'}">{title}</a><br />
{/entry_titles}
{/exp:weblog:category_archive}
That will produce code like this:
<h3>Category one</h3>
<a href="www.mysite.com/1/">title one</a><br />
<a href="www.mysite.com/2/">title two</a><br />
<a href="www.mysite.com/3/">title three</a><br />
<a href="www.mysite.com/4/">title four</a><br />
<a href="www.mysite.com/5/">title five</a>
<h3>Category two</h3>
<a href="www.mysite.com/6/">title one</a><br />
<a href="www.mysite.com/7/">title two</a>
The "backspace" parameter is only allowed if you are using the "linear" style. It is not applicable if you use the "nested" style for the display of the list.
class=
class="my_custom_class"
When using the "nested" style of display (see the style= parameter), this lets you specify the value of the "class" attribute in the opening <ul> tag. The default value is "nav_cat_archive".
disable=
disable="category_fields"
The disable= parameter allows you to turn off aspects of the tag that you might not be using in order to improve performance. Valid options are:
- category_fields
id=
id="my_custom_id"
When using the "nested" style of display (see the style= parameter), this lets you specify the value of the "id" attribute in the opening <ul> tag. The default value is "nav_cat_archive".
For instance, if you set the parameter as id="my_custom_id", then the beginning of the nested category output would be:
<ul id="my_custom_id">
orderby=
orderby="date"
The "order" parameter sets the display order of the entries. Setting options for this parameter include:
- orderby="date"
- orderby="title"
- orderby="comment"
- orderby="most_recent_comment"
If this parameter is not set, it will default to ordering by the title.
show=
show="4|7"
With this parameter, you can specify which categories will be included in the list. For instance, if you wanted to keep a particular category from being listed you could specify only those you wanted displayed to be included. Category IDs are separated by the pipe character to specify more than one category.
You may alternatively specify which categories to not show:
show="not 3|6|8"
show_empty=
show_empty="no"
show_empty="yes"
This parameter determines whether or not categories that contain no entries are displayed. If you set the parameter to "no" then categories which do not contain any entries will not be included in the list.
By default, categories with no entries will be included.
show_future_entries=
show_future_entries="yes"
You can determine whether you wish for entries dated in the "future" to be included. This option is useful when doing things like creating a list of events, some of which have not occurred yet.
sort=
sort="asc"
sort="desc"
The sort order can be "asc" (ascending order or "oldest item first") or "desc" (descending order or "newest item first"). If you do not use a sort order the default is desc.
Note: The order of the categories will always follow the Category Order specified in the control panel. The only things the sort parameter changes is the order of the entries within each category.
status=
status="open"
You may restrict to entries with a particular status. You can choose multiple statuses using a pipe:
status="draft|reviewed|published"
Or exclude statuses using "not"
status="not submitted|processing|closed"
style=
style="linear"
There are two list "styles" for your categories: "nested" and "linear".
By default, the category list is displayed fully "nested" to show the parent/child hierarchy between the categories. It will display the categories as nested "unordered lists" and will automatically enclose the contents in <li> tags and nest them correctly to show the hierarchy.
When using the "nested" style of display, the opening <ul> tag of the list will have an id of "nav_cat_archive" applied to it. This can be used as a "hook" for javascript or CSS in providing DHTML or other functionality.
<ul id="nav_cat_archive">
The list can also be shown in a flat "linear" style.
For more information about how this option works see the parameter description on the Weblog Categories page.
weblog=
weblog="weblog"
This indicates the name of the weblog that the categories are assigned to. Only a single weblog may be specified since this is a category list for a specific weblog. The weblog parameter is required unless you only have a single weblog.
Variable Pairs
There are two variable pairs to delineate where the category markup starts/ends and where the title markup starts/ends.
{categories} Variable Pair
There are several variables available for use inside the {categories}{/categories} variable pair.
- {category_description}
- {category_id}
- {parent_id}
- {category_image}
- {category_name}
- {category_url_title}
- {path='site/categories'}
- Custom Category Fields
category_description
{categories}
<p>{category_description}</p>
{/categories}
This displays the content of the "category description" field associated with the category. The variable may also be wrapped in a conditional statement so that it only displays if there is content in the field:
{categories}
{if category_description}{category_description}{/if}
{/categories}
category_id
{category_id}
The category ID associated with the category.
parent_id
{parent_id}
The category ID associated with the category's parent (or 0 in the case of a top level category).
category_image
{category_image}
The image link (or other information) you can optionally store with each category within the Control Panel.
category_name
{categories}
<h3>{category_name}</h3>
{/categories}
This displays the name of the category.
category_url_title
{category_url_title}
This variable displays the URL title of the category
path
{categories}
<a href="{path='site/categories'}">{category_name}</a>
{/categories}
The path (template_group/template) is used to create a URL to display a list of the entries belonging to this category.
<a href="{path='site/categories'}">{category_name}</a>
You can also use SITE_INDEX in your path to point to your main site index page. If you show your categories on your home page, using SITE_INDEX is preferable since it will make the URL cleaner.
<a href="{path='SITE_INDEX'}">{category_name}</a>
Custom Category Fields
All custom fields assigned to a category can be accessed using the "short name" of the field:
{class}
{extended_description}
{category_name_fr}
etc..
These are totally dynamic in that any field you create for your category will automatically be available by its "short name" as a variable.
{entry_titles} Variable Pair
There are several variables available for use inside the {entry_titles}{/entry_titles} variable pair.
entry_date
{entry_date format="%Y %m %d"}
The date the entry was submitted
entry_id_path
{entry_titles}
<a href="{entry_id_path='site/index'}">{title}</a>
{/entry_titles}
The path (template_group/template) is used to create a URL to display this entry. This variable uses the entry's id number in the URL. This is typically used within a standard HTML link tag:
<a href="{entry_id_path='site/index'}">{title}</a>
You can also use SITE_INDEX in your path to point to your main site index page. If you show your blog on your home page, using SITE_INDEX is preferable since it will make the URL cleaner.
<a href="{entry_id_path='SITE_INDEX'}">{title}</a>
path
{entry_titles}
<a href="{path='site/index'}">{title}</a>
{/entry_titles}
The path (template_group/template) is used to create a URL to display this entry. This variable uses the entry's url_title in the URL. This is typically used within a standard HTML link tag:
<a href="{path='site/index'}">{title}</a>
You can also use SITE_INDEX in your path to point to your main site index page. If you show your blog on your home page, using SITE_INDEX is preferable since it will make the URL cleaner.
<a href="{path='SITE_INDEX'}">{title}</a>
title
{entry_titles}
{title}
{/entry_titles}
This variable is replaced by the title of the entry.