Guide to Table of Contents Page (toc_page) Plugin for Cotonti

Version: 1.1.4
Date: August 24, 2026

Table of Contents

• Introduction
  • About the Plugin
  • Features
  • Requirements
• Installation and Configuration
  • Installing the Plugin
  • Initial Setup
  • Multilingual Configuration
  • Select2 Setup
• Managing Trees
  • Creating a Tree
  • Editing a Tree
  • Deleting a Tree
  • Insertion Code for a Tree
• Managing Items
  • Adding an Item
  • Item Types
    • Category
    • Page
    • Custom Link
  • Editing an Item
  • Changing Item Type
  • Sorting and Order
  • Hierarchy and Parent Items
  • Enabling and Disabling
  • Deleting an Item
• Multilingual Support
  • Enabling and Configuring Languages
  • Translating Titles and URLs
  • How Language Detection Works
  • Functions for i18n Developers
• Integration with Cotonti
  • Displaying a Tree on a Page
  • The cot_toc_page_render() Function
  • The toc_page.tpl Template
  • Using in TPL Templates
• AJAX Page Search (Select2)
  • Enabling
  • How It Works
  • Configuring Minimum Length
• SQL Dump Generator
  • Purpose
  • Preparing an HTML List
  • Creating a Dump
  • Importing into Database
• Advanced Functions
  • Functions for Retrieving Data
  • Working with Translations Directly
• Frequently Asked Questions
  • Why is the tree not displayed?
  • How do I change the item type?
  • How do I add a new language?
  • How do I remove the plugin?
• Examples
  • Simple Tree
  • Tree with Sublevels
  • Multilingual Tree

Introduction

About the Plugin

Table of Contents Page (toc_page) is a plugin for the Cotonti content management system designed to create manageable tables of contents on website pages. It allows building hierarchical menus (trees) consisting of items of different types: links to categories, individual pages, or arbitrary URLs. Items can be manually sorted, assigned parent-child relationships, enabled or disabled, and their titles and URLs translated into different languages.

The plugin is especially useful for:

• creating knowledge bases and reference sections;
• manually managed navigation menus;
• hierarchical tables of contents for long guides;
• multilingual navigation structures.

The main feature is full control over the order and nesting of items, which distinguishes the plugin from automatically generated menus based on category or page structure.

Features

• Unlimited number of trees: you can create multiple independent tables of contents for different sections of the site.
• Three item types:
  • Category — a link to a Cotonti category;
  • Page — a link to a specific page;
  • Custom Link — any external or internal URL.
• Manual sorting: each item is assigned a numeric order within its parent.
• Hierarchy: unlimited nesting of items.
• Multilingual support: translation of titles and URLs into additional languages (when enabled).
• AJAX page search: convenient page selection via Select2 instead of a bulky dropdown list.
• Pagination in the admin panel for working with large trees.
• Editing item type after creation.
• SQL dump generator: allows quickly importing a ready tree structure from an HTML list.
• Easy integration: displaying a tree with a single function in any template.
• Security: access rights support, AJAX requests protected.

Requirements

• Cotonti version 1.0 or higher (the latest is recommended).
• PHP 8.5 or higher.
• MySQL 8.4 or higher (with InnoDB and utf8mb4 support).
• The Page module must be enabled (mandatory).
• For multilingual support, the i18n plugin is recommended (optional).

Installation and Configuration

Installing the Plugin

1. Download the toc_page plugin archive.
2. Unpack the archive into the plugins/ directory of your Cotonti site. The following structure should be obtained:

plugins/
└── toc_page/
    ├── toc_page.setup.php
    ├── toc_page.admin.php
    ├── toc_page.functions.php
    ├── toc_page.ajax.php
    ├── lang/
    │   ├── toc_page.ru.lang.php
    │   ├── toc_page.en.lang.php
    │   └── toc_page.uk.lang.php
    ├── tpl/
    │   ├── toc_page.admin.tpl
    │   └── toc_page.tpl
    └── setup/
        └── toc_page.install.sql

3. Log in to the Cotonti administration panel.
4. Go to the Extensions section → Plugins.
5. Find Table of Contents Page in the list and click Install.
6. After successful installation, the plugin will be activated.

During installation, three tables will be created in the database:

• cot_toc_page_trees — trees (titles, descriptions, timestamps);
• cot_toc_page_items — tree items (type, reference, title, URL, sorting, status);
• cot_toc_page_i18n — translations of item fields (item_title, item_url, etc.).

Note. If you have a different table prefix (for example, my_), replace cot_ in the SQL file with your prefix before installation. Usually this can be done automatically during installation if the system uses a dynamic prefix, but check for reliability.

Initial Setup

After installation, go to Settings → Plugins → Table of Contents Page. The following parameters are available:

It is recommended to set default_tree immediately after creating the first tree so that the output function works without parameters.

Multilingual Configuration

1. Enable the Activate and use multilingual support option.
2. Set the main language code in the toc_page_i18n_lang_code_default field. This must be the same code as the global Cotonti setting $cfg['defaultlang']. Item titles in the main table cot_toc_page_items are considered the original for this language.
3. For each additional language:
   • set its code (for example, en, uk, de);
   • enable the Use ... flag.
4. Save the settings.

Now a Translations tab will appear in the plugin admin panel, where you can enter translations of titles and URLs for each active additional language.

Important: if you already have items, enabling multilingual support will not change their original values; they will remain in the main table.

Select2 Setup

Select2 is an enhanced dropdown list with search. In the plugin, it is used to select a page in the add/edit item forms.

How to enable:

1. In the plugin settings, find the Use AJAX page search via Select2 option.
2. Set the value to Yes.
3. Save.

After that, in the add item form of the Page type, the regular <select> will be replaced by an autocomplete field. When entering at least two characters, an AJAX request is sent to the server, which returns a list of pages matching the query.

Select2 is automatically loaded from Cotonti resources. If you want to configure the minimum input length, you can change it in the code (minimumInputLength: 2) in the toc_page.admin.php files (two places: the tree editing tab and the item editing tab). The default threshold is 2 characters.

Managing Trees

Creating a Tree

1. Go to the plugin admin section: Other → Table of Contents Page.
2. Open the Trees tab.
3. At the bottom of the page, there is an Add Tree form:
   • Tree name — mandatory field (e.g., "Knowledge Base").
   • Description — optional short description (displayed only in the admin panel).
4. Click the Create button.

After saving, the tree will appear in the list of trees with an assigned ID.

Editing a Tree

Each tree in the list has an Edit button (pencil icon). Clicking it opens the edit form directly in the list (the Trees tab). The editable fields are name and description. Click Update to save.

Deleting a Tree

In the list of trees, each tree has a Delete button. When deleting:

• all items of this tree are removed from cot_toc_page_items;
• all translations of these items are removed from cot_toc_page_i18n (cascade);
• the tree record is removed from cot_toc_page_trees.

Deletion is irreversible — it is recommended to back up the database beforehand.

Insertion Code for a Tree

In the Insertion Code column for each tree, ready-made code is automatically generated for insertion into a TPL template or PHP code.

Code example:

<!-- IF {PHP|cot_plugin_active('toc_page')} -->
{PHP|cot_toc_page_render(1)}
<!-- ENDIF -->

Here 1 is the tree ID. You can copy this code with the Copy button and paste it into the desired location.

Managing Items

Adding an Item

1. Go to the Tree Editing tab (the Items button next to the desired tree in the tree list).
2. At the bottom of the page, there is an Add Item form.
3. Select the item type:
   • Category — you will need to choose a category from the dropdown list.
   • Page — you will need to choose a page (regular list or via Select2).
   • Custom Link — you will need to enter a URL.
4. Fill in the title (if left empty for Page or Category types, the title may be automatically taken from the linked object).
5. If necessary, select a parent from the list (default is "Top level").
6. Click Add.

The new item will be added to the end of its parent's list with an automatically calculated order number (item_sort).

Item Types

Category

When this type is selected, you must specify a category from the Cotonti page structure. The category code is stored in the item_ref field. When displayed on the site, the link will lead to the category page, and the title (if not manually set) will be taken from the category name.

If the category is later deleted or renamed, the plugin will show the title stored in item_title, or display "Category not found".

Page

The Page type requires selecting a specific page from the list of published pages (page_state = 0). The numeric page ID is stored in item_ref. When displayed, the page URL is generated, and the title is taken from the page name or from the item_title field.

When using AJAX Select2 search, you can quickly find the required page by name.

Custom Link

This type allows specifying any external or internal URL (e.g., https://example.com or /some/page). Nothing is stored in item_ref, and the entered URL is placed in item_url. The title should be manually set in the Title field.

Editing an Item

To edit an item, click the Edit button (pencil icon) in the item row on the Tree Editing tab. A separate Item tab will open with a full edit form.

Here you can change:

• item type;
• linked object (category, page, or URL);
• title;
• parent item;
• sorting order;
• status (enabled/disabled).

After saving, you will remain on the edit page to see the changes made.

Changing Item Type

Previously, after creating an item, its type could not be changed. In version 1.1.4, this issue has been resolved: in the item edit form (Item tab), there is a Type dropdown. You can freely switch the type between Category, Page, and Custom Link. The corresponding object selection fields will change automatically via JavaScript.

Sorting and Order

The order of items within one parent is determined by the number in the item_sort field. It is filled automatically when adding an item (maximum value + 1). You can change the order in two ways:

1. In the general list (Tree Editing tab): change the number in the Order column and click Save Changes at the bottom of the table.
2. In the item edit form: specify the desired number in the Order field.

It is recommended to use sequential numbers (1, 2, 3...). Items with the same order are sorted by ID.

Hierarchy and Parent Items

Each item can have a parent selected from the list of all items in the same tree. Top level corresponds to parent_id = 0. Nesting is unlimited. When displayed on the site, nested items are automatically placed inside the parent item's <ul>.

In the parent item list, it is impossible to select the item itself (to avoid cycles) — this is taken into account in the item edit form.

Enabling and Disabling

Each item has an Enabled flag. If unchecked, the item is not displayed on the site but remains in the database. This is convenient for temporarily hiding menu items without deleting them.

Flag management:

• In the item list table — a checkbox in the Enabled column.
• In the item edit form — a similar checkbox.

Deleting an Item

To delete an item on the Tree Editing tab, click the Delete button (red icon). When deleting:

• the item itself is deleted;
• all its child items are deleted recursively;
• all translations of the deleted items are also deleted (cascade due to foreign key).

A confirmation prompt will appear before deletion.

Multilingual Support

Enabling and Configuring Languages

Detailed configuration is described in the Multilingual Configuration section. To recap:

1. Enable the toc_page_i18n_use option.
2. Set the main language (toc_page_i18n_lang_code_default).
3. Enable the required additional languages (toc_page_i18n_lang_code_first_use, etc.) and set their codes.

Translating Titles and URLs

After enabling multilingual support, a Translations tab appears in the plugin admin panel. It is available only if a specific tree is selected (on the left in the tree list). This tab displays a table of all tree items with fields for each active additional language:

• Title — translation of the item name;
• URL — translation of the link (if needed, e.g., for different language versions of pages).

Original values (in the main language) are shown in the Title column without editing capability (they are edited on the Tree Editing or Item tab).

To save translations, fill in the required fields and click Save Changes. Empty fields delete the translation (if it existed), leaving the original for that language.

How Language Detection Works

Language detection is performed in the toc_page_i18n_get_value() function. Logic:

1. If multilingual support is disabled, the original is returned.
2. The main language is determined from the plugin settings (toc_page_get_default_lang()).
3. The current visitor's language is determined (Cot::$usr['lang'] or the main language if guest).
4. If the current language matches the main language, the original is always returned (translations for the main language are not used).
5. Otherwise, the translation is loaded from cot_toc_page_i18n by item_id, field_name, lang. If a translation is found, it is returned; otherwise, the original.

Thus, original fields are always used for the main language, and translations are applied only for additional languages.

Functions for i18n Developers

For developers, the following functions are available in toc_page.functions.php:

• toc_page_i18n_enabled() — checks whether multilingual support is enabled.
• toc_page_get_active_langs() — returns an array of codes of active additional languages.
• toc_page_get_default_lang() — returns the main language code.
• toc_page_i18n_load($itemId, $fieldName, $lang) — loads a translation.
• toc_page_i18n_save($itemId, $fieldName, $lang, $value) — saves/deletes a translation.
• toc_page_i18n_get_value($itemId, $fieldName, $originalValue) — returns the value considering translation.

These functions can be used in custom extensions or templates.

Integration with Cotonti

Displaying a Tree on a Page

The plugin provides a simple way to display a tree anywhere on the site using the cot_toc_page_render($treeId) function.

Call methods:

1. In a TPL template:

{PHP|cot_toc_page_render(1)}

Where 1 is the tree ID.

2. In PHP code (e.g., in a module or plugin):

$out = cot_toc_page_render(1);

Then pass $out to the template.

The function returns ready HTML generated according to the toc_page.tpl template.

The cot_toc_page_render() Function

Signature:

function cot_toc_page_render($treeId, $tpl = 'toc_page')

Parameters:

• $treeId — the ID of the tree to display.
• $tpl — template name (without the .tpl extension). Default is toc_page.

Function:

1. Gets all enabled tree items via toc_page_get_tree().
2. Calls recursive rendering toc_page_display().
3. Returns HTML.

If the tree is empty or the ID is invalid, it returns an empty string.

The toc_page.tpl Template

The toc_page.tpl file (in the tpl/ folder) controls the tree markup. By default, it has the following structure:

<!-- BEGIN: LIST -->
<ul class="toc-page level-{LIST_LEVEL}">
    <!-- BEGIN: ROW -->
    <li class="toc-page-item level-{ROW_LEVEL}">
        <!-- IF {ROW_URL} -->
        <a href="{ROW_URL}">{ROW_TITLE}</a>
        <!-- ELSE -->
        <span class="toc-page-title">{ROW_TITLE}</span>
        <!-- ENDIF -->
        {ROW_ITEMS}
    </li>
    <!-- END: ROW -->
</ul>
<!-- END: LIST -->

You can modify this template to fit your design. Available variables:

• {LIST_LEVEL} — nesting level of the root list (usually 0);
• {ROW_LEVEL} — level of a specific item;
• {ROW_URL} — generated link (if any);
• {ROW_TITLE} — title (taking into account translation and HTML cleaning);
• {ROW_ITEMS} — recursively generated HTML of child items.

Using in TPL Templates

The most common scenario is to insert a tree into a sidebar or page content. Example:

<div class="block">
    <h3>Knowledge Base</h3>
    {PHP|cot_toc_page_render(1)}
</div>

If you need to display different trees on different pages, you can use Cotonti conditional operators or PHP logic in the template.

For global visibility of the function in TPL, ensure the plugin is active and the function is registered (this happens automatically when toc_page.functions.php is loaded).

AJAX Page Search (Select2)

Enabling

To use Select2 for page selection, enable the Use AJAX page search via Select2 option in the plugin settings.

How It Works

When Select2 is enabled, in the add/edit item forms of the Page type, instead of a standard <select>, a hidden field and a Select2 element appear. The user enters at least 2 characters, after which an AJAX request is sent to the public URL index.php?r=toc_page&ajax=search&q=.... The server (file toc_page.ajax.php) searches for pages where page_state = 0 and the title contains the entered substring (case-insensitive). Results are returned in JSON format for Select2.

Access rights are additionally filtered: only administrators can use the search (in the current implementation, cot::$usr['isadmin'] is checked). Access for non-administrators is not provided, as AJAX is used only in the admin panel.

Configuring Minimum Length

The minimum input length for search is set in the JavaScript code in the toc_page.admin.php files (two places: the tree editing tab and the item editing tab). Find the line:

minimumInputLength: 2,

and replace 2 with the desired number. After the change, save the file and clear the browser cache.

SQL Dump Generator

Purpose

The generate_toc_dump.php script is designed to automatically create an SQL dump of the plugin tables based on an HTML list. This is convenient when you need to quickly import a ready tree structure (for example, from an existing static menu) without manually adding items in the admin panel.

Preparing an HTML List

The HTML list must be a valid nested <ul><li> list. Rules:

• Each item is an <li>, which may contain a nested <ul>.
• <nav></nav> inside <li> is ignored (you may omit it).
• HTML entities are automatically converted.
• Do not leave extra spaces between the closing </li> and the next <li>.

Example:

<ul>
    <li>Parent
        <ul>
            <li>Child 1</li>
            <li>Child 2</li>
        </ul>
    </li>
    <li>Another parent</li>
</ul>

Creating a Dump

1. Open the generate_toc_dump.php file in an editor.
2. Insert your HTML into the $html variable (between <<<'HTML' and HTML;).
3. Fill in the $translations array (if translations are needed), where the key is the original and the value is the translation.
4. Specify tree parameters: $treeId, $treeTitle, $treeDescription.
5. Check the table prefix (default cot_). Replace if necessary.
6. Upload the file to the site root via FTP.
7. Run it in the browser: https://your-domain/generate_toc_dump.php.
8. The script will create a toc_page_dump_YYYYMMDD_HHMMSS.sql file in the site root.
9. Download this file via FTP.

Importing into Database

1. Go to phpMyAdmin and select your database.
2. Go to the Import tab.
3. Select the downloaded .sql file.
4. Make sure the encoding is utf-8.
5. Click Import.

Important: the script, when imported, deletes existing cot_toc_page_* tables and creates them anew. Make a backup if you already have data.

After import, the tree will appear in the plugin admin panel.

Advanced Functions

Functions for Retrieving Data

The following functions are defined in toc_page.functions.php:

• toc_page_get_tree($treeId) — returns a nested array of all enabled tree items. Each item contains all table fields + children (array of children).
• cot_toc_page_render($treeId, $tpl = 'toc_page') — renders a tree according to the template.
• toc_page_display($items, $level, $tpl) — recursively outputs items. Usually not called directly.

Multilingual functions described earlier are also available for developers.

Working with Translations Directly

If you need to programmatically add or retrieve a translation, use:

// Load a translation
$translated = toc_page_i18n_load($itemId, 'item_title', 'en');

// Save a translation
toc_page_i18n_save($itemId, 'item_title', 'en', 'English title');

// Delete a translation (pass null or an empty string)
toc_page_i18n_save($itemId, 'item_title', 'en', '');

These functions automatically handle insert/update/delete.

Frequently Asked Questions

Why is the tree not displayed?

• Check that the plugin is activated.
• Make sure the tree ID is correct and the tree contains at least one enabled item.
• Check that the correct call {PHP|cot_toc_page_render(ID)} is used in the TPL template.
• Clear the Cotonti cache.
• Make sure items are not disabled (Enabled flag).

How do I change the item type?

1. Open the Tree Editing tab.
2. Find the desired item and click the Edit button.
3. In the opened Item tab, change the type in the dropdown list.
4. Fill in the corresponding fields (category, page, or URL).
5. Click Update.

How do I add a new language?

1. In the plugin settings, enable multilingual support.
2. In the field for an additional language, enter the code (e.g., de) and enable the Use flag.
3. Save the settings.
4. Go to the Translations tab and fill in translations.

A maximum of two additional languages is supported (plus the main one).

How do I remove the plugin?

1. Back up the database.
2. In the Cotonti admin panel, go to Extensions → Plugins.
3. Find Table of Contents Page and click Uninstall.
4. If necessary, delete the plugin files from the plugins/toc_page directory.

Warning: when uninstalling the plugin, the cot_toc_page_* tables are usually not removed automatically. If you want to completely clean the database, delete them manually via phpMyAdmin or run SQL commands DROP TABLE IF EXISTS ....

Examples

Simple Tree

Suppose you need to create a sidebar menu with three items:

- Home
- About Us
- Contacts

Steps:

1. Create a tree with ID 1.
2. Add three items of the Custom Link type with URLs: /, /about, /contacts.
3. Set the order 1, 2, 3.
4. Insert into the template:

<div class="sidebar">
    {PHP|cot_toc_page_render(1)}
</div>

Tree with Sublevels

Structure:

- Services
  - Development
  - Design
- Portfolio
  - Websites
  - Logos

Implementation:

1. Add the items Services and Portfolio as parent items (parent = 0).
2. Add child items, selecting the corresponding parent item in the Parent field.
3. Configure the order.

Multilingual Tree

It is required to display a menu in Russian and English.

1. Enable multilingual support, set the main language ru, additional en.
2. Create items with Russian titles.
3. Go to the Translations tab, enter English titles for each item.
4. When visiting the site in English, the titles will automatically be replaced.

If no translation is set for an item, the Russian original will be displayed.

This guide covers the main aspects of working with the Table of Contents Page plugin version 1.1.4. For additional information, refer to the documentation on GitHub or the support forum.