Scripting API (Preview)

This page describes a development version which will only work with preview/alpha/beta/test versions of Freeplane. If you are seeking for the stable released version see Scripting API.

Overview over the changes

The development is currently driven by the implementation of the Formula feature that provides mindmappers with features you know from spreadsheet processors like Excel. This implies

• The syntax must allow more concise statements. For instance to convert a node text to a number you can now write to.num instead of Double.parse(node.text). Attributes are available as node['name'] in addition to the old node.attributes.get('name').
• The API must provide additional functionality that is needed for formulas.
• The API must be re-organized to provide a read-only API for formulas.

Extended Namespace for Scripts

Methods and attributes of the current node are directly available to a script so instead of node.children.size() you may simply write children.size().

Additionally the following methods are directly available:

<groovy>

 /** Shortcut for node.map.node(id) - necessary for ids to other maps. */
 Node N(String id);
 
 /** Shortcut for node.map.node(id).text. */
 String T(String id);
 
 /** Shortcut for node.map.node(id).value. */
 public Object V(String id);
 
 /** returns valueIfNull if value is null and value otherwise. */
 public Object ifNull(Object value, Object valueIfNull);

</groovy>

Convertible

A very important usability improvement, not only for formula writers, is the introduction of the class Convertible that is returned now by some new methods/properties:

• node.to (or node.getTo())
• node['attr_name'] (or node.getAt('attr_name'))
• node.note (or node.getNote())

Extended Setters

Many "setters" on the other hand, like node.setText() have been extended to accept not only Strings but Objects. Much effort was spent to ensure that this conversion matches the conversions that Convertible performs for Strings. For example node.text = new Date() is converted to 2010-10-05T22:11:03.243+0000 which Convertible knows how to convert back to date (try node.to.date).

For formulas it's important that the formulas itself don't change the state of the map. Currently only the first step is made: All subinterfaces Xyz have a base interface XyzRO that includes only the methods that are suitable for formulas. The Proxy implementations implement the full interfaces currently and the constraint is not enforced.

New Controller methods

Some controller methods were introduced mainly for testing:

• Controller.newMap()
• Controller.undo()
• Controller.redo()

Example Maps

• Scripting API improvements (download only since the browser doesn't support formulas yet)

Entry Points

Each script is given two variables:

<groovy> final Proxy.Node node; final Proxy.Controller c; </groovy>

New: Methods and properties of the current node are directly available so you can write children.size() instead of node.children.size().