jEdit maintains a list of "properties", which are name/value pairs used to store human-readable strings, user settings, and various other forms of meta-data. During startup, jEdit loads the default set of properties, followed by plugin properties stored in plugin JAR files, finally followed by user properties. Plugins can access properties from all three sources.
Property files contained in plugin JARs must end with the filename extension .props, and have a very simple syntax, which the following example illustrates:
# Lines starting with '#' are ignored. name=value another.name=another value long.property=Long property value, split over \ several lines escape.property=Newlines and tabs can be inserted \ using the \t and \n escapes backslash.property=A backslash can be inserted by writing \\. |
The following types of plugin information are supplied using properties:
Information regarding the name, author, and version of the plugin. This information is required. Here is an example:
plugin.MyPlugin.name=My Plugin plugin.MyPlugin.author=Jay Edit plugin.MyPlugin.version=1.0.3 |
Note that each property is prefixed with plugin., followed by the fully qualified name of the plugin core class (including a package name, if there is one).
Identification of any dependencies the plugin may have on a particular version of a Java runtime environment, the jEdit application, or other plugins.
Each dependency is defined in a property prefixed with plugin.class name.depend., followed by a number. Dependencies must be numbered in order, starting from zero.
The value of a dependency property is one of the words jdk, jedit, or plugin, followed by a Java version number, a jEdit build number, or plugin class name and plugin version number, respectively.
Here are some examples:
plugin.MyPlugin.depend.0=jdk 1.4 plugin.MyPlugin.depend.1=jedit 04.00.99.00 plugin.MyPlugin.depend.2=plugin console.ConsolePlugin 3.2.1 |
A list of external class library JARs shipped with the plugin. If your plugin bundles extra JARs, this property is required for the plugin manager to be able to remove the plugin completely.
The property is a space-separated list of filenames. Here is an example:
plugin.xslt.XSLTPlugin.jars=xml-apis.jar xalan.jar |
Labels for user actions for inclusion in menus and option panes relating to toolbars and keyboard shortcuts.
Action labels are defined in properties named by the action's internal name as specified in the action catalog, followed by .label:
myplugin.label=My Plugin myplugin-grok.label=Grok Current Buffer |
The list of menu items contained in plugin menus, if any.
This is discussed in detail in the section called "Action Labels and Menu Items".
Labels and other information regarding the controls contained in the plugin's windows. These properties can be named any way you like, however take care not to choose names which may conflict with those in other plugins.
The titles of dockable windows, as displayed in a tabbed or floating container.
These labels are specified in properties named by the dockable window's identifier (as specified in the dockables.xml file, see the section called "The Dockable Definition File"), suffixed with .title. For example:
quick-notepad.title=QuickNotepad |
Actions define procedures that can be bound to a menu item, a toolbar button or a keyboard shortcut. They can perform any task encompassed in a public method of any class currently loaded in jEdit, including plugin classes and classes of the host application. Among other things, they can cause the appearance and disappearance of plugin windows.
To manage user actions, jEdit maintains a lookup table of actions using descriptive strings as keys. The values in the table are sets of statements written in BeanShell, jEdit's macro scripting language. These scripts either direct the action themselves, delegate to a method in one of the plugin's classes that encapsulates the action, or do a little of both. The scripts are usually short; elaborate action protocols are usually contained in compiled code, rather than an interpreted macro script, to speed execution.
Actions are defined by creating an XML file entitled actions.xml and placing it in the plugin JAR file. A sample action catalog looks like so:
<!DOCTYPE ACTIONS SYSTEM "actions.dtd"> <ACTIONS> <ACTION NAME="quicknotepad.choose-file"> <CODE> view.getDockableWindowManager() .getDockable(QuickNotepadPlugin.NAME).chooseFile(); </CODE> </ACTION> <ACTION NAME="quicknotepad.save-file"> <CODE> view.getDockableWindowManager() .getDockable(QuickNotepadPlugin.NAME).saveFile(); </CODE> </ACTION> <ACTION NAME="quicknotepad.copy-to-buffer"> <CODE> view.getDockableWindowManager() .getDockable(QuickNotepadPlugin.NAME).copyToBuffer(); </CODE> </ACTION> </ACTIONS> |
The defined elements have the following functions:
ACTIONS is the top-level element and refers to the set of actions used by the plugin.
An ACTION contains the data for a particular action. It has three attributes: a required NAME; an optional NO_REPEAT, which is a flag indicating whether the action should not be repeated with the Control-Enter command (see the section called "Command Repetition"); and an optional NO_RECORD which is a a flag indicating whether the action should be recorded if it is invoked while a user is recording a macro. The two flag attributes can have two possible values, "TRUE" or "FALSE". In both cases, "FALSE" is the default if the attribute is not specified.
An ACTION can have two child elements within it: a required CODE element which specifies the BeanShell code that will be executed when the action is invoked, and an optional IS_SELECTED element, used for checkbox menu items. The IS_SELECTED element contains BeanShell code that returns a boolean flag that will determine the state of the checkbox.
More discussion of the action catalog can be found in the section called "Actions".
The jEdit Plugin API uses BeanShell to create the top-level visible container of a plugin's interface. The BeanShell code is contained in a file named dockables.xml. It usually is quite short, providing only a single BeanShell expression used to create a visible plugin window.
The following example from the QuickNotepad plugin illustrates the requirements of the data file:
<?xml version="1.0"?> <!DOCTYPE DOCKABLES SYSTEM "dockables.dtd"> <!-- QuickNotepad dockable windows --> <DOCKABLES> <DOCKABLE NAME="quicknotepad"> new QuickNotepad(view, position); </DOCKABLE> </DOCKABLES> |
In this example, the <DOCKABLE> element has a single attribute, the dockable window's identifier. This attribute is used to key a property where the window title is stored; see the section called "Plugin Properties". The contents of the <DOCKABLE> element itself is a BeanShell expression that constructs a new QuickNotepad object. The view and position are predefined by the Plugin API as the view in which the plugin window will reside and the docking position of the plugin.
While not required by the plugin API, a help file is an essential element of any plugin written for public release. A single web page is often all that is required. There are no specific requirements on layout, but because of the design of jEdit's help viewer, the use of frames should be avoided. Topics that would be useful include the following:
a description of the purpose of the plugin;
an explanation of the type of input the user can supply through its visible interface (such as mouse action or text entry in controls);
a listing of available user actions that can be taken when the plugin does not have input focus;
a summary of configuration options;
information on development of the plugin (such as a change log, a list of "to do" items, and contact information for the plugin's author); and
licensing information, including acknowledgments for any library software used by the plugin.
The location of the plugin's help file should be stored in the plugin.class name.docs property.