adi_menu – section hierarchy, section menu and breadcrumb trail

gomedia · 2008-07-15 14:16:03

Summary

adi_menu will create a section menu based on a predefined section hierarchy.

Once installed and activated, you’ll get:

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

See the help supplied with the plugin, or have a look online.

Out of the box functionality

Once adi_menu has been installed and activated, the <txp:adi_menu /> tag will produce a <ul> list of sections (in a similar manner to <txp:section_list wraptag="ul break="li" />), and <txp:adi_menu_breadcrumb /> will produce a breadcrumb trail.

By assigning parents to sections in the adi_menu admin tab, a section hierarchy can be created.

For example:

A
B
- B1
- B2
C
- C1
D

will be rendered as:

<ul id="mainmenu" class="section_list">
   <li>Home</li>
   <li>A</li>
   <li class="menuparent">B
      <ul>
         <li>B1</li>
         <li>B2</li>
      </ul>
   </li>
   <li class="menuparent">C
      <ul>
         <li>C1</li>
      </ul>
   </li>
   <li>D</li>
</ul>

Note that:

by default adi_menu will output a link to the ‘default’ section, which again by default is named “Home’ (this behaviour can be modified using adi_menu tag attributes)
for clarity, I’ve omitted the link markup.

Admin tab features

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
Preferences
A summary of the configured section hierarchy

Redirecting sections

If required, sections can be redirected:

to different sections
to links

Redirecting a section to another is handy if a parent section doesn’t actually have any content & you just want to send users to a child section.

Redirecting a section to a link enables you to bounce a user off site. Note that the links must be defined in the TXP database (see Links tab).

Redirection is defined in the adi_menu admin tab.

Attack of the clones

Why on earth would you want to repeat a section in its own subsection list?

Well, I reckon that dropdown menus can lead users astray. When menus are hovered over, people might not think that the top section is a link. By using clones, combined with an alternative title, you can ensure that sections don’t get overlooked.

Using the previous example, if section B is ticked as a clone then the following menu is created:

B
- Summary
- B1
- B2

The Summary link points to section B. Note that the clone’s title defaults to “Summary” but can be changed in the adi_menu admin tab.

If you’re not on the list, you’re not getting in

Sections can be excluded from the menu, on a permanent basis, by ticking their Exclude option in the adi_menu admin tab.

Sections can also be excluded, over and above those excluded in the admin tab, by using the exclude attribute in the adi_menu tag.

By default, adi_menu will normally output all (non-excluded) sections. If you want to be explicit regarding the sections that need to appear then use the sections attribute. This will mean that only the sections listed (together with their children) will be output.

Separated at birth

If you have a requirement for separate primary and submenus then try the following serving suggestion:

<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 original method of rendering submenus (below), which only really worked for second level submenus, has been deprecated. However for backwards compatibility, the associated attributes and functionality will* be retained.

<txp:adi_menu menu_id="nav" include_children="0" active_parent="1" />
<txp:adi_menu menu_id="subnav" include_current="1" include_parent="0" />

the first tag generates a menu containing the top level sections only (i.e. without their children)
the second tag generates a submenu of the currently active section’s children
active_parent="1" causes the parent of the currently active child to have the active class applied to it
the two menus have unique ids applied using the menu_id attribute

Pure escapism

As of version 0.12, thanks to ttr, adi_menu should cope with HTML special characters (i.e. &, “, ‘, <, >) and accented characters without having to resort to the escape attribute.

For backwards compatibility, the escape attribute is still available. If you’re still seeing some dodgy output with accented characters you can override the new default behaviour. See the plugin help 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.

Span, lovely span

An unadorned <txp:adi_menu /> generates markup without any spans. But as we all know, to do anything easily in CSS we need hooks. The following attributes inject  into adi_menu’s HTML sandwich.

link_span adds a span around the contents of a link: <a>...</a>
list_span wraps the contents of a <li> in a span, i.e. <li><a>...</a></li>
list_prefix adds a prefix surrounded by a span: <li>PREFIX<a>...</a></li>
speaking_block adds a speaking block enclosed by a span: <a>...Speaking Block</a>

Use them all at once (e.g. link_span="1" list_span="1" list_prefix="// " speaking_block="1") and a link to the default section might look like:

<li><span><span class="menu_prefix">// </span><a class="active_class" href="http:..."><span>Home</span><span>Come on home</span></a></span></li>

Class Action

To help with styling the menu, a plethora of CSS classes & HTML IDs are at your disposal.

Some are applied automatically:

Top level <ul>
- Class = section_list (class attribute)
- HTML id = mainmenu (menu_id attribute)
Parent section <li>
- Class = menuparent (parent_class attribute)
Active section <a>
- Class = active_class (active_class attribute)
Articles <li>
- Class = menu_article (article_class attribute)
Prefix 
- Class = menu_prefix (prefix_class attribute)
Speaking block  (speaking_block attribute)
- Class = speaking_block
Redirected section <li> (adi_menu admin)
- All redirects: class = menu_redirect
- Plus if link redirect: class = menu_ext_link
Alternative section title (adi_menu admin)
- Class = menu_alt_title
Odd & Even <li> (odd_even attribute)
- Class = menu_odd or menu_even

Some are explicitly specified using attributes:

Unique HTML id per <li> (list_id attribute)
- HTML id = menu_ plus section name, e.g. menu_default (attribute list_id_prefix)
Active <li> (active_li_class attribute)
Active parent <li> & <a> (active_parent attribute)
- active_class applied to <a>
- active_li_class applied to <li>
Active ancestors (active_ancestors attribute)
- same classes as active parent applied to all ancestors
First <li> item (first_class attribute)
Last <li> item (last_class attribute)

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 could only be placed 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 if you want to use the old ways.

One other change in articles’ behaviour is that the default article limit has been set to 9999. Previously, the standard limit of 10 was used.

The arcane method of feeding attributes into the article retrieval process – i.e. using standard <txp:article_custom /> attributes within adi_menu’s article_attr attribute has continued. Article sort, however, is available as an attribute (article_sort).

Version History

1.4
- new feature: virtual sections
- new categories features:
  - redirect to Article category option
  - categoried articles in menu
  - new attributes ‘cat_article_include’, ‘cat_article_exclude’, ‘cat_article_sort’, ‘cat_article_attr’
- new admin feature: drag & drop section ordering
- new classes ‘menu_virtual’, ‘menu_category’, ‘menu_clone’
- new attribute ‘ignore_alt_title’ for adi_menu & adi_breadcrumb tags
- new attributes ‘exclude_clone’, ‘role’ **, ‘override_exclude’ & suppress_url_sections for adi_menu tag
- new attribute ‘labeltag’ for adi_breadcrumb
- new attributes ‘force_current’ & ‘current_descendants_only’ (for detail)
- new tags: adi_menu_info & adi_menu_if_info
- fix: stop clone inheriting an alternative title
- fix: adi_breadcrumb now uses alternative title
- fix: article list defaults to live only (use status=”“ for both live & sticky) **
- fix: active class applied to menu items that are redirected to active section **
- fix: disallow sections to be selected as parents of, or redirect to, themselves
- fix: disabled submenus on error pages
- fix: breadcrumb less crummy on error pages
- fix: prevent empty HTML class attribute when adi_breadcrumb ‘linkclass’ is empty (thanks CeBe)
- fix: table prefix issue (thanks sochicomputerRU)
- deprecated attributes: ‘clone_title’, ‘test’, ‘new_article_mode’ **
- deprecated “old article mode” **
- now updates lastmod
- TXP 4.5+ only
- updated for TXP 4.6
- removed versions output from debug
- fix: blank adi_menu_redirect_link now set to default (0) not ‘’
- fixed dodgy 4.6 fix: restored greyness to menu key item
- fix: memory limit exceeded error with numeric section names (thanks kees-b & Bruce Bowden)
1.3.1
- lifecycle “upgrade” pseudo-event
- fixed links to section tab in TXP 4.5
1.3
- TXP 4.5-ified
- moved install/uninstall to plugin options
- Textpack added
- tooltips thrown in the tip
- fix: preferences fully deleted on uninstall
- enhancement: adi_menu admin section redirect warning message
- enhancement: admin preference “Prevent widowed words in article titles” now obeyed (for springworks)
- code tidy up
- change: removed import functionality
- change: admin tab name changed “adi_menu” -> “Menu”
- change: use pluggable_ui instead of old inject method in Article tab
1.2
- section-specific article sort (for bg)
- enhancement: adi_menu admin sections link to TXP section tab
- fix: ampersands in article titles (thanks renobird)
- fix: admin styling for Hive
- now uses lifecycle events for install/uninstall
1.1
- enhancement: section redirection (for me & caruso_g)
- enhancement: alternative section titles
- enhancement: adi_menu admin tab now only shows admin options (i.e. install/uninstall/import) if relevant
- enhancement: admin tab sanity checks – sections renamed or links deleted
- enhancement: write tab section popup list format & indent preferences (for Bloke)
- enhancement: new article method, attribute ‘new_article_mode’ to switch off (‘test’ attribute ignored)
- new attribute: ‘odd_even’ to generate <li> classes on odd/even items
- change: section sort now defaults to “adi_menu_sort” (use sort=”“ to override)
- fix: dodgy bold in hierarchy summary, added italics & “default” now “Home”
- fix: errors in admin tab if sections renamed
1.0
- testing only, not officially released
0.12.1
- fix: error on error page when sub_menu_level > 1 (thanks CeBe)
- fix: error with submenu if active section excluded in admin
0.12
- new attribute ‘current_children_only’ (for ttr & caruso_g)
- enhancement: new (automatic) way of coping with accented characters (thanks ttr)
- enhancement: minor admin tab improvements
- fix: error when adi_menu_breadcrumb used more than once on a page (thanks jcd)
- fix: current_children_only not functioning correctly (thanks jcd)
- fix: couple of uninitialised variables generating error_log messages (lines 827, 837)
0.11
- new adi_menu attributes: ‘wraptag’, ‘wraptag_id’, ‘wraptag_class’
- enhancement: sections attribute now overrides admin excluded sections
0.10
- enhancement: speaking blocks
- new adi_menu attributes: ‘speaking_block’ & ‘speaking_block_form’
- new adi_menu attributes: ‘label’, ‘labeltag’, ‘label_class’, ‘label_id’
- fix: empty <ul></ul> output for section-less submenus
0.9.2
- fix: static sections (sed_section_fields) visible to non-Publisher users in Write tab (thanks Didjee)
- fix: sections with clones wrongly indented in Write tab section popup
0.9.1
- fix: accented characters getting escaped in admin (for jpdupont)
- enhancement: new ‘escape’ attribute option: htmlspecial
0.9
- enhancement: multiple sub_menus (for emerald)
- new adi_menu attribute: ‘sub_menu_level’
- fix: selected section in Write tab changes to first section in list after saving new article
0.8.1
- fix: submenus not being generated properly
- fix: suppressed output of ‘id=”“’ & ‘class=”“’ in top level <ul> when menu_id=”“ & class=”“
0.8
- enhancement: section hierarchy now appears in Article/Write tab section popup
- new adi_menu attributes: ‘first_class’, ‘last_class’, ‘suppress_url’ (for renobird)
- new adi_menu attributes: ‘list_prefix’ & ‘prefix_class’ (for nubian)
0.7
- new adi_menu & adi_menu_breadcrumb attribute: ‘escape’
- new adi_menu attribute: ‘active_ancestors’ (for Didjee)
- fix: adi_menu admin hierarchy summary now shows children again
- fix: no longer get double row of admin page tabs before adi_menu is installed
0.6
- articles (beta)
- enhancement: new adi_menu attributes – ‘include_children’, ‘include_current’ & ‘active_parent’ (for sub menus)
- enhancement: new adi_menu attribute: ‘list_span’ (for sIFR support)
0.5
- fix: adi_menu errors if ‘default’ section excluded (thanks Uli)
- fix: adi_menu tab section hierarchy would generate lots of errors if adi_menu not installed
- enhancement: sections attribute functionality improved:
  - children now output automatically
  - new tags ‘include_parent’ & ‘include_childless’
0.4
- enhancement: adi_breadcrumb tag attribute ‘link_last’ – last section crumb in list displayed in plain text (now the default behaviour)
- fix: adi_menu_breadcrumb error when visiting sections/pages that don’t exist when in clean URL mode
- fix: adi_menu_breadcrumb displayed default section as link regardless of ‘link’ attribute setting
0.3
- enhancement: new adi_menu tag attribute ‘link_span’ – wrap … around contents of links
- enhancement: new adi_menu tag attributes ‘list_id’ & ‘list_id_prefix’ – output unique IDs to <li> elements
- enhancement: new adi_menu tag attribute ‘active_li_class’ – output class on active <li>
- enhancement: adi_menu admin now displays summary of configured section hierarchy
- modification: adi_breadcrumb tag attribute ‘sep’ deprecated for ‘separator’
0.2
- fix: adi_menu_breadcrumb error when visiting pages that are excluded in adi_menu admin
- fix: adi_menu_breadcrumb now copes with section loops, error message output
- fix: adi_menu tag can now be used more than once on a page
- enhancement: adi_menu admin section loop warning message
- enhancement: adi_menu admin now displays sections in alphabetical order
0.1
- initial release

Requirements

Textpattern 4.5.0+ (due to use of plugin lifecycle events).

Textpack

There is a mechanism to install a Textpack in the adi_matrix options page under the Plugins tab.

Currently the Textpack contains:

Czech (thanks mikulas)
French (thanks Pat64)
Polish (thanks BKawalec)

The voice of caution

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.

Download & Installation

Download adi_menu and install the plugin in the usual way.*

As of version 1.2, adi_menu will sort out what it needs to do in the database automatically when you install & uninstall the plugin.

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

Style the menu & breadcrumb trail using CSS.

* If you’ve been a 1.4beta user, visit the adi_menu admin tab immediately after installing 1.4 in order to automatically run an upgrade process.

Bugs

Let me know if you find any “undocumented features”.

Feedback

Comments & suggestions are most welcome.

Credits

It’s not possible to list all the plugins I’ve dissected to create adi_menu but notable mentions should go to Christian Nowak’s cnk_section_tree and Rob Sable’s rss_admin_db_manager. Thanks also to the many Textpattern users who have offered suggestions, found bugs & performed testing.

Hug a developer

If you find this plugin useful and would like to experience an inner glow every time you use it, please consider donating to the Textpattern development team.

Last edited by gomedia (2021-01-06 05:43:45)

jakob · 2008-07-15 15:10:35

HI, looks like it could be very promising. I like the idea of the new tab as a sort of menu-builder.

Without having tried it (yet) three questions:

is the sub-section structure also reflected in the URL, e.g. /sectionparent/sectionchild/article-or-category?
Does the user see this when assigning a section in the write tab?
How does it interact with categories? Can categories exist at all levels?

uli · 2008-07-15 15:50:52

I got a post-it “Suckerfish in txp” sticking on my monitor. No more pretext, ouch! ;)
Do you reject articles in menus categorically or will there be a chance you hand them in sometime later?
The summary feature seems elaborate, will need that!

Thanks for sharing, Adi!

gomedia · 2008-07-15 21:43:30

jakob:
In answer to your questions:
1) the URL should reflect the “Permanent link mode”
2) no, I wanted to avoid interfering with the standard tabs
3) adi_menu deals with sections only

Uli,
My own requirement was for a section menu, so adi_menu only deals with sections. I hadn’t intended to expand it to encompass articles as well. I’m guessing that to do that, I’d have to worry about categories?

Adi

uli · 2008-07-15 23:11:46

gomedia wrote:

I’m guessing that to do that, I’d have to worry about categories?

No, not at all :)
I often needed something slightly different: the plugin should sort out all these section names that have articles attached to them, and display the articles instead (just the top level sections remain always visible). Thus the sections are just the invisible skeleton, that is populated with visible articles following the form underneath.
Let the mouse go over a menu item, and an individual article pops up, no matter if you let go over a leaf or a branch of the menu tree.

gomedia · 2008-07-15 23:55:05

Uli,

Do you mean like the way cnk_section_tree lists articles under sections? If it would help send me an example via email (Forum email or via my website).

Adi

uli · 2008-07-16 01:17:17

Do you mean like the way cnk_section_tree lists articles under sections?

No. Closer, but not exactly, as cnk_section_tree jumbles sections with articles sitting in the same level.

Let’s take the good old suckerfish example itself:

At the moment, using your plugin, all menu items are sections, there’d be no single article in the menu. Nowhere.

What I’d like to have were just the first level menu items be sections, those from the second level and below be articles, even these with child items underneath. This way you could access an individual article on Remoras (first menu, first item) or Echeneis (2nd sublevel) or Sharksuckers (3rd sublevel) when you let the mouse button go over the corresponding menu item. You wouldn’t see section names in the menu tree, you’d only see articles. Whereas the roots were sections.

lee · 2008-07-16 10:12:53

Feature idea: make the list of “sections to include” an option in the sections tab, so that when creating a section it’s possible to include it in the menu by use of a check box. This way non tech clients can add a section without having to edit the tag.

Thanks for the plugin, I’ll be using this a lot.

Best wishes
Lee

Edit: Scrub that, what you’ve done already works well.

Last edited by lee (2008-07-16 10:15:32)

gomedia · 2008-07-18 06:12:30

Version 0.2 released, see first post for information about fixes & enhancements.

jelle · 2008-07-18 08:58:12

Great plugin…been looking for this for a while. Even had a shot at making a plugin like this myself….but failed misreably.

The only thing I don’t like is the backend. I can handle it but I it’s to elaborate for some less technical clients. May I suggest a drag and drop jQuery system (like this http://www.gimiti.com/kltan/demo/jTree/) for menu building?

chriloi · 2008-07-18 10:53:15

gomedia schrieb:

adi_menu vs cnk_section_tree

Adi,

you are wrong. Showing articles in the tree is an option, but not the core functionality of my plugin. So I really don’t get why your plugin is so different to mine.

I also had a look at your code and I would say, that the greatest difference is performance. While my code is able to handle very large trees with no performance loose, your code gets slower with every new section level.

Another big thing is, that I’m currently implementing nice urls, which means it takes some time to realease the next version, so it is not very nice of you to bring out your (very similar) plugin and sell it as something better than mine and promote it in my plugin support thread.

Last edited by chriloi (2008-07-18 10:53:44)

kemie · 2008-07-18 11:38:03

This looks super interesting! I’ve had to manually create menus for suckerfish-type navigation, so it’s great to have this plugin be able to generate it dynamically!

Textpattern CMS

Textpattern CMS support forum

#1 2008-07-15 14:16:03

adi_menu – section hierarchy, section menu and breadcrumb trail

#2 2008-07-15 15:10:35

Re: adi_menu – section hierarchy, section menu and breadcrumb trail

#3 2008-07-15 15:50:52

Re: adi_menu – section hierarchy, section menu and breadcrumb trail

#4 2008-07-15 21:43:30

Re: adi_menu – section hierarchy, section menu and breadcrumb trail

#5 2008-07-15 23:11:46

Re: adi_menu – section hierarchy, section menu and breadcrumb trail

#6 2008-07-15 23:55:05

Re: adi_menu – section hierarchy, section menu and breadcrumb trail

#7 2008-07-16 01:17:17

Re: adi_menu – section hierarchy, section menu and breadcrumb trail

#8 2008-07-16 10:12:53

Re: adi_menu – section hierarchy, section menu and breadcrumb trail

#9 2008-07-18 06:12:30

Re: adi_menu – section hierarchy, section menu and breadcrumb trail

#10 2008-07-18 08:58:12

Re: adi_menu – section hierarchy, section menu and breadcrumb trail

#11 2008-07-18 10:53:15

Re: adi_menu – section hierarchy, section menu and breadcrumb trail

#12 2008-07-18 11:38:03

Re: adi_menu – section hierarchy, section menu and breadcrumb trail

Board footer