ResourceLoader/Requirements
This page is obsolete. It is being retained for archival purposes. It may document extensions or features that are obsolete and/or no longer supported. Do not rely on the information here being up-to-date. Current information lives at ResourceLoader/Architecture. |
Requirement | Features | Benefits | Issues |
---|---|---|---|
Debugging | |||
Support direct resource inclusion | Allows JS resources to be included individually and without being run through the loader software | JS resources can be more easily debugged because file names and line numbers correspond to the actual JS resources | Requires L10n fallbacks to be embedded in JS resources |
Support stand-alone use of loader | Allows the script loader system to be integrated into other frameworks or used as a stand-alone service | Development efforts can be shared with non-MediaWiki developers, and those developers' efforts can benefit us | Makes MediaWiki integration difficult, makes code more foreign to MediaWiki developers |
Useful information on loading failure | Provides useful, verbose information about failures to load resources | Makes development easier | Requires more code to be written |
Packaging | |||
Remove debug statements | Allows JS resources to contain debug information which is stripped out before being sent to the client | Debug information can remain in JS resources for future use | More moving parts to break |
JS/CSS Minification | Strips whitespace and comments from JS and CSS resources | Reduces the amount of data sent to the client | Makes debugging more difficult |
JS Closure Compilation | Simplifies and aggressively optimizes JS functions | Reduces the amount of data sent to the client, and improves the performance of many JS functions | Makes debugging very difficult |
CSS Janus transformation | Flips CSS rules to make LTR stylesheets appropriate for RTL | No need to keep separate files around for this if we can apply this transformation in PHP along with the others | Makes it slightly more difficult to figure out what the RTL version of a given CSS file looks like |
Resource batching / concatenation | Multiple resources can be included in a single request | Reduces the number of requests from clients | Potentially increases cache size, potentially causes double inclusion of resources |
Parameterize batched loading | Set a URL param to indicate we need resources for a certain combination of prefs/logged-in-ness rather than detecting this on the server | Eliminates the need for uncacheable-for-logged-in-users Vary: Cookie responses | Increases the number of URL variants |
Web-server-level resource caching | Caches processed (localized, minified, etc.) scripts on the server | Makes it faster to batch resources in different combination | Caching is not free, it takes time and space |
Use short client-side expiry times | Tells clients to refresh cached resources in short intervals (~1h) | Eliminates the need to expire HTML (expensive) to force clients to refresh resources | Requires that RL requests be cheap, so they should support 304 and be cached in Squid |
Use highest-timestamp versioning scheme | Version each RL request with the highest last-modified timestamp of the resources involved, formatted in ISO 8601 and rounded to 10s | No more manual style versions. 10s rounding and human-readable format allows faster and easier purging of bad resources from Squid | May cause conflicts when new JS is served with old HTML, need to code around that in JS |
In-place localization | Includes localized messages directly within JS resources | Allows i18n of JS software without adding additional requests | Mixes i18n work with development work |
Localization API | Makes messages available on demand individually or in groups | Provides yet another option for getting L10n to the client | Very inefficient way to get L10n to the client |
Separate message resource system | Generates JS blobs for l10n separately, stores them in the DB | Only relevant JS is regenerated when a message changes | Makes stand-alone usage more difficult |
Export user preferences to JS | |||
CSS grouping (without JS) | |||
CSS includes registered in JS namespace | Allows JS resources to check existence of CSS resources and require CSS resources to be loaded before proceeding | Fewer CSS resources need to be included initially and modules can safely avoid re-loading already-loaded CSS resources | Requires more code to be written |
Resource buckets | Allows resources to be grouped into buckets such as "all", "view", "edit", etc. | Reduces number of individual requests needed | Potentially too many things will get put in these buckets |
Runtime loading of JS and CSS | Allows resources to be included dynamically | Reduces the initial payload sent to clients | Potentially presents delay between user action and resource availability |
Module based loading | Resources are identified by module names | Provides a standard way of expressing requirements and checking what resources are already loaded | |
Module loaders | Modules each have associated loader functions which are executed to load the module | Provides more flexibility in loading | Increases the amount of code sent to the client and level of complexity in development |
Configurable URL scheme | Allows flexibility in request URL formats | Makes using a localhost, web-server or CDN a matter of configuration | |
Allow version aliasing | In the case that a buggy version of a script is released, a version redirect can be put in place | Avoids purging PHP generated HTML to resolve JS bugs | Potentially introduces level of indirection causing negative performance impact. Not needed if scripts are versioned and cached in Squid |
Dependency order preservation | Allows dependencies to automatically be included in a specific order if needed | Makes dependencies simpler to use | May make dependency specification more complex |
Structure | |||
Clear division of libraries | Makes JS resources communicate with each other using well documented APIs | Improves the re-usability of JS resources | Takes more time to develop and document |
Control a specific JS namespace | Specifies a unified naming convention and access point for JS resources | Improves maintainability and reduces difficulty to learn the system | Requires porting existing code to conform |
Control naming between PHP and JS resources | Specifies clear naming between PHP extensions and JS modules | Improves maintainability and reduces difficulty to learn the system | Requires porting existing code to conform |
Package-level dependency resolution | JS modules can form packages, which can then be required/included as a whole | Reduces complexity of specifying requirements making development easier | Reduces specificity of requirements potentially causing resources to be loaded that will not be used |
Map files, buckets and dependencies in PHP | Have an associative array structure in PHP that defines objects, which optionally contain a file and optionally have dependencies | Makes for fewer distinct URLs (?), which eases caching and purging | Limited support for JS-based conditions, would have to be done through parameterization, cannot scale to user scripts |
Division between loading and execution | JS modules can be loaded on demand, and executed independently | Makes dependencies simpler to use | Makes writing modules more complex |
Allow explicit re-loading | Resources are not loaded more than once by default, but can be re-loaded if desired | Makes overwriting/re-loading possible/easier | |
jQuery should be the primary way of extending functionality | |||
jQuery plug-ins should be centrally organized | All jQuery plug-ins should be committed to a central place, with version numbers in their names | Makes sharing plug-ins easier / more likely to happen and everyone benefits from bug-fixes equally | Causes issues with maintaining extensions or if people cloud the plug-in folder with low-quality plug-ins |
JS module version conflict management | Makes module version information available to JS resources | Makes it possible to migrate to newer versions of plug-ins over time | Sends more data to the client, adds complexity to configuration |
Utilities | |||
JS localization functions | JS facilities for handling 18n functionality such as {{PLURAL}} and $ replacement | Messages can be more flexible and reusable | Must be maintained in parallel with PHP i18n functions, limitations must be well understood by translators |
Sources
editThis document is a synthesis of the following sources