Documentation for plugin authors

Nao

  • Dadman with a boy
  • Posts: 16,079
Re: Add-on Manager: Mechanics
« Reply #15, on September 23rd, 2011, 12:26 PM »
Now we'll be able to move this to the Wedge documentation and split it into several areas or something because it's probably a bit too monolithic to digest... ;)

dorje

  • Krabi krabong: the wedge of martial arts. :P
  • Posts: 97
Re: Add-on Manager: Mechanics
« Reply #16, on September 30th, 2011, 11:47 AM »
Well... I think that it is a great way to manage the add-ons.

You know: I feel my itchy hands cannot wait to write something... :eheh:
Krabi Krabong & programming :D

Arantor

  • As powerful as possible, as complex as necessary.
  • Posts: 14,278
Re: Add-on Manager: Mechanics
« Reply #17, on September 30th, 2011, 01:52 PM »
:)

Same here, I now have a very large list of plugins I want to write, and over the next few days I'll probably bash a few of them out because the only way I can prove the system works, and spot any holes in it, is to actually thoroughly use it.

I do already foresee one problem: folks who have masses of things installed - it's going to make a very long page, so I might have to do something about that, but that's the sort of thing only experience can teach, as theory only goes so far.

I have to admit, I have browsed through the list of mods for SMF lately, to see the different sorts of things people have done, which has given me a variety of ideas, and already highlighted a couple of weaknesses that can readily be addressed and a couple of things that do need refinement in the system (not specifically plugin related)

I'm going to find it interesting going back over my old mods though, to see how cleanly they can be rewritten ;)
Re: Add-on Manager: Mechanics
« Reply #18, on September 30th, 2011, 03:10 PM »
I just realised a weakness in the system that hasn't been accounted for: new actions.

Right now in order to add new actions, a file still has to be loaded (or already have been loaded) to extend the action array. Now, properly complex action juggling is going to have to remain in the hook behaviour (like what WD does, until I add more hooks :D) but for simple hook behaviour there's no need for having to load a file.

What I'm thinking is that there would be an <actions> block:

Code: [Select]
<actions>
   <action action="myaction" function="myfunction" file="$plugindir/MyFile.php" />
</actions>

On a technical level, I'd push that into the per-plugin cache in $modSettings['plugin_' . *] as a new key, and pop it off the stack during the load phase.[1]

It's less of an issue for menu changes because menu changes all require more than a single line of code to define, so loading a file for those isn't the hassle it is for actions.[2]
 1. Yes, even before starting to post, I'd already assessed all the technical implications :P This is more of a pre-flight warning as to what I'm going to implement...
 2. Your choices are to have a tiny file just for the action change plus the action itself as a separate file, minimising parsing but has the file overhead, or to have a single file that contains the action's code as well but then you have to load a larger file every single page load, unnecessarily in most cases.
When we unite against a common enemy that attacks our ethos, it nurtures group solidarity. Trolls are sensational, yes, but we keep everyone honest. | Game Memorial

Nao

  • Dadman with a boy
  • Posts: 16,079
Re: Add-on Manager: Mechanics
« Reply #19, on September 30th, 2011, 03:19 PM »
A template block? You mean using the ui to store non-ui data? I'm sure we could think of something more elegant..?

Arantor

  • As powerful as possible, as complex as necessary.
  • Posts: 14,278

Nao

  • Dadman with a boy
  • Posts: 16,079
Re: Add-on Manager: Mechanics
« Reply #21, on September 30th, 2011, 03:25 PM »
Oh you mean in plugin-info.XML? You had me confused with blocks ;)

Arantor

  • As powerful as possible, as complex as necessary.
  • Posts: 14,278
Re: Add-on Manager: Mechanics
« Reply #22, on September 30th, 2011, 03:27 PM »
Uh, yeah... you wouldn't store that stuff in the UI anywhere, it's purely in the XML for a given plugin, and avoids having to include a file just to have a function with one line in it.

Nao

  • Dadman with a boy
  • Posts: 16,079

Arantor

  • As powerful as possible, as complex as necessary.
  • Posts: 14,278
Re: Add-on Manager: Mechanics
« Reply #24, on September 30th, 2011, 03:46 PM »
No worries - with the mad late-summer heat here it's entirely possible I'd got confused. You know what they say about mad dogs and Englishmen and the mid-day sun, right? We've just had mid-day sun run on for much later in the day at the moment :(
Re: Add-on Manager: Mechanics
« Reply #25, on September 30th, 2011, 06:03 PM »
OK, so today I've been working on a DTD for the plugin XML format, to describe what it should contain and in what order.

The real question I've been wrangling with is whether I should enforce the order of things in the file, e.g. <hooks> can contain 1+ function tags, 1+ language tags and 0 or 1 provides tags. Now, in my example files and all my own files, I've always put functions first, then language files, then provides tags.

Now, the parser itself doesn't care too much, it's built to be more forgiving, but I'm thinking that it shouldn't be so forgiving, that having a set process/standard will encourage better behaviour than being more forgiving, so that I'm thinking about the DTD validator being more strict.

So, for example, I wouldn't have it enforce the order of most tags, but stuff like <hooks>, I'd enforce the order like that.

Thoughts?


Disclaimer: there is a secondary reason for doing it like this: it's actually a pain in the arse writing a DTD that has rules where there are mandatory tags and optional tags, and that there isn't a set order because you have to define all the possible permutations.[1]
 1. Like the DTD definition for the HTML head tag, as it has to state a mandatory title tag, an optional base tag and 0+ optional other tags, and that's still a multi-line definition through a %entity replacement.

Dragooon

  • I can code! Really!
  • polygon.com has to be one of the best sites I've seen recently.
  • Posts: 1,841
The way it's meant to be

Arantor

  • As powerful as possible, as complex as necessary.
  • Posts: 14,278
Re: Add-on Manager: Mechanics
« Reply #27, on September 30th, 2011, 06:16 PM »
Well, the document is very much WIP, so it's not like I can't make it unordered, just I get the impression that if I force it to be in more set orders, it'll encourage authors to be more thorough. Especially if I add validation into the upload/publish process :niark:

Nao

  • Dadman with a boy
  • Posts: 16,079

live627

  • Should five per cent appear too small / Be thankful I don't take it all / 'Cause I'm the taxman, yeah I'm the taxman
  • Posts: 1,670
Re: Add-on Manager: Mechanics
« Reply #29, on October 1st, 2011, 06:37 PM »
Will there also be a XML block for inserting new rows into the database?
A confident man keeps quiet.whereas a frightened man keeps talking, hiding his fear.