Allow extension developers to easily add nav menu items

Extension developers using hook_civicrm_navigationMenu have to do some gymnastics to get new menu items in the navigation menu--or at least to do it properly. I have my own standard way of doing it, and I suspect many others do as well, and I also know that many extensions do so in a problematic way.

I'm proposing to include a class in core to provide an easy way to do this. I've put it as CRM_Utils_NavAdd, but it could go somewhere else if others think that makes sense.

Here's the usage:

function yourextension_civicrm_navigationMenu(&$menu) {
  $adder = new CRM_Utils_NavAdd($menu);
  $attributes = array(
    'label' => ts('One thing'),
    'name' => 'One thing',
    'url' => 'civicrm/onething',
    'permission' => 'access CiviCRM, administer CiviCRM',
    'operator' => 'AND',
    'separator' => 1,
    'active' => 1,
  );
  $adder->addItem($attributes, array('Administer'));
  $attributes = array(
    'label' => ts('Other thing'),
    'name' => 'Other thing',
    'url' => 'civicrm/otherthing',
    'permission' => 'access CiviCRM',
    'separator' => 1,
    'active' => 1,
  );
  $adder->addItem($attributes, array('Contributions', 'Pledges'));
  $menu = $adder->getMenu();
}

For now, it will need to run a fresh lookup of the maximum ID (triggered by the constructor) for each implementation of hook_civicrm_navigationMenu becuase most extensions adding menu items won't be using this–the maximum ID could have been incremented without this class being involved.

All in all, I think this will make adding menu items more efficient and reliable for developers.