Scripting environment setup

Modern Integrated Development Environments like Eclipse or Idea make it much easier to edit Groovy scripts for Freeplane as in a normal text editor. Syntax highlighting, code completion, error detection, debugging and source navigation are extremely useful especially if you are not that experienced.

But it's more or less difficult for beginners to setup an IDE properly for Groovy scripting, so here's a step-by-step guide:

Installations

• First download and install a Java Development Kit (JDK) -if you don't have it. There is a hyperlink on the Eclipse download page.
• Then download and install a "Eclipse IDE for Java Developers" or "Eclipse for RCP and RAP Developers" (the latter is more useful for regular Freeplane developers) from Eclipse download page. Read how to unpack here (N.B. for Windows 7 it is not possible to unpack directly into c:/Program Files; no warning is given !)
• Launch Eclipse for the first time and select some directory as your workspace root

• Install the Groovy-Eclipse plugin.
• Close Eclipse

Setup workspace

Install freeplane_bin

1. Download the current Freeplane binary distribution (e.g. freeplane-1.2.13.zip) and unpack it into the selected workspace
2. Rename the latter directory into freeplane_bin and make sure this directory is in the workspace.

On the command line (Linux/Unix/Mac):

   cd <workspace> # your selected workspace, like ~/freeplanescripts
   unzip freeplane_bin-1.2.13.zip
   mv freeplane-1.2.13 freeplane_bin

Install freeplane_src

Download matching Freeplane source distribution (e.g. freeplane_src-1.2.13.tar.gz) and unpack it into the selected workspace. Unpacking this archive may require an additional program like 7zip, jzip or winzip on Windows (check by trying to open the file in the Explorer). Unpacking may need two steps:

1. In a program like 7zip open the archive freeplane_src-1.2.13.tar.gz. Most unpackers will allow directly extract into a directory, but jzip creates an intermediate freeplane_src-1.2.13.tar file
2. Rename freeplane-1.2.13 into freeplane_src and make sure this directory is in the workspace.

On the command line (Linux/Unix/Mac):

   cd <workspace> # your selected workspace, like ~/freeplanescripts
   tar -xzvf freeplane_src-1.2.13.tar.gz
   mv freeplane-1.2.13 freeplane_src

Install groovy support

Freeplane's regular script directory <freeplaneuserdir>/scripts will be the script project directory where script development happens. To add special support for Freeplane scripting you have to copy the file freeplane_bin/scripts/freeplane.dsld to the script directory. On the command line (assuming that ~/.freeplane/1.2.x/scripts is Freeplane's script directory; Linux/Unix/Mac):

   cd <workspace> # your selected workspace, like ~/freeplanescripts
   cp ./freeplane_bin/scripts/freeplane.dsld ~/.freeplane/1.2.x/scripts

Create projects

Create a Java Project for the Freeplane binaries

2. Set the project name to the name of the folder containing the Freeplane binaries

3. Allow scripts access to the Freeplane libraries

Create a Groovy Project for the scripts

2. Set the project name to the name of the folder containing the scripts

3. Connect the scripts with the Freeplane libraries.

4. Select a different build output folder. Otherwise a lot of .class files would pollute the scripts directory. This is not required but helpful.

Connect the scripts with the Freeplane source files

1. Type Shift+Ctrl+T ("Open Type") and enter "freeeplanescript" to open the class FreeplaneScriptBaseClass.

2. The source for the class can not be found. Click on "Attach source", then "External folder" and browse to the freeplane_src directory in the workspace

and click OK. The source of the class is shown now.

Using Eclipse

Edit a script

Code completion and quickfixes

Eclipse helps you quite a lot in avoiding and fixing errors. Here are some examples.

Let's assume that you have created a class in a file Hello.groovy that you want to use in another script: <groovy> package hellopackage

class Hello {

   def hello() {
       c.statusInfo = "Hello world!"
   }

} </groovy>

When we want to use class Hello we have to consider that it is defined in the package "hellopackage". Let's use Eclipse' editing aids to use it: After entering def hello = new hell hit Ctrl+Space

You will see that there is an error since the required "import hellopackage" is unfortunately not added automatically (as it is for imported Java classes). But the small red "x" indicates that a "Quick fix" is available which you can select either by clicking on the "x" or by hitting Ctrl+1

After selecting the first suggestion by hitting Enter you will be done:

My tip: Test what happens if you type Ctrl+Space whenever you think that Eclipse might have an idea what you are about to type. The idea is: You do the creative work and and Eclipse cares for the tedious details of exact naming and locating objects.

Magic keys

• ALT+Space
  • Initiates content assist, completes typed texts.
  • Import declarations for completed types are automatically added.
  • Example: type "str" (without the quotes) and hit ALT space.
• F3
  • Navigates to the definition of the variable/class under the cursor.
  • This also works for Java and Freeplane classes - allowes to lookup details of the class.
• ALT+Cursor_Left
  • Navigates to the last remembered location.
• Shift+Ctrl+T
  • Open a type (e.g. a class or interface).
  • Try entering "proxy" and select the Proxy from org.freeplane.plugin.script.proxy
  • Proxy is the API definition.
• Shift+Ctrl+R
  • Use this to open a script
• Ctrl+1
  • Quickfix

Making available groovy classes to your mind map

If in Eclipse you define and run Hello.groovy, Eclipse compiles and saves it as Hello.class in the build output folder you specified above. If you supplied a package name in the script e.g. package hellopackage, this name is used as a subdirectory, hellopackage/Hello.class. If you used the default (which it advised for scripts), it is just Hello.class.

• Open Freeplane and open Tools > Preferences > Plugins.

On the last row add the path to Eclipse' build output folder:

• If you followed the procedure above the build output folder is scripts/bin in the Freeplane user directory. In this case enter scripts/bin.
• If you have choosen some other directory (e.g. in the Eclipse workspace) you have to specify the full path.

In Windows 7 with non-English localization this has the following complication: Suppose the full path of the build output folder is shown in a Dutch Windows 7 as C:/Gebruikers/Beheerder/workspaceFP/scripts/bin then the script class path must be C:\Users\Beheerder\workspaceFP\scripts\bin since Windows 7 translates the real path C:\Users to Dutch C:\Beheerder. Furthermore note that all slashes MUST BE backslashes on Windows. You could avoid these complications by using the Freeplane script directory directly in Eclipse as described above.

• To take effect, restart Freeplane. (In case of problems, check the log file if Freeplane did could install the path).