yiismartmenu

General Information ¶

YiiSmartMenu auto checks permissions to define visibility of any menu item. It can be used with any authManager component since that one has configured to use the Yii::app()->user->checkAccess() authorization method.

YiiSmartMenu can work out-of-the-box with the Rights.

This is how YiiSmartMenu works: it iterates through the received items and turns its visibility true or false depending on result of checkAccess() function to that specific menu item. If you prefer, you can define the auth item name to be checked for yourself but if you don't, YiiSmartMenu will auto compound it by concatenating the module (whether any), the controller and the action defined in url or submit options of your menu's items.

Some Vantages ¶

• Out-of-the-box use. You just need to extract and change the widgets that are using CMenu to YiiSmartMenu;
• Less database queries: if a menu item is not accessible due to checkAccess() restrictions, none of its children are checked. In some menus it could save dozens of queries;
• You can use YiiSmartMenu in the main menu, in the operations menu or any other menu where you would use CMenu;
• Very customizable. You can define your own auth params and your own auth item name or you can define init options to customize how YiiSmartMenu will generate them. You can even define your own "visible" rule to your menu item and YiiSmartMenu will not touch it;

Examples ¶

It could be use, for example, in //layouts/main or //layouts/column2 menus:

$this->widget('application.components.YiiSmartMenu',array(
        //No required init options
        'partItemSeparator'=>'.',
        'upperCaseFirstLetter'=>true,
 
        //Same options used in CMenu
    'items'=>array(
            array(
                  'label'=>'Home Page',
                  'url'=>array('/site/index',
            ),
            array(
                  'label'=>'Other Page',
                  'url'=>array('something/other'),
 
                  //optional, if not set, YSM will controll visibility;
                  'visible'=>{your own rule, YSM will not touch this},
 
                  //optional, params to be sent to checkAccess() function;
                  //if not set, YSM will use params from url/submit options
                  //or $_GET.
                  'authParams'=>array('myParam'=>'myValue', ...),
 
                  //optional, auth item name to be used in checkAccess() function;
                  //if not set, YSM will auto generate this.
                  'authItemName'=>'myAuthItemName',
           ),
            ...
        ),
        ...

In the first menu item above, YiiSmartMeny would use the property url ('/site/index') to generate and execute the following checkAccess() function:

Yii::app()->user->checkAccess("Site.Index", $_GET)';

Setting 'partItemSeparator'=>'' (empty string) makes YSM generate:

Yii::app()->user->checkAccess("SiteIndex", $_GET)';

And if you also has set 'upperCaseFirstLetter'=>false YSM would generate:

Yii::app()->user->checkAccess("siteindex", $_GET)';

This way, the menu item 'Home Page' would only be visible if the current logged user had access privilegies to an auth item named 'Site.Index' (or 'siteindex' if init options was set like in the example). Note that $_GET is passed as $params to checkAccess() if you do not define 'authParams' option of your menu item or if the "url" or "submit" options has no additional params.

Init Options ¶

• partItemSeparator string defines which char(s) separator to use when concatenating to generate auth item name. Defaults to '.'(dot);
• upperCaseFirstLetter boolean if true, the module, controller and action will be lcfirst() before to be concatened to generate the auth item name. Defaults to true;

Logs ¶

If you have trace logs enabled you can check traces messages to view why each menu item was turned visible or not. The template of the showed trace messages is:

Item {MenuItemName} is [*not*] visible. You have [no] permissions to [ModuleW.]ControllerX.ActionY with params:
paramX=valX ...

Installation ¶

1. Put YiiSmartMenu.php in your application.components folder;
2. Change your widget menus from $this->widget('zii.widgets.CMenu', ... to $this->widget('application.components.YiiSmartMenu',... (Please, see the examples above);

Requirements ¶

• PHP 5.3+ (Due to use of the function ucfirst());
• Tested with Yii 1.1.7. Should work ok with earlier versions;

Resources ¶

• https://github.com/sidtj/Yii-Smart-Menu;
• Forum Discussion
• CMenu Documentation

Acknowledgements ¶

• Thanks to Binc for let me know about correct use of the english word 'set'.

Change Log ¶

• Version 0.3.0

  • Looks for url/submit additional params to send to checkAccess() if 'authParams' is not set. $_GET will only be sent if 'authParams' is not set and url/submit has no additional params;
  • Improoved trace messages. Now they show what params are being sent to checkAccess();
  • The code has been refactored;

• Version 0.2.1

  • Allow to set the new option 'params'=>array(...) in a menu item to be sent to checkAccess() function instead of the default var $_GET;
  • Allow to set the new option 'authItemName'=>'CanDoX' in a menu item to be used in checkAccess() function instead of auto generate it based in 'url' or 'submit' options;

• Version 0.1.0 First Version;