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.

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 – created by assigning parents
Excluding sections – 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
Cloning – specify that a section must appear as a child in its own subsection list (more on that below)
Redirection – redirect to another section or link
Admin functions – install, uninstall, import & preferences
A summary of the configured section hierarchy

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

Submenus

If required, adi_menu can be used more than once on a page. For example, to render a submenu 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 submenus are based on the currently active section
on the upper levels, include_children="0" prevents child sections from being rendered
on the lowest submenu, all children & grandchildren are rendered (unless attributes specify otherwise)
active_ancestors="1" enables the “active_class” on the upper levels

The old method of rendering submenus (using a combination of include_current="1" & include_parent="0"), which only really worked for second level submenus, has been deprecated. However for backwards compatibility, the associated attributes and functionality have been retained. 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.

Articles

In adi_menu version 1.1, the method of generating articles changed. Instead of using a form (i.e. adi_menu_articles), the plugin retrieves articles directly from the database.

This means that there is now a bit of variety in where articles can be positioned in the menus.

Previously they would only appear after sections in submenus. Now, with the help of the article_position attribute they may be placed “before”, “after” or “dovetail”. By selecting “dovetail” you can interleave articles and sections in a submenu. Currently only the section/article title is used for sorting/interleaving.

The old method of generating articles is still available but has to be switched back on using new_article_mode="0" and, for new installations of adi_menu, the adi_menu_articles form will need to be manually created containing:
<li class="menu_article"><txp:permlink><txp:title/></txp:permlink></li>.

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 the class defined using 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 andthe class defined using 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 <li> within a <ul>. Default = “” (no class). Note that this class is applied to the first item of every level of the menu.

last_class="class name"

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

odd_even="boolean"

- add “menu_odd” & “menu_even” classes to <li>. Default = “0” (no odd/even classes).

include_default="boolean"

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

default_title="text"

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

clone_title="text"

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

escape="method"

- convert characters in section titles to HTML entities. Default = “” (convert all applicable characters, using UTF8 character set). Use html to convert all applicable characters using ISO-8859-1 character set only (pre v0.12 default) or htmlspecial to only convert special characters (&, “, ‘, <, >). Use none to disable conversion completely.

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.

sort="sort values"

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

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). If you’re wanting to generate submenus, then sub_menu_level might be a better option.

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.

current_children_only="boolean

- only the children of the current section will be output. Default = “0” (all child sections output). Note that siblings will also be output.

sub_menu_level="level"

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

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, except limit which is 9999 in new article mode).
Usage example: article_attr='sort="Title" limit="20"'. Note the use of single quotes.

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

article_class="class name"

- the class applied to <li> elements that contain articles. Default = “menu_article”. New article mode only.

Note: If you are not using the new article mode then this may only be changed by editing the adi_menu_articles form.

article_position="position"

- defines where the articles should be displayed in relation to sections in submenus. Values: “after” (the default, place articles after sections), “before” (place articles before sections), “dovetail” (interleaves articles and subsections alphabetically according to title). Default = “after”. New article mode only.

article_sort="sort values"

- specifies how the articles should be sorted. Default = “Posted desc”. For database order use article_sort="". If used in conjunction with article_position="dovetail" then only “Title”, “Title asc” or “Title desc” are recognised. New article mode only.

- section-specific article sorting is available:

article_sort="section1:title" – default sort “Posted desc”, articles in section1 sorted by “title”
article_sort="title;section2:posted desc" – default sort “title”, articles in section2 sorted by “Posted desc”
article_sort=";section1:posted desc;section2:custom_5" – default sort is database order, articles in section1 sorted by “Posted desc” & section2 articles sorted by custom field

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”

escape="method"

Breadcrumb trail example

To output a breadcrumb trail, including the article’s title, try the following:

<div id="breadcrumb">
<txp:adi_menu_breadcrumb />
<txp:if_individual_article>&#187;&#160;<txp:title/></txp:if_individual_article>
</div>

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.

website design - editorial & pr services - freelance journalism