plugin Generator (single file wikis) RFC

[TonyM]

Folks,

Request for Comment from plugin builders.

I am building a generator to create all related tiddlers when building a plugin. I am doing this because I will be migrating dozens of macro solutions to plugins.

This post is seeking input, the result will be shared.

The basic functionality is as follows;

• Designer provides a 
• plugin prefix "$:/plugins/brand/"
• and Project name "myproject/" 
• Then a set of tiddler titles will be generated as follows
  $:/plugins/brand/myproject
  

readme $:/plugins/brand/myproject/readme Standard

usage $:/plugins/brand/myproject/usage Standard

docs $:/plugins/brand/myproject/docs     Optional for more complex

macros    $:/plugins/brand/myproject/macros $:/tags/Macro

config $:/plugins/brand/myproject/config connect to config tiddlers

examples $:/plugins/brand/myproject/examples Example documentation +

settings $:/plugins/brand/myproject/settings alternative to config

license $:/plugins/brand/myproject/license MIT default

styles $:/plugins/brand/myproject/styles $:/tags/Stylesheet

data $:/plugins/brand/myproject/data Dictionary tiddler of config values etc...

keyboard $:/plugins/brand/myproject/keyboard (Document any keys defined)

history $:/plugins/brand/myproject/history (version release history)

• There will be a set of tiddlers to use or configure as the source for each of these tiddlers.
• You can exclude any tiddler you do not want
  
• Each tiddler can be created one at a time or generated from a source tiddler
• Other tiddlers can be added to the list including config tiddlers $:/config/tiddlername
• Tiddlers can then be customised with standard edit
• A filter will be generated for use in the Tinka Plugin
• Where possible I will populate the tinka values
• You then generate the plugin using Tinka

Any thoughts additions or deletions, templates etc.. please share.

Regards

Tony

[Mohammad]

I would absolutely recommend Thirflow

--

Use the Third Flow plugin in your Node.js-based TiddlyWikis to develop your customization plugins inside TiddlyWiki but with support for well-structured source code repository layouts.

The Third Flow plugin supports your plugin development in that it organizes all your tiddler source files into a clear hierarchical folder structure based on tiddler titles. An additional plugin creation command module makes it easy to create the package plugin itself as well as a demonstration TiddlyWiki without the hassle of having to maintain separate and even multiple tiddlers/ and plugin/ folders. Also, the Third Flow relieves you from shuffling tiddler source code files around in your source code repository.

There's only a single tiddler source code tree and it is synchronized to your tiddler's title-based structure. Thus, no more need for external editing sessions and source file shuffling.

Simply install this plugin into your TiddlyWiki in which you are developing your customizations. For more information, please go to the Third Flow project website.

You can use the new File Storage control panel tab to configure how your tiddlers get organized into folders and subfolders in your source code repository.

Enjoy the Third Flow!

---

[PMario]

On Monday, January 13, 2020 at 8:09:11 AM UTC+1, TonyM wrote:

..

examples $:/plugins/brand/myproject/examples Example documentation +

Examples should be shown in an edition to avoid plugin bloat.

Usage needs to be enough to show all functions. It should also contain a link to the edition.

-m

[TonyM]

Mohammad,

Whatever my long term choice do share if you see any essential content missing from my Original Post.

Third flow seems a great long term investment in the life of a plugin developer. It however needs me to build on top of node, be familiar with file based organisation and more. I may still go that direction but I note my own work would be adding more within ThirdFlows Plugin Boilerplate, and Adding template tiddlers for Plugin Field Details

which I do not yet know how customisable it is.

I see in part how you manage to be so productive and generating plugins, with demo and release.

My dilemma here is the the choice I need to make between continuing my own solution or investing the time to adopt Third Flow. In my case I have dozens of macros and wikitext based solutions, without javascript, that I currently store as bundles, that I would like to publish. As a result any productivity gains I can find will reduce the publishing effort. It feels that third flow requires an investment and despite it saying "all in the browser" it requires command line and file/folder structures outside the browser. The investment in third flow would be needed by future designers of simple plugins, yet should I develop and intermediate solution?

Finally in the long run I see opportunities with my own tool to develop a concept where by a plugin is imported to serve a development function, during its use it can be customised, enhanced such that in each use it evolves more features, is regenerated and used in the next project. In this use the requirements of third flow are too disruptive. This is in keeping with my deep interest in rapid development, "set based" iterative design processes.

Regards

Tony

[TonyM]

Mario,

Thanks for the tip. Perhaps I need to add a scope or something to "examples", in the case of my current intended plugins most will provide a solution but also be generic enough to be used in other ways, I thought I would use examples like an extended usage document (sometimes). But as you suggest if it was more than a few KB it would be best in an edition. Do you agree?

Regards

Tony

[PMario]

Hi Tony,

I try to be as minimalistic with the plugin as possible. ... BUT ... There should be enough info, that an experienced user has enough info to adjust the basic settings.

eg: my tocP plugin. has a readme, which should be enough to get you going. ... BUT if you want to tweak every aspect you need to open the edition, which has more details. So a link to more DOCs is recommended.

If you have a look at the license tab in the plugin, you'll see, that I don't include the full license text. Just the "dynamic" header + a link to the generic text. If the license is "strict" I do include more info.

have fun!

mario

[TonyM]

Mario,

Thanks for this advice. 

Before I go and make these plugins I want to let you know they are all macros and in json bundles already if not without readme and licences.

I wonder if we should make bundle distribution more common, rather than me moving to plugins, although plugins have the advantage of deleting modified tiddlers reverts to the shadow. It's also nice to pack multiple plugins in a bundle.

I have thought of making the import process bundle aware. So the description, filter and more will be displayed before import.

Regards

Tony

[Mohammad]

Tony!

 I think the simplest for you is to use Tinka!

Tinka lets you to work in browser with single html and simply add remove your tiddlers.

Get Tinka from: https://tinkaplugin.github.io/

Best

Mohammad

[PMario]

On Tuesday, January 14, 2020 at 1:08:18 PM UTC+1, TonyM wrote:

...

Before I go and make these plugins I want to let you know they are all macros and in json bundles already if not without readme and licences.

Yea, bundles need a bit more info and may be a better interface.

 

I wonder if we should make bundle distribution more common, rather than me moving to plugins, although plugins have the advantage of deleting modified tiddlers reverts to the shadow. It's also nice to pack multiple plugins in a bundle.

The "shadow" behaviour is key for plugins. Where the "normal" tiddler behaviour is key for bundles. ... As above better UI would help.

 

I have thought of making the import process bundle aware. So the description, filter and more will be displayed before import.

The problem with the existing import process is relatively deeply berried in the core. If the import mechanism "deactivates" a tiddler its content is physically deleted. So if you re-enable the checkbox _nothing_ happens. .. That's a big systematic problem.

-m

[Jeremy Ruston]

Hi Mario

On 14 Jan 2020, at 18:14, PMario <pmar...@gmail.com> wrote:

The problem with the existing import process is relatively deeply berried in the core. If the import mechanism "deactivates" a tiddler its content is physically deleted. So if you re-enable the checkbox _nothing_ happens. .. That's a big systematic problem. 

Can you explain that a little more? Clearing the checkbox in the $:/Import tiddler does not affect the incoming tiddler, and it can be re-enabled as expected.

Best wishes

Jeremy.

[TonyM]

Mario,

Additional UI for bundles should be trivial. I would be keen to respond to incoming bundles and present a little more bundle information and notes. I like to include the .bundle tiddler in the bundle and place metadata on it.

Of note is many plugins will behave more like bundles in 5.1.22 because of less cases where a reload is required.

When using bundles my existing solutions all live under $:/PSaT/solutionname because it would misrepresent them to place them under plugins. This is part of the current thread, the process of migrating bundles to plugins requires the namespace change.

Regards

Tony

[PMario]

See: system.js and plugins.js

I'm OK, that some plugins are blocked, but I don't see, why I shouldn't be able to load "older" plugins again, if I know, what I do.

The same is true for System-tiddlers, where it isn't possible to open a special CotrolPanel-tab with a tiddlers.json file, because /state/ and /temp/  tiddlers are deleted. So enabling the checkbox doesn't restore the tiddlers.

Being able to import state tiddlers would be extremely helpful here in the list, if I want to point to a specific app-state.

-mario

[TonyM]

I agree Mario;

Especially when there is a check box you can tick in front of temp and state tiddlers if there are such tiddlers in the import. 

The check boxes are not honored so perhaps its a bug?

[prefix[$:/state]] [prefix[$:/temp]] can export them and they are listed on import, but checking the item for import, fails to import them.

Fixing this should still be backwardly compatible, as the user chooses with check boxes. If they do they should be permitted, if they done they will not be imported.

Regards

Tony

[PMario]

On Wednesday, January 15, 2020 at 6:15:59 AM UTC+1, TonyM wrote:

...

The check boxes are not honored so perhaps its a bug?

At the moment it's "by design" or by code, if you have a look at the links. see: tiddlers[title] = Object.create(null); which deletes them.

 

[prefix[$:/state]] [prefix[$:/temp]] can export them and they are listed on import, but checking the item for import, fails to import them.

That's my point, which started to be an issue as I did create the bundler plugin. ... I think it would be cool to create a post here in the group, with a tiddlers.json attachment, that says:

 - Import this file

 - Check all the tiddlers for importing

 - Hit the import button

and it will show you $:/ControlPanel : Appearence : Toolbars : Editor Toolbar. ... You can change settings there.

 

Fixing this should still be backwardly compatible, as the user chooses with check boxes. If they do they should be permitted, if they done they will not be imported.

That's done automatically. The existing code will "uncheck" them, but it should keep the content. The user is responsible if s/he enables them again.

 

-mario

[PMario]

Hi

I do have a similar issue with the upcoming "stories" extensions. Stories can be saved and imported. .. I think it should be possible, to import _and_ activate them, in 1 go, if the user enables importing of $:/StoryList

I'm OK if the default import mechanism disables everything, that can create unexpected behaviour. I do like "the principle of least surprise" but I also like: The user is in control.

-m

[TonyM]

Mario,

Thanks for sharing "the principle of least surprise" great stuff.

To be clear, since the temp and state tiddlers are automatically "unchecked", if the import mechanism honored checked temp and state tiddler (not deleting them) then the user importing the tiddlers can choose. 

Am I wrong? This is a functional limitation or bug, whos repair remains backwardly compatible, makes it behave as expected and will introduce new functionality?

The functionality we seek is being able to import configurations, or current state.

By the way my existing method is making a bookmarklet, this works very well, but it is a practice that must occur outside tiddlywiki in the browser.

Are we in furious agreement?

A Work around or method could be an alternate import button tiddler tagged with a special system tiddler (I cant find which one) that would allow a full import.

Tony