๐ In-browser Tiddlywiki 5 plugin development support plugin
The Third Flow plugin brings to you another way to develop customizations for TiddlyWiki 5. It is not enforcing a specific development flow, it simply tries to help you. Otherwise, it tries to stay out of your way. You can develop some parts of your plugin inside the browser, and other parts in your favorite code editor -- get the best of all worlds.
You can develop your plugin directly from within your browser. A server-based
TiddlyWiki instance running on Node.js ensures that all your source tiddlers are
neatly stored in a clean and hierarchically organized folder structure.
$ npm run develop
is your friend.
Source code management is done as usual using your favorite source code
management tool, such as git
. As the Third Flow plugin neatly structures your
tiddler source files, you'll get a well-organized repository structure at no
price.
For packaging your plugin you finally simply run a shell script which
packs the plugin tiddler and saves it to disk. Additionally, you may opt to
create an additional demonstration TiddlyWiki to teach your future plugin users
how to use your AWESOME plugin. npm run release
is all you need.
Of course, the Third Flow plugin is developed using the same process it supports. We actually eat our own dog food.
Enough words for now, let's follow the old proverb that ยซa single figure lies more than a thousands wordsยป...
(1) Development:
(2) Source Code Control:
git
and GitHub.(3) Release:
While working on the source tiddlers of a plugin from within a web browser, the ThirdFlow plugin lends you a helping hand.
For instance, there's a new tab called "Plugin Sources". It lives inside the sidebar's "More" tab, and it shows you all your plugin source tiddlers neatly listed in order. But more importantly, this additional view is much more concise than the existing "System" and "Shadows" views. The latters are fine when you need to see everything. But they are unwieldy while focusing on your own plugin(s)s. That's exactly what the additional "Plugin Sources" view is about.
Creating a new plugin is now also now easier than before. Simply go to the "Plugin Sources" tab in the sidebar. Then click on "+ new plugin", which you'll find right at the top of the view.
With the new plugin tiddler being shown for editing, simply fill in the fields. Make sure to replace PublisherName and PluginName with something more sensible. You should notice how the Plugin Meta Data fields update accordingly.
And then you're done. Well, for the plugin itself. Now you can start populating your new plugin with cool new tiddlers.
First, you should add the standard boilerplate tiddlers readme
, license
and history
. You may notice that there's already an action for this appearing
for your still empty plugin.
Simply click on it and you get the boilerplate tiddlers opened in the right places, ready to be edited.
To speed up your plugin development, ThirdFlow offers to create certain types of tiddlers in well-known places inside your plugin, giving you an easy start by filling in template code.
When you're ready to release, first configure what to release. That's easy, simply go to the Control Pane and open its "ThirdFlow" tab. Then click on its "Release" sub-tab.
Check the plugin you want to release and set their filenames. Optionally, check the "demo wiki" and also set its filename.
Then switch to a terminal session and simply run npm run release
to generate
your release files inside the editions/release/output/
folder.
The easiest way to get started with your own plugin development is to clone the dedicated skeleton repository on GitHub, and then use that:
$ git clone https://github.com/TheDiveO/TiddlyWikiPluginSkeleton
$ cd TiddlyWikiPluginSkeleton
$ npm install
$ npm run develop
Navigate your browser to localhost:8080 and start developing your plugin. You'll now be greeted with the shiny new "Plugin Kickstarter" tiddler. Fill in the fields and follow its instructions by clicking through the few steps to create a new plugin.
NOTE: you can change the default port on which the development server can be reached to a different port by either specifying a different port as an argument:
$ npm run develop --tw5-thirdflow:port=9999
...or by constantly changing the configuration value:
$ npm config set tw5-thirdflow:port 9999
Use
npm config delete tw5-thirdflow:port
to restore the default setting.
Also make sure to visit the ThirdFlow tab in the Control Panel, and its Release tab. Enable the creation of release file and set their filenames. And then, simply run:
$ npm run release
The release files are to be found inside editions/release/output
.
First clone this repository, then change into it, and finally run npm install
inside it to get the whole shebang set up correctly.
$ git clone https://github.com/TheDiveO/ThirdFlow.git
$ cd ThirdFlow
$ npm install
Then run the development server for ThirdFlow itself:
$ npm run develop
...and open localhost:8080.
As mentioned above, you can change the port on which your develop server can be reached, either temporarily:
$ npm run develop --tw5-thirdflow:port=9999
...or permanently.
$ npm config set tw5-thirdflow:port 9999
Use npm config delete tw5-thirdflow:port
to restore the default setting.
The Third Flow plugin is covered by the following licenses:
The Third Flow plugin is licensed under the MIT license.
The hierarchical file system adapter is licensed under the TiddlyWiki 5 license (links to GitHub TW5 repository). It bases on filesystemadaptor.js and brings in storing tiddlers into hierarchical folder structures according to their titles.
Other content of this TiddlyWiki which is not part of the plugin or TiddlyWiki 5 is covered by the CC BY 3.0 license.