standardized plugin/macro templates

[FND]

Hi all,

I've noticed some people (noticeably Simon[1] and Martin[2]) have looked
into creating a template for creating plugins and/or macros.
Having intended to do this myself for ages, I think we should combine
our efforts and create a universal template for this purpose.

Having a consistent structure for all plugins would probably also help
with the upcoming plugin library.

I've already started creating the basic framework for this:
http://www.tiddlywiki.org/wiki/Dev:Plugin_Template
All that's left, really, is making sure all fields (for the meta table
and documentation) are covered. The code samples should be easy.

As a final goal, it'd be nice to have a simple HTML page (or TW plugin)
with a bunch of input and textarea fields to compile ready-made
templates on demand.

-- F.

[1] http://tinyurl.com/25a4cg
(http://simonmcmanus.wordpress.com/2007/10/16/macro-template-for-tiddlywiki/)
[2] http://tinyurl.com/2a5k75
(http://trac.tiddlywiki.org/browser/Trunk/contributors/MartinBudden/plugins/ExamplePlugin.js)

[dawn ahukanna]

How about having the main fields (not the documentation, notes etc) as properties of the plugin/macro using the version.extensions object?
e.g.
...
!Code
***/
//{{{
version.extensions.foo=
{
major: 2,
minor: 1,
revision: 0,
date: new Date("Jan 2, 2007"),
code: "http://localhost/tiddlywiki.htm#Macro",
doc: " http://localhost/tiddlywiki.htm#MacroDoc",
author:"<Name> <email>",
summary:"<short 10 word summary>",
description: "<short description of a few sentences>",
coreVersion: "<Minimum supported Tiddlywiki version"
};

config.macros.foo = {};
config.macros.foo.handler = function(place, macroName, params, wikifier, paramString, tiddler) {
/* ... */
}

The detailed documentation can go in a separate tiddler.

Then all you need to do is have a plug-in that will automatically generate the field documentation in a standard format by inspecting the plugins.  It also means the code has some basic self-documentation and the plugin library generation can use the same structure.

What do you think?

Dawn.

--
http://dahukanna.net

[FND]

> How about having the main fields (not the documentation, notes etc) as
> properties of the plugin/macro using the version.extensions object?

I'm not sure what the benefit of this would be*; the "meta table" can
already be parsed/interpreted.
It should be easy to adapt getPluginInfo() and/or getTiddlerSlices() for
pretty much any language (in the case of the Plugin Library, probably
Ruby or PHP).

> Then all you need to do is have a plug-in that will automatically
> generate the field documentation in a standard format

I'm not sure I follow; why a plugin? If anything, it'd probably be a
core component, automatically inserting the meta table when rendering
systemConfig tiddlers. (Obviously, regular users should be able to view
the meta table without having to dig into the code.)
But that seems like a lot of unnecessary overhead!?

-- F.

* I'm probably the only one who'd care about a consistent order for the
fields' presentation...

[dawn ahukanna]

It doesn't have to be a plugin that is used to generate the documentation, it was just an example. The main point I was trying to make is that the formating of the standard documentation can be separated and from the actual content.
The metatable can then be generated from the plugin code as will always be present, is guaranteed to be consistent with the code and is available to ordinary users.

Dawn.

--
http://dahukanna.net

[Xavier Verges]

On Oct 19, 3:24 pm, "dawn ahukanna" <dawn.ahuka...@gmail.com> wrote:
> The metatable can then be generated from the plugin code as will always be
> present, is guaranteed to be consistent with the code and is available to
> ordinary users.

I like the Don't Repeat Yourself idea, so it makes lots of sense that
the same info is not at the same time in the metatable and in the
code.

However, I'm under the impression that things are is simpler if the
single source of truth is the metatable, and that the few plugins that
need access to the metadata do it by quering the parsed metatable.

Worthless 2c from someone that has never published a plugin .-)

-Xv

[dawn ahukanna]

Xavier,
That's a fair comment.

Dawn.

--
http://dahukanna.net

[Jeremy Ruston]

The reason that we encode the plugin metadata as slices rather than as
part of the version.{} object is so that we can inspect the metadata
without having to execute the plugin, potentially exposing security
risks. In the future, if we added plugin signatures for security, this
approach would enable us to scan and verify plugins before execution.
It also makes it easier for server side crawlers to pick out the
metadata without needing to be able to execute javascript.

Cheers

Jeremy

--
Jeremy Ruston
mailto:jer...@osmosoft.com
http://www.tiddlywiki.com

[FND]

I've put some more thought into this, and think that a standardized,
consistent structure for plugin tiddlers is necessary for two reasons:
* provide guidelines for new TiddlyWiki developers
* simplify automated aggregation (e.g. for the plugin library)

I have attempted to record the current implicit consensus on the
community wiki:
http://www.tiddlywiki.org/wiki/Dev:Plugin_Template

Naturally, that list is probably incomplete and contentious.
However, it is not supposed to be comprehensive. For example, individual
plugin authors can add custom meta-table fields (e.g.
"BookmarkletReady") to their plugins if they like.
Nevertheless, constructive criticism is very welcome!

Once we have an explict consensus on this, I'd like to whip the official
plugins into shape* to provide a practical reference.

-- F.

* cf. http://groups.google.com/group/TiddlyWikiDev/t/53c0b136c5b3eddb/