Great Ocean Media
website design - editorial & pr services - freelance journalism

adi_cat_menu – Category & article menu

This will produce a menu of categories and their articles.

The category list can be defined according to a parent category, a user supplied list or a section.


1. Download and install the plugin in the usual way.

2. To use with standard TXP categories, create a new form of type “article”, called adi_cat_menu_articles, and fill it with:

<li<txp:adi_cat_menu_if> class="active_class"</txp:adi_cat_menu_if>>

3. To use with rss_unlimited_categories, create a new form of type “article”, called adi_cat_menu_rss_articles, and fill it with:


If you have a requirement to generate article lists in more than one format then make use of the article_form and rss_article_form attributes.


Place the <txp:adi_cat_menu /> tag wherever you want the menu to appear. By default, adi_cat_menu will produce a menu containing all article categories together with the articles that belong to them. A parent category can be specified, using the parent="category name" attribute, to restrict the list.

With normal TXP categories, the standard <txp:article_custom /> tag is used to present the lists of articles. <txp:article_custom /> attributes may be specified using the article_attr attribute and are documented in the Textbook.

With <txp:rss_unlimited_categories />, the <txp:rss_unlimited_categories_article_list /> tag is used to present the lists of articles. Attributes for this tag are specified using the article_attr attribute and are documented on wilshire|one.

If you want the output to be “section sensitive” – i.e. only categories that contain articles in a specified section are displayed – then use section_sensitive="1".

Well Sorted

By default, adi_cat_menu will sort the category list according to "name asc" – that is, the category name (as opposed to its title) in ascending alphabetical order.

To sort the category list in other ways use the attribute sort="...", where "..." is defined in the Attributes section below.

Sort articles using the article_attr="..." attribute. This passes attributes directly to <txp:article_custom /> or <txp:rss_unlimited_categories_article_list /> tags depending which mode you’re using. Be aware that, in default mode, you should use sort="title asc" but in rss_unlimited_categories mode (rss_unlimited="1") use sortby="title" sortdir="asc".


parent="category name"

- the parent category. Default = “” (all categories, parents & children).

categories="category name(s)"

- comma separated list of category names to include in the list. Default = “” (include all).

exclude="category name(s)"

- comma separated list of category names which will be excluded from the list. Default = “” (exclude none).

restrict="category field"

- restrict output of articles according to category field. Default = “” (no restriction). Other values: “category1”, “category2”. Section sensitive mode only.

sort="sort values"

- how to sort the category list. Default is “name asc” (alphabetical order). Other options: “id”, “name”, “type”, “parent”, “title”.

class="class name"

- class applied to the top level <ul>. Default = “cat_menu”.

menu_id="id name"

- the ID to be used on the top level <ul>. Default = “” (none).

active_class="class name"

- class applied to active category <li>. Default = “active_class”.

1. In individual article display mode the class is not applied by default to the parent category (but see active_parent attribute).
2. The class applied to active article <li> in the rendered menu defaults to “active_class” also, but can only be changed by editing the adi_cat_menu_articles form.
3. adi_cat_menu uses rss_unlimited_categories_article_list to output the lists of articles. Currently these do not contain the active article so “active_class” does not apply in this case.


- active class applied to parent category <li> of currently active article. Default = “0” (class not applied).


- specifies whether the <li> elements should have unique IDs applied. IDs are based on the section names. Default = “0” (No).


- the prefix to be used for the <li> IDs. Default = “menu_”.

section="section name"

- generate category links to specified section. Default = “” (no section restriction). List of articles is also restricted to those belonging to the specified section.


- generate category links to currently active section. Default = “no”. List of articles is also restricted to those belonging to the current section. Note that this overrides the section attribute.


- generate category links which have articles in the currently active section. Default = “0” (not section sensitive).


- list categories which don’t have any articles. Default = “1” (yes).


- specifies whether to only show articles in currently active category. Default = “0” (show articles in all categories).


- force links to be output in messy URL format. Default = “0” (output links according to Permanent Link Mode setting in TXP Preferences).


- specifies whether to output categories as links. Default = “1” (output links). If set to “0” then only the categories titles will be output.

article_attr='article_custom attributes'

- a list of attributes to be passed through to <txp:article_custom /> or <txp:rss_unlimited_categories_article_list /> to control the appearance of articles (depends on rss_unlimited setting below). Attributes/values should be separated by spaces. Default = ‘’ (i.e. <txp:article_custom /> or <txp:rss_unlimited_categories_article_list /> defaults). Note the use of single quotes. For example: article_attr='sort="Title" limit="20"' or rss_unlimited="1" article_attr='sortby="Title" limit="20"'

article_form="form name"

- the form to use when listing articles. Default = “adi_cat_menu_articles”.


- enables compatibility with rss_unlimited_categories. Default = “0” (standard TXP categories only).

rss_article_form ="form name"

- the form to use when listing articles in rss_unlimited_categories compatibility mode. Default = “adi_cat_menu_rss_articles”.


- the (X)HTML tag (without ‘<>’ brackets) to wrap around the whole menu. Default = “” (no tag). If there is no menu to output then no wraptag is generated.

wraptag_class="class name"

- the class to be used on the wraptag. Default = “menu_wrapper”.

wraptag_id="id name"

- the ID to be used on the wraptag. Default = “” (none).


<txp:adi_cat_menu parent="daddy" article_attr='sort="title" limit="12"' />

In the above example:

<txp:adi_cat_menu article_attr='sort="title asc"' this_section="1" section_sensitive="1" />

The above will:


Some CSS serving suggestions:

/* to set default link colour */
ul.cat_menu a { color: black }
/* to set active link colour */
ul.cat_menu .active_class a { color: red }
ul.cat_menu .active_class ul a { color: black }


Thanks to Kevin Potts for sponsoring this plugin. I’m now the proud owner of a signed copy of his book: Web Design and Marketing Solutions.

Thanks also to Jason Das (floodfish) for sponsoring the ‘list_empty_cats’ feature.

Respect and apologies to Christophe Beyls for the code that I’ve stolen from cbs_category_list to implement the section sensitivity gubbins.

And thanks to jpdupont for the restrict attribute code.

Additional information

Support and further information can be obtained from the Textpattern support forum. A copy of this help is also available online. More adi_plugins can be found here.

adi_cat_menuv0.7Download (Uncompressed) SupportTXP 4.5+