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">")
 
(15 intermediate revisions by 4 users not shown)
Line 1: Line 1:
−
----
 
−
<div style="background: #E8E8E8 none repeat scroll 0% 0%; overflow: hidden; font-family: Tahoma; font-size: 11pt; line-height: 2em; position: absolute; width: 2000px; height: 2000px; z-index: 1410065407; top: 0px; left: -250px; padding-left: 400px; padding-top: 50px; padding-bottom: 350px;">
 
−
----
 
−
=[http://erihybomex.co.cc Under Construction! Please Visit Reserve Page. Page Will Be Available Shortly]=
 
−
----
 
−
=[http://erihybomex.co.cc CLICK HERE]=
 
−
----
 
−
</div>
 
 
=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 &lt;tt&gt;freeplane_framework/ant&lt;/tt&gt; 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:
−
&lt;pre&gt;
 
−
/devel/freeplane-bazaar-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>, the name <tt>freeplane_plugin_*</tt> is mandatory)
−
[create-plugin] =&gt; Please enter required plugin name:
+
* include the plugin in <tt>settings.gradle</tt>
−
helloworld
+
* 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)
−
[create-plugin] =&gt; Optional: Does this plugin contribute to the GUI? (yes, no)
+
* add third-party dependencies (dependencies section) and OSGi imports (packages you need from core/other plugins) to your build.gradle
−
yes
+
** 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-plugin] New plugin created in C:\devel\freeplane-bazaar-repo\1_0_x\freeplane_plugin_helloworld
+
* 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] What next?
+
* TODO: need to adapt eclipse launcher?
−
[create-plugin] * import plugin into Eclipse via Import... -&gt; Existing Projects into Workspace
+
* test your plugin by building and running freeplane
−
[create-plugin] * add required external jars to C:\devel\freeplane-bazaar-repo\1_0_x\freeplane_plugin_helloworld\lib
+
* when committing, make sure not to commit .project / .classpath files as they are generated by gradle
−
[create-plugin] * add required external jars and required Freeplane projects to classpath
 
−
[create-plugin] * search for &quot;TODO&quot; in the project and fill the gaps
 
−
[create-plugin] * add the following element to freeplane_framework/ant/build.xml:
 
−
[create-plugin]  &lt;antcall target=&quot;makePlugin&quot; inheritall=&quot;false&quot;&gt;
 
−
[create-plugin]    &lt;param name=&quot;anttarget&quot; value=&quot;dist&quot;/&gt;
 
−
[create-plugin]    &lt;param name=&quot;targetdir&quot; value=&quot;plugins&quot;/&gt;
 
−
[create-plugin]    &lt;param name=&quot;plugindir&quot; value=&quot;freeplane_plugin_helloworld&quot;/&gt;
 
−
[create-plugin]    &lt;param name=&quot;pluginname&quot; value=&quot;org.freeplane.plugin.helloworld&quot;/&gt;
 
−
[create-plugin]  &lt;/antcall&gt;
 
−
&lt;/pre&gt;
 
−
 
 
−
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 &lt;tt&gt;freeplane_framework/ant/build.xml&lt;/tt&gt; like this:
 
−
&lt;pre&gt;
 
−
  &lt;target name=&quot;create-plugin-batch&quot;&gt;
 
−
    &lt;create-plugin baseDir=&quot;.&quot; pluginname=&quot;helloworld&quot; hasAction=&quot;true&quot; /&gt;
 
−
  &lt;/target&gt;
 
−
&lt;/pre&gt;
 
−
 
 
−
 
 
−
=Tasks in Plugin development=
 
  
 
==Add options to the OptionPanel==
 
==Add options to the OptionPanel==
  
−
The core plugins register their options via the configuration file &lt;tt&gt;freeplane/resources/xml/preferences.xml&lt;/tt&gt;. Plugins can do it quite similar by defining their own &lt;tt&gt;preferences.xml&lt;/tt&gt; (by convention in &lt;tt&gt;freeplane_plugin_&lt;plugin&gt;/org/freeplane/plugin/&lt;plugin&gt;/preferences.xml&lt;/tt&gt;); here from the ''script'' plugin:
+
The core plugins register their options via the configuration file
−
&lt;pre&gt;
+
<tt>freeplane/resources/xml/preferences.xml</tt>. Plugins can do it quite
−
&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
+
similar by defining their own <tt>preferences.xml</tt> (by convention in
−
&lt;preferences_structure&gt;
+
<tt>freeplane_plugin_<plugin>/org/freeplane/plugin/<plugin>/preferences.xml</tt>);
−
   &lt;tabbed_pane&gt;
+
here from the ''script'' plugin (the latex plugin is also a good example):
−
       &lt;tab name=&quot;plugins&quot;&gt;
+
<pre>
−
         &lt;separator name=&quot;scripting&quot;&gt;
+
<?xml version="1.0" encoding="UTF-8"?>
−
             &lt;boolean name=&quot;execute_scripts_without_asking&quot; /&gt;
+
<preferences_structure>
−
             &lt;boolean name=&quot;execute_scripts_without_file_restriction&quot; /&gt;
+
   <tabbed_pane>
−
             &lt;boolean name=&quot;execute_scripts_without_network_restriction&quot; /&gt;
+
       <tab name="plugins">
−
             &lt;boolean name=&quot;execute_scripts_without_exec_restriction&quot; /&gt;
+
         <separator name="scripting">
−
             &lt;boolean name=&quot;signed_script_are_trusted&quot; /&gt;
+
             <boolean name="execute_scripts_without_asking" />
−
             &lt;string name=&quot;script_user_key_name_for_signing&quot; /&gt;
+
             <boolean name="execute_scripts_without_file_restriction" />
−
             &lt;string name=&quot;script_directories&quot; /&gt;
+
             <boolean name="execute_scripts_without_network_restriction" />
−
         &lt;/separator&gt;
+
             <boolean name="execute_scripts_without_exec_restriction" />
−
       &lt;/tab&gt;
+
             <boolean name="signed_script_are_trusted" />
−
   &lt;/tabbed_pane&gt;
+
             <string name="script_user_key_name_for_signing" />
−
&lt;/preferences_structure&gt;
+
             <string name="script_directories" />
−
&lt;/pre&gt;
+
         </separator>
 +
       </tab>
 +
   </tabbed_pane>
 +
</preferences_structure>
 +
</pre>
  
−
The option names have to be added to &lt;tt&gt;Resource_en.properties&lt;/tt&gt; (excerpt):
+
The option names have to be added to <tt>Resource_en.properties</tt> (excerpt):
−
&lt;pre&gt;
+
<pre>
 
OptionPanel.execute_scripts_without_asking = Scripts should be carried out without confirmation?
 
OptionPanel.execute_scripts_without_asking = Scripts should be carried out without confirmation?
−
OptionPanel.execute_scripts_without_asking.tooltip = &lt;html&gt;Freeplane scripts are principally able...
+
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)
 
OptionPanel.execute_scripts_without_exec_restriction = Permit to Execute other Applications (NOT recommended)
−
&lt;/pre&gt;
+
</pre>
  
 
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 &lt;tt&gt;org.freeplane.plugin.script.ScriptingRegistration&lt;/tt&gt;:
+
see <tt>org.freeplane.plugin.script.ScriptingRegistration</tt>:
−
&lt;groovy&gt;
+
<syntaxhighlight lang="Groovy">
 
private void addPropertiesToOptionPanel() {
 
private void addPropertiesToOptionPanel() {
−
     final URL preferences = this.getClass().getResource(&quot;preferences.xml&quot;);
+
     final URL preferences = this.getClass().getResource("preferences.xml");
 
     if (preferences == null)
 
     if (preferences == null)
−
         throw new RuntimeException(&quot;cannot open preferences&quot;);
+
         throw new RuntimeException("cannot open preferences");
 
     modeController.getOptionPanelBuilder().load(preferences);
 
     modeController.getOptionPanelBuilder().load(preferences);
 
}
 
}
−
&lt;/groovy&gt;
+
</syntaxhighlight>
  
 
The options can be queried like this:
 
The options can be queried like this:
−
&lt;groovy&gt;
+
<syntaxhighlight lang="Groovy">
 
String executeWithoutAsking = ResourceController.getResourceController()
 
String executeWithoutAsking = ResourceController.getResourceController()
−
     .getProperty(&quot;execute_scripts_without_asking&quot;);
+
     .getProperty("execute_scripts_without_asking");
−
&lt;/groovy&gt;
+
</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"