<?xml version="1.0"?>

<document xmlns="http://maven.apache.org/XDOC/2.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">

  <properties>
    <title>Plugins</title>
    <author email="lukas_theussl_AT_users_DOT_sourceforge_DOT_net">Lukas Theussl</author>
  </properties>

  <head>
    <link rel="icon" href="../images/favicon.ico" type="image/x-icon"/>
    <link rel="shortcut icon" href="../images/favicon.ico" type="image/x-icon"/>
    <meta name="description" content="Plugin tutorial"/>
  </head>

  <body>

  <section name="JaxoDraw plugins">
    <p>
      In version 2.0 a plugin architecture was added to <strong>JaxoDraw</strong>.
      Plugins are software components that may optionally be added to the program
      at runtime, ie without the need of changing or re-compiling the main program.
      This makes it easy to use optional features, in particuar export to uncommon
      formats or import of other custom file formats, while keeping the size of the
      main program at a minimum. In fact, the original main purpose of the plugin
      architecture was to draw some functionality out of the
      <strong>JaxoDraw</strong> core.
    </p>
    <p>
      This document gives some instructions on how to use plugins, and a short
      tutorial on how to write your own!
    </p>

  <subsection name="Installing and using plugins">
    <p>
      Please check the
      <a href="http://jaxodraw.sourceforge.net/plugins/">JaxoDraw Plugins</a>
      home page for an overview of currently available plugins and
      installation instructions.
    </p>
  </subsection>

  </section>

  <section name="Writing plugins">

    <p>
      To write your own custom export plugin you should extend the
      <code>JaxoExportPlugin</code> class and implement all required
      abstract methods.
    </p>
    <p>
      The following is a template that you can use for an export plugin:
    </p>
    <source>package net.sf.jaxodraw.plugin;

import javax.swing.JComponent;

import net.sf.jaxodraw.io.JaxoPreview;

public class TestJaxoPlugin extends JaxoExportPlugin {
    public void commitConfiguration() {
        // Apply the changes made in the configuration panel.
        throw new UnsupportedOperationException("Not supported yet.");
    }

    public JComponent getConfigurationPanel() {
        // Returns a panel that allows to configure optional parameters of this
        // export format. May return null if there is nothing to configure.
        throw new UnsupportedOperationException("Not supported yet.");
    }

    protected void exportTo(String fileName) throws JaxoPluginExecutionException {
        // Export a JaxoGraph to the given nonempty file name.
        // The graph is obtained from the getGraph() method.
        throw new UnsupportedOperationException("Not supported yet.");
    }

    public void preview(JaxoPreview p, boolean sameWindow) {
        // Show a preview of the export.
        throw new UnsupportedOperationException("Not supported yet.");
    }

    public String getWarningForGraph() {
        // Returns a warning for the graph, eg if some objects cannot be exported.
        throw new UnsupportedOperationException("Not supported yet.");
    }

    public String getFormatName() {
        // The name of the export format.
        throw new UnsupportedOperationException("Not supported yet.");
    }

    public String getFileExtension() {
        // The file extension to be used for generated files.
        throw new UnsupportedOperationException("Not supported yet.");
    }

    public String getFileExtensionDescription() {
        // Description to be used for plugin file extensions.
        throw new UnsupportedOperationException("Not supported yet.");
    }

    public String pluginId() {
        // This must return the class name of the plugin:
        return TestJaxoPlugin.class.getName();
    }

    public String getShortName() {
        // Return a short name for this plugin.  This is used to construct names
        // of output files, eg to get a "jaxodraw-pdf-plugin.properties" file,
        // the short name should just be "pdf".
        throw new UnsupportedOperationException("Not supported yet.");
    }

    public String description() {
        // A short description  of what this plugin does.
        throw new UnsupportedOperationException("Not supported yet.");
    }

    public String version() {
        // Return the version number of this plugin.
        throw new UnsupportedOperationException("Not supported yet.");
    }

    public boolean makeAvailableAtRuntime() {
        // Checks some eventual runtime requirements for the plugin,
        // eg if some required runtime dependencies are present.
        throw new UnsupportedOperationException("Not supported yet.");
    }

    public void updateLanguage() {
        // update any components after a language change.
        throw new UnsupportedOperationException("Not supported yet.");
    }
}</source>

    <p>
      Import plugins look very similar except that you should extend
      <code>JaxoImportPlugin</code>, and the important method to implement is:
    </p>

    <source>protected JaxoGraph importGraph(InputStream inputStream)
        throws JaxoPluginExecutionException {
        // return a graph read from an InputStream
    throw new UnsupportedOperationException("Not supported yet.");
}</source>

  <subsection name="Internationalization">
    <p>
      If you want to internationalize your plugin (so it shows messages
      in the same languages as <strong>JaxoDraw</strong>), you have to
      register a <code>JaxoDictionary</code> for your plugin. This is
      done by calling the <code>registerDictionary(Class)</code> method
      of the abstract super-class <code>AbstractJaxoPlugin</code>,
      in the constructor of your plugin:
    </p>
<source>    public TestJaxoPlugin() {
        registerDictionary(TestJaxoPlugin.class);
    }</source>
    <p>
      The dictionary is then accessed with the <code>getLang()</code>
      method
    </p>
<source>String i18n = getLang().translate("TestJaxoPlugin.myKey");</source>
    <p>
      You should put your translations into <code>language.properties</code>
      files in a directory <code>resources/properties/</code> relative to
      your main code. Voila!
    </p>
  </subsection>

  <subsection name="Logging">
    <p>
      You may use the same logging system as the main <strong>JaxoDraw</strong>
      program by calling the <code>getLog()</code> method, eg:
    </p>
    <source>getLog().debug("Plugin registered!");</source>
  </subsection>

  <subsection name="Properties">
    <p>
      Your plugin can store its own set of properties that will be initialized
      automatically by <strong>JaxoDraw</strong> when the plugin is loaded.
      You can load, set and store properties with the commands
    </p>
<source>String propertyValue = getProperty("property.key");
setProperty("property.key", "property.value");
storeProperties();
</source>
    <p>
      Note that you need to set properties before you can store them.
      The properties are stored in a file
      <code>jaxodraw-<em>shortname</em>-plugin.properties</code>
      (where <em>shortname</em> is the String returned by the
      <code>getShortName()</code> method) in the <strong>JaxoDraw</strong>
      plugins directory (<code>~/.jaxodraw/$VERSION/plugins/</code>).
    </p>
    <p>
      Have a look at the pdf plugin for a realistic example where a
      custom pdf viewer may be stored in a property.
    </p>
  </subsection>

  <subsection name="Compilation and packaging">
    <p>
      To compile the plugin you have to add a <strong>JaxoDraw</strong> jar
      to your classpath, and don't forget to bundle up any resource files
      (language properties) in your jar.
    </p>
    <p>
      You may check the
      <a href="http://jaxodraw.svn.sourceforge.net/svnroot/jaxodraw/trunk/plugins/">source code</a>
      of the available plugins for some realistic examples.
    </p>
  </subsection>

  </section>

  </body>

</document>
