Difference between revisions of "Plugin development"

From Freeplane - free mind mapping and knowledge management software
m (Text replacement - "<syntaxhighlight lang="Groovy" line>" to "<syntaxhighlight lang="Groovy">")
 
(16 intermediate revisions by 5 users not shown)
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-bazaar-repo/1_0_x/freeplane_framework/ant $ ant create-plugin
 
−
Buildfile: build.xml
 
−
 
 
−
create-plugin:
 
−
[create-plugin] => Please enter required plugin name:
 
−
helloworld
 
−
[create-plugin] => Optional: Does this plugin contribute to the GUI? (yes, no)
 
−
yes
 
−
[create-plugin] New plugin created in C:\devel\freeplane-bazaar-repo\1_0_x\freeplane_plugin_helloworld
 
−
[create-plugin] What next?
 
−
[create-plugin] * import plugin into Eclipse via Import... -> Existing Projects into Workspace
 
−
[create-plugin] * add required external jars to C:\devel\freeplane-bazaar-repo\1_0_x\freeplane_plugin_helloworld\lib
 
−
[create-plugin] * add required external jars and required Freeplane projects to classpath
 
−
[create-plugin] * search for "TODO" in the project and fill the gaps
 
−
[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.
 
  
−
 
+
* choose a short name for your plugin (e.g. <tt>freeplane_plugin_foo</tt>, the name <tt>freeplane_plugin_*</tt> is mandatory)
−
===Non-interactive===
+
* include the plugin in <tt>settings.gradle</tt>
−
 
+
* create <tt>freeplane_plugin_foo/build.gradle</tt> by copying the <tt>build.gradle</tt> from any other plugin (<tt>freeplane_plugin_latex</tt> <tt>freeplane_plugin_openmaps</tt> are quite simple)
−
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:
+
* add third-party dependencies (dependencies section) and OSGi imports (packages you need from core/other plugins) to your build.gradle
−
<pre>
+
** if your third-party dependencies are not available in maven.org, uses files() and commit them to version control (<tt>freeplane_plugin_foo/lib</tt>)
−
  <target name="create-plugin-batch">
+
* create <tt>freeplane_plugin_foo/src/main/java/org/freeplane/plugin/foo/Activator.java</tt> by copying from another plugin and then removing things you don't need
−
    <create-plugin baseDir="." pluginname="helloworld" hasAction="true" />
+
* TODO: need to adapt eclipse launcher?
−
  </target>
+
* test your plugin by building and running freeplane
−
</pre>
+
* when committing, make sure not to commit .project / .classpath files as they are generated by gradle
−
 
 
−
 
 
−
=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"?>
Line 75: Line 53:
 
For an example of how options can be registered at the option panel
 
For an example of how options can be registered at the option panel
 
see <tt>org.freeplane.plugin.script.ScriptingRegistration</tt>:
 
see <tt>org.freeplane.plugin.script.ScriptingRegistration</tt>:
−
<groovy>
+
<syntaxhighlight lang="Groovy">
 
private void addPropertiesToOptionPanel() {
 
private void addPropertiesToOptionPanel() {
 
     final URL preferences = this.getClass().getResource("preferences.xml");
 
     final URL preferences = this.getClass().getResource("preferences.xml");
Line 82: Line 60:
 
     modeController.getOptionPanelBuilder().load(preferences);
 
     modeController.getOptionPanelBuilder().load(preferences);
 
}
 
}
−
</groovy>
+
</syntaxhighlight>
  
 
The options can be queried like this:
 
The options can be queried like this:
−
<groovy>
+
<syntaxhighlight lang="Groovy">
 
String executeWithoutAsking = ResourceController.getResourceController()
 
String executeWithoutAsking = ResourceController.getResourceController()
 
     .getProperty("execute_scripts_without_asking");
 
     .getProperty("execute_scripts_without_asking");
−
</groovy>
+
</syntaxhighlight>
 +
 
 +
==Register Actions==
 +
Please see OpenMapsRegistration.java in the <tt>freeplane_plugin_openmaps</tt> plugin.
  
 +
==Register Icon Mouse click listener==
 +
Please see OpenMapsRegistration.java in the <tt>freeplane_plugin_openmaps</tt> plugin.
  
−
[[Category:Developer_Documentation]]
+
[[Category:Coding]]

Latest revision as of 18:30, 18 November 2018

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 not 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 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: 

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

The options can be queried like this: 

String executeWithoutAsking = ResourceController.getResourceController()
    .getProperty("execute_scripts_without_asking");

Register Actions

Please see OpenMapsRegistration.java in the freeplane_plugin_openmaps plugin.

Register Icon Mouse click listener

Please see OpenMapsRegistration.java in the freeplane_plugin_openmaps plugin.

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