isiikoivan/yii2-eltab-menu

Advanced multi-pass dynamic tab context active matching highlight system and persistence tracker for Yii2 framework.

dev-main 2026-05-28 10:30 UTC

Requires

• php: >=5.6.0
• yiisoft/yii2: ~2.0.0

MIT

• isiikoivan

README

# Yii2 Eltabs Dynamic Menu & Contextual State Tracker

`yii2-eltab-menu` is a highly optimized, decoupled layout extension designed to isolate context sub-menus, tab matrices, and complex active tracking loops from view template files.

By integrating a centralized configuration registry with a high-priority **Two-Pass Execution Engine**, this package automatically maintains active sub-navigation highlight states across intricate workflows (such as deep CRUD record creation, updates, multi-action tabs, and module cross-context jumps) while completely avoiding state-bleeding or false positives.

---

## Key Features

* **Decoupled Architecture:** Strips raw visual list tags, routing links, RBAC permissions checks, and tracking logic out of your layout files and into a clean, centralized data dictionary.
* **Two-Pass Matching Engine:** Guarantees a strict single-active-tab limit by resolving direct explicit URL hits completely before executing fallback matching algorithms.
* **State Persistence Safety Net:** Uses HTTP Referrer checks combined with active query parameter address string scanning to prevent tabs from losing active focus during browser refreshes (F5), deep-linking, or bookmarked browser navigation history.
* **Dynamic Reflection Fallback:** Bypasses manual string-matching configurations by dynamically scanning controller methods for matching inline/external actions when explicit rules aren't specified.
* **Cross-PHP Version Compatibility:** Hand-crafted using legacy-safe fallback checks to execute flawlessly on environments ranging from legacy **PHP 5.6** all the way to modern **PHP 8.x**.

---

## Installation

The preferred way to install this extension is through [Composer](http://getcomposer.org/download/).

Run the following command in your terminal:

```bash
composer require isiikoivan/yii2-eltab-menu

or add this line directly to the require block of your application's composer.json file:

"isiikoivan/yii2-eltab-menu": "~1.0.0"

Component Architecture Implementation

1. The Data Hub Configuration (EltabsMenuRegistry.php)

Create a custom menu registry utility inside your application (e.g., in app\components) to house your layout configurations. Group them under array indices matching the target runtime Yii::$app->controller->id.

<?php

namespace app\components;

class EltabsMenuRegistry
{
    /**
     * Fetch navigation tab items for the given controller ID key context.
     *
     * @param string $key The current executing Controller ID
     * @return array
     */
    public static function getTabs($key)
    {
        $configs = [
            'student' => [
                // Global action domain filter boundary for fallback sub-page sniffing
                'refActions' => ['index', 'create', 'update', 'view', 'attendance', 'fees'],

                'list' => [
                    'label'       => 'Student Roster',
                    'url'         => ['/student/index'],
                    'controllers' => ['student', 'attendance'], 
                    'actions'     => ['index', 'create'], 
                    'ref'         => 'ref=students',  
                    'visible'     => true         
                ],
                'attendance' => [
                    'label'       => 'Attendance Log',
                    'url'         => ['/student/attendance'],
                    'controllers' => ['student'],
                    'actions'     => ['attendance'],
                    'ref'         => 'ref=attendance',
                    'visible'     => \Yii::$app->user->can('view-attendance'),
                ],
            ],
        ];

        return isset($configs[$key]) ? $configs[$key] : [];
    }
}

2. Layout Integration (views/layouts/main.php)

Query your navigation matrix registry cleanly inside your master application layout frame file and stream the tracking widget context conditionally into your DOM tree:

<?php
use Isiikoivan\Yii2EltabMenu\EltabMenuWidget;
use app\components\EltabMenuRegistry;

$currentControllerId = Yii::$app->controller->id;
$dynamicTabs = EltabMenuRegistry::getTabs($currentControllerId);
?>

<div class="col-9 container">
    <?php if (!empty($dynamicTabs)): ?>
        <div class="dynamic-tabs-navigation-frame">
            <?= EltabMenuWidget::widget([
                'controllerId' => $currentControllerId,
                'items'        => $dynamicTabs
            ]) ?>
        </div>
    <?php endif; ?>
    
    <?= $content ?>
</div>

Configuration Property Blueprint Matrix

Each individual link item array configuration passed into the collection array matrix supports the following operational parameters:

Parameter	Data Type	Requirement	Description
label	string	Required	The plain text name rendered safely inside the template tab link layout anchor.
url	`array	string`	Required
visible	boolean	Optional	Controls rendering authorization. If explicitly false (e.g. from an RBAC can() failure check), the tab is completely pruned before execution loops. Defaults to true.
controllers	array	Optional	Array of controller IDs that bound this tab's primary focus scope domain.
actions	array	Optional	Array of specific action IDs that immediately claim an absolute active match on Pass 1.
ref	string	Optional	Custom query string unique token match signature verified against the HTTP Referrer and Active URL during Pass 2 string scanning fallbacks.

License

This software project is open-source software released under the terms of the MIT License. See the accompanying LICENSE file for full declaration terms.