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">")
 
(18 intermediate revisions by 6 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:
 +
 
 +
* choose a short name for your plugin (e.g. <tt>freeplane_plugin_foo</tt>, the name <tt>freeplane_plugin_*</tt> is mandatory)
 +
* 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)
 +
* 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 (<tt>freeplane_plugin_foo/lib</tt>)
 +
* 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
 +
* 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
 +
<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>
−
/devel/freeplane-bazaar-repo/1_0_x/freeplane_framework/ant $ ant create-plugin
+
<?xml version="1.0" encoding="UTF-8"?>
−
Buildfile: build.xml
+
<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>
 +
</pre>
  
−
create-plugin:
+
The option names have to be added to <tt>Resource_en.properties</tt> (excerpt):
−
[create-plugin] => Please enter required plugin name:
+
<pre>
−
helloworld
+
OptionPanel.execute_scripts_without_asking = Scripts should be carried out without confirmation?
−
[create-plugin] => Optional: Does this plugin contribute to the GUI? (yes, no)
+
OptionPanel.execute_scripts_without_asking.tooltip = <html>Freeplane scripts are principally able...
−
yes
+
OptionPanel.execute_scripts_without_exec_restriction = Permit to Execute other Applications (NOT recommended)
−
[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>
 
</pre>
  
−
Follow the suggestions in the printed message.
+
For an example of how options can be registered at the option panel
−
 
+
see <tt>org.freeplane.plugin.script.ScriptingRegistration</tt>:
 +
<syntaxhighlight lang="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);
 +
}
 +
</syntaxhighlight>
  
−
===Non-interactive===
+
The options can be queried like this:
 +
<syntaxhighlight lang="Groovy">
 +
String executeWithoutAsking = ResourceController.getResourceController()
 +
    .getProperty("execute_scripts_without_asking");
 +
</syntaxhighlight>
  
−
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:
+
==Register Actions==
−
<pre>
+
Please see OpenMapsRegistration.java in the <tt>freeplane_plugin_openmaps</tt> plugin.
−
  <target name="create-plugin-batch">
 
−
    <create-plugin baseDir="." pluginname="helloworld" hasAction="true" />
 
−
  </target>
 
−
</pre>
 
  
 +
==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"