sfMenuGeneratorPlugin

Overview

Simple hierarchical menu structure generator. The menu is output as html unordered lists.

YES

• Easily configuration in the application (app.yml)
• Module level configuration available to override the application configuration settings (module.yml)
• Credential management
• Shortcuts (version 0.2.0 needs Prototype 1.6.0. so this version requires that sfPrototypePlugin is installed.)

NO

• No fancy behaviours
• No css

Symfony version compatibility

Symfony 1.0

• 0.1.1
• 0.1.2
• 0.2.0

Symfony 1.1 RC1 and 1.1 RC2

The plugin has not been written to be compatible with 1.1 but some versions have been found to work (Please see the section below titled Installing on Symfony 1.1).

• 0.1.2 Seems to work fine.
• 0.2.0 Seems to work except when shortcuts are used.

Installation

symfony plugin-install http://plugins.symfony-project.com/sfMenuGeneratorPlugin

Installation on Symfony 1.1

To use the plugin on 1.1. you must make changes to the package.xml file.
Change this

   <package>
    <name>symfony</name>
    <channel>pear.symfony-project.com</channel>
    <min>1.0.0</min>
    <max>1.1.0</max>
    <exclude>1.2.0</exclude>
   </package>

to this:

   <package>
    <name>symfony</name>
    <channel>pear.symfony-project.com</channel>
    <min>1.0.0</min>
    <max>1.2.0</max>
    <exclude>1.2.0</exclude>
   </package>

If you wish to use version 0.2.0 of the plugin you must also remove the required dependency for the sfPrototypePlugin.
Remove this:

   <package>
    <name>sfPrototypePlugin</name>
    <channel>plugins.symfony-project.com</channel>
    <min>1.6.0</min>
   </package>

Example usage

The menu is configured with default settings for the application in 'app.yml'. Module override settings are configured in 'module.yml'. This example is as you might use in app.yml or module.yml:

all:

  sf_menu_generator:

    root:
      text:  'Choose'
      items: [users, contacts]

    contacts:
      text:     'Contacts'
      link:     'contacts/list'
      shortcut: 'c'
      deny:     [manager, contenteditor]

    users:
      text:   'Users Menu Node'
      link:   'users/list'
      items:  [listusers, newuser, modifyuser]
      allow:  [admin]

    listusers:
      text:     'User List'
      link:     'users/list'
      shortcut: 'ctrl+lu'

    newuser:
      text:     'New user'
      link:     'users/new'
      shortcut: 'ctrl+nu'
    
    modifyuser:
      text: 'Modify user'
      link: 'users/modify'

The helper

The helper is simple to use:

<?php use_helper('MenuGenerator')?>
....
<?php echo mg_menuitem(array('root'),array('class'=>'menu'))?>

The first argument is an array with the menu nodenames, as they are defined and discussed in the 'app.yml' and/or 'module.yml'.
The second argument defines html attributes to pass to the main "ul" tag of the menu.

Example HTML

<ul class="menu">
  <li>
    <ul>
      <li>
        <ul>
          <li>
            <a href="users/list">User List</a>
          </li>
          <li>
            <a href="users/new">Nuew user</a>
          </li>
          <li>
            <a href="users/modify">Modify user</a>
          </li>
        </ul>
        <a href="users/list">Users Menu Node</a>
      </li>
      <li>
        <a href="#">Contacts</a>
      </li>
    </ul>
    <a href="#">Choose</a>
  </li>
</ul>

You can also specify branches of the hierarchical menu and more html attributes as in this example:

<?php echo mg_menuitem(array('contacts','users'),array('class'=>'menu','style'=>'display:inline;'))?>

Detailed configuration settings

The menu items are not defined hierarchically as you might expect in yml. Instead, each menu item has an items section to define its 'child' sub-menu items.
Each menu item can be defined as follows:

  itemName:
    text:       'text to show'
    link:       'link to be fed into link_to()'
    shortcut:   'sh1+ctrl'
    items:      [subitem1, subitem2]
    allow:      [credential1, credential2]
    deny:       [credential3, credential4]
    html_id:    'idItem'
    html_style: 'float:left;color:#FF00FF;'
    html_class: 'mypersonalclassname'
    a_id:       'idAItem'
    a_target:   'blank'

Menu item parameters

• text: this is the text meant to be inside the li element. Can be anything, even html tags. Not mandatory.
• link: this is the link the menu item will point to. it's not mandatory if nothing is set, then an '#' is generated.
• shortcut: if you want to have a keyboard shortcut to make the browser goes to the url defined by the 'link' attribute, type it here. any character combination that can be seen on any editor is valid. you can only indicate one modifier: ctrl (or not).
• items: this is an array of the menu items (defined just like this one elsewhere in the yml file) which are supposed to be the childs of this one.
• allow: Array of the credentials a user must have to view this particular item . If none is given , 'any' wildcard is assumed .
• deny: Array of the credentials a user must not have to view this particular item. If there is collision between this parameter and the allow parameter, the most resctrictive approach is taken.
• a_*: attributes for the "a" tag. can be anything .
• html_*: attributes for the "li" tag.

Default html class names

If 'html_class' is not specified the "li" tags have the class="mg node_<nodename>" by default.
If there is an 'html_class' parameter the "li" tag will have that class name, plus "node_<nodename>" e.g.

  user:
    text: 'Users'
    html_class: 'soft'

will generate:

  <li class="soft node_user">
    ...
  </li>

Parameter precedence. (Overriding default settings using module.yml)

The helper will read the configuration from app.yml and then module.yml.
Menu items can be defined in both files.

app.yml:

  user:
    text: 'users'
    items: [user1, user2]

  user1:
    text: 'user1'

module.yml:

  user2:
    text: 'user2'

As you see in the previous example, you can use child items that are defined elsewhere.

Overlapping configurations

In case of overlapping the module.yml definitions have precedence.

app.yml:

  user: 
    text: 'user from the root menu'
    items: [user1, user2]

module.yml:

  user:
    text: 'user from the module'

is equivalent to:

  user: 
    text: 'user from the module'
    items: [user1, user2]

Overlapping the items, allow and deny section

Special rules apply when there is overlapping in the 'items', 'allow' and 'deny' sections. The syntax is similar to the one used on stylesheets section of view.yml.

• The items|allow|deny section defined for an overlapping menu item at module.yml file are added to the items|allow|deny section defined at the app.yml configuration file.
• If there is a '-' prefix for one of the elements of the items|allow|deny array, then that element is removed.
• The special '-*' instructs the plugin to remove all elements defined in the items|allow|deny section. (Following elements are not affected).

So, if we have these two overlapping menu items:

app.yml:

  user:
    ...
    items: [user1, user2, user3, user4]
    allow: [cred1, cred2]

module1.yml:

  user:
    items: [user5, -user2]
    deny: [cred2]

module2.yml:

  user:
    items: [-*,user6]
    allow: [-cred1]

- In module1.yml, the 'user5' child will be added, and the 'user2' will be removed. The 'cred2' credential is denied - In module2.yml all the childs defined in app.yml will be removed, and the 'user6' child will be added. The cred1 is no longer allowed

Shortcuts

In order to assure maximun compatibility, shortcuts are kept simple.

• A shortcut defined in any menu item will just make the browser go to the address specified by the 'link' param. No more, No less.
• Shortcuts can be made of single characters or words.
• Shortcuts are defined by the 'keypress' event, so any character combination that can be seen on an editor is admisible: 'a' , 'a8', '#er', etc.
• The only modifier which is to be taken into account is 'ctrl', and is specified like this 'ctrl+a' or 'bebe + ctrl' or '111+ctrl', etc.
• If the cursor is inside a text input field only the shortcuts defined with the ctrl modifiers will work.
• You can make an input field lose focus by pressing and releasing the ctrl or ESC keys.
• If the shortcut is more than one character (a 'word' shortcut), you have two seconds between keypresses. If you delay for longer the system will empty the 'shortcut buffer'.

Changelog

0.2.0

• JoeZ99: added shortcuts (requires Prototype 1.6.0 - this version requires that sfPrototypePlugin is installed.)

0.1.2

• JoeZ99: second release

0.1.1

• JoeZ99: initial release