README

Yii 2 Navigation Locator

Yii 2 Navigation Routing Locator for active menu identification

FEATURES

• Smartly identifying active navigation on current controller action

• Multi-validators for grouping active navigation

• Route prefix setting support

OUTLINE

• Demonstration
• Requirements
• Installation
• Usage
  • is()
  • in()
  • setPrefix()

DEMONSTRATION

Giving a 3-layer controller action route structure for Yii 2 framework:

yii2/
├── controllers/           
    ├── data/      
        ├── ListController.php
        └── StructureSettingController.php
    ├── datacenters/            
        ├── ClusterSettingController.php
        └── ListController.php
    └── SiteController.php      

In the view of global navigation menu, write active conditions by Nav Locator:

<?php
use yidas\NavLocator as Locator;
use yii\helpers\Url;
?>

<li class="treeview <?php if(Locator::in('data/')):?>active menu-open<?php endif ?>">
  <a href="#">
    <i class="fa fa-database"></i> <span>Data</span>
    <span class="pull-right-container">
      <i class="fa fa-angle-left pull-right"></i>
    </span>
  </a>
  <ul class="treeview-menu">
    <li class="<?php if(Locator::in('data/list')):?>active<?php endif ?>"><a href="<?=Url::to(['data/list'])?>"><i class="fa fa-circle-o"></i> Data List </a></li>
    <li class="<?php if(Locator::in('data/structure-setting')):?>active<?php endif ?>"><a href="<?=Url::to(['data/structure-setting'])?>"><i class="fa fa-circle-o"></i> Structure Setting </a></li>
  </ul>
</li>

<li class="treeview <?php if(Locator::in('datacenters/')):?>active menu-open<?php endif ?>">
  <a href="#">
    <i class="fa fa-server"></i> <span>Data Centers</span>
    <span class="pull-right-container">
      <i class="fa fa-angle-left pull-right"></i>
    </span>
  </a>
  <ul class="treeview-menu">
    <li class="<?php if(Locator::in('datacenters/list/')):?>active<?php endif ?>"><a href="<?=Url::to(['datacenters/list'])?>"><i class="fa fa-circle-o"></i> Node List </a></li>
    <li class="<?php if(Locator::in('datacenters/cluster-setting/')):?>active<?php endif ?>"><a href="<?=Url::to(['datacenters/cluster-setting'])?>"><i class="fa fa-circle-o"></i> Cluster Setting </a></li>
  </ul>
</li>

• Example 1 active URI: data/list, data/list/action
• Example 2 active URI: data/structure-setting, data/structure-setting/action
• Example 3 active URI: datacenters/list, datacenters/list/action
• Example 4 active URI: datacenters/cluster-setting, datacenters/cluster-setting/action

Nav Locator even supports route rule mapping. If you have a rule 'test' => 'data/list', the Nav Locator could identify as in data/list when you enter with test route.

REQUIREMENTS

This library requires the following:

• PHP 5.4.0+
• Yii 2.0.0+

INSTALLATION

Install via Composer in your Yii2 project:

composer require yidas/yii2-nav-locator

USAGE

is()

Validate current controller action is completely matched giving route

public static boolean is(string $route)

Example:

Suppose site/index as the current controller action:

use yidas\NavLocator as Locator;

Locator::is('site');            // False (Route `site` could not refer to a actual action)
Locator::is('site/');           // False (There is no difference between using a slash or not)
Locator::is('site/index');      // True  (Successfully match the same controller ID and same action ID)
Locator::is('site/index/');     // True 
Locator::is('site/other');      // False (Failed to match the same controller ID but the different action ID)
Locator::is('site/other/');     // False 

The giving route need to be defined precisely, the format is module-ID/controller-ID/action-ID.

in()

Validate current controller action is under giving route

public static boolean in(string $route)

Example:

Suppose site/index as the current controller action:

use yidas\NavLocator as Locator;

Locator::in('site');            // True  (Current route `site/index` is indeed in `site` layer)
Locator::in('site/');           // True 
Locator::in('site/index');      // True  (Current route `site/index` is indeed the `site/index` layers)
Locator::in('site/index/');     // True 
Locator::in('site/other');      // False (Current route `site/index` is not in `site/other` layers)
Locator::in('site/other/');     // False 
Locator::in('si');              // False (Current route `site/index` is not in `si` layer, `site` != `si`)
Locator::in('si/');             // False 
Locator::in('site/index/index');// False (This route means `site` module with `index` controller and `index` action)

The giving route will divide into independent and precise route layers by each separator, letting you distinguish whether the current controller action belongs to the parent navigation.

setPrefix()

Set prefix route for simplifying declaring next locator routes

public static self setPrefix(string $prefix)

Example:

<?php
use yidas\NavLocator as Locator;
?>

<li class="treeview <?php if(Locator::setPrefix('data/')->in('/')):?>active menu-open<?php endif ?>">
  <a href="#">
    <i class="fa fa-database"></i> <span>Data</span>
    <span class="pull-right-container">
      <i class="fa fa-angle-left pull-right"></i>
    </span>
  </a>
  <ul class="treeview-menu">
    <li class="<?php if(Locator::in('list/')):?>active<?php endif ?>"><a href="<?=Url::to(['data/list'])?>"><i class="fa fa-circle-o"></i> Data List </a></li>
    <li class="<?php if(Locator::in('structure-setting/')):?>active<?php endif ?>"><a href="<?=Url::to(['data/structure-setting'])?>"><i class="fa fa-circle-o"></i> Structure Setting </a></li>
  </ul>
</li>

<li class="treeview <?php if(Locator::setPrefix('datacenters/')->in('/')):?>active menu-open<?php endif ?>">
  <a href="#">
    <i class="fa fa-server"></i> <span>Data Centers</span>
    <span class="pull-right-container">
      <i class="fa fa-angle-left pull-right"></i>
    </span>
  </a>
  <ul class="treeview-menu">
    <li class="<?php if(Locator::in('list/')):?>active<?php endif ?>"><a href="<?=Url::to(['datacenters/list'])?>"><i class="fa fa-circle-o"></i> Node List </a></li>
    <li class="<?php if(Locator::in('cluster-setting/')):?>active<?php endif ?>"><a href="<?=Url::to(['datacenters/cluster-setting'])?>"><i class="fa fa-circle-o"></i> Cluster Setting </a></li>
  </ul>
</li>

You could call it without parameter for reset prefix: \yidas\NavLocator::setPrefix()