= sfMenuGeneratorPlugin = 
== Overview ==

Simple menu structure generator.
=== YES ===
 - Easily configurable through .yml files
 - advanced module.yml overriding
 - Credentials management
=== NO ===
 - No javascripts
 - No fancy behaviors
 - No css
[[BR]][[BR]]
''Just plain old html!''
== Installation ==
{{{
symfony plugin-install http://plugins.symfony-project.com/sfN1IterationPlugin
}}}

== Quick & Dirty ==

Configuration at 'app.yml' and 'module.yml'
{{{
all:
  ...
  ...
  sf_menu_generator:
  
    root:
      text:  'Choose'
      items: [users, contacts]

   contacts:
     text:   'Contacts'
     deny: [manager, contenteditor]
    
    users:
      text:   'Users Menu Node'
      link:   'users/list'
      items:  [listusers, newuser, modifyuser]
      allow:  [admin]
      

    listusers:
      text: 'User List'
      link: 'users/list'

    newuser:
      text: 'New user'
      link: 'users/new'
    
    modifyuser:
      text: 'Modify user'
      link: 'users/modify'
}}}

Use of the helper
{{{
<?php echo mg_menuitem(array('root'),array('class'=>'menu'))?>
}}}

Generated 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>
}}}

== config explained ==

The plugins use 'menu items' defined in app.yml or module.yml. 
[[BR]]
These items are not defined hierarchically. Instead of that each menu item has an '''items''' sections which refers to the other menu items that are to be considered childs.[[BR]]
Each menu item is defined as follows:
{{{

  itemName:
    text: 'text to show'
    link: 'link to be fed into link_to()'
    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'
}}}

=== params explained ===

  - '''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.
  - '''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 classnames ===

If no 'html_class' is providen, the "li" tags have the class="mg node_<nodename>".[[BR]]
If there is an 'html_class' parameter, then the "li" tag will have that class name, plus "node_<nodename>".
{{{
  user:
    text: 'Users'
    html_class: 'soft'

will generate ..
  ...
  <li class="soft node_user">
  ....
    <a ..>Users</a>
  </li>
}}}

=== parameters preference . Use of the ''module.yml'' ===

The helper will read its configuration from both '''app.yml''' and '''module.yml'''.[[BR]]
Items can be defined in both files.[[BR]]
app.yml:
{{{
  user:
    text: 'users'
    items: [user1, user2]

  user1:
    text: 'user1'
}}}
[[BR]]
module.yml:
{{{
  user2:
    text: 'user2'
}}}

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

In case of overlapping, the module.yml definitions have precedence.[[BR]][[BR]]
app.yml:
{{{
  user: 
    text: 'user from the root menu'
    items: [user1, user2]
..
}}}
[[BR]]
module.yml:
{{{
  user:
    text: 'user from the module'
}}}

is equivalent to:
{{{
  user: 
    text: 'user from the module'
    items: [user1, user2]
}}}

[[BR]][[BR]]
'''Overlapping the ''items, allow and deny'' section'''[[BR]]
Regarding the 'items' , 'allow' and 'deny' sections, special rules apply when there is overlapping. 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 from the childs.
  - The special '-*' instructs to remove all the elements that are already defined at the ''items|allow|deny'' section , at the moment the parser reads that special character. (The 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

== helper explained ==

The helper is fairly simple to use:
{{{
<?php use_helper('MenuGenerator')?>
....
<?php echo mg_menuitem(array('node1','node2'),array('class'=>'menu','style'=>'display:inline;'))?>
}}}
The first argument is an array with the menu nodenames, as they are defined and discussed in the previous section.[[BR]]
The second argument are html attributes to pass to the main "ul" tag of the menu.