Difference between revisions of "Scripting"

Latest revision as of 10:47, 21 November 2020

Freeplane's builtin functionality can be extended by Groovy and JavaScript scripts. Starting with Freeplane 1.3.5_05 you can use many other languages, e.g Python. This page gives a first impression what you can do with Groovy scripting and helps to get started.

With Freeplane scripting you can

write your own functions and use them from the menu or via keyboard shortcuts,
use formulas in your map to compute stuff like in Excel, and
create add-ons to share it with other users,
have init scripts executed on startup that changes Freeplane's behavior (since Freeplane 1.5).

Most people use scripting to automate otherwise tedious procedures like creating a node with a special style and some standard attributes. But much more is possible with scripting.

External Groovy scripts can be integrated simply by placing them in the scripts subdirectory of the Freeplane homedir. Such scripts can be used like any other built-in function of Freeplane.

After some preparation we'll create the first script.

Preparation

A newly installed Freeplane installation is almost ready for scripting:

The scripts directory is created in the User Configuration Folder which you can open via Tools > Open user directory. It's empty, initially.
This directory is automatically searched for ".groovy" files on startup.
Scripting is disabled by default, but we'll fix that in a minute.

First create a new mindmap with this content (just copy 'n paste it into a new map):

test
  numbers
    1
    2
    3
  text
  text
  text ok
  text okay

Then add some icons to the map - no matter how many and which icons. But we'll need them later.

Select an editor

You will need a text editor. For the first steps presented on this page any editor will do, such as Notepad on Windows (though the free Notepad++is much better), Sublime Text or TextEdit on Mac OS X. You can find an overview of editors with Groovy support on Stackoverflow and on the Groovy website.

Freeplane also has a small script editor built into it. It is reached through Tools->Edit Script. You can run the scripts directly in the editor and store them as attributes of the node you are working in. But such map local scripts are most useful for quick tests since you can not write the scripts directly to ".groovy" files.

For ambitious scripting projects or if you have Java/Eclipse know-how you should have a look at the page on Scripting environment setup.

The first script: HelloWorld.groovy

"Hello World" is the traditional first program when taking up a programming language. Let's create a Groovy Freeplane version of it:

Create an empty Groovy script file named HelloWorld.groovy in your scripts directory (remember that you can get there via Tools > Open user directory). The suffix .groovy is mandatory.
Open HelloWorld.groovy in an appropriate editor as detailed above.
Copy the following script into the file and save it.

node.text = "Hello World!"

Now save your script in the editor and restart Freeplane since Freeplane will only find new scripts after a restart. Then you will find your new script in the Freeplane menu location Tools->Scripts->Hello World. You see three sub menus Execute on one selected node, Execute on all selected nodes and Execute on all selected nodes, recursively. [Note: starting with FP version 1.5 there is no sub menu anymore. The execution mode is shown on mouse hover over the menu entry]
At Tools->Preferences->Plugins->Scripting
- set Script execution enabled to Yes
- enable Permit File/Read Operations (NOT recommended) - despite the warning.
These changes take effect without restarting Freeplane and only need to be done once. For more details see Scripting: Security considerations.
Execute the script by selecting Tools->Scripts->Hello World->Execute on one selected node. (Never mind the difference between the Execute ... variants; we'll come to that later.)
The text of the selected node will be changed to "Hello World!".
To restore the original, press Ctrl-Z.
If you like try the other "Execute..." menu items. Test the influence of selecting multiple nodes. Always press Ctrl-Z to revert the changes.

Hello Controller

Every script is given the variables

node	set to the currently selected node
c	tool box for various tasks relating to the map or Freeplane altogether

These give access to the two most important bits of a map. In HelloWorld we used node, which gave access to the selected node.

Now we'll change HelloWorld.groovy to use the second, the Controller variable c:

Copy the following script into the file and save it:

c.statusInfo = "Hello World!"

Execute the script by selecting Tools->Scripts->Hello World->Execute on one selected node.

The "Controller" manages the status bar. By assigning "Hello World!" to the Controller attribute "statusInfo" we are able to print text to the status bar.

The scripting API

The variables node and c are "objects" with a list of attributes (like "text", "details" or "style") and methods that operate on the object, like "addConnector()", "createChild()" or "moveTo()". The "type" of the object decides on the list of attribute of attributes and methods an object has. "node" is of type Proxy.Node while "c" has the type Proxy.Controller.

To get started with Freeplane scripting you have to get slowly accustomed to the Groovy syntax and the Freeplane specialities too. The types and objects that Freeplane supports are defined by Freeplane's scripting API. You can learn it step by step: Very little is required to write useful scripts.

An important resource is the built-in scripting documentation that is available via Help->Scripting API. Open it now and search for the statusInfo attribute at Scripting API->Proxy->Controller->statusInfo: String (w). The text means: The Controller has an attribute statusInfo that only can be written to (w), that is you can't find out what is currently displayed on the status bar. The attribute has type String (either use "double quotes" or 'single quotes'). If you unfold the node you see void setStatusInfo(String). That means that

c.statusInfo = 'Hello World!'

and

c.setStatusInfo('Hello World!')

are equivalent. But the first "attribute" style is preferable since it is clearer. The clickable links in the "Scripting API" map carry to the respective location in the detailed API description which might be a bit overwhelming at this point.

Setting links

In the "Scripting API" map, near to statusInfo you find the userDirectory attribute. You can use it to add a link to this directory to your map. Create a new script file addLink.groovy in the script directory with the following content:

node.link.file = c.userDirectory

Here an slightly extended version that adds an external link to the selected node(s) and creates a node with a local link back to its parent node:

node.link.text = 'http://freeplane.org/wiki/index.php?title=Scripting'

This script creates a local link back to its parent node:

node.link.node = node.parent

In the next section we'll see what the "@ExecutionModes" line is about.

Execution modes

For each script we had three submenu entries of "Hello World". These entries are different with respect to multiple selected nodes:

In the case of Execute on one selected node a script is executed only once no matter how many nodes are selected. It's best to be used when only a single node is selected since in this case the node variable of the script is set to the selected node. If multiple nodes are selected then node is set to one of the nodes arbitrarily. That is, you shouldn't count on the selection if multiple nodes are selected.
With Execute on all selected nodes it is called once for each selected node (with node set to the respective node) and with
Execute on all selected nodes, recursively the selection will be implicitly extended by all child trees of the selected nodes.

If we chose Execute on all selected nodes for the first version of "Hello World" then the text of all selected nodes changed. - Probably what you expect. By adding the line

// @ExecutionModes({ON_SELECTED_NODE})

all other choices would be suppressed.

The second "Hello World" version printed to the status bar. This only has to happen once so here Execute on one selected node is the right choice and we have to add the line

// @ExecutionModes({ON_SINGLE_NODE})

It's a good idea to put the "annotations" at the beginning of the script. (In section Simple text replacement we will see an exception.) ON_SELECTED_NODE_RECURSIVELY applies a script on any node in the branch that has a selected node as root. You can also enable more than one mode by concatening them with commas:

// @ExecutionModes({ON_SELECTED_NODE, ON_SELECTED_NODE_RECURSIVELY})

Note that for Groovy this is a comment. - This line is only interpreted by Freeplane. Omitting the // will result in a Groovy compilation error.

Menu locations

Scripts can determine to which menu or submenu a script will be added. Even the menu title can be set (although the standard file name to menu title translation should be enough in most cases):

// @ExecutionModes({on_single_node="/menu_bar/help[scripting_api_generator_title]"})

You can find out about the internal menu keys using the Developer Tools > Menu item info.

Per node execution: addIcon.groovy

Now let's use the node variable again in our next script, addIcon.groovy (restart Freeplane to see it in the menu). This script will add the "button_ok" icon to any selected node:

node.icons.add("button_ok")
// @ExecutionModes({ON_SELECTED_NODE})

This will add the "check" icon to each selected node. Hopefully it's clear that the execution mode Execute on one selected node makes no sense in this case. So let's remove this from the "Extra" menu:

// @ExecutionModes({ON_SELECTED_NODE, ON_SELECTED_NODE_RECURSIVELY})
node.icons.add("button_ok")

(To see the change in the menu you have to restart Freeplane.)

We will extend this script now a little further to only set the icon if the node text contains the words "yes" or "OK" (case insensitively):

// @ExecutionModes({ON_SELECTED_NODE, ON_SELECTED_NODE_RECURSIVELY})
if (node.text.toLowerCase().matches(".*\\b(yes|ok)\\b.*"))
    node.icons.add("button_ok")

Note that node.text makes use of the special (compared to Java) attribute handling - see section On Groovy properties and the Scripting API.

The status bar again: getIconName.groovy

Finding the proper name of an icon may be a bit difficult. One way is to use the wanted icon in some map and to look it up in the sources. The XML for a node with an icon might look like that:

 <node TEXT="done" ID="ID_789648746" CREATED="1239285242562" MODIFIED="1242658193277">
   <icon BUILTIN="button_ok"/>
 </node>

This script writes the icon names of the selected node to the status bar:

c.statusInfo = "Icons: " + node.icons.icons

Note: For built-in icons, the icon name is the same as the corresponding graphic file name, that may be found here.

Formulas

Starting with Freeplane 1.2 one use scripts as Formulas directly in the node core like in Excel. Type this formula in the node core:

= "Icons: " + node.icons.icons

This will display the result of the formula instead of the formula itself.

Notes:

The equal sign has to be the very first character in the script.
On typing the equal sign as the first character a special script editor pops up which supports syntax highlighting.

Data parsing and formatting

TODO: add text

node.object = 40
def answer = node.to.num0 + 2

node.text = '2013-02-15'
c.statusInfo = node.to.date + 1

node.object = 42
node.format = '#.00'

c.statusInfo = format(42, '#.00').toString()

Navigation and iteration

Many useful scripts operate only on the current/selected node. But most scripts need to access multiple nodes. The scripting API provides methods for accessing special nodes:

node.parent - parent node
node.map.root - root of the map

For example this script prints the text of the parent node to the status bar:

c.statusInfo = node.parent.text

Other methods return node lists:

children - list of all children of a node, maybe empty
c.findAll() - all nodes of the map in breath first order
c.findDepthFirst() - all nodes of the map in depth first order
c.find(<closure>) - all nodes for which <closure> returns true.

The use of this methods requires some knowledge of Groovy collections.

Filtering

The most important concept is that of "closures", small code blocks that are used for filtering and modification of the element currently being iterated over. Let's start with filtering:

def matches = c.find{ it.text.contains('ok') }
c.statusInfo = matches.size() + " nodes contain 'ok'"

The method find has a closure argument which is applied to all nodes in the map. All nodes for which the closure returns true are returned as a new list which is assigned to the matches variable. In the closure the "current item" has a default name it. As c.find iterates over nodes it is a Node that has the attribute text which is a String that has a method contains() returning true if OK is contained somewhere in the text, like in "grok" or "it's ok".

Transformation

Many Groovy methods transform lists/collections into others:

def squares = children.collect{ it.to.num0 * it.to.num0 }

and others transform lists into single values:

def sumOfSquares = children.sum(0){ it.to.num0 * it.to.num0 }

When using sum() it's always a good idea to give it a start value since if the node had no children sumOfSquares would be null instead of 0.

Clones (since 1.5.5)

There are several methods to create clones of nodes and to act on the clones of a node. Note that cloning works symmetrically so we could better speak of shared nodes instead of clone and cloned since none of both is privileged. However each clone or shared node has a unique nodeId and may or not (depending on the share mode) have its own child nodes.

Add two clones of this node to the root node, one as single node, one including the branch starting at this node. Warning: before beta-1.5.5-pre03 appendAsCloneWithSubtree and appendAsCloneWithoutSubtree have reversed meaning!

def root = node.map.root
def lonelyClone = root.appendAsCloneWithoutSubtree(node)
def childWithSubtree = root.appendAsCloneWithSubtree(node)
// add nodes to the clones
lonelyClone.createChild('a child not shared')
childWithSubtree.createChild('a shared child')

Mark a node with yellow background color if it has any clone:

if (node.getCountNodesSharingContent() > 0)
    node.backgroundColorCode = '#ffff00'

Mark all nodes of a map having any clone:

c.find{ it.getCountNodesSharingContent() > 0 }.each {
    it.backgroundColorCode = '#ffff00'
}

If you should be interested in clones that share also the subtree (and not only the core properties) filter for countNodesSharingContentAndSubtree instead of countNodesSharingContent.

Add a connector from node to all of its clones using property-access instead of method (nodesSharingContent instead of getNodesSharingContent()):

node.nodesSharingContent.each { node.addConnectorTo(it) }

TODO: Tutorial ends here...

Appendix

Using external libraries

Some libraries are already included, but almost all other available Java libraries can be used. Place them in the lib directory in the <freeplane_userdir> which is already included in the "Script classpath" (see also Tools->Preferences->Plugins). All .class files and the content of all .jar files are automatically available in scripts and formulas.

Starting with Freeplane 1.3 utility scripts on the script classpath are compiled automatically.

You can also create your own utility script library.

The add-on scriptlib contains some libraries you can load and install. They include some node operations missing in the scripting API, file operations and a method to play audio with a hidden player.

On Groovy

Although Groovy is more or less a superset of Java it would be a shame not to use the new opportunities Groovy provides. On the other hand there are notable differences between Groovy and Ruby. In this section some of the differences between Java, Groovy and Ruby will be listed.

Using external libraries from groovy scripts and formulas

Freeplane 1.7.4 and later also support groovy annotation @grab to add required libraries to your scripts. It means you do not need to place your libraries in lib folder and they are downloaded and managed by groovy itself. The whole dependency management in Groovy scripts is documented at http://docs.groovy-lang.org/latest/html/documentation/grape.html .

The following example shows using a cvs parsing library from https://github.com/xlson/groovycsv available at maven central repository

@Grab('com.xlson.groovycsv:groovycsv:1.3')
import static com.xlson.groovycsv.CsvParser.parseCsv

def csv = '''Name,Lastname
Mark,Andersson
Pete,Hansen'''

def data = parseCsv(csv)
for(line in data) {
    node.createChild("$line.Name $line.Lastname")
}

On iteration

Groovy provides much improved ways to work on collections of data. This helps a lot in Freeplane scripting since most of the time you are working with collection of Node instances. From Java you might be used to this pattern:

  // NEVER do that in Freeplane scripting!!!
  for (i = 0; i < c.selecteds.size()-1; i++) {
    aNode = c.selecteds[i]
    aNode.text = "Do it groovy instead!"
  }

But this code is not even ineffective in Freeplane scripting (since every "c.selecteds" call creates a new list with new wrapped Node instances!) but it might even lead to errors since the list might change on the way. The following is better...

  // better, but still NOT GOOD
  def selected = c.selecteds
  for (i = 0; i < selected.size()-1; i++) {
    def aNode = selected[i]
    aNode.text = "Do it groovy instead!"
  }

Do yourself a favor and read this short article on Groovy Collections. Then you will see that the best way to do the same is

// Good!
c.selecteds.each {
  it.text = "That's groovy!"
}

c.selecteds is only evaluated once and there are no redundant variables and method calls.

On Groovy properties and the Scripting API

If an object, e.g. Node node, has a method getXyz() then groovy allows to use node.xyz. If it also has a proper setXyz() method (proper in the sense of the JavaBeans specification) then the property is writable.

Example of a read-only property:

assert node.getId() == node.id
println("ok")

This will print "ok" into the logfile since the assertion is valid.

Example of a read-write property:

println(node.text)
node.text = "please note!"
println(node.text)

The second println will print the changed node text.

It's considered better style in Groovy if you use the properties instead of getters and setters. So better use

c.statusInfo = "Icons: " + node.icons.icons

instead of

c.setStatusInfo("Icons: " + node.getIcons().getIcons())

The menu item Help -> Scripting API shows the attributes instead of get/set methods where possible and indicates if the attributes are read-only, read-write or write-only.

The operator == means equals()

In Groovy the operator == is overridden to mean equals(). To check for identity use the method is():

Integer i = new Integer(3)
Integer j = new Integer(3)
assert i == j
assert ! i.is(j)

Caveat

Note that - unlike in Ruby - it's not allowed to omit the parens of a function without parameters in Groovy. So to get the number of children a node has, use node.children.size(), not node.children.size. The latter would be OK if java.util.List had a method getSize().

Wanted: Your participation!

It's very likely that scripting support lacking some functionality that would be useful for a large number of users. For this reason you are strongly encouraged to give feedback on issues you are having with scripting and on things you are missing.

For discussions use the Freeplane open discussion forum.
Submit bugs here and feature requests here.
Please add useful scripts to the Scripts collection Wiki page.
To ask questions directly related to this page, use the discussion page.

What users say

Advice for taking up scripting by Quinbus and Miguel.