User:Salvatore Ingala/Notes

= Intro = Scope of the project is to make gadgets customizable, that is:
 * Allow gadget writers to easily export their gadget's customization variables.
 * Provide the users with a nice UI for customizing those variables.

This page contains a newer design than the one I proposed in my application, since the scope of the project has slightly changed.

Places
I'm working on this branch: http://svn.wikimedia.org/viewvc/mediawiki/branches/salvatoreingala/Gadgets/ Previous brainstorming was done on EtherPad. This is the last useful revision.

= Features definition = These are the needed features:
 * 1) Ability to specify what preferences do we have for a gadget;
 * 2) *Will do this in JSON format.
 * 3) *Where? For now, I'm using a fixed page MediaWiki:Gadget-mygadget.preferences or something similar. Likely to change (with low impact)
 * 4) *Supported field types should probably be all those of HTMLForm.php, and some other. It's not impossible to use HTMLForm to generate the HTML of the configuration interface (delivered on-demand via AJAX calls), but it will likely become a mess. It's probably safer to do that independently. Maybe useful:
 * 5) **http://docs.jquery.com/Plugins/validation
 * 6) **http://jquery.bassistance.de/validate/demo/
 * 7) *STATUS: implemented with HTMLForm (just for a mockup), buggy and with (very) minimal validation; only works with simpler field types.
 * 8) Hooking up to Special:Preferences to add per-gadget prefs
 * 9) *Currently done like this: every enabled gadget shows a "configure" link near his checkbox in Special:Preferences. Clicking on the link pops up a modal dialog with the configuration interface. Saving preferences for that specific gadget could be done when closing the dialog. This should be robust against future changes of Special:Preferences.
 * 10) *STATUS: incomplete-but-working UI mock-up
 * 11) Store preferences somewhere
 * 12) *Currently using the existing user_properties table. This solution implies that we must hook UserLoadOptions to hide the fields when they are read from the DB (or they will be delivered to mw.user.options like any other preferences, and we don't want this).
 * 13) *Unused preferences need to be deleted. Saving policy to maintain coherency:
 * 14) **When saving the configuration of a gadget, throw away any previous configuration for that gadget (so to clean up old values for no-longer-existing settings).
 * 15) **When reading the configuration of a gadget, check it against its specification and assume default for missing values or values that fail validation (if specifications changed).
 * 16) *STATUS: implemented in mockup (little to no validation, efficiency issues; needs much more work)
 * 17) Provide the preferences to gadgets. Concepts:
 * 18) *mw.gadgets.options.get( 'gadgetname' )?
 * 19) *mw.loader.options.get( 'modulename' )?
 * 20) *binding the configuration to this in gadget's context. (may have issues with RL2, unreliable for now)
 * 21) *STATUS: currently binding the configuration to this, which is my preferred solution :P - It's easy to switch to any other version. Current implementation doesn't honor declared datatypes (always returns strings).
 * 22) Internationalization of strings used by the gadget
 * 23) *There are two types of "messages" to handle:
 * 24) *#messages shown in the configuration dialog; these don't need to be passed to the gadget's module, and may be interpreted server-side, when building the dialog code during the AJAX request. Should fetch their names form the configuration JSON (maybe adding some common prefix);
 * 25) *#other messages used by the gadget; this is in the scope of RL2.
 * 26) *STATUS: unimplemented