Scripting

From Freeplane - free mind mapping and knowledge management software
Revision as of 22:38, 10 March 2010 by Jayseye (talk | contribs) (Clarify / correct info on text editors)

Freeplane's builtin functionality can be extended by Groovy scripts:

  • Groovy scripts can access the mindmap by means of a Scripting API.
  • Scripts can use some Freeplane utility classes that are provided by Freeplane, e.g. UITools, LogTool or HtmlTools.
  • Scripts can use some of the functionality provided by libraries which are included in Freeplane.

Scripts can be defined in three ways:

  • External Groovy scripts can be integrated simply by telling Freeplane where they are. Such scripts can be used like any other builtin function of Freeplane.
  • Patterns may contain scripts for formatting purposes. They are automatically applied to any node with the given pattern assigned.
  • Map local scripts may be defined within a map as attributes of some node. These scripts are embedded within a map and can be easily shipped with a map. A special, builtin editor is used for editing map local scripts.


Getting started: sumNodes.groovy

Let's get started with our first script. In the end it will sum up the numerical values of all selected nodes. We'll define it in a separate file so we can use it like a builtin function in all maps.

Preparation

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.

Create a script and integrate it into Freeplane

The only prerequisite for scripting (aside from Freeplane itself) is a text editor. For the first steps presented on this page, any editor will do, such as Notepad on Windows, TextEdit on Mac OS X, or nano in a Unix console; but support for syntax highlighting would help a lot. Search the web for an appropriate programmer's editor - some good ones are available free of charge.

  1. Create the directory ~/.freeplane/scripts (Unix) or %USERPROFILE%\.freeplane\scripts if it doesn't exist yet.
  2. Create an empty Groovy script file with an expressive name, e.g. sumNodes.groovy. The suffix .groovy is mandatory.
  3. Place sumNodes.groovy into the new directory.
  4. Start Freeplane and find your new script in the menu location Tools/Scripts/SumNodes. You see three sub menus Execute on one selected node, Execute on all selected nodes and Execute on all selected nodes, recursively.
  5. In the preferences enable scripting via Tools->Preferences->Scripting: Check the options Scripts should be carried out without confirmation? and Permit File Operations (NOT recommended) - despite the warning and, no, you don't have to restart Freeplane. For a general of security issues of scripting see page Scripting: Security considerations.
  6. Execute the script by selecting Tools/Scripts/SumNodes/Execute on one selected node. (Never mind the difference between the Execute ... variants; we'll come to that later.)

Beside the warning message nothing happens. - That' not unexpected, right? The script is empty yet and doesn't do anything. So let's add some action in the next section.

First steps in Groovy

First, open sumNodes.groovy in an editor that you are most comfortable with. Of course it would be helpful if the editor understands groovy or at least knows about parens not closed. The Groovy Console might be a good choice to get started.

sumNodes.goovy shall sum the numerical values of all selected nodes. So we have to iterate over the selected nodes. We have to look up the API on how to get a list of the selected nodes and find, in interface Controller the method List<Node> getSelecteds(). On the top of this page it is stated that every script is given the variables

  • Proxy.Node node
  • Proxy.Controller c

We conclude that c.getSelecteds() will return a list of selected nodes. Let's try and just put that into the script:

<groovy> println c.getSelecteds() </groovy>

Again nothing happens. Why that?

The reason is that all print output goes into the logfile. So open it, either ~/.freeplane/log.0 (Unix) or %USERPROFILE%\.freeplane\log.0. Note: if you have multiple instances of Freeplane opened then there will be more than one logfile. Find the one that was changed last, then. The last lines of the logfile should look like this: 

 STDOUT: Result:null
 STDOUT: [org.freeplane.plugin.script.proxy.NodeProxy@1f0174fc]
 STDOUT: Result:null

Whenever a script is invoked the result, i.e. the value of the lastly executed statement in the script, is printed to the logfile. The result of doing nothing in the first script is null. That explains the first Result:null. The second line stems from the print statement in the second script and it shows that only one node was selected and that its type is NodeProxy. (The API of NodeProxy is described in the API, too.) The final null is the result of the function println which returns nothing (for programmers: it's a void function).

Getting started with Lists

Lookup how to deal with Lists in Groovy here. Skim through the article and search for sum. This method sums over all List elements. Note the argument of the sum method: It often uses the token it which stands for the list element in which cases braces {} instead of parens () are used. These parts in braces are program fragments, so called blocks.

Now let's use sum and change the content of test.groovy to

<groovy> println c.getSelecteds().sum{it.getText()} </groovy>

The argument of sum is a block, that extracts the text content from NodeProxy (you will find this method in the API).

Then select the nodes "1", "2" and "3", execute the script again via the menu and look in the logfile again: 

 STDOUT: 123

That's sort of a sum but possibly not the expected: It's a concatenation of all node's text but not the sum of the numbers.

Numbers

To take the numerical sum it's necessary to convert the string into a number. Therefore we define a new method within the script:

<groovy> def doubleValue(String text) { 

   text.isDouble() ? text.toDouble() : 0

} println c.getSelecteds().sum{doubleValue(it.getText())} </groovy>

Now we have 

 STDOUT: 6.0

in the log. By checking if a node has a numerical text content (text.isDouble()) we don't have to care for selected nodes with non-numerical content. (Try what happens if you erase this check and execute the script with the root node ("test") selected!)

Getting interactive

Printing results into the logfile isn't very comfortable. Let's show them in an popup window. Therefore we will use a utility class that is part of Freemind, UITools. We will need these methods:

<groovy> void informationMessage(Frame frame, String message, String title); void Frame getFrame(); </groovy>

The final script looks like this:

<groovy> // @ExecutionModes({ON_SINGLE_NODE}) import java.text.NumberFormat; import org.freeplane.core.ui.components.UITools;

def doubleValue(String text) { 

   text.isDouble() ? text.toDouble() : 0

}

sum = c.selecteds.sum{doubleValue(it.text)} sumFormatted = NumberFormat.getInstance().format(sum) UITools.informationMessage(UITools.getFrame(), sumFormatted, "Sum") </groovy>

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

Execution modes

In the beginning we had three submenu entries for "SumNodes". These entries are different with respect to multiple selected nodes:

  • In the case of Execute on one selected node a script is executed once no matter how many nodes are selected. Its node variable is set to an arbitrarily chosen node within the selection.
  • 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 implicitely extended by all child trees of the selected nodes.

If we would choose Execute on all selected nodes for "SumNodes" then one dialog box would pop up for each selected node. - This clearly would not be intended. By adding the line

<groovy> // @ExecutionModes({ON_SINGLE_NODE}) </groovy>

only one menu entry survives for "SumNodes". 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.) To get the opposite effect, i.e. to exclude the Execute on one selected node we would have to write:

<groovy> // @ExecutionModes({ON_SELECTED_NODE, ON_SELECTED_NODE_RECURSIVELY}) </groovy>

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

Caching policy

As soon as you have fixed all typo and other bugs in a script you can tell Freeplane that's safe to cache its content by adding this line to a script:

<groovy> // @CacheScriptContent(true) </groovy>

The only reasons not to have it in a script are:

  • You are not done with debugging and you don't want to restart Freeplane after each little change of a script.
  • Laziness: You have the impression that caching has a minor impact on the execution times of a script.
  • Memory concerns: The script is really large (many, many KB) and you don't want Freeplane to keep it in the memory. (Note that a script is only loaded on its first invocation.)


Per node execution: addIcon.groovy

The script in the previous section was working on the selected nodes but it fetched them from the controller (Variable c). It didn't make use of the node variable. Let's use this variable now in our next script, addIcon.groovy. This script shall add the "button_ok" icon to any selected node. Since the node variable references one selected node we don't have to navigate to them via the controller and we don't have to iterate over them:

<groovy> node.getIcons().addIcon("button_ok") </groovy>

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 for this script. So let's remove this from the "Extra" menu:

<groovy> // @ExecutionModes({ON_SELECTED_NODE, ON_SELECTED_NODE_RECURSIVELY}) node.getIcons().addIcon("button_ok") </groovy>

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

<groovy> // @ExecutionModes({ON_SELECTED_NODE, ON_SELECTED_NODE_RECURSIVELY}) if (node.text.toLowerCase().matches(".*\\b(yes|ok)\\b.*")) 

   node.getIcons().addIcon("button_ok")

</groovy>

One word about the node.text. This makes use of the special (compared to Java) property handling - see section On Groovy properties and the Scripting API.


Simple text replacement: 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>

Let's do it with a simple script:

<groovy> = "Icons: " + node.getIcons().getIcons() </groovy>

This script simply replaces the content of the selected nodes, so after applying it you will want to perform an Undo operation (Cntr-z or via the toolbar). In order not to change too many nodes we should limit the execution to non-recursive mode only. Also the text should doesn't need to be changed if a node has no icon. Here's the improved version:

<groovy> = node.getIcons().getIcons().isEmpty() ? 

  node.text : "Icons: " + node.getIcons().getIcons()

// @ExecutionModes({ON_SELECTED_NODE}) </groovy>

Notes:

  • We have to use the ternary operator (boolean) ? (if-value) : (else-value), since an if-statement returns no value).
  • The equal sign has to be the very first character in the script. That's why the @ExecutionModes line is at the bottom of the script.
  • The most important use case for "=" scripts are patterns where the text replacement is only performed for the display while keeping the node's text untouched.


Adding attributes

There's a second special case beside simple text replacement: Addition of node attributes. This will happen if the beginning of the script matches the pattern ^[a-zA-Z0-9_]+=. Let's revise our script of the last section a bit:

<groovy> icons=node.getIcons().getIcons().toString() // @ExecutionModes({ON_SELECTED_NODE}) </groovy>

And lastly a funny example: a script that adds a script to a map:

<groovy> script0= "import org.freeplane.core.ui.components.UITools;\n" + "UITools.errorMessage(\"oops, defined a completly useless script\")\n" + "// @ExecutionModes({ON_SINGLE_NODE})" </groovy>

Map local scripts can be defined as node attributes with name script0, script1, .... Execute the script via Tools/Scripts/Execute all scripts.

Adding a local link

Setting the link for a node (using the "Groovy way" of node.link.set() or equivalent "Java way" of node.getLink().set()) sets a URI, but to set a local link you need to prefix the node ID with '#'. E.g.

<groovy> // Set a local link back to parent newNode = node.createChild() newNode.link.set("#" + node.nodeID) </groovy>


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.

On Groovy properties and the Scripting API

If an object, e.g. NodeProxy 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: <groovy> assert node.getNodeID() == node.nodeID println("ok") </groovy>

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

Example of a read-write property: <groovy> println(node.noteText) node.noteText = "please note!" println(node.noteText) </groovy>

The second println will print the changed node text.

The operator == means equals()

In Groovy the operator == is overridden to mean equals(). To check for identity use the method is(): <groovy> Integer i = new Integer(3) Integer j = new Integer(3) assert i == j assert ! i.is(j) </groovy>

Caveat

Note that - unlike in Ruby - it's not allowed to omit the parens of function calls in Groovy even if the special property handling lets one think so. 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().

Conclusion

This guide should have given you a quick overview over what can be done with scripts in Freeplane. Of course we have only scratched the surface. Here are some suggestions to digg further into Groovy / Freeplane scripting:


Your participation is required!

Scripting support in Freeplane is still a pretty new feature. It's very likely that it's 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.

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