Basic Enterprise Application Realm

Basic Enterprise Application Realm Documentation
  • 1 PHP Reference
    • 1.1 Introduction
    • 1.2 shared_lib.php
    • 1.3 ac_tables.php
    • 1.4 ac_email.php
  • 2 Javascript Reference
    • 2.1 Introduction
    • 2.2 ac_ajax
    • 2.3 ac_event
    • 2.4 ac_filter
    • 2.5 ac_menu
    • 2.6 ac_panel
    • 2.7 ac_select
    • 2.8 ac_toc
  • 3 Forms
    • 3.1 Introduction
    • 3.2 How It Works
    • 3.3 AJAX
    • 3.4 form_processor_v2
    • 3.5 form_processor

2.8 ac_toc

March 25th, 2025

This class provides is simple, but powerful way of generating high quality tables of contents from HTML unordered lists (<ul> elements). The end user expectation is to have reactive lists with expanding and collapsing submenus and that is exactly what this class provides. It covers three main usage scenarios:

  • Navigation menus (though for this purpose ac_menu provides more enriched functionality).
  • Dynamic documentation TOCs. For TOCs drawn on-the-fly, this can be called to render the TOC after an unordered list is sent to the browser.
  • Static documentation TOCs. This can be embedded in offline or static content made of multiple HTML pages for each document. Because the TOC supports call time indexes, each static document loaded can still display the TOC expanded to the current location with the current page highlighted.

Current version: 1
Dependencies: none

2.8.1 Public Properties

None.

2.8.2 Public Methods

Version Arguments Purpose
addTOC 1 list ID(string)[, autoselect ID(boolean). root style(string)] Draws a full interactive TOC starting from <ul> element with the ID specified. If autoselect is true, then the TOC is rendered with all branches expanded up to the list item <li> with the matching location of the current URI. The TOC from the root CSS style indicated. If nothing is specified for the root style, then the root style "toc" from the BEAR CSS styles is assumed.

2.8.3 HTML Attributes

Special attributes are not mandatory. ac_toc will also generate interactive TOCs from unordered lists with links inside regular <a hreaf="link"></a> tags. This is useful for making TOCs that work with or without ac_toc.

The autoselect feature only works when using the special HTML attributes shown below. It does not work with HTML links.

Version Type Mandatory [Y/N] Purpose
ac:link 1 string N Indicates the page to link to. Effectively an alternative to using a tags.
ac:target 1 string N used to specify the name of the window or frame to open the link in. Behaves exactly the same as <a target="target">
ac:action 2 string N If used, must be set to submit. This will then refer to ac_form and ac:value.
ac:form 2 string N* Indicates the HTML ID of the form that will be submitted.
ac:value 2 string N* The HTML form's action attribute that will be overwritten before submission.

* ac:form and ac:value become mandatory when ac:action="submit" is present.

The reason for using the dedicated attributes instead of HTML links is that it ensures more consistent rendering by completely avoiding interactions with the browser's attempt to render and highlight links.

2.8.4 The TOC Stylesheet

CSS is used to render the TOC in a rich and interactive way. However, ac_toc doesn't need to know about the entire stylesheet, just the root style to be applied to the outermost <ul>. It is worth pointing out that the unordered list should have no styles applied in the HTML as this will be managed by ac_toc. However, for this to work, the root style must provide a number of child styles or sibling styles that follow a naming convention based around the name of the root style.

The stylesheet must provide the following:

Style Default Purpose
<ROOT> .toc The master baseline style that is applied to the entire <ul> and all child elements.
<ROOT> li .toc li The style applied to each list item <li> on the TOC. This applies to all such elements regardless of whether they contain active links, actions, or are expandable.
<ROOT>_item .toc_item The style applied to each list item <li> on the TOC that denotes an actual page link.
<ROOT>_item:hover .toc_item:hover The style applied to each list item <li> on the TOC that denotes an actual page link while the cursor hovers over it.
<ROOT>_expandable .toc_expandable The style applied to list item <li> which are expandable.
<ROOT>_expandable;hover .toc_expandable:hover The style applied to list item <li> which are expandable while the cursor hovers over it.
<ROOT>_expanded .toc_expanded The style applied to list item <li> which are expanded.
<ROOT>_selected .toc_selected The style applied to list item <li> which are currently selected.
<ROOT>_link .toc_link This style is sued to override the browser's default behaviour of highlighting links in <a href="link"></a> tags. It should effectively nullify that effect so that the above styles take precedent.
<ROOT>_link:hover .toc_link:hover see above
<ROOT>_link:link .toc_link:link see above
<ROOT>_link:visited .toc_link:visited see above

2.8.5 Usage Examples

Applying to a preexisting list of links

In this example, a page already contained a list of items with multiple HTML links which renders correctly but as a non interactive TOC.

Javascript

ac_toc.addTOC('instructionManual');

HTML

<ul id="instructionManual"> <li><a href="introduction.html" target="_self">Introduction</a></li> <li><a href="relase_notes.html" target="_self">Release Notes</a></li> <li>Installation</li> <ul> <li><a href="requirements.html" target="_self">System Requirements</a></li> <li><a href="intalling.html" target="_self">Running the Installer</a></li> <li><a href="setup.html" target="_self">First Time Setup</a></li> </ul> <li><a href="adding_users.html" target="_self">Adding Users</a></li> <li><a href="logging.html" target="_self">Logging</a></li> <li><a href="upgrading.html" target="_self">Upgrading</a></li> </ul>

Loading a page with a TOC item pre-selected

When building a documentation book comprised of discrete HTML files that incorporate the TOC on every page, it is useful to show the user where in the documentation TOC tree they are. Providing an autoselector does this.

Javascript

ac_toc.addTOC('instructionManual',true);

HTML

<ul id="instructionManual"> <li ac:link="introduction.html" ac:target="_self">Introduction</li> <li ac:link="relase_notes.html" ac:target="_self">Release Notes</li> <li>Installation</li> <ul> <li ac:link="requirements.html" ac:target="_self">System Requirements</li> <li ac:link="intalling.html" ac:target="_self">Running the Installer</li> <li ac:link="setup.html" ac:target="_self">First Time Setup</li> </ul> <li ac:link="adding_users.html" ac:target="_self">Adding Users</li> <li ac:link="logging.html" ac:target="_self">Logging</li> <li ac:link="upgrading.html" ac:target="_self">Upgrading</li> </ul>

Submitting forms instead of links

It is also possible to submit forms based on the contents of a link which may be useful for contextual execution where more options are required than is reasonably provided by a row of buttons.

Javascript

ac_toc.addTOC('instructionManual');

HTML

<ul id="instructionManual"> <li ac:action="submit" ac:form="docLoader" ac:value="docLoader.acx?docID=1000034">Introduction</li> <li ac:action="submit" ac:form="docLoader" ac:value="docLoader.acx?docID=1000035">Release Notes</li> <li>Installation</li> </ul>

previous: ac_select next: Introduction