ResourceLoader/Requirements/Michael Dale

Existing Documentation

It will help the discussion for people to read the existing documentation / summary of stuff.

• The high level overview: (might be slightly outdated but overall communicates the high level goals) JS2_Overview
• Documentation for API usage as extension developer: /extensions/JS2Support/README
• mwEmbed library (JavaScript side to the script-loader) MwEmbed

High level goals

Basically we want a JavaScript framework that promotes modular reusable components, with clean separation of core libraries, configuration, invocation binding and interface code. We want to make it easy to develop "this way" both for extension developers and gadget authors. The framework will promote development of code that is easy for performance engines to optimize for client side performance. The script-loader should enable timed payload delivery for high "perceived' or "real" client side performance as the set of javascript interfaces continue to grow. The framework should work with reasonable server side resource consumption and ultimately assist in vastly reducing server load.

Balance considerations

• Balance considerations can in many cases be data driven decisions based on industry norms and real world information about the present usage. The design should balance "high performance" initial views, with high performance of repeat views via more common cache hits. Script grouping for low number of initial requests vs many requests for distinct cacheable resources for many contexts.
  • Preset design leans towards low number of requests

• The design should balance cluster wide multi-language script cache vs extra round trips for interface language messages.
  • Preset design assumes little benefit multi-language script cache promotes interface msgs packaged with js code to reduce number of requests

• The design should balance ease of modular JavaScript development and debugging with scalability and ease of deployment.
  • Present design includes minimal javascript parsing to ascertain named javascript class paths, remove debug statements and swap in localized messages

Features / Technical requirements

• Tools for debug, ability to run the entire package with direct reference to all underling JavaScript, css and image assets.
• JS transformation and packaging.
  • Removal of debug statements
  • Minification (either php-min or Google closures java compiler )
  • Include localized messages in requested language.
• CSS transformation and packaging -
  • CSS grouping for page views (where the user may have JavaScript disabled, CSS with proper paths and content type is served)
  • CSS for use in dynamic interface loading (here CSS is a line of JavaScript so that it can be part of the JavaScript package and reduce round-trips / requests)
  • CSS includes should be registered in the JavaScript name-space so the loader can easily identify if a defined style-sheet has been included.
• Script Buckets - includes the concept of script-buckets for php side on-page included scripts. This makes it easy to separate php generated page script grouping by core / all-page scripts, page, page set, user scripts, site configuration and user configuration. This avoids per-page, per-user, scripts mangling the cache for "all-page" scripts.
• JavaScript Modules - a concept of a module that includes some minimal "module loader code" that can be invoked in conjunction with the script-loader to dynamically load a set of JavaScript, CSS and interface messages. For example inline section editing, or the add-media-wizard button in the editor that loads only once users invoke it by pressing the edit section or "insert-image" respectively. A minimal bit of "loader" code is always included that can be called to "load" a given module.
  • Modules provide points of encapsulation for localization and a means for easy enabling or disabling. An extension could include multiple "JavaScript modules"
• JavaScript localization - a JavaScript localization system that parallels the PHP based MediaWiki system for ease of use. This includes use of the {{PLURAL}} template transforms, and support for inline jQuery bound link substitution for conventional MediaWiki [$1 link name] msg text.

For example:

mw.addMessages( { "my-msg-key": "You should [$1 click here]" } ); 
$j('#target').append( 
    gM( 'my-msg-key', 
        $j('<a />').click( 
            function(){ 
                alert('foo' )
            }
        )
    )
);
/*
* Will result in the text "You should click here" with 'click here' carrying the jquery binding. 
*/

• Stand Alone usage - the script-loader should be able to used in 'stand-alone-mode' for reusing these modules outside of Wikimedia.
• Work with and without a reverse proxy in-front. Script-loader should support "fast-cache-hits". The entire MediaWiki code-base and localization system should not be invoked every time a client wants to display a pre-defined script group cache key. This is especially important for poor mans gzip support on shared host deployments of MediaWiki.

Assist in vastly reducing server load / future work

Currently logged in users are served dynamically generated page content this adds anywhere from a half second to 2 in "before transport" costs. Sending cache pages to everyone with default settings and dynamically requesting the "dynamic" part of the page ( user gadgets and user menu ) via JavaScript cookie, could vastly improve performance and reduce server load for logged in users. This could enable a much larger set of users to be logged-in with less server side resources. A special cookie would have to be recognized at the squid level, to enable serving logged in users the cached "anonymous page"