wikibits: Mark importScript/importStylesheet utilities as deprecated

The global variable loadedScripts and the import functions from wikibits.js
have been deprecated since 1.17 [1].

The global loadedScripts is used to keep track which scripts have
been loaded through importScriptURI. To do this, it only needs to be
a local variable, not a global.

For scripts using the global to check whether a particular script
has been loaded, here are some possible substitutes:

* Use mw.loader.getState() for scripts loaded through ResourceLoader
  (which includes Gadgets).
* Use hooks (mw.hook) to communicate between the scripts.
* Use $( 'script[src="..."]' ).length to check whether a script with
  a specific URL has been loaded.
* Use $( 'script[src]' ) for a list of all scripts (excluding inline
  scripts), and filter it for whatever you are looking for.

The functions importScriptURI and importStylesheetURI are used to
load scripts and stylesheets resp. from a URI. Use mw.loader.load() instead.
Note that there are minor differences between the deprecated functions
and mw.loader.load(), see [1] for details.

The importScript and importStylesheet shortcuts have been deprecated as well.

[1] https://www.mediawiki.org/wiki/RL/LJS#wikibits.js

Change-Id: Icc87243a8213841bfe46e48a9c074301c241041c

diff --git a/RELEASE-NOTES-1.25 b/RELEASE-NOTES-1.25
index aad2976..8a589f6 100644 (file)
--- a/RELEASE-NOTES-1.25
+++ b/RELEASE-NOTES-1.25
@@ -431,6 +431,8 @@ changes to languages because of Bugzilla reports.
 * $wgResourceModuleSkinStyles no longer supports per-module local or remote paths. They
   can only be set for the entire skin.
 * Removed global function swap(). (deprecated since 1.24)
+* The global importScript and importStylesheet functions, as well as the loadedScripts object,
+  from wikibits.js (deprecated since 1.17) now emit warnings through mw.log.warn when accessed.
 
 == Compatibility ==
 

diff --git a/resources/src/mediawiki.legacy/wikibits.js b/resources/src/mediawiki.legacy/wikibits.js
index dffc6e8..f5aeb3f 100644 (file)
--- a/resources/src/mediawiki.legacy/wikibits.js
+++ b/resources/src/mediawiki.legacy/wikibits.js
@@ -5,7 +5,8 @@
        var msg,
                win = window,
                ua = navigator.userAgent.toLowerCase(),
-               onloadFuncts = [];
+               onloadFuncts = [],
+               loadedScripts = {};
 
        /**
         * User-agent sniffing.
@@ -159,38 +160,39 @@
 
        /**
         * Wikipage import methods
+        *
+        * See https://www.mediawiki.org/wiki/ResourceLoader/Legacy_JavaScript#wikibits.js
+        *
+        * @deprecated since 1.17 Use mw.loader instead. Warnings added in 1.26.
         */
 
-       // included-scripts tracker
-       win.loadedScripts = {};
-
-       win.importScript = function ( page ) {
+       function importScript( page ) {
                var uri = mw.config.get( 'wgScript' ) + '?title=' +
                        mw.util.wikiUrlencode( page ) +
                        '&action=raw&ctype=text/javascript';
-               return win.importScriptURI( uri );
-       };
+               return importScriptURI( uri );
+       }
 
-       win.importScriptURI = function ( url ) {
-               if ( win.loadedScripts[url] ) {
+       function importScriptURI( url ) {
+               if ( loadedScripts[url] ) {
                        return null;
                }
-               win.loadedScripts[url] = true;
+               loadedScripts[url] = true;
                var s = document.createElement( 'script' );
                s.setAttribute( 'src', url );
                s.setAttribute( 'type', 'text/javascript' );
                document.getElementsByTagName( 'head' )[0].appendChild( s );
                return s;
-       };
+       }
 
-       win.importStylesheet = function ( page ) {
+       function importStylesheet( page ) {
                var uri = mw.config.get( 'wgScript' ) + '?title=' +
                        mw.util.wikiUrlencode( page ) +
                        '&action=raw&ctype=text/css';
-               return win.importStylesheetURI( uri );
-       };
+               return importStylesheetURI( uri );
+       }
 
-       win.importStylesheetURI = function ( url, media ) {
+       function importStylesheetURI( url, media ) {
                var l = document.createElement( 'link' );
                l.rel = 'stylesheet';
                l.href = url;
@@ -199,6 +201,13 @@
                }
                document.getElementsByTagName( 'head' )[0].appendChild( l );
                return l;
-       };
+       }
+
+       msg = 'Use mw.loader instead.';
+       mw.log.deprecate( win, 'loadedScripts', loadedScripts, msg );
+       mw.log.deprecate( win, 'importScript', importScript, msg );
+       mw.log.deprecate( win, 'importScriptURI', importScriptURI, msg );
+       mw.log.deprecate( win, 'importStylesheet', importStylesheet, msg );
+       mw.log.deprecate( win, 'importStylesheetURI', importStylesheetURI, msg );
 
 }( mediaWiki, jQuery ) );