How to build a settings panel for a plugin

[stefano franchi]

Is there a discussion of this anywhere? I couldn't find it the dev|user docs and looking at the code brought scant enlightenment.

Besides, Google Groups seemed to have stopped working for me tonight.

I am working on node and I am not quite sure how to:

1. Create the panels the make up the various tabs of the plugin page

2. Create a settings for my plugin that would either be added to the control panel or be accessible from the plugin page

3. Access said settings from the plugin code

Pretty basic stuff, I am afraid, all help greatly welcome. I promise to pay back by writing this stuff up if it isn't already.

Cheers,

S.

--

__________________________________________________
Stefano Franchi

stefano...@gmail.com
http://stefano.cleinias.org

[stefano franchi]

Never mind again, got it from the Railroad plugin:

1. Create the panels the make up the various tabs of the plugin page

In  the plugin.info file, add a "list" field with the names of the panels, then create corresponding tiddlers with prefix

$:/plugins/yourName/yourPlugin

 

2. Create a settings for my plugin that would either be added to the control panel or be accessible from the plugin page

 See above foe the plugin page panel. If going for the control panel, then create and use a $:/config/myPlugin tiddler

3. Access said settings from the plugin code

  use $tw.wiki.getTiddlerData()

 

--

__________________________________________________
Stefano Franchi

stefano...@gmail.com
http://stefano.cleinias.org

[Simon Huber]

Hi Stefano,

I can provide you some information:

* a widget is based on $:/core/modules/widgets/widget.js ... all the methods defined there are also accessible in your widget (and work with values based on your widget, like the refreshSelf method, that works with your parentDomNode defined on top with this.parentDomNode = parent), or you provide your own which will be used instead of the one in widget.js

* for your configuration panel this will be useful so that the widget refreshes its configuration whenever one of its configuration tiddlers changes:

YourWidget.prototype.refresh = function(changedTiddlers) {
//here, decide what to do, how to refresh when a configuration tiddler changes
if(changedTiddlers["$:/plugins/myname/myplugin/config/myconfig"] || changedTiddlers["$:/plugins/myname/myplugin/config/myotherconfig"]) {
//maybe when these tiddler change the widget needs a full refresh - depends on how your widget works. note that the refreshSelf method depends on this.parentDomNode being accessible, that's why it's saved at the top of the render method
this.refreshSelf();
return true;
} else if(changedTiddlers["$:/plugins/myname/myplugin/config/myotherotherconfig"]) {
//maybe this config needs just to update a configuration value ...
this.configvalue = this.widget.wiki.getTiddlerText("$:/plugins/myname/myplugin/config/myotherotherconfig");
//maybe I need to do some other processing / updating / refreshing based on an external library, maybe there's a way to update ... otherwise the refreshSelf method updates everything,
//given that somewhere, like in the execute method (which is usually called in the render method and used to get attributes and make child widgets), you get those values from the configuration tiddlers

}
}
//if none of our configuration tiddlers is contained within the array of all changed tiddlers (or if it's the otherotherconfig), just refresh the children based on this widget and the changed tiddlers
//see widget.js how the refreshChildren method looks like
return this.refreshChildren(changedTiddlers);
};

So, the refresh method basically makes changes in your configuration in user-land update the configuration in your widget

[PMario]

Hi Stefano,

New tabs in the ControlPanel can be created, if you add the tag: $:/tags/ControlPanel

to your tiddler.

Be sure you also add a caption, otherwise the title would be shown in the tab!!!

have fun!

mario

[stefano franchi]

On Wed, Feb 13, 2019 at 11:30 PM stefano franchi <stefano...@gmail.com> wrote:

Never mind again, got it from the Railroad plugin:

1. Create the panels the make up the various tabs of the plugin page

In  the plugin.info file, add a "list" field with the names of the panels, then create corresponding tiddlers with prefix

$:/plugins/yourName/yourPlugin

 

I thought the above would be enough to get the aux files (Usage/Doc, etc) to show up as tabs in the plugin page, but apparently it isn't.

I can't find anything else in the core plugins to explain how the tabs are created. No additional info in the tiddlywiki.files, no tags in the tiddlers themselves, etc.

Suggestions appreciated.

 Cheers,

S.

[Matthew Lauber]

That should be correct.  Keep in mind, in the list field, the file will be named "readme" but the shadow tiddler needs to be named "$:/plugins/yourName/yourPlugin/readme"

Matt

[stefano franchi]

On Thu, Feb 14, 2019 at 2:49 PM Matthew Lauber <ma...@mklauber.com> wrote:

That should be correct.  Keep in mind, in the list field, the file will be named "readme" but the shadow tiddler needs to be named "$:/plugins/yourName/yourPlugin/readme"

My bad. I was using an overly complicated naming scheme and had made a mistake. Thanks for pointing out my understanding was correct and directing me to the real problem.

Cheers,

S.

 

[Mohammad Rahmani]

Stefano,

 Could you please bruch up the procedure based on the received comments. I would like to add it to TW-Scripts.

Cheers

Mohammad

[stefano franchi]

On Fri, Feb 15, 2019 at 12:04 AM Mohammad Rahmani <mohammad...@gmail.com> wrote:

Stefano,

 Could you please bruch up the procedure based on the received comments. I would like to add it to TW-Scripts.

Well, there isn't much to write up. As always the solution is simple once it's been found...

But here we go:

1. How to create the panels that make up the various tabs of the plugin page. It takes three steps:

 a - In the plugin.info file of the plugin you are writing, add a line with "list" followed by a list of your panels in double quotes.

      In my case I wanted 6 panels: readme usage syntax example license and config. So I added this line:

      "list": "readme usage syntax example license config"

b. Create the files corresponding to the panels in the "files" subdirectory of your plugin, as plain text, or in wikitext, or HTML.

    I wanted them in a separate dir to keep everything uncluttered, and i put them in a new subdir files/doc 

    So I created 6 new files: files/doc/readme.txt, file/doc/usage.txt, etc. and put some filler text in each just o be sure I could test if they showed up in TW

c. Finally, in the tiddlywiki.files file in your files subfolder, add a block for each one of the new file you have created, making sure the last part of the

   "title" field is identical to what you wrote in the "list" line of your plugin info, while the first part is the identifier of your plugin: $:/plugins/yourName/YourPluginName/. In my case,

    I am working on a plugin called "sgfeditor", and the name I am using is "cleinias", so the name prefix is always "$:/plugins/cleinias/sgfeditor" .

   For example, to add the content of the files/doc/readme.txt file as a "readme" panel, you would add the following block to the tiddlywiki.files file:

   

         {
            "file": "doc/readme.txt",
            "fields": {
             "type": "text/plain",
                "title": "$:/plugins/cleinias/sgfeditor/readme"
                        }
                       },

   Notice two important things: (1) the path in the "file" line is relative to the files sub directory, NOT to the plugin directory.

   (2) The last part  of the can title (i.e. "readme") can actually be anything you want, AS LONG AS it corresponds to one of the

    item in th e"list" line of plugin.info file. For instance, you could have your readme info in README.txt (following usual

    conventions), and then "readme" in all lowercase and no ext in the "title" field.

2. How to create a settings for my plugin that would either be added to the control panel or be accessible from the plugin page
   To have the settings accessible from the config panel, you need to create a config file and then tag it with $:/tags/ControlPanel as PMario said. If you want it as

  a tab (panel) in the plugins page add it to the "list" line in plugin.info.

   In either case, the basic procedure is the same as above: create a file in the format of your choice (see point 3 below) in the "files" subdir of your plugin, then add a block describing

   it in the tiddlywiki.files in the files subdirectory. If you go for the config panel, you also add a line with "tags": "$:/tags/ControlPanel" . I went the second route, and decided to put my settings  in  a "config" panel of the plugin, and to use the json format. So I created config.json, added "config" to the "list" line in plugin.info and added this block to tiddlywiki.files:

            {
            "file": "config.json",
            "fields": {
                "type": "application/json",
                "title": "$:/plugins/cleinias/sgfeditor/config"
                        }
              },

   Notice that I changed the type to the correct json MIME type.

3. How to access said settings from the plugin code:

   I haven't tried to access the settings from the config panel, so I cannot say anything about it. I only had to add two lines to read the config tiddler from  my plugin code (I  copied them from the railroad plugin):

 

// getTiddlerData reads a Json file into a javascript object:   

var config = $tw.wiki.getTiddlerData( "$:/plugins/cleinias/sgfeditor/config")  

Then for every setting, I provide three options: the value in the config panel, the value possibly present in a corresponding field of the tiddler the plugin widget is working on, or a default value I set in code (this is also copied from the railroad plugin). So I have an object that reads all the config parameters:

        var options = {
            size         :  this.getAttribute("size", config.size || 19),
            panels     :  this.getAttribute("panels", config.panels || ['control', 'names', 'comment', 'tool', 'tree', 'file'])

     ...... and do on

   That's all.

Cheers,

S.

  

[Mohammad Rahmani]

Thank you!

Added to TW-Scripts