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.

Installation

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>>
<txp:permlink><txp:title/></txp:permlink>
</li>

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

<li>
<txp:rss_sct_permlink><txp:title/></txp:rss_sct_permlink>
</li>

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.

Usage

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”, where 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".

Attributes

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).

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”.

Notes:
1. 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_menu_cat_articles form.
2. 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.

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.

this_section="boolean"

- 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.

section_sensitive="boolean"

- generate category links which have articles in the currently active section. Default = “no”.

active_only="boolean"

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

messy_url="boolean"

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

link="boolean"

- 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”.

rss_unlimited="boolean"

- 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”.

Examples

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

In the above example:

• only child categories belonging to parent category “daddy” will be listed
• the class on the top level <ul> will be “cat_menu”
• the class on the active <li> (category or article) will be “active_class”
• the articles will be sorted according to their titles
• the number of articles per category will be limited to 12

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

The above will:

• create a menu of categories that contain articles belonging to the current section
• list the categories in alphabetical order according to their titles

Styling

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 }

Credits

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 and respect and apologies to Christophe Beyls for the code that I’ve stolen from cbs_category_list to implement the section sensitivity gubbins.

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.

Version 0.4 - Download Support