An example to explain the use of $GROUP_EVENTS$: imagine you have a controller with a subject list of "*" (i.e. all page items) and an event filter of 'subjectModified'.

Now do a 'select all' on a spread, and move the selected page items a bit up.

The controller will now be hammered with 'subjectModified' messages - one for each page item. That might become increasingly slow.

That's where setting $GROUP_EVENTS$ on your controller comes in - instead of getting multiple 'subjectModified' events, you now only get a single subjectModified event, and an array of all page items that have been subjected to that event. That makes processing often much more efficient.

The same trick can be used to make menu handling more efficient.

So, it's totally optional, but it can offer significant speedups.

Below some code of a 'skeleton' for a .spln (as used with APIDTemplate) that handles menu items using $GROUP_EVENTS$:

Code:

// Header - matches anonymous function trailer at bottom
(function(theItem)
{
// End Header

...

var gAppVersion = parseFloat(app.version);

Main(theItem);

...

// ********************

function EnableMenu(thePlugin,theMenuItem)
{
  var retVal = false;
  
  switch (theMenuItem)
  {
    case "menuYadiYadi":
      retVal = <true or false>;
      break;
    ...
  }
  
  return retVal;
}

// ********************

function EnableMenus(thePlugin)
{
  var retVal = false;

  //
  // Check for grouped menu items (API 1.0.40 or higher
  // when thePlugin.setDataStore("$GROUP_EVENTS$",true))
  //
  if (thePlugin.eventData instanceof Array)
  {
    var retVal = [];
    //
    // Needs APIR 1.0.40 or higher for grouped menu items
    //
    for (var idx = 0; idx < thePlugin.eventData.length; idx++)
    {
      retVal.push(EnableMenu(thePlugin,thePlugin.eventData[idx]));
    }
  }
  else
  {
    retVal = EnableMenu(thePlugin,thePlugin.eventData);
  }
  
  thePlugin.tempDataStore = retVal;
}

....

// ********************

function Main(thePlugin)
{
  var thePageItem = thePlugin.eventSource;
  var theEventCode = thePlugin.eventCode;
  
  if (theEventCode == "docLoaded" || theEventCode == "selected")
  {
    Setup(thePlugin,theEventCode);
  }
  else if (theEventCode == "enableMenus")
  {
    EnableMenus(thePlugin);
  }
  else if (theEventCode == "menuYadiYadi")
  {
    ...
  }
  ...
  
}

// ********************

function Setup(thePlugin,theEventCode)
{
  var theErr;

  thePlugin.setDataStore("$GROUP_EVENTS$",true);
  
  try
  {
    app.registerMenuItem("menuYadiYadi","Main:0x90B50kActivePageItemMenuKey:.Yadi Stuff:.YadiYadi");
    ...
  }
  catch (theErr)
  {
  }
}


...

// Trailer - matches anonymous function header at top
}
)(theItem);
// End Trailer