ResourceLoader/Version 2 Design Specification


 * Initial work to sketch out this document are on the RL2 Etherpad
 * "Pseudocode Architecture Session" : RL2-GadgetAbstract

= Module sources = Tracking: bug 30022

= Gadget Manager = Tracking: bug 29398

Use-cases
By having a visual manager gadget managers will no longer have to learn yet another syntax to register gadgets and/or modify their properties. The Special-page will be able to log events which will enable users to easily see who changed what. They will be able to get that information chronologically for all gadgets (What has been done in the last few days?), or for one particular gadget (What happened to Gadget Foo ?). This is handled through  and. Over the last year more and more options have been added to gadgets and resource loader modules. There's about a dozen module properties and half a dozen Gadget properties (gadget title, description, and settings (required rights, enabled by default), module scripts, styles, dependencies, messages, and more..). Having them in a nicely designed form with responsive javascript interactions and suggestions will make it easier to understand and extendable without complicating the "Gadget syntax" (which will cease to exist). Through this interface, the process of 'Adding' (or 'Creating') a gadget will be as simple as a click. Aside from writing one from scratch another goal of the Gadget Manager is to enable easy exporting and importing of Gadget properties from one wiki to another. This is done through the JSON format which can be read and written natively in most browsers (and for other browsers an emulation module is present in SVN). Note however that duplicating is no longer intended to happen as much within the Wikimedia farm due to the new Shared gadgets feature, which no longer needs the local wikis to "copy" or "redirect" a gadget from a central place. If time and tech allows we might even implement an InstantCommons-like feature in MediaWiki which allows third party wikis to easily get useful gadgets, that are actively developed within Wikimedia, onto their own wikis.
 * Usability
 * Tracking
 * Extendable
 * Sharing

Storage of Gadget properties
The properties of each gadget will be stored in a new MediaWiki database table,. mysql> DESCRIBE mw_gadgets; +--+-+--+-+-+---+ +--+-+--+-+-+---+ +--+-+--+-+-+---+ There may be an additional column insert before  (" ") in which case gd_name wouldn't be the   but a. A numerical id could be handy in some places. This is to be discussed.
 * Field       | Type                | Null | Key | Default | Extra |
 * gd_name     | varbinary(255)      | NO   | PRI | NULL    |       |
 * gd_blob     | mediumblob          | NO   |     | NULL    |       |
 * gd_shared   | tinyint(1) unsigned | NO   |     | 0       |       |
 * gd_name: Canonical name of the gadget. Lowercase [a-z], 0-9 and dashes allowed. Cannot be changed after creation.
 * gd_blob: JSON string containing the module and gadget properties
 * gd_shared: Whether this is a shared gadget. If another wiki uses this wiki as a ForeinGadgetRepo, these are the gadgets included.
 * "global" is somewhat wiki-farm specific. Perhaps "shared" is more appropriate ?
 * Yes, we basically agreed on this a while ago. Hereby updated to avoid further confusion.

There will be an API module to read from and write to this table. This will primarily be used in the javascript enhanced Gadget Manager (Saving on-demand to the API without a page refresh).

The definitions will be saved to a wiki page for versioning, history, watching etc.

Gadget resources
The resources will stay where they are: As pages with revisions in the wiki database. The difference intended to be made as part of the ResourceLoader 2 project is moving these out of the prefixed "Gadget-" scope in the MediaWiki:-namespace (which is intended for messages, not actual wiki content (let alone executable resources). Instead move them to a new Gadget:-namespace only editable by users with the  right.

Messages
The title of the gadget and the description associated with will stay in the MediaWiki:-namespace. The main reason for this is, is to enable easy localization and centralization of the description.

Aside from the title (eg. ) and the description (eg. ) a gadget can have a number of custom made messages. These are handled by the existing system present in MediaWiki which is suited for this already and are loaded through the messages framework in ResourceLoader (associated at module registration and passed to the browser through ).

User rights
To keep track of what user rights are talked about in the specification and task management, a short summary
 * gadgets-edit: Edit gadget resources in the Gadget:-namespace
 * gadgets-definition-create: Creating pages directly in the Gadget definition:-namespace (and access to "Special:GadgetManager?action=create")
 * gadgets-definition-edit: Edit in the Gadget definition:-namespace (and access to "Special:GadgetManager?action=modify")
 * gadgets-definition-delete: Deleting pages directly in the Gadget definition:-namespace (and access to "Special:GadgetManager?action=delete")

Special:GadgetManager format

 * View: :
 * Modify: :
 * Create:
 * Delete:

Related bugs

 * (bug 27561) Register modules client side
 * (bug 27771) Mechanism for loading site wide JavaScript libraries
 * (bug 27281) Add support in the front-end for loading wiki pages as resources

Designs

 * todo

= Shared gadgets = One of the most wanted features for gadgets is shared gadgets. Users want to share gadgets, reach a wider audience, and avoid outdated and redundant copies at all costs. By having a "Foreign Gadget Repo" this problem will be solved. Having a gadget added to this wiki and marked "shared" will make it show up on all wikis who have their ForeignGadgetRepo set to that wiki.

For Wikimedia wikis this will most likely be set as default for all wikis (like Wikimedia Commons is set as ForeignFileRepo). They would probably be stored on mediawiki.org (since they're not Wikimedia-specific). If it's not too much work, we may create a convenience configuration boolean like "InstantCommons" to easily allow third party wikis to get these useful, actively developed, gadgets from Wikimedia, onto their own wikis.

Use-cases
No more need to duplicate, distribute, update etc. gadgets will be centrally organized and developed. Due to the nature of ResourceLoader it will be relatively simple to get interface messages in the user language. These messages would be fetched from the ForeignGadgetRepo, which means all messages will be together rather than on each wiki separately. Thanks for the fallback principle they could even be translated on TranslateWiki.
 * Sharing
 * Translation
 * Less duplication / Re-use of code:
 * Use-cases for dependancy model:
 * Just loading a shared gadget from repo
 * Loading a gadget on repoy that depends on other gadget from repo
 * Using gadget on local wiki that depends on gadget from repo

Preferences

 * Preferences would either be:
 * 1 tab ("Gadgets") showing them mixed organized by 'section' with some kind of indication which are shared and which aren't.
 * 2 tabs ("Gadgets", "Shared gadgets") both have their own sections. Why not ? Perhaps end users should not be aware of it. Why good ? Clearer seperation, feels better. Needs more motivation for 2 tabs to remain an option.
 * WMF could override "Shared" with "Global"

Client-side support
Keep track of origin in the registry. The internal registry will have an origin-key for each module (just like it has for groups). The execute-function will use the right loader-script as needed. And split up requests per module source.

GadgetRepo

 * abstract GadgetRepo, implemented as LocalGadgetRepo, ForeignDBGadgetRepo and ForeignApiGadgetRepo


 * Query to mw_gadgets table or api depending on Foreign-method
 * Registered in the start-up module just like the local ones.

ApiQueryGadgets

 * Filter by either gd_name (string) or gd_shared (boolean)
 * Allow multiple names, if no names given: Return all
 * Properties:
 * name (gd_name)
 * metadata (gd_blob)
 * titlemsg
 * title (parse: plain; uselang)
 * descriptionmsg
 * description (parse: html; uselang)


 * metadata example here

ApiQueryGadgetCategories

 * Category keys
 * Category display title in user language
 * Category member count

= Top load queue =

Use-cases
Modules that style the output from the server directly (ie. not content generated by JavaScript) should load from the top instead of the bottom. This to avoid a "flash of unstyled content". By loading it from the top the styling will be known to the browser when the content is parsed, thus no "flash of unstyled content" will appear. Modules that insert, modify or remove elements on the page need to be loaded from the top in a "document ready" wrapper. Otherwise the user could see a short "jump" in the page where something is added, removed or otherwise changed. By loading these from the top they will be able to queue themselves to start "changing" the content as soon as it's loaded.
 * Content styling
 * Content modification

Implementation proposal
The top load queue is actually quite easy to implement. What we need:
 * An additional property in the module registry for "position" which can be set to "bottom" (default) or "top".
 * The OutputPage class needs to be adapted to know about "positions" and add a loader command in the top if there are any modules with the "top" position, and in the bottom the load-everything part needs to be changed to filter only the modules with their position set to "bottom".

= Noscript stylesheets =

Use-cases

 * todo

Statistics

 * http://krinkle-tools.grizzdesign.nl/noscript-head/ (Blue JS | Green JS-off)

More numbers: RL2-noscript-head
 * IE6 and higher: OK
 * FF 2 and higher: OK
 * Opera 10 and higher: NO
 * Safari 3 and higher: OK
 * Chrome 10 and higher: OK