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.
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"
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.
> 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.
> 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...
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.
> > 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...
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 .-)
> 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 .-)
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
On 10/19/07, dawn ahukanna <dawn.ahuka...@gmail.com> wrote:
> On 10/19/07, Xavier Verges <xver...@gmail.com> wrote:
> > 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 .-)
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)
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.
