Scripting

From Freeplane - free mind mapping and knowledge management software
Revision as of 09:45, 4 September 2011 by Seatrout (talk | contribs) (Wrote an even simpler intro section, highlighting the power of the new 1.2 script editor)

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: Baby Steps

Freeplane 1.2 has a small script editor built into it, which is probably the easiest way to take baby steps into scripting. It is reached through the Tools menu, as "Edit Script". Any scripts written like this are stored as attributes of the node you are working in, but this is often also good for testing: you can't break nodes you can't reach.

It is often helpful when writing scripts to use function keys to summon the script editor and to run test scripts: press F10. A popup will appear. using the mouse, choose "Tools -> Edit script" from the menu bar. Then press F11, and this time when the popup appears, choose "Tools -> Execute Selected Node scripts".

Within the script editor, you can type your script and then choose "Run" from the file menu. When it works properly, choose "save and exit". Scripts written in this way can be renamed by editing the attributes of a note. There, the name of the script appears in the left-hand column, and the whole script written out on one line on the right. Double click on the name and you can replace it with something more helpful than "Script1"

Scripts of this sort can only be run from the node that contains them. If you want to make the available anywhere on a map, they must be copied and pasted into the script file, and given a filename ending with ".groovy".

Here is the simplest script possible:

<groovy name="HelloWorld"> // @ExecutionModes({ON_SINGLE_NODE}) node.setText("Hello World!") </groovy> Cut and paste it into the script editor, then run it. The text of the node will change. To restore the original, press Ctrl-Z.

So, scripting can be very simple. But it can also be very powerful and useful. The rest of this section and the example scripts, show how to make it so.


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

First we'll create mind map for testing, then we'll set up a folder to store your Groovy scripts where Freeplane can find them.

Create a Test Map

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.

Set up a scripts folder

Create a scripts sub-directory if one doesn't already exist in your Freeplane User Configuration Folder:

  1. Find your User Configuration Folder:
    • For Freeplane 1.1.x:
    ~/.freeplane (in Unix / Mac), or
    %USERPROFILE%\.freeplane (in Windows)
    • For Freeplane 1.2.x:
    ~/.freeplane/1.2.x (in Unix / Mac), or
    %USERPROFILE%\Application Data\Freeplane\1.2.x (in Windows)
  2. Create a sub-directory there, using the name scripts.

todo: link here to FAQ instead? -- Volker

Create a script and integrate it into Freeplane

If you are using Freeplane 1.1, or writing scripts directly into the scripts folder, 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), TextEdit on Mac OS X, gedit on Ubuntu Linux or, in a Unix console your favorite text-mode editor. You find an overview of editors with Groovy support on the Groovy web site.

Of course it would be helpful if the editor understands groovy (to provide syntax highlighting), or at least knows about mismatched parentheses. The Groovy Console might be a good choice to get started. Or search the web for other free open source programmer's editors - some good ones are available such as jEdit which, like Freeplane, is written in Java.

  1. Create an empty Groovy script file with an expressive name, for example sumNodes.groovy, in your scripts directory. The suffix .groovy is mandatory.
  2. 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. Note that new scripts are only recognized at Freeplane's start. Restart Freeplane after adding a script.
  3. In Freeplane's Preferences... enable these scripting options:
    • For Freeplane 1.1.x in Preferences...->Scripting:
      • Scripts should be carried out without confirmation?
      • Permit File Operations (NOT recommended) - despite the warning
    • For Freeplane 1.2.x in Preferences...->Plugins->Scripting:
      • Script execution enabled
      • Permit File/Read Operations (NOT recommended) - despite the warning
    • These changes take effect without restarting Freeplane. For more details see Scripting: Security considerations.
  4. 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.)

Nothing happens. - That's not unexpected, right? The script is empty so it doesn't do anything yet. So let's add some action in the next section.

First steps in Groovy

First, open sumNodes.groovy in an appropriate editor as detailed above.

sumNodes.goovy will 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 not?

The reason is that all print output goes into the logfile which is located in your User Configuration Folder. So navigate there and look at the file named log.0 using your text editor. Note: if you have multiple instances of Freeplane opened then there will be more than one logfile. In that case, find the one that was changed most recently. The last lines of the logfile should contain a line like this: 

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

This line stems from the print statement in our second script and it shows that only one node was selected and that its type is NodeProxy. (The API of Node that is implemented by NodeProxy is described in the API, too.) In versions 1.1.x: don't care about the Result:null line.

Getting started with Lists

Look up 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 case braces {} instead of parens () are used. The parts in braces are program fragments, so called blocks.

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

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

The argument of sum is a block, that extracts the text content via Node.getText() (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 one: It's a concatenation of all node's text rather than the sum of the numbers.

Numbers

To take the numerical sum it's necessary to convert each 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's text content is numeric ( via text.isDouble() ) we don't have to worry about selected nodes with non-numeric content. (Check what happens if you erase this test and execute the script with the root node ("test") selected!)

Getting interactive

Printing results into the logfile isn't very convenient. Let's show them in an popup window, using a utility class that is part of Freeplane, UITools (for Freeplane 1.2.x it's different, see below). 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 name="sumNodes"> // @ExecutionModes({ON_SINGLE_NODE}) import org.freeplane.core.ui.components.UITools;

def doubleValue(String text) { 

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

}

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

Note for Freeplane 1.2.x: The scripting API in the upcoming Freeplane version provides much simpler access such sort of functionality. Here's the script for 1.2.x and above: <groovy name="sumNodes"> // @ExecutionModes({ON_SINGLE_NODE}) def sum = c.selecteds.sum{it.to.num0} def sumFormatted = java.text.NumberFormat.getInstance().format(sum) ui.informationMessage(ui.frame, 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 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 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 typos 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 (restart Freeplane to see it in the menu). 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 def 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. 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: <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.text) node.text = "please note!" println(node.text) </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. (The only exception is println, see above.) 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 dig 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=2505"