Advanced Custom Menu Items

Through the EditLive! configuration file, administrators can easily define custom menu and toolbar items. The text, icon, action and what elements the item is enabled in can all be declared as part of the configuration. The Plugin APIs however provide additional control over how these custom items appear and behave.

The key to this customisation is the ActionController class that can be accessed via theELJBean.getActionController() method. The ActionController class gives plugin developers access to theEphoxAction classes that control the appearance and behaviour of all menu and toolbar items in the editor. In this article we’ll take a look at how to get finer grained control over when a custom item is enabled. In future articles we’ll look at some of the other ways the ActionController and EphoxAction classes can be used to create more intuitive custom items.

Note that the ActionController is only safe to use once the editor has finished loading. 

First, in the configuration file (or the plugin’s XML file) we define the basics of the custom item we need:

<customMenuItem name="customActionName" text="Perform custom action..."
  action="raiseEvent" value="customAction" />

Now we need to get a reference to that action instance from the plugin:

EphoxAction action =
  eljbean.getActionController().getAction(”customActionName”);

Now we can use any of the methods on EphoxAction to modify how the action looks and behaves.  In this case we want to control when it’s enabled, which means adding a custom EnabledFilter:

action.addEnabledFilter(new CustomEnabledFilter());

Enabled filters have two key tasks and two methods to implement that match them:

1. Decide whether or not the action is enabled by implementing the isEnabled() method. An action is only enabled if all the enabled filters applied to it return true.
2. Inform listeners when the enabled state of the filter changes. This allows the EditLive! user interface to correctly update when actions are enabled or disabled. PropertyChangeListeners are added using the addPropertyChangeListener method. This pattern of change listeners is used very commonly throughout Swing so it should be familiar to most developers.

Your EnabledFilter can do anything it needs to as part of deciding when to enable or disable the action, including listening for caret updates or document changes. However, it is important to remember that the isEnabled() method will be called very frequently so it needs to return very fast.  In most cases, the enabled state of the filter should be stored as a simple boolean variable and updated only when change events are received. Don’t forget to notify the property change listeners whenever the state changes, otherwise the change will not be noticed by EditLive!