Difference between revisions of "Plugin development"

From Freeplane - free mind mapping and knowledge management software
m (→‎Interactive)
(deprecate "ant create-plugin", describe how to add plugins with gradle)
Line 1: Line 1:
 
=Create a new Plugin=
 
=Create a new Plugin=
  
−
A simple tool helps to get started with the development of plugins. It's an Ant Task named 'create-plugin' that is available from the <tt>freeplane_framework/ant</tt> directory.
+
With the introduction of the gradle build system (Freeplane >= 1.4.1), the
 +
"create-plugin" ant task is deprecated because adding plugins "manually"
 +
has become very simple using gradle.
  
−
===Interactive===
+
==Steps==
−
The task reads all required parameters from the command line by default. The following transcript shows input and output of a ''create-plugin'' invocation (Windows/Cygwin):
+
Here are the steps you need to perform:
−
<pre>
 
−
/devel/freeplane-repo/1_0_x/freeplane_framework/ant $ ant create-plugin
 
−
Buildfile: build.xml
 
  
−
create-plugin:
+
* choose a short name for your plugin (e.g. <tt>freeplane_plugin_foo</tt>)
−
[create-plugin] => Please enter required plugin name:
+
  (the name <tt>freeplane_plugin_*</tt> is mandatory)
−
helloworld
+
* include the plugin in <tt>settings.gradle</tt>
−
[create-plugin] => Optional: Does this plugin contribute to the GUI? (yes, no)
+
* create <tt>freeplane_plugin_foo/build.gradle</tt> by copying the <tt>build.gradle</tt>
−
yes
+
  from any other plugin (<tt>freeplane_plugin_latex</tt> <tt>freeplane_plugin_openmaps</tt> are quite simple)
−
[create-plugin] New plugin created in C:\devel\freeplane-repo\1_0_x\freeplane_plugin_helloworld
+
* add third-party dependencies (dependencies section) and OSGi imports (packages you need from core/other plugins) to your build.gradle
−
[create-plugin] What next?
+
** if your third-party dependencies are no available in maven.org, uses files() and commit them to version control (<tt>freeplane_plugin_foo/lib</tt>)
−
[create-plugin] * import plugin into Eclipse via Import... -> Existing Projects into Workspace
+
* create <tt>freeplane_plugin_foo/src/main/java/org/freeplane/plugin/foo/Activator.java</tt> either by copying from another plugin and then removing things you don't need
−
[create-plugin] * add required external jars to C:\devel\freeplane-repo\1_0_x\freeplane_plugin_helloworld\lib
+
* TODO: need to adapt eclipse launcher?
−
[create-plugin] * add required external jars and required Freeplane projects to classpath
+
* test your plugin by building and running freeplane
−
[create-plugin] * search for "TODO" in the project and fill the gaps
+
* when committing, make sure not to commit .project / .classpath files as they are generated by gradle
−
[create-plugin] * add the following element to freeplane_framework/ant/build.xml:
 
−
[create-plugin]  <antcall target="makePlugin" inheritall="false">
 
−
[create-plugin]    <param name="anttarget" value="dist"/>
 
−
[create-plugin]    <param name="targetdir" value="plugins"/>
 
−
[create-plugin]    <param name="plugindir" value="freeplane_plugin_helloworld"/>
 
−
[create-plugin]    <param name="pluginname" value="org.freeplane.plugin.helloworld"/>
 
−
[create-plugin]  </antcall>
 
−
</pre>
 
−
 
 
−
Follow the suggestions in the printed message.
 
−
 
 
−
===Non-interactive===
 
−
 
 
−
If you want to do it non-interactively instead you have to create your own (temporary) Ant task in <tt>freeplane_framework/ant/build.xml</tt> like this:
 
−
<pre>
 
−
  <target name="create-plugin-batch">
 
−
    <create-plugin baseDir="." pluginname="helloworld" hasAction="true" />
 
−
  </target>
 
−
</pre>
 
−
 
 
−
 
 
−
=Tasks in Plugin development=
 
  
 
==Add options to the OptionPanel==
 
==Add options to the OptionPanel==
  
−
The core plugins register their options via the configuration file <tt>freeplane/resources/xml/preferences.xml</tt>. Plugins can do it quite similar by defining their own <tt>preferences.xml</tt> (by convention in <tt>freeplane_plugin_<plugin>/org/freeplane/plugin/<plugin>/preferences.xml</tt>); here from the ''script'' plugin:
+
The core plugins register their options via the configuration file
 +
<tt>freeplane/resources/xml/preferences.xml</tt>. Plugins can do it quite
 +
similar by defining their own <tt>preferences.xml</tt> (by convention in
 +
<tt>freeplane_plugin_<plugin>/org/freeplane/plugin/<plugin>/preferences.xml</tt>);
 +
here from the ''script'' plugin (the latex plugin is also a good example):
 
<pre>
 
<pre>
 
<?xml version="1.0" encoding="UTF-8"?>
 
<?xml version="1.0" encoding="UTF-8"?>

Revision as of 19:01, 13 January 2015

Create a new Plugin

With the introduction of the gradle build system (Freeplane >= 1.4.1), the "create-plugin" ant task is deprecated because adding plugins "manually" has become very simple using gradle.

Steps

Here are the steps you need to perform:

  • choose a short name for your plugin (e.g. freeplane_plugin_foo)
 (the name freeplane_plugin_* is mandatory)
  • include the plugin in settings.gradle
  • create freeplane_plugin_foo/build.gradle by copying the build.gradle
 from any other plugin (freeplane_plugin_latex freeplane_plugin_openmaps are quite simple)
  • add third-party dependencies (dependencies section) and OSGi imports (packages you need from core/other plugins) to your build.gradle
    • if your third-party dependencies are no available in maven.org, uses files() and commit them to version control (freeplane_plugin_foo/lib)
  • create freeplane_plugin_foo/src/main/java/org/freeplane/plugin/foo/Activator.java either by copying from another plugin and then removing things you don't need
  • TODO: need to adapt eclipse launcher?
  • test your plugin by building and running freeplane
  • when committing, make sure not to commit .project / .classpath files as they are generated by gradle

Add options to the OptionPanel

The core plugins register their options via the configuration file freeplane/resources/xml/preferences.xml. Plugins can do it quite similar by defining their own preferences.xml (by convention in freeplane_plugin_<plugin>/org/freeplane/plugin/<plugin>/preferences.xml); here from the script plugin (the latex plugin is also a good example): 

<?xml version="1.0" encoding="UTF-8"?>
<preferences_structure>
   <tabbed_pane>
      <tab name="plugins">
         <separator name="scripting">
            <boolean name="execute_scripts_without_asking" />
            <boolean name="execute_scripts_without_file_restriction" />
            <boolean name="execute_scripts_without_network_restriction" />
            <boolean name="execute_scripts_without_exec_restriction" />
            <boolean name="signed_script_are_trusted" />
            <string name="script_user_key_name_for_signing" />
            <string name="script_directories" />
         </separator>
      </tab>
   </tabbed_pane>
</preferences_structure>

The option names have to be added to Resource_en.properties (excerpt): 

OptionPanel.execute_scripts_without_asking = Scripts should be carried out without confirmation?
OptionPanel.execute_scripts_without_asking.tooltip = <html>Freeplane scripts are principally able...
OptionPanel.execute_scripts_without_exec_restriction = Permit to Execute other Applications (NOT recommended)

For an example of how options can be registered at the option panel see org.freeplane.plugin.script.ScriptingRegistration: <groovy> private void addPropertiesToOptionPanel() { 

   final URL preferences = this.getClass().getResource("preferences.xml");
   if (preferences == null)
       throw new RuntimeException("cannot open preferences");
   modeController.getOptionPanelBuilder().load(preferences);

} </groovy>

The options can be queried like this: <groovy> String executeWithoutAsking = ResourceController.getResourceController() 

   .getProperty("execute_scripts_without_asking");

</groovy>

Retrieved from "https://www.freeplane.org/oldwiki/index.php?title=Plugin_development&oldid=5509"