<?xml version="1.0" encoding="UTF-8"?>
<chapter id="plugin-intro">
    <title>Introducing the Plugin API</title>
    <!-- :indentSize=2:tabSize=2:noTabs=true:wrap=soft:maxLineLen=90:     -->
    <!-- :xml.root=users-guide.xml: -->
    <!-- jEdit buffer-local properties:                         -->

    <indexterm>
        <primary>Plugin API</primary>
        <secondary>introduction</secondary>
    </indexterm>

    <para>The <firstterm>jEdit Plugin API</firstterm> provides a framework for
    hosting plugin applications without imposing any requirements on the design
    or function of the plugin itself. You could write an application that
    performs spell checking, displays a clock or plays chess and turn it into a
    jEdit plugin. There are currently over 50 released plugins for jEdit. While
    none of them play chess, they perform a wide variety of editing and file
    management tasks.</para>

    <para>A detailed listing of available plugins is available at <ulink
    url="http://plugins.jedit.org">plugins.jedit.org</ulink>. You can also find
    beta versions of new plugins in the <quote>Downloads</quote> area of <ulink
    url="http://community.jedit.org">community.jedit.org</ulink>.</para>

    <para>Using the <quote>Plugin Manager</quote> feature of jEdit, users with
    an Internet connection can check for new or updated plugins and install and
    remove them without leaving jEdit. See <xref linkend="using-plugins" /> for
    details.</para>

    <para>Requirements for <quote>plugging in</quote> to jEdit are as
    follows:</para>

    <itemizedlist>
        <listitem>
            <para>This plugin must supply information about itself, such as its
            name, version, author, and compatibility with versions of
            jEdit.</para>
        </listitem>

        <listitem>
            <para>The plugin must provide for activating, displaying and
            deactivating itself upon direction from jEdit, typically in response
            to user input<footnote>
                    <para>You should test your plugin by loading and unloading
                    it from both the Plugin Manager, as well as the <emphasis
                    role="bold">Activator Plugin</emphasis>.</para>
                </footnote>. Make sure you can continue to use both your plugin
            and the editor after it has been reloaded.</para>
        </listitem>

        <listitem>
            <para>Each Plugin has an ActionSet defined by jEdit, which is added
            to the main ActionContext. The ActionSet is a container for
            EditAction instances. The plugin may define
            <firstterm>actions</firstterm> in a number of ways. One way is
            explicitly, with an action definition file known as
            <literal>actions.xml</literal>. Another is implicitly, by defining
            dockable windows in <literal>dockables.xml</literal>.</para>

            <para>Most EditActions are small blocks of BeanShell code that jEdit
            will perform on behalf of the plugin upon user request. They provide
            the <quote>glue</quote> between user input and specific plugin
            routines.</para>

            <para>By convention, plugins display their available actions in
            submenus of jEdit's <guimenu>Plugins</guimenu> menu; each menu item
            corresponds to an action. Plugin authors do not define specific
            shortcuts - the user can/will assign EditActions to keyboard
            shortcuts, toolbar buttons, or entries in the text area's Context
            menu (right-click menu).</para>
        </listitem>

        <listitem>
            <para>The plugin may, but need not, provide a user interface.</para>

            <para>If the plugin has a visible interface, it can be shown in any
            object derived from one of Java top-level container classes:
            <classname>JWindow</classname>, <classname>JDialog</classname>, or
            <classname>JFrame</classname>. jEdit also provides a dockable window
            API, which allows plugin windows derived from the
            <classname>JComponent</classname> class to be docked into views or
            shown in top-level frames, at the user's request.</para>

            <para>Plugins can also act directly upon jEdit's text area. They can
            add graphical elements to the text display (like error highlighting
            in the case of the <application>ErrorList</application> plugin) or
            decorations surrounding the text area (like the
            <application>JDiff</application> plugin's summary views). These
            plugins are dependent on the JEditTextArea class, which is currently
            getting refactored.</para>
        </listitem>

        <listitem>
            <para>Plugins may provide a range of options that the user can
            modify to alter their configuration.</para>

            <para>If a plugin provides configuration options in accordance with
            the plugin API, jEdit will make them available in the
            <guilabel>Global Options</guilabel> dialog box.</para>
        </listitem>

        <listitem>
            <para>While it is not required, plugins are encouraged to provide
            documentation.</para>
        </listitem>
    </itemizedlist>

    <para>As noted, many of these features are optional; it is possible to write
    a plugin that does not provide actions, configuration options, or dockable
    windows. The majority of plugins, however, provide most of these
    services.</para>

    <sidebar>
        <title>Plugins and different jEdit versions</title>

        <para>As jEdit continues to evolve and improve, elements of the API may
        change with a new jEdit release.</para>

        <para>On occasion an API change will break code used by plugins,
        although efforts are made to maintain or deprecate plugin-related code
        on a transitional basis. While the majority of plugins are unaffected by
        most changes and will continue working, it is a good idea to monitor the
        jEdit change log, and join the <literal>jedit-devel</literal> mailing list, to keep updated on changes and bug reports, so that you will know when your
        plugin needs to be updated. If you allow the source code to be managed
        by the jEdit project, then other plugin developers can help fix things
        when they break more easily.
        </para>
    </sidebar>
</chapter>
