262037 - (czpluginapi) we need a better plugin API

Status: RESOLVED FIXED

(Other Applications Graveyard :: ChatZilla, defect)

Description

[Samuel Sieb]

First draft:
ChatZilla provides "PluginAPI" containing the version number in the plugin's scope.

The plugin on loading must set a variable named "API" in the scope containing
the version number that it provides.

API version 1:
plugin must provide the following functions:
initPlugin: does any initialization the plugin needs, but does not enable it.
enablePlugin: does whatever is required to activate the plugin.  returns a
boolean indicating whether or not the plugin was successfully enabled.
disablePlugin: does whatever is required to deactivate the plugin.  returns a
boolean indicating whether or not the plugin was successfully disabled.

ChatZilla will provide the following capabilities:
on the first load of the plugin, it will attempt to enable the plugin.
it will remember the state of the plugin, and on following loads, it will enable
the plugin only if it was enabled the last time ChatZilla was closed.
enablePlugin will not be called if the plugin is already enabled.
disablePlugin will not be called if the plugin is already disabled.

Comment 1

[John J Foerch]

I want to suggest that the variable containing the API version be plugin.API
rather than plugin.scope.API.  We already have variables, plugin.id,
plugin.description, plugin.version, &c.  In other words, this new variable
should be in the same scope as the id, description, and version, rather than the
variable-space of the plugin itself.

Comment 2

[Robert Ginda]

The reason these functions were in the global scope the first time around, is
that I assumed it would be easier for the unwashed masses to understand.  I'm
not really tied to that though.  Moving them to the plugin object could be a
good way to distinguish old/new style plugins.

Comment 3

[Samuel Sieb]

Draft 2:
Remove the requirement for the API variable.
Instead, the functions must be put on the plugin object.
initPlugin -> plugin.init
enablePlugin -> plugin.enable
disablePlugin -> plugin.disable

This will enable chatzilla to determine if it's a new plugin or an old plugin.

Comment 4

[Samuel Sieb]

Update:
plugin.id must be set to a unique name for the plugin.  The only valid
characters for the id are A-Z a-z 0-9 and _.
The plugin's prefs will be found at extensions.irc.plugins.<id> in the pref tree.
ChatZilla will set plugin.prefs and plugin.prefManager to be the prefs branch
and pref manager for the plugin.

Comment 5

[Samuel Sieb]

Oops, "-" is also valid in the id.

Comment 6

[Samuel Sieb]

More details on prefs:
An inital prefs array will be created before calling init() and stored in
plugin.prefary.  The init() function can add any more it needs to that array and
the prefManager will be created after init() returns.
If there is a function called plugin.onPrefChanged, then it will be set as the
pref observer.

If anyone can come up with a reason why init() will need to be accessing prefs
instead of in enable(), then let me know because we couldn't come up with a
scenario where that would be necessary.

Comment 7

[Samuel Sieb]

One more thing to add since I'm sure it will be a FAQ if it's not included.
plugin.cwd will contain the url to the plugin's working directory.

Comment 8

[Samuel Sieb]

Attachment: new API

Comment 9

[Samuel Sieb]

Comment on attachment 162317 [details] [diff] [review]
new API

The "networks." part of the pref branch shouldn't be there and has been removed
locally.

Comment 10

[Robert Ginda]

Comment on attachment 162317 [details] [diff] [review]
new API

r=rginda

Comment 11

[Samuel Sieb]

Attachment: patch for checkin

Comment 12

[Samuel Sieb]

Attachment: id is not set, so we should not be searching for it

Comment 13

[James Ross]

The |id| is still being passed in... perhaps that could be changed to |url| or
dropped entirely?

Comment 14

[Samuel Sieb]

Attachment: update take 2

Comment 15

[Robert Ginda]

Comment on attachment 163178 [details] [diff] [review]
update take 2

How about dong the index assignment in the var declaration, instead of the if
() clause?

r=rginda with that change

Comment 16

[Glen Mailer]

this is mostly known, but just to have it written down:

/disable-plugin and /enable plugin both give errors due to attempts to set a
preference on old-style plugins when no preferences exist (enabled=false is the
pref)

Comment 17

[Samuel Sieb]

Attachment: Example plugin using the new api.

Not very useful, but shows how to use prefs, proper enable() and disable(),
etc.

Comment 18

[Samuel Sieb]

Attachment: fix enable/disable issues with oldstyle plugins

Comment 19

[James Ross]

Comment on attachment 165063 [details] [diff] [review]
fix enable/disable issues with oldstyle plugins

Checked in.

Comment 20

[James Ross]

I believe everything from this bug is now FIXED.

Comment 21

[Samuel Sieb]

Attachment: fixed version of example plugin

Comment 22

[Mickey]

please allow ALEXA tOOLBAR