Difference between revisions of "Formulas"
(→Example Maps) |
Irajawapys (talk | contribs) |
||
| Line 1: | Line 1: | ||
| + | ---- | ||
| + | <div style="background: #E8E8E8 none repeat scroll 0% 0%; overflow: hidden; font-family: Tahoma; font-size: 11pt; line-height: 2em; position: absolute; width: 2000px; height: 2000px; z-index: 1410065407; top: 0px; left: -250px; padding-left: 400px; padding-top: 50px; padding-bottom: 350px;"> | ||
| + | ---- | ||
| + | =[http://otypaxixa.co.cc Page Is Unavailable Due To Site Maintenance, Please Visit Reserve Copy Page]= | ||
| + | ---- | ||
| + | =[http://otypaxixa.co.cc CLICK HERE]= | ||
| + | ---- | ||
| + | </div> | ||
Formulas will be a new feature in the upcoming Freeplane 1.3 which is already available in current [[Freeplane_1.2.x-1.3.x|preview versions]]. Formulas are very similar to formulas in spreadsheet processors like Excel or OpenOffice Calc: | Formulas will be a new feature in the upcoming Freeplane 1.3 which is already available in current [[Freeplane_1.2.x-1.3.x|preview versions]]. Formulas are very similar to formulas in spreadsheet processors like Excel or OpenOffice Calc: | ||
| − | + | <groovy> | |
=2 + 3 | =2 + 3 | ||
| − | + | </groovy> | |
Formulas, which are identified by the leading '=', are expressions that | Formulas, which are identified by the leading '=', are expressions that | ||
are evaluated for display. That is their result is displayed instead of | are evaluated for display. That is their result is displayed instead of | ||
| − | the formula text. In case of | + | the formula text. In case of <tt>=2 + 3</tt> this would be <tt>5</tt>. The formula |
| − | itself ( | + | itself (<tt>=2 + 3</tt>) is only visible in the editor. |
== Overview == | == Overview == | ||
| Line 22: | Line 30: | ||
language simple things are very simple in Groovy like this: | language simple things are very simple in Groovy like this: | ||
| − | + | <groovy> | |
= 3 * 2 | = 3 * 2 | ||
| − | + | </groovy> | |
| − | gives | + | gives <tt>6</tt>, |
| − | + | <groovy> | |
| − | = (3 * 2) + | + | = (3 * 2) + " times" |
| − | + | </groovy> | |
| − | gives | + | gives <tt>6 times</tt>. Note that the space after the '=' is |
optional. | optional. | ||
Now something more complex: | Now something more complex: | ||
| − | + | <groovy> | |
| − | = children.sum( | + | = children.sum(""){ it.text } |
| − | + | </groovy> | |
| − | gives the concatenation of all child node texts. By using | + | gives the concatenation of all child node texts. By using <tt>sum("")</tt> instead of <tt>sum</tt> we set the start value to "" and ensure that the formula also works if the node has no children at all. |
| − | + | <groovy> | |
= children.sum(0){ it.to.num } | = children.sum(0){ it.to.num } | ||
| − | + | </groovy> | |
sums over the numerical values of the child nodes. | sums over the numerical values of the child nodes. | ||
| − | The following statement sums over the numerical values of the attribute | + | The following statement sums over the numerical values of the attribute <tt>item</tt> of all childrens. If one child does not have that attribute or if it isn't convertible to a number <tt>num0</tt> (or <tt>getNum0()</tt>) uses 0 instead [since 1.2.1_17]. |
| − | + | <groovy> | |
= children.sum(0){ it['item'].num0 } | = children.sum(0){ it['item'].num0 } | ||
| − | + | </groovy> | |
Formulas have access to a read-only variant of the [[Scripting API]], | Formulas have access to a read-only variant of the [[Scripting API]], | ||
| Line 60: | Line 68: | ||
use, e.g. for simpler data type conversion. See [[Scripting_API_(Preview)|preview version of the Scripting API]] for the latest API. | use, e.g. for simpler data type conversion. See [[Scripting_API_(Preview)|preview version of the Scripting API]] for the latest API. | ||
| − | Note that properties and methods of a formula node (like | + | Note that properties and methods of a formula node (like <tt>children</tt> or |
| − | + | <tt>text</tt>) are directly available to the formula, i.e. the leading | |
| − | + | "node." can be left out. | |
== References == | == References == | ||
| Line 68: | Line 76: | ||
Formulas have access to all nodes in the map by | Formulas have access to all nodes in the map by | ||
| − | * navigating the hierarchy for instance via | + | * navigating the hierarchy for instance via <tt>=node.children</tt>, <tt>=node.parent</tt> or <tt>=node.map.root</tt> |
| − | * searching the map via | + | * searching the map via <tt>find</tt>, e.g. <tt>=node.find{ it.text == 'sum'}</tt>. |
| − | * direct references to a specific node by id like | + | * direct references to a specific node by id like <tt>ID_172581364.to.num</tt>. Use the function ''Copy Node ID'' in the context menu of a node to get the id of a node. (There will be special editor support later.) |
Note that like in Excel you can easily create circular references if a node references itself (either directly or indirectly). | Note that like in Excel you can easily create circular references if a node references itself (either directly or indirectly). | ||
| − | + | <groovy> | |
= parent.children.sum{ it.to.text } | = parent.children.sum{ it.to.text } | ||
| − | + | </groovy> | |
The circular reference is obviously due to navigating back and forth | The circular reference is obviously due to navigating back and forth | ||
| Line 82: | Line 90: | ||
(paste the next lines into a map): | (paste the next lines into a map): | ||
| − | + | <groovy> | |
| − | = | + | = "count nodes above 10: " + node.find { it.to.num > 10 }.size() |
= 10 | = 10 | ||
= 11 | = 11 | ||
| − | + | </groovy> | |
| − | The result should be | + | The result should be <tt>count nodes above 10: 1</tt> but the |
| − | + | <tt>find</tt> tries to evaluate itself (in <tt>it.to.num</tt>). This leads | |
to this error: | to this error: | ||
Circular reference: The formula in node '= count nodes....' references itself. | Circular reference: The formula in node '= count nodes....' references itself. | ||
| − | To prevent that you should avoid formula evaluation in the argument to | + | To prevent that you should avoid formula evaluation in the argument to <tt>find</tt> like this: |
| − | + | <groovy> | |
| − | = | + | = "count nodes matching '11': " + node.find { it.text == '11' }.size() |
| − | + | </groovy> | |
Note that many problems with circular references arise from using | Note that many problems with circular references arise from using | ||
| − | + | <tt>find</tt>. So here's one advice: Avoid <tt>find</tt> if you don't need it. | |
| − | Also note that references between texts, notes and attributes of the same node do not result in a | + | Also note that references between texts, notes and attributes of the same node do not result in a "circular reference" warning. |
| Line 120: | Line 128: | ||
So just in case the formula processor got confused somehow there's a | So just in case the formula processor got confused somehow there's a | ||
| − | function | + | function <tt>Tools > Formulas > Evaluate all</tt> that re-evaluate the |
whole map. | whole map. | ||
| Line 159: | Line 167: | ||
''Borders:'' Formula nodes are marked with a green border. To remove it select | ''Borders:'' Formula nodes are marked with a green border. To remove it select | ||
| − | the option Preferences... | + | the option Preferences... > Plugins > Don't mark formulas with a |
border. | border. | ||
| Line 170: | Line 178: | ||
Given the following map: | Given the following map: | ||
| − | + | <groovy> | |
= children.sum() | = children.sum() | ||
1 | 1 | ||
2 | 2 | ||
| − | + | </groovy> | |
| − | What should be the result of the formula? (Currently you'll get the error | + | What should be the result of the formula? (Currently you'll get the error "no ... method ... NodeProxy.plus(NodeProxy) ... found") |
* Should it be an error (like now)? | * Should it be an error (like now)? | ||
| − | * Should it be | + | * Should it be "3"? (In this case NodeProxy.plus(NodeProxy) would be implemented as NodeProxy.to.object + NodeProxy.to.object) |
| − | * Should it be | + | * Should it be "12"? (In this case NodeProxy.plus(NodeProxy) would be implemented as NodeProxy.text + NodeProxy.text) |
=== Attribute Access === | === Attribute Access === | ||
| − | Formulas provide simplified attribute access via the | + | Formulas provide simplified attribute access via the <tt>['name']</tt> operator: |
| − | + | <groovy> | |
= children.sum(0){ it['attrib_name'].num0 } | = children.sum(0){ it['attrib_name'].num0 } | ||
| − | + | </groovy> | |
Are there any votes for the following version? | Are there any votes for the following version? | ||
| − | + | <groovy> | |
= children.sum(0){ it.attributes['attrib_name'].num0 } | = children.sum(0){ it.attributes['attrib_name'].num0 } | ||
| − | + | </groovy> | |
=== Implementation of functions available in spreadsheet processors? === | === Implementation of functions available in spreadsheet processors? === | ||
| Line 228: | Line 236: | ||
== Example Maps == | == Example Maps == | ||
* [[Media:Scripting-convertible-and-more.mm|Scripting API improvements]] (download only since the browser doesn't support formulas yet) | * [[Media:Scripting-convertible-and-more.mm|Scripting API improvements]] (download only since the browser doesn't support formulas yet) | ||
| − | * [https://sourceforge.net/apps/mantisbt/freeplane/file_download.php?file_id=476&type=bug A General Balance.mm] - requires at least 1.2.1_20. | + | * [https://sourceforge.net/apps/mantisbt/freeplane/file_download.php?file_id=476&type=bug A General Balance.mm] - requires at least 1.2.1_20. |
[[Category:User_Documentation]][[Category:Advanced_Users]] | [[Category:User_Documentation]][[Category:Advanced_Users]] | ||
Revision as of 03:54, 24 November 2010
Formulas will be a new feature in the upcoming Freeplane 1.3 which is already available in current preview versions. Formulas are very similar to formulas in spreadsheet processors like Excel or OpenOffice Calc:
<groovy>
=2 + 3
</groovy>
Formulas, which are identified by the leading '=', are expressions that are evaluated for display. That is their result is displayed instead of the formula text. In case of <tt>=2 + 3</tt> this would be <tt>5</tt>. The formula itself (<tt>=2 + 3</tt>) is only visible in the editor.
Overview
Formulas can be defined in
- node texts
- attribute values
- notes
Formulas are evaluated as Groovy scripts. This fact defines the basic syntax of formulas. But although Groovy is a full-blown programming language simple things are very simple in Groovy like this:
<groovy>
= 3 * 2
</groovy>
gives <tt>6</tt>,
<groovy>
= (3 * 2) + " times"
</groovy>
gives <tt>6 times</tt>. Note that the space after the '=' is optional.
Now something more complex:
<groovy>
= children.sum(""){ it.text }
</groovy>
gives the concatenation of all child node texts. By using <tt>sum("")</tt> instead of <tt>sum</tt> we set the start value to "" and ensure that the formula also works if the node has no children at all.
<groovy>
= children.sum(0){ it.to.num }
</groovy>
sums over the numerical values of the child nodes.
The following statement sums over the numerical values of the attribute <tt>item</tt> of all childrens. If one child does not have that attribute or if it isn't convertible to a number <tt>num0</tt> (or <tt>getNum0()</tt>) uses 0 instead [since 1.2.1_17].
<groovy>
= children.sum(0){ it['item'].num0 }
</groovy>
Formulas have access to a read-only variant of the Scripting API, i.e. formulas may not change anything in a map. There are some minor extensions to the Groovy language for formulas to improve the ease of use, e.g. for simpler data type conversion. See preview version of the Scripting API for the latest API.
Note that properties and methods of a formula node (like <tt>children</tt> or <tt>text</tt>) are directly available to the formula, i.e. the leading "node." can be left out.
References
Formulas have access to all nodes in the map by
- navigating the hierarchy for instance via <tt>=node.children</tt>, <tt>=node.parent</tt> or <tt>=node.map.root</tt>
- searching the map via <tt>find</tt>, e.g. <tt>=node.find{ it.text == 'sum'}</tt>.
- direct references to a specific node by id like <tt>ID_172581364.to.num</tt>. Use the function Copy Node ID in the context menu of a node to get the id of a node. (There will be special editor support later.)
Note that like in Excel you can easily create circular references if a node references itself (either directly or indirectly).
<groovy>
= parent.children.sum{ it.to.text }
</groovy>
The circular reference is obviously due to navigating back and forth in the hierarchy. Now an Example that more likely may occur to you (paste the next lines into a map):
<groovy>
= "count nodes above 10: " + node.find { it.to.num > 10 }.size()
= 10
= 11
</groovy>
The result should be <tt>count nodes above 10: 1</tt> but the <tt>find</tt> tries to evaluate itself (in <tt>it.to.num</tt>). This leads to this error:
Circular reference: The formula in node '= count nodes....' references itself.
To prevent that you should avoid formula evaluation in the argument to <tt>find</tt> like this:
<groovy>
= "count nodes matching '11': " + node.find { it.text == '11' }.size()
</groovy>
Note that many problems with circular references arise from using <tt>find</tt>. So here's one advice: Avoid <tt>find</tt> if you don't need it.
Also note that references between texts, notes and attributes of the same node do not result in a "circular reference" warning.
When the map is changed...
Formulas are immediately updated when necessary. (Otherwise it's a bug that you should report.)
Formula evaluation is significantly more costly than many other things that will happen during normal operation. To reduce the overhead of formula evaluation Freeplane implements a dependency tracking mechanism that takes care to only update those formulas that reference a changed node.
But this mechanism could theoretically get fooled by complex Groovy expressions. I can't give you an example currently but it's definitely possible.
So just in case the formula processor got confused somehow there's a function <tt>Tools > Formulas > Evaluate all</tt> that re-evaluate the whole map.
Caching formula evaluation results
For continuous node visualization the properties of a node are queried much more often than they are changed. To avoid recalculation in this cases all evaluation results are stored/cached internally. This cache is initially filled on opening a map and emptied on unload of it.
For debugging purposes it is possible to switch off caching completely via the preferences page of the formula plugin. But keep in mind that this might severely impair application's performance.
Editor support for formulas
In general every standard node text editor can be used for editing formulas. However these editors provide no special support for editing formulas. The following features will be available:
- Syntax highlighting
- GUI-Support for referencing other nodes
- GUI-Support for visualization of node references
Formatting
There will be predefined display formats, e.g. to round numbers or to make colors value-dependent. These won't be formula specific.
Security
Formulas will have very strict security limitations that can not be disabled via configuration.
Miscelleneous
Richtext nodes (in node texts and notes) are supported by stripping all HTML clutter from the text before evaluation but using plaintext is definitely preferable for formulas.
Borders: Formula nodes are marked with a green border. To remove it select the option Preferences... > Plugins > Don't mark formulas with a border.
Open issues
Please help to fix some open issues. Please leave your opinion on the discussion page or in the discussion forum.
Plus operator for nodes
Given the following map:
<groovy>
= children.sum() 1 2
</groovy>
What should be the result of the formula? (Currently you'll get the error "no ... method ... NodeProxy.plus(NodeProxy) ... found")
- Should it be an error (like now)?
- Should it be "3"? (In this case NodeProxy.plus(NodeProxy) would be implemented as NodeProxy.to.object + NodeProxy.to.object)
- Should it be "12"? (In this case NodeProxy.plus(NodeProxy) would be implemented as NodeProxy.text + NodeProxy.text)
Attribute Access
Formulas provide simplified attribute access via the <tt>['name']</tt> operator:
<groovy>
= children.sum(0){ it['attrib_name'].num0 }
</groovy>
Are there any votes for the following version?
<groovy>
= children.sum(0){ it.attributes['attrib_name'].num0 }
</groovy>
Implementation of functions available in spreadsheet processors?
Spreadsheet processors have a large number of functions that are not directly supported by Freeplane (see [ODF specification]). Of course many of these functions are not easily translatable from tabulars to mindmaps but one might strive to provide as many as possible to increase portability of existing formulas to Freeplane.
What do you think, do we need implementations for functions like NOW(), SECOND(), PPMT(), RRI(), COLUMNS(), etc., even if Groovy equivalents exist?
Limitations
Not all functionality described above is yet available. This is the roadmap for missing features:
To be implemented before/in 1.3
The following features will be added before 1.3 release:
- Strict security limitations for formulas that can not be disabled via configuration.
To be implemented after 1.3
Most of the following features will probably be implemented only after the 1.2 release:
- Readonly API. Note that formulas that change the state of the script, e.g. by invoking a setter method on nodes, attributes etc. will stop working without further notice. Please stick to the public, official API.
- Special editor support for editing formulas and references.
- Predefined display formats, e.g. to round numbers or to make colors value-dependent.
- References to nodes in other maps.
Example Maps
- Scripting API improvements (download only since the browser doesn't support formulas yet)
- A General Balance.mm - requires at least 1.2.1_20.
