This is a list of changes that wikis may need to make when making their custom JavaScript UCP-compatible during Phase 1. See also the list of different/renamed classes for changes that may need to be made to CSS selectors within custom JavaScript.
Mastheads[]
User profile mastheads are now lazy-loading. While we do not know for sure whether this behavior will remain until the end of Phase 1, something similar to the following can be used to wait for the masthead to load before attempting any actions with it:
var interval = setInterval(function() {
if ($('#userProfileApp').length) {
clearInterval(interval);
// You can now do stuff with the masthead.
}
// Change 1000 to the amount of seconds you want to be rechecking
// whether the masthead exists.
}, 1000);
To detect whether a masthead is supposed to load on a page, you can search for one of the profile
-prefixed globals, such as mw.config.get('profileUserName')
.
AMD[]
Legacy MediaWiki used AMD's require
and define
functions to separate Fandom-specific JavaScript into modules. UCP does not, and so places where these functions were used will throw errors.
AMD has been replaced with MediaWiki's mw.loader
methods, such as mw.loader.using
and mw.loader.require
, and AMD modules have been replaced with regular ResourceLoader modules. mw.loader.require
can be passed a ResourceLoader module name to retrieve the object associated with that module. mw.loader.using
can be used to load ResourceLoader modules required for your script to function:
mw.loader.using('mediawiki.api').then(function() {
// You can now use mw.Api.
});
mw.loader.using(['mediawiki.api', 'mediawiki.util']).then(function() {
// You can use mw.Api and mw.util.
});
$.when($someDeferredInstance, mw.loader.using('mediawiki.api')).then(function() {
// mw.loader.using returns a $.Deferred instance that can be
// awaited with other $.Deferred in constructs such as $.when.
});
A lot of useful ResourceLoader modules now have randomized suffixes, such as isTouchScreen-0264e82b.js
. To find exact names of these modules, you can use the following:
var moduleNames = mw.loader.getModuleNames().filter(function(moduleName) {
return moduleName.indexOf('isTouchScreen-') === 0;
});
if (moduleNames.length) {
var isTouchScreen = mw.loader.require(moduleNames[0]).isTouchScreen;
console.info('Is your screen touchable?', isTouchScreen());
}
AMD module replacements[]
wikia.window
,mw
andjquery
modules need no replacement. If you were requiring only these modules in arequire()
call, you do not need that require call and can just replace it with an IIFE.wikia.browserDetect
does not have a replacement, butisTouchScreen-SUFFIX
can be used to detect whether the device is a mobile device instead.- If your code was using banner notifications, you may want to consider using
mw.notify
instead.- If you were previously inserting HTML into your notifications, you will have to wrap it in a jQuery or a DOM node before passing it to
mw.notify
. If you were previously escaping it, you no longer need to do that.
- If you were previously inserting HTML into your notifications, you will have to wrap it in a jQuery or a DOM node before passing it to
wikia.nirvana
and$.nirvana
are no longer available, but you can use thenirvana-SUFFIX
module instead. However, as it only includes asendRequest
function (and no longergetJson
/postJson
functions), you may want to consider just sending a plain HTTP request to Nirvana (via$.get
,$.post
,$.ajax
orfetch
).
OOUI[]
A bunch of forms, as well as all modals ($.showCustomModal
, wikia.ui.modal
), on the UCP now use OOUI. The use of jQuery UI as well as some other core modules is now deprecated in favor of OOUI. Migration guides for legacy components to OOUI are coming.
Porting scripts that make use of $.showCustomModal
can be done conveniently by importing the ShowCustomModal library.
jQuery[]
Here are listed differences under the $
global object, that may be related to jQuery or Fandom-specific modules adding their interface through them.
- The module
jquery.autocomplete
has been renamed tojquery.ui.autocomplete
. - The function
$(...).exists()
($.fn.exists
) no longer exists. You can use$(...).length
($.fn.length
) instead. $.storage
no longer exists. You can usemw.storage
(which is a wrapper aroundlocalStorage
that doesn't throw any errors) with similarget
andset
methods, but these can only store plain strings that will have to be parsed withJSON.parse
when read and stringifed withJSON.stringify
when written (setObject
andgetObject
are available on newer MediaWiki versions).$.getUrlVar
does not exist. You need to ensure themediawiki.util
module has loaded and then usemw.util.getParamValue
.- There were a couple of changes to how
$.Deferred()
instances work in newer versions of jQuery:- They are behaving more in-line with how
Promise
instances work. This means.then(...)
callbacks are executed asynchronously even if their promises have already resolved. .error(...)
no longer exists on the UCP, and.fail(...)
should be used instead.
- They are behaving more in-line with how
$.escapeRE
no longer exists. You can usemw.RegExp.escape
instead (please note this has changed tomw.util.escapeRegExp
in MediaWiki 1.34, so add a fallback to that too).
Wiki theme colors[]
As the wgSassParams
global is no longer available (presumably due to Fandom no longer using SCSS), wiki theme colors will have to be grabbed directly from the page. An exception to this is ThemeDesigner, where mw.config.get('themeSettings')
can be used.
You can see examples of how theme colors can be fetched in the source code for the Colors library - color-body
, color-body-middle
(should always be the same as color-body
) and color-community-header
can be fetched from background colors of respective elements and color-links
, color-page
and color-buttons
can be fetched from respective CSS variables set on the :root
element.
Editor[]
The new editor is more-or-less completely different from all three editors used on legacy Fandom. Here are only listed some of differences that most often cause errors in scripts.
- The
wgAction
global does not change toedit
while under the new VisualEditor. You can use thewgIsProbablyEditable
global and a hook to wait for the editor to load. Note that you may still want to check forwgAction
on pages where the new VisualEditor has been disabled (currently possible via?action=edit&venoscript=1&debug=1
or?action=submit
URL parameters, or when undoing an edit, or when the user chooses the 2010 Source Editor as their preferred editor on their Preferences). - To check whether the regular source editor or the code editor is being used, you may want to check the
wgPageContentModel
global.
importArticles[]
- Article syntax for
importArticles
no longer assumes JavaScript pages cannot be located under the main namespace and tries to load them from there instead of redirecting to the MediaWiki namespace. As a result,'u:dev:DiscordIntegrator/code.js'
is no longer equal to'u:dev:MediaWiki:DiscordIntegrator/code.js'
. - You currently can't pass multiple objects in
importArticles
's parameters. If you did, you now need to split it into multiple function calls. - Passing multiple articles of the same name in the same call throws an error.
Globals[]
addOnloadHook
function does not exist. Replacing it with just$
should work.- Fetching some global variables directly from global scope instead of via
mw.config
(for example,wgUserName
orwindow.wgUserName
instead ofmw.config.get('wgUserName')
is now going to throw warnings in your browser console (but still work). - Underscore.js is not available on the UCP. If you were using the
_
global object for anything, you might be able to substitute it with thelodash-SUFFIX
ResourceLoader module which has some functionality of Underscore.js. Check out lodash's official guide for migrating from Underscore.js. - The
window.Wikia
object does not exist. wgIsMainPage
does not exist. You can use thewgMainPageTitle
global, but make sure that the page name you're comparing it with (for example,wgPageName
) does not contain underscores instead of spaces.- A way to approach this would be
mw.config.get('wgPageName').replace(/_/g, ' ') === mw.config.get('wgMainPageTitle')
.
- A way to approach this would be
wgCityId
is now a number instead of a string.wgTrackID
doesn't exist.wgUserId
, however, exists on both legacy and UCP.wgCatId
doesn't exist, but its string variant,wikiVertical
exists. On legacy, it's calledwgWikiVertical
.
MediaWiki API[]
- Obtaining tokens now must be done through
action=query&meta=tokens
, as other methods of obtaining tokens have been deprecated.
Other differences[]
mediawiki.util
is no longer loaded before custom JavaScript executes. If your code usedmw.util
and didn't wait for the module to load, it will need to usemw.loader.using('mediawiki.util').then(function() {/* your code */})
to wait for themw.util
methods to become available.- The string
<script>
(outside of code comments, as these are stripped by ResourceLoader) in your personal or site-wide JavaScript may break all JavaScript loaded by Fandom. - If your code was using
query-continue
on legacy, you may need to switch to usingrawcontinue
on the UCP. - The debug mode does not currently work, so you will have to wait for ResourceLoader cache to refresh while debugging your through JavaScript pages.
- The
loaded
on#WikiaRail
is nowis-ready
, in case your code was checking the former to see whether the Rail has already loaded. - Wikitext parser output (on-page, as well as
action=parse
) is now wrapped in a.mw-parser-output
element. - The Facebook spinner icon does not exist on UCP, but you may want to use the
mw-ajax-loader
for a loader icon instead. - Defining variables outside of functions no longer makes them global (placed under
window
) as ResourceLoader wraps all custom JS in a function (so they are function-scoped, not global-scoped). - When an error occurs during an API call,
mw.Api
rejects the promise instead of resolving it. That means if your API error handling was in the.done(...)
call, it must be moved to the.fail(...)
call. The first parameter of the function passed to.fail(...)
is the error code (set tohttp
if it was an AJAX call error, which was previously the only reason why this callback would be called) and the second is the actual error object. mediawiki.action.history.diff
ResourceLoader module is nowmediawiki.diff.styles
.- The
ext.wikia.LinkSuggest
module is not available due to its functionality not being ported to UCP yet (but is planned to be added).