Tree Cats Page Plugin for Cotonti Siena 0.9.26+

Professional Technical Guide (Theory + Practice)

PART I — ARCHITECTURE, CONCEPTS, AND DESIGN PRINCIPLES (NO CODE)

1. Introduction

 Tree Cats Page is a structural extension  designed for the Page module of Cotonti Siena. Its purpose is to programmatically build and render a hierarchical tree of page categories anywhere within a website’s theme layer.

Unlike basic category navigation blocks, this plugin:

• Generates a full recursive tree
• Supports exclusion logic (blacklist)
• Integrates with Cotonti’s permission system
• Respects multilingual structures (i18n)
• Allows complete template override
• Decouples logic from presentation

This guide is divided into two professional sections:

1. Conceptual and architectural overview
2. Practical implementation and code-level integration

The documentation assumes familiarity with Cotonti’s structure system, template engine, and theme architecture.

2. Problem Statement

Cotonti’s Page module stores categories in a hierarchical structure (structure.page). However, default themes typically:

• Render only top-level categories
• Hardcode category links
• Lack dynamic recursion
• Do not expose structural metadata consistently

For projects such as:

• Content marketplaces
• Blog platforms
• Knowledge bases
• News portals
• Multi-level publication systems

A fully dynamic tree representation of categories becomes essential.

Tree Cats Page addresses this by introducing:

• A reusable tree builder
• Template-based rendering
• Offcanvas UI integration (Bootstrap 5.3)
• Support for structural metadata

3. Architectural Overview

3.1 Logical Layers

The plugin architecture follows separation of concerns:

This separation ensures:

• Predictable behavior
• Maintainability
• Theme independence
• Reusability in multiple layouts

4. Category Structure Processing

The plugin operates on:

structure.page

Each category node contains:

• Code
• Path
• Title
• Description
• Icon (if defined)
• Page count
• Parent
• Extra fields (if defined)

The tree builder performs:

1. Root discovery
2. Recursive traversal
3. Child grouping
4. Visibility filtering
5. Blacklist exclusion
6. Permission check
7. Localization mapping

The output is a fully structured hierarchical dataset.

5. Permission Model

Rendering occurs only if:

• Page module is active
• Plugin is active
• User has R (read) access for categories

This ensures:

• No unauthorized structure leakage
• No access control bypass
• Compliance with Cotonti security model

The plugin does not override Cotonti permissions. It consumes them.

6. Blacklist Mechanism

The configuration option:

blacktreecatspage

Accepts comma-separated category codes.

This allows:

• Excluding system categories
• Hiding landing nodes
• Restricting internal structures
• Customizing navigation context

Filtering occurs before tree rendering.

7. Internationalization (i18n)

Tree Cats Page respects:

• Localized category titles
• Localized descriptions
• Multilingual structures if enabled

If localized fields exist, they are used automatically.

No separate translation layer is introduced.

8. Template Strategy

The plugin loads templates dynamically using Cotonti’s template resolution logic.

Primary template:

treecatspage.page.tree.tpl

However, you may:

• Create alternative layouts
• Define context-based templates
• Add theme-specific variants
• Pass custom template suffixes

This design allows:

• Sidebar tree
• Footer tree
• Offcanvas tree
• Mega-menu tree
• Landing page tree

Without duplicating logic.

9. Bootstrap 5.3 Integration

The default UI layer is based on Bootstrap 5.3.

Why Bootstrap 5.3?

• Native offcanvas support
• Collapse components
• Accessible ARIA structure
• Minimal JS footprint

The plugin does not bundle Bootstrap. It assumes your theme includes:

• bootstrap.min.css
• bootstrap.bundle.min.js

If not present, UI behavior will fail.

10. Theme Integration Philosophy

The plugin does not assume any specific theme.

However, it includes a ready integration profile for the 2waydeal theme.

For other themes:

• Offcanvas block must be manually included
• Trigger element must be added
• Bootstrap must be present

This preserves portability.

11. Custom Template Routing

Tree Cats Page supports dynamic template selection via:

cot_build_structure_page_tree('', '', 0, 'sidebar')

This enables contextual rendering.

Example use cases:

This modular strategy makes the plugin production-ready for enterprise projects.

12. When to Use This Plugin

Recommended for:

• Multi-level blog networks
• Marketplace publications
• Hierarchical documentation
• Corporate content systems
• Structured content portals

Not required for:

• Flat single-category blogs
• Minimal landing websites

PART II — PRACTICAL IMPLEMENTATION AND CODE EXAMPLES

1. Installation Workflow

Step 1 — Download the Plugin

Obtain the plugin from its official GitHub repository.

Upload:

/plugins/treecatspage/

To your Cotonti installation.

2. Theme Integration — 2waydeal Theme

If using the 2waydeal theme:

Add to:

/themes/2waydeal/header.tpl

After the info block include:

{FILE "{PHP.cfg.themes_dir}/{PHP.cfg.defaulttheme}/inc/header/treecatspageLeftOffcanvas.tpl"}

Then modify:

/themes/2waydeal/inc/header/sidebarMenuSections.tpl

Replace static page links with plugin trigger block.

3. Theme Integration — Custom Theme (Example: CleanCot)

If using the CleanCot theme:

Open:

/themes/cleancot/inc/header/treecatspageLeftOffcanvas.tpl

Modify the container:

<div class="offcanvas offcanvas-start bg-costum-dgrey"
     tabindex="-1"
     id="treecatspageLeftOffcanvas"
     aria-labelledby="treecatspageLeftOffcanvasLabel">

This ensures correct contrast.

CleanCot repository:
cot-CleanCot

4. Ensuring Bootstrap 5.3 Is Loaded

Verify in your theme resource file:

Resources::addFile('lib/bootstrap/css/bootstrap.min.css');
Resources::linkFileFooter('lib/bootstrap/js/bootstrap.bundle.min.js');

Without Bootstrap 5.3:

• Offcanvas will not open
• Collapse will not function
• UI will break

5. functions.custom.php Requirement

To ensure child categories expand correctly:

File:

/system/functions.custom.php

Must exist.

If missing — upload it.

Then confirm in:

/datas/config.php

$cfg['customfuncs'] = true;

If false — set to true.

6. Enabling the Plugin

Admin Panel:

Administration → Extensions → Tree Cats Page → Install

Then configure blacklist categories if required.

7. Core Template Loader Logic

The plugin builds template paths dynamically:

$tpl_ExtCode          = 'treecatspage';
$tpl_PartExt          = 'page';
$tpl_PartExtSecond    = 'tree';
$tpl_PartCostumTpl    = $template;

$extTplFile = cot_tplfile(
    [
        $tpl_ExtCode,
        $tpl_PartExt,
        $tpl_PartExtSecond,
        $tpl_PartCostumTpl
    ],
    'plug',
    true
);

$t1 = new XTemplate($extTplFile);

This enables flexible routing.

8. Creating a Custom Sidebar Template

Create file:

/themes/yourtheme/plugins/treecatspage/treecatspage.page.tree.sidebar.tpl

Example usage in template:

<!-- IF {PHP|function_exists('cot_build_structure_page_tree')} AND {PHP|cot_auth('page', 'any', 'R')} -->
    {PHP|cot_build_structure_page_tree('', '', 0, 'sidebar')}
<!-- ENDIF -->

This calls the tree builder with template suffix sidebar.

9. Creating Multiple Layout Variants

You can define:

• treecatspage.page.tree.footer.tpl
• treecatspage.page.tree.mega.tpl
• treecatspage.page.tree.mobile.tpl

Call them using:

cot_build_structure_page_tree('', '', 0, 'mega')

No duplication of logic required.

10. Example Offcanvas Trigger

<li class="nav-item">
  <a class="nav-link"
     type="button"
     data-bs-toggle="offcanvas"
     data-bs-target="#treecatspageLeftOffcanvas"
     aria-controls="treecatspageLeftOffcanvas">
      <i class="fa-regular fa-newspaper me-2"></i>
      Publications
  </a>
</li>

11. Security and Stability Notes

• Never bypass cot_auth()
• Do not remove permission checks
• Do not hardcode category paths
• Always use cot_url()
• Ensure PHP 8.4 compatibility

12. Performance Considerations

For large structures:

• Blacklist unused branches
• Avoid rendering tree in every page if unnecessary
• Use caching strategies if needed
• Avoid excessive nested markup

13. Final Recommendations

Tree Cats Page is a structural navigation enhancement plugin for:

Cotonti Siena 0.9.26+

It enables:

• Full hierarchical rendering
• Theme-level flexibility
• Enterprise-grade structural navigation
• Clean separation of logic and UI

For structured content websites, this plugin transforms static navigation into a fully dynamic, extensible category tree system.

Author: webitproff
Date: July 09, 2025
Version: 1.0

Compatibility: Cotonti Siena 0.9.26+
PHP: 8.4+