Scripting Documentation - New Structure (Reorganizing)

[sifran-github]

INTRO

In our ensemble meeting, we discussed having a new outline to our Scripting Documentation.
I did A LOT of thinking about the content & structure, and I came up with a possible way to restructure our scripting documentation in a very useful way.

In order to think and organize, I used a little program called Freeplane (did you know that it is an amazing program?)

in my mindmap:

• brown = folder (without any content by itself!)
• blue = page
• gray/no color as a child of a page = topics inside the page.

here we go...

CATEGORIES

These are my suggested main categories.

LETS TALK ABOUT CHEAT SHEET (& LARGE SCRIPT COLLECTION)

First, lets talk about cheat sheet. This is the most important part that is currently missing in the scripting documentation. This is the main key that will unlock the potential of people adding more examples and usages. I dont know if the name is correct but what i mean by this is having :

1. scripts that are very short and have only 1 specific purpose.
2. organized into categories.

I tried to do something recently, #20 but then i looked and saw that the "getting started" guide already contains a lot of info, and i stopped (my mistake).
Others also tried to point out that it is needed: #73

Now, regarding the "large scripts collection": during our ensemble meeting, I put our existing "scripts collection" in "references"... but after thinking about it today, it is far from it. Currently, the existing "scripts collection" is a mixture of cheat sheet material, and large scripts. Think about it, part of the scripts there have the purpose of showing one specific capability (and should move to cheat sheet) and some of them are just large scripts that are doing many things, and we can keep them in the "large scripts collection".

if you want me to be more specific, these scripts should go to cheat sheet (maybe after small refactoring):
clipboard:
https://docs.freeplane.org/#/scripting/Scripts_collection?id=copy-link-of-a-node-to-the-clipboard
sorting nodes:
https://docs.freeplane.org/#/scripting/Scripts_collection?id=sort-child-nodes-alphabetically-by-length-or-by-other-properties
attributes:
https://docs.freeplane.org/#/scripting/Scripts_collection?id=add-up-attribute-values-of-subnodes

and these scripts should go to larger scripts:
https://docs.freeplane.org/#/scripting/Scripts_collection?id=create-a-map-with-firefox-bookmarks
https://docs.freeplane.org/#/scripting/Scripts_collection?id=pomodoro-timer

MANUAL

Scripting Manual will contain every explanation about freeplane scripting.

currently can contain:

• getting started guide (see next point)
• freeplane scripting capabilities: this is a new category that i wrote, to describe all of the ways that someone could write scripts in freeplane. there are so many ways... that i think each way should be listed here.
• additional topics

Note also that i split the security considerations into their topics (formulas, add ons). it should be there, not separated.

GETTING STARTED GUIDE

This guide is currently under the scripting folder. when you click on "scripting" you get a huge page. This page is currently very messy. it contains a lot of information about many topics. in my opinion, a lot content should move to cheat sheet, and the guiding principle of this guide is not to include as much as possible, but rather to have "a simple way to start writing very simple scripts in freeplane", and if the user wants to know more he should go to other pages (that will be organized by categories).

REFERENCES

finally, references. we will put links to resources like groovy language and concept for non-programmers (that are explained already on the internet), and the api (or instructions of how to view it from the freeplane).

SUMMARY

So this is my proposed new structure for the scripting documentation.

I include the mindmap here: scripting_docs_new_structure.zip

I am not sure how much of this re-organization i will be able to do by myself. it includes a lot of work such as re-organizing and breaking up the "getting started guide" and also the "scripts collections" into the cheat sheet, but i will do my best.

I will wait for your comments before proceeding.

[sifran-github]

Just to understand why this reorganization is required, this is the current situation today:

so currently, in order to find how to do something in scripting, one has to jump between a huge guide that is hidden in the folder, a huge script collection... confusing menu.... and more.

it is not clear.

I hope my suggestion will make it much better.

[euu2021]

I liked your reorganization. Later, I will make some comments and give some ideas.

[euu2021]

At first, I thought you were cutting the "Getting Started" too short, but now I agree that it should teach only how to make the basic setup.
I think something that will help in defining the stop point of each page is having in mind the kinds of users that will use the documentation ("personas"). I can think of 3 kinds of personas:

• User A: He has read in the forum that his problem is solved by a script, that was posted there. Now, he wants to know how to use that script in FP. For now, he has no interest in creating his own scripts.

• User B: He has read about the things that scripts can do, and is interested in learning how to use and create scripts. He never wrote a line of code in his life.

• User C: Experienced programmer. He just wants to know the basic setup, read some examples in the Script Collection, and he is ready to go straight into creating his own scripts. If he doesn't know Groovy, he can quickly learn it from an external source.

Notice that, after the basic setup, the paths of each Persona are different, so it makes sense cutting it there.

---

Now, about User B, I think he should have the option for a "full course" on scripting. I.e., a sequence of "chapters" that teaches things from the fundamentals. Writing the complete thing is a difficult task, but I think I already can write the first chapters of it, so I think it can be considered a realistic goal to have a full course like this on a long term timespan. I'm thinking of something like this (the chapters in blue, and each one would be a page inside the documentation):

This map:
EXAMPLE guide.zip

---

About the Cheat Sheet
Yes, I think it would be useful.

As I said before, an example for each method would be useful. Just today, I spent like an hour trying to make get working the method to change the shape of a node. Try to create it and notice which path do you take to find an answer (I will leave the answer in a spoiler bellow).

Spoiler warning

node.geometry.shape = 'WIDE_HEXAGON'

The path I took was:

• first, try what sounds the most intuitive to me: node.setShape("OVAL")
• then, search for setShape in the Scripts Collection, the old forum, and the github in general: nothing
• then, making analogies with other methods, after a lot of trial and error, I got a good result

The Cheat Sheet could help in this process.

[macmarrum]

Just today, I spent like an hour trying to make get working the method to change the shape of a node.

Yes. I used to spend a lot of time too, until I found out that I can use a search engine available at Help->Freeplane API…

It might be a good idea to mention in the scripting docs about the search functionality, and maybe an example how it can be used.

Based on the findings, and after reading the page on NodeShape, which contains all possible shapes that can be applied, the expression will be as follows

import org.freeplane.api.NodeShape

node.getGeometry().setShape(NodeShape.WIDE_HEXAGON) // Java-style

OR

node.geometry.shape = 'WIDE_HEXAGON' // Groovy-style

[euu2021]

My difficulty was finding what should I put between node and shape. Now that you wrote the Java-style version, I see that the middle term is a short for the get method. I've seen the getGeometry() method, and even created a sample script with it, but I didn't know that this (the get method) is the element that, after being shortened, appears as the middle term in expressions like node.cloud.shape = 'ROUND_RECT'

Again, that question about getters/setters. Groovy is shorter, but Java is clearer. I will make some tests to see if I really understood, and then explain that in the documentation.

[macmarrum]

Groovy is shorter, but Java is clearer.

Scripting / formulas in FP can use Java-style code instead of Groovy-style.
There are some differences between Java and Groovy, but for regular scripting they have little significance – https://groovy-lang.org/differences.html
And when people get more into scripting, they usually start using an IDE. IntelliJ IDEA has syntax checker and gives hints about what can be changed. So most mistakes can be caught and corrected before running the code.

All in all, feel free to write Java-style scripts. They will work just fine in Freeplane.

node.getCloud().setShape("ROUND_RECT")

Finally, in case of documentation for beginners, I would propose to decide on one style and stick to it, at least within a single script / snippet.

[macmarrum]

I noticed that something that was confusing me is the fact that the other classes of this list, besides the Node and Controller, can't have the instances called directly.

It's because this is the agreement, i.e. we always start from node or c and access any other properties or methods from there. It makes perfect sense to people familiar with programming. I can understand it might be unclear to others.

This example might help.
Let's have a very simplified description of a person. This person has a name, has hair of a certain color and eyes of a color.

class Person {
    String name
    Hair hair
    Eyes eyes

    Person (String name, String hairColor, String eyesColor) {
        this.name = name
        hair = new Hair()
        hair.color = hairColor
        eyes = new Eyes()
        eyes.color = eyesColor
    }

    static class Hair {
        String color
    }

    static class Eyes {
        String color
    }
}

Let's use the class to describe Fred, who has blond hair and blue eyes.

def fred = new Person('Fred', 'blond', 'blue')

Now, let's create a function that returns the color of a person's eyes. We want to say to the function "Here's a person (Fred). Give me the color of his eyes".

def getColor(p) {
    return p.eyes.color
}

We could make a different agreement with the function, saying "Here are the persons eyes. Give me their color".

def getColor(e) {
    return e.color
}

Now let's ask the function to also give the color of a person's hair. In the last function we need to add another argument to the function, i.e. hair, otherwise the function cannot access its color.

def getColor(e, h) {
    return e.color + ' ' + h.color
}

In the first form of the function, we don't need to pass anything else except for a person.

def getColor(p) {
    return p.eyes.color + ' ' + p.hair.color
}

In Freeplane scripting, we always get node and c, similar to arguments in the example function.

We also get the utilities described in FreeplaneScriptBaseClass, i.e. ui, logger, htmlUtils, textUtils, menuUtils, config.
This is why, when writing a formula, we can do

=config.getIntProperty('max_shortened_text_length')

instead of

=import org.freeplane.plugin.script.FreeplaneScriptBaseClass.ConfigProperties
def conf = new ConfigProperties()
conf.getIntProperty('max_shortened_text_length')

[macmarrum]

scripting_person_example.zip

[euu2021]

Ok, thanks for the explanation. I think that, now, I'm able to better understand what happens when I write a simple expression in a script.

---

Now, with that knowledge, I went back to analyze the difficulty that I had trying to set a style to a node inside a script. The problem there is that I was trying to use the method setStyle, that I found by searching for "style" in the API. The "setStyle" is what looks the most promising when the user does that search:

I don't understand this method, and can't make it work.

And, the most interesting, is that, even now, I would have difficulty in setting a style, because I would follow this path:

• I would look in the classes list (inside the Help->Api Generator), for something about Styles. I would find the NodeStyle class.
• inside it, I would find the style property, with the get and set method.
• so, I would compose this expression: node.nodeStyle.style = "styleX" . And the reasoning would be: node as the usual start, nodeStyle, to call the instance of the NodeStyle class, and style to set the property.
• And... it doesn't work

But, if I looked at the Help->Freeplane API…, I would find the explanation: Node's style: node.style - read-write, and, only then, I would succeed. If I had to guess, I would say that what happened there is that, usually, the properties of the node class have the same name as the other classes (but, starting with lower case), but, for the style property, there is a mismatch in the name.

So, the takeaways:

• The Help->Api Generator has the disadvantage of not having the clarification notes
• Some classes do need these clarification notes. And, for amateurs, a note like the one I mentioned above (Node's style: node.style - read-write) is not enough
• I need a working example of the setStyle method

[macmarrum]

if I looked at the Help->Freeplane API…, I would find the explanation: Node's style: node.style - read-write

You have found a bug in the documentation. This should say read-only, just like it does in Help->Api Generator: Proxy->Node->style: NodeStyle (r). I will create a PR to fix the note (Java doc).

so, I would compose this expression: node.nodeStyle.style = "styleX" . And the reasoning would be: node as the usual start, nodeStyle, to call the instance of the NodeStyle class, and style to set the property.

I see. I will try to explain by expanding our Person example. Let's rename Hair to PersonHair, Eyes to PersonEyes.

Notice that private has been added in Person for personEyes. It means that personEyes can only be accessed from within Person. In other words, fred.personEyes won't work. This is what getters and setters are for. They allow us to get and to set private stuff from the outside.

class Person {
    private String name
    public PersonHair personHair
    private PersonEyes personEyes

    Person(String name, String hairColor, String eyesColor) {
        this.name = name
        personHair = new PersonHair()
        personHair.color = hairColor
        personEyes = new PersonEyes()
        personEyes.color = eyesColor
    }

    def getName() {
        return name
    }

    def getHair() {
        return personHair
    }

    def getEyes() {
        return personEyes
    }

    def setEyes(PersonEyes personEyes) {
        this.personEyes = personEyes
    }

    static class PersonHair {
        String color
    }

    static class PersonEyes {
        String color
    }
}

def getEyesColor(Person p) {
    // return p.personEyes.color // won't work because personEyes is private
    return p.getEyes().color // Java-style
    // return p.eyes.color // Groovy-style
}

def fred = new Person('Fred', 'blond', 'blue')
getEyesColor(fred)

Note that I have given the getter and setter shorter names, i.e. getEyes() and setEyes(...), instead of getPersonEyes(), setPersonEyes(...). So in Groovy we can write fred.eyes, whereas in Java we'd write fred.getEyes(); and fred.eyes = ... instead of fred.setEyes(...).

It's similar with NodeStyle. Its getter in NodeRO is getStyle(), not getNodeStyle(). So in Groovy we can write node.style, not node.nodeStyle.

Once we get NodeStyle object by calling node.getStyle() or node.style, we can use the properties and methods belonging to NodeStyle, like getName() and setName(...), or simply name. This results in node.style.name = 'styleX'.

---

We can still write fred.personHair.color, because personHair is public (availabe from the outside of Person). But because there is a getter, we can also write fred.getHair() or fred.hair → fred.hair.color.

We cannot write fred.hair = ... or fred.setHair(...) because there is no setter. We'd need to access it direclty, i.e. fred.personHair = .... There's more to it in Groovy, but to keep the example simple and more generic, I'll skip the details.

def fred = new Person('Fred', 'blond', 'blue')
def kate = new Person('Kate', 'black', 'brown')

def kateHair = kate.hair
fred.personHair = kateHair

"""\
kate: ${kate.hair.color}
fred: ${fred.hair.color}
"""
// kate: black
// fred: black

Interestingly, now when Kate's hair color changes, it changes also for Fred.

kate.hair.color = 'pink'

"""\
kate: ${kate.hair.color}
fred: ${fred.hair.color}
"""
// kate: pink
// fred: pink

This is because Fred was given the same hair as Kate. In the real world they would be joint by their hair, like conjoined twins.

To only give the same color, we would need to create new hair for Fred, and just apply Kate's color.

def fred = new Person('Fred', 'blond', 'blue')
def kate = new Person('Kate', 'black', 'brown')

def kateHair = kate.hair
def fredHair = new Person.PersonHair()
fredHair.color = kateHair.color
fred.personHair = fredHair

kate.hair.color = 'pink'

"""\
kate: ${kate.hair.color}
fred: ${fred.hair.color}
"""
// kate: pink
// fred: black

[euu2021]

👍I will study your explanation.

[euu2021]

Just to update my current situation here: I wanted to learn a bit about Java before writing up the scripting pages in the documentation. Only last week, I managed to allocate some time in my weekly schedule to go through a basic Java course. So, I will still need some time before I learn enough to write those pages that I planned above.

[dpolivaev]

Please check my post Using ChatGPT to Develop High Quality Documentation for Freeplane Features . It might simplify everything.