adi_menu – Section hierarchy, section menu and breadcrumb trail

This plugin provides:

a new tab under Presentation, to set up the section hierarchy
two new tags:
- <txp:adi_menu /> to output the section menu markup
- <txp:adi_menu_breadcrumb /> to output a breadcrumb trail

Installation

Installation of adi_menu will add some columns to your Textpattern database. These columns are named with an “adi_menu” prefix so should not interfere with anything else. That said, if you are of a cautious frame of mind then I can thoroughly recommend rss_admin_db_manager to do database backups before installation.

Once the plugin is installed and activated, go to the adi_menu tab under Presentation, select Install and click the “Do admin” button. Here you will find an Uninstall option as well.

Next, select the Import option if you want to copy section parent settings from cnk_section_tree.

Assign parents, sort order etc and add the <txp:adi_menu /> & <txp:adi_menu_breadcrumb /> tags to your pages or forms.

Style the menu using CSS.

Admin tab

Users with sufficient privileges will see the adi_menu admin tab, under Presentation. This provides:

Section hierarchy – can be created by assigning parents
Section exclusion – define which sections should be permanently excluded from the rendered section menu (sections can also be excluded using a <txp:adi_menu /> tag attribute)
Sorting – specify a custom sort order, if required
Cloning – specify that a section must appear as a child in its own subsection list (more on that below)
Admin functions – install, uninstall and import
A summary of the configured section hierarchy

Tooltips are available here – just hover over anything with a dashed underline.

Articles

Note that a form called adi_menu_articles will be automatically created when you install adi_menu. If this form gets deleted, simply go to the adi_menu tab & it will be created again. Alternatively, if this form has been changed and you want to revert back to default, delete it & go to the adi_menu tab.

The standard <txp:article_custom /> tag is used to list the articles in the section menu (when articles="1") using the adi_menu_articles form. Articles appear after sections in the same level.

To alter the way that the articles are listed, use the article_attr attribute to specify standard <txp:article_custom /> attributes. See below for details.

Sub-menus

If required, adi_menu can be used more than once on a page. For example, to render a sub-menu separately from a top-level menu you could use:

<txp:adi_menu menu_id="top" include_children="0" active_ancestors="1" />
<txp:adi_menu menu_id="sub" sub_menu_level="2" />

For three tiers of menus:

<txp:adi_menu menu_id="top" include_children="0" active_ancestors="1" />
<txp:adi_menu menu_id="sub" sub_menu_level="2" include_children="0" active_ancestors="1" />
<txp:adi_menu menu_id="subsub" sub_menu_level="3" />

Notes:

for styling purposes, you can use the menu_id attribute to set unique ID’s on the menu <ul>
sub_menu_level is section-sensitive, so sub-menus are based on the currently active section
on the upper levels, include_children="0" prevents child sections from being rendered
on the lowest sub-menu, all children & grandchildren are rendered (unless attributes specify otherwise)
active_ancestors="1" enables the “active_class” on the upper levels

The original method of rendering sub-menus, which only really worked for second level sub-menus, has been deprecated. However for backwards compatibility, the associated attributes and functionality will be maintained. See the forum for details.

Speaking Blocks

A speaking block is some additional information added to menu items to enhance usability. When you switch on speaking blocks in adi_menu (speaking_block="1"), each section’s sticky article excerpt is added into the menu, enclosed within a ... inside the <a>...</a> link.

Note that because <a> is by default an inline element, block elements such as  are not allowed within. Consequently you should turn off Textile in the excerpt.

In Textpattern versions 4.0.7 & above, the default speaking block form contains <txp:excerpt />, and does not need to be added manually. If you want to output more than just the sticky article excerpt, for example to include an image, then create a new form containing the required tags and use the speaking_block_form attribute.

For older versions of Textpattern, to emulate the above default behaviour, you should create a new article form and use the speaking_block_form attribute in the adi_menu tag.

adi_menu – tag usage

Place the <txp:adi_menu /> tag wherever you want the menu to appear.

adi_menu – tag attributes

class="class name"

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

menu_id="id name"

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

active_class="class name"

- class applied to the active section link. Default = “active_class”.

active_li_class="class name"

- class applied to the active section <li> element. Default = “” (no class).

active_parent="boolean"

- specifies whether the immediate parent of the active section should be made “active” also. Default = “0” (No). If switched on then active_class will be applied to the parent’s section link and, if defined, active_li_class will be applied to the parent’s <li>.

active_ancestors="boolean"

- specifies whether all ancestors of the active section should be made “active”. Default = “0” (No). If switched on then active_class will be applied to the ancestor’s section link and, if defined, active_li_class will be applied to the ancestor’s <li>. Note that parents are ancestors too, so active_parent="1" active_ancestors="1" is the same as active_ancestors="1".

parent_class="class name"

- the class to be used on section <li> that are parents. Default = “menuparent”.

link_span="boolean"

- specifies whether the contents of the links should be wrapped in a span, i.e. <a>...</a>. Default = “0” (No).

list_id="boolean"

- specifies whether the <li> elements should have unique IDs applied. IDs are based on the section names. Default = “0” (No). Note that cloned section IDs will have a suffix of “_clone” added.

list_id_prefix="text"

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

list_span="boolean"

- specifies whether the contents of the <li> should be wrapped in a span, i.e. <li><a>...</a></li>. Default = “0” (No).

list_prefix="string"

- string to be used as a prefix. Default = “” (no prefix). Note: prefix is inserted within its own  (and class). For example:
<li>PREFIX<a>...</a></li>
If link_span and list_span are also switched on, then the markup becomes:
<li>PREFIX<a>...</a></li>
Use in conjunction with first_class attribute to turn prefix into a separator.

prefix_class="class name"

- class added to the list prefix .... Default = “menu_prefix”.

first_class="class name"

- the class to be used on the first section <li> within a <ul>. Default = “” (no class). Note that this class is applied to the first section of every level of the menu.

last_class="class name"

- the class to be used on the last section <li> within a <ul>. Default = “” (no class). Note that this class is applied to the last section of every level of the menu.

include_default="boolean"

- include ‘default’ section in menu or not. Default = “1” (Yes).

default_title="text"

- title to be used for default section. Default = “Home”.

escape="html"

- escape HTML entities in section titles. Default = “html” (escape all applicable characters). Use escape=“htmlspecial” to only convert &, “, ‘, <, >; or escape=”“ to switch off.

default_first="boolean"

- specifies whether the default section should be listed first. Default = “1” (Yes).

exclude="section list"

- comma separated list of sections to be excluded from the menu. Default = none. Use if you want to exclude sections over and above what has already been excluded in the adi_menu admin tab.

sections="section list"

- comma separated list of sections (& their children) to be included in menu. Default = all.

include_current="boolean"

- specifies whether the current section should be added to the sections list. Default = “0” (No). Note that if the sections attribute is empty then include_current="1" will result in only the current section (& possibly its children) being output.

include_children="boolean"

- specifies whether children should be included in the menu. Default = “1” (Yes).

include_parent="boolean"

- specifies whether top level sections are output. Default = “1” (Yes). Use if you want to output the children of a section but not the parent section itself. Childless top level sections are not output in this case either (see include_childless attribute).

include_childless="boolean"

- overrides the include_parent attribute for childless top level sections. Default = “0” (No). Use if you want to output sections that have no children along with the children of other sections.

sub_menu_level="level"

- the sub-menu level to be output, where “level” is 2 or more. Default=“0” (complete menu generated). This attribute is section-sensitive, so sub-menus are based on the currently active section. Note that the first sub-menu is level 2.

sort="sort values"

- the sort method to be used for sections. Default = database order (i.e. the order in which sections were originally added). Other options: “name” – alphabetical order; “adi_menu_sort” – use order specified in admin tab; “adi_menu_sort, name” – use sort order, then if same use alphabetical order.

clone_title="text"

- the default title to be used for cloned sections, if no title has been specified in the admin tab. Default = “Summary”.

suppress_url="mode"

- suppress the URL of the href attribute in a parent section link (i.e. set it to “#”). Set to “all” to suppress all parent section links or “top” to suppress top-level parent section links only. Default= “” (do not suppress).

speaking_block="boolean"

- enables speaking blocks. Default = “0” (no speaking blocks). By default, speaking blocks are generated from the section’s sticky article excerpt.

speaking_block_form="form name"

- alternative form to be used for the speaking block. Default = “” (none). Note that for Textpattern versions 4.0.7 & above, this attribute is optional (the default form contains: <txp:excerpt />). For older versions, this attribute is required & must reference an existing article form.

label="text"

- some text to precede the menu. Default = “” (no label). If there is no menu to output then no label is generated.

labeltag="tag"

- the (X)HTML tag (without ‘<>’ brackets) to wrap around the label. Default = “” (no tag).

label_class="class name"

- the class to be used on the label’s tag. Default = “menu_label”.

label_id="id name"

- the ID to be used on the label’s tag. Default = “” (none).

wraptag="tag"

- the (X)HTML tag (without ‘<>’ brackets) to wrap around the whole menu (including the label). 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).

articles="boolean"

- specifies whether articles should be included in the menu. Default = “0” (No).

article_attr='article_custom attributes'

- a list of <txp:article_custom /> attributes, separated by spaces, for controlling the appearance of articles. Default = ‘’ (i.e. <txp:article_custom /> defaults). Note the use of single quotes.
For example: article_attr='sort="Title" limit="20"'.

article_include="section list"

- comma separated list of sections that will have their articles included in the menu. Default = “” (all).

article_exclude="section list"

- comma separated list of sections that won’t have their articles included in the menu. Default = “” (none).

active_articles_only="boolean"

- set if you want articles listed for the currently active section only. Default = “0” (articles in all sections listed).

Note: The CSS class applied to article links in the rendered menu defaults to “menu_article” but can be changed by editing the adi_menu_articles form.

adi_menu_breadcrumb – tag usage

Place the <txp:adi_menu_breadcrumb /> tag wherever you want the breadcrumbs to appear.

adi_menu_breadcrumb – tag attributes

label="text"

- the text to precede the breadcrumb trail output. Default = “You are here: “.

separator="text"

- the text to use as a separator between the crumbs. Default = “ » “.

title="boolean"

- specifies whether the section titles should be used. Default = “1” (Yes).

link="boolean"

- specifies whether the sections should links or not. Default = “1” (Yes).

linkclass="class name"

- the CSS class assigned to the breadcrumb links. Default =“noline”.

link_last="boolean"

- specifies whether the last section crumb in list (i.e. the current section) should be a link or not. Only applies in article list mode. Default = “0” (No).

include_default="boolean"

- specifies whether the ‘default’ section should be output. Default = “1” (Yes).

default_title="text"

- the title to be used for the ‘default’ section. Default = “Home”