DynarchMenu.MenuItem -- the object

When the action of some menu item involves calling a JavaScript function, that function can determine what the clicked item is. This helps having one handler for multiple actions, as you can learn in menu actions documentation. The MenuItem object provides methods and properties that allow one to investigate item properties or change its state, label, icon and so on.

Determining the item

Say we have the following menu:

  <ul id="menu">
    <li><a href="javascript:retval = my_handler(this);">Item</a></li>
  </ul>

That's a very simple menu with one item. That item calls a function handler and assigns its value to retval; we'll talk about retval in a moment. The function handler can be written like this:

  function my_handler(action) {
    var menu_item = action.info;
    alert(menu_item.label);
    return false;
  }

So, in order to retrieve the menu item just use the “info” property of the first argument. Note that in order for this to work we need to include “this” when we designate my_handler (in the href attribute). The above handler just displays the label of the clicked menu item, whatever would that be, using the “label” property of the MenuItem object.

retval is a variable that exists in the context where the event handler is evaluated; assigning false to it (or not assigning it at all) will instruct DynarchMenu to close the popup shortly after the handler executed. There are cases where you might want to keep the popup on screen, such as when you have one popup full of checkboxes and you want to allow users to click them all before closing the menu, so in that case you could simply return true from the function handler; the value would be passed to retval which is hooked by DynarchMenu. Don't worry about globals--it's not global in that context.

Want other items?

On occasions you might need to modify items other than the clicked one in an action handler, or even if you're not in some action handler. How do you get a reference to the item in this case? DynarchMenu makes it pretty simple. First, you must declare unique ID-s (using the id attribute) to those LI-s that define items you think you might need to access. DynarchMenu internally keeps a hash table that maps these ID-s to object references. Example:

  <script type="text/javascript">
    var menu;
    function my_handler(action) {
      var clicked_item = action.info;
      var other_item = menu.items["item2"];
      if (other_item.disabled) {
         // let's enable it
         other_item.disable(false);
         clicked_item.setLabel("Disable next item");
      } else {
         other_item.disable(true);
         clicked_item.setLabel("Enable next item");
      }
    };
  </script>
  <ul id="menu">
    <li id="item1"><a href="javascript:my_handler(this)">Enable next item</a></li>
    <li id="item2" class="disabled">Foo Bar</li>
  </ul>

The above example assumes that you initialize the menu with:

menu = DynarchMenu.setup("menu");

that is, you need to keep a reference to the DynarchMenu object in the “menu” variable.

So as you can see, if you have kept a reference to the DynarchMenu object (the “menu” variable in our case) then you can use it to retrieve items by ID, as in item = menu.items['id'].

MenuItem properties

The object has, besides “label”, a lot of other interesting properties:

1. id -- string. This contains the item ID, when one has been assigned. You can assign an ID by passing it to the <li> element: <li id="our-item">. Inside action handlers, you can determine the item that has been clicked in the easiest way by inspecting it's "id" property.
2. separator -- boolean, it is true if the item is a separator.
3. icon -- a reference to the IMG element that displays the item icon, if any (beware that this is null when no icon is present).
4. label -- the item's label; might be HTML--you have been warned! ;-)
5. parent -- a reference to the parent menu item, which is an object of the same type, or null if there is no parent (as is the case for the toplevel menu bar).
6. tooltip -- the item's tooltip.
7. disabled -- true if the item is disabled, false if enabled
8. visible -- true if the item is visible, false if hidden
9. pressed -- true if the item is pressed, false if depressed

As you can see, there are some interesting properties, such as “pressed”, “disabled” or “visible”--but setting them directly doesn't have any effect. The next section describes the methods that you can use to set or change these properties.

MenuItem methods

1. disable(state) -- this method will disable the menu item if the “state” parameter is true, will enable it if “state” is false or will toggle the current state if no argument was passed.
2. display(state) -- this method will hide the item if “state” is true, will make it visible if “state” is false or will toggle the state if no argument was passed.
3. setPressed(state) -- this method will set the pressed state of the item (useful in a toolbar); similar to the above functions, it will make the button pressed if the argument is true, will make it depressed if the argument is false or will toggle it if no argument was passed.
4. setLabel(text) -- this method can be used to change the item's label. Just pass the new label. Note that at this stage no keybindings can be defined and the underscore characters will remain intact.

The above properties and methods are exemplified in our complex sample, Creating a toolbar.