FANDOM


For code review, see Board:Code Review.
For requesting a new script, see Board:Script Suggestions.
This page is a help resource for users maintaining scripts on FANDOM Open Source Library (FOSL). It lists naming conventions, best documentation practice and coding conventions.

Naming conventions

The following table lists expected page titles for FOSL items:

Item Location
Script/style/application documentation PAGENAME
Lua documentation Global Lua Modules/PAGENAME
JavaScript module MediaWiki:PAGENAME.js
JavaScript submodule MediaWiki:PAGENAME/<submodule>.js
CSS stylesheet MediaWiki:<STYLESHEET>.css
CSS component MediaWiki:PAGENAME/<component>.css
Lua module Module:PAGENAME
Lua test cases Module:PAGENAME/testcases
MediaWiki/HTML dependency Template:PAGENAME

Note: Historically, FOSL scripts and stylesheets didn't obey these conventions:

They were named PAGENAME/code.<ext> and were stored as subpages of the documentation page. However, due to security concerns, these were moved to the MediaWiki namespace, which makes //code.<ext> unnecessary for new scripts.

Coding conventions

JavaScript

  • When developing a library or platform-agnostic script, wrap code in any IIFE like so:
;(function (window, $, mw) {
    // code
}(this, jQuery, mediaWiki));
  • When writing a FANDOM userscript, enclose script code in a modil statement:
require(["wikia.window", "jquery", "mw"], function (window, $, mw) {
    // code
});
  • When using >3 MediaWiki variables, you can cache them using mw.config.get:
console.log(mw.config.get('wgUserName'));
// or
var conf = mw.config.get([
    'wgUserLanguage',
    'wgContentLanguage',
]);
console.log(conf.wgContentLanguage);
// $ 'en'
  • Scope window variables to window.dev:
(window.dev = window.dev || {}).script = {};
  • Prevent double loading, usually in the below format:
if (window.PAGENAMELoaded) {
    return;
}
window.PAGENAMELoaded = true;
  • If the script already exposes a global variable, it might be preferable to check for that variable during double-load prevention instead of creating a new global.

CSS

  • In stylesheets, please don't use HTML tag names as selectors - this causes style leakage:
/* BAD - affects *14* elements in this page */
.skin-oasis section {
    border-width: 1px;
}
/* GOOD - is scoped to a specific element */
.skin-oasis .activity-module {
    border-width: 1px;
}
  • Limit your CSS in scope with >=3 selectors - this reduces bugs:
/* BAD - affects multiple scripts */
.wds-global-navigation__user-menu .wds-list {
    font-weight: bold;
}
/* GOOD - targets the user menu list only */
.wds-global-navigation__user-menu > .wds-dropdown > .wds-list {
    font-weight: bold;
}

Lua

  • Add a <nowiki>, <pre>, or <syntaxhighlight> (a.k.a. <source>) tag to the very top of the module, to prevent code like [[...]] or {{...}} from being interpreted as wikitext:
-- BAD - adds the module to Special:WhatLinksHere/Not_a_real_page
local redlink = "[[Not a real page]]"
-- GOOD - sometimes a string is just a string
-- <nowiki>
local redlink = "[[Not a real page]]"
  • Create the exported package table at the start of the module, not the end:
-- BAD - module creates table at the end
function test(frame)
    return 'Hello World!'
end
return {
    test = test
}
-- GOOD - module creates table at the start
local hw = {}
function hw.test(frame)
    return 'Hello World!'
end
return hw
  • Datastores should encapsulate the table in a return { --[[--]] } statement.

Documentation best practice

A script's documentation likely includes a number of things. The most common are:

  • A description of the script and its features
  • Import instructions and any setup instructions
  • Details about configuration, interface changes and commands

Much of the information you might want to include is in ready-to-use templates. Information and attribution is added using a infobox template. CSS and JS documentation should use the installation templates.

Documentation i18n

To facilitate i18n in your script documentation, you can structure the main documentation page like so:

<noinclude><!--
 -->{{LangSelect}}
</noinclude>
<includeonly>
{{Languages}}
{{Infobox JavaScript
| description = {{{description}}}
}}
'''{{subst:BASEPAGENAME}}''' {{{intro}}}

== Installation ==
{{Script Install}}
</includeonly>

And create language-specific subpages in the following format:

{{:{{subst:BASEPAGENAME}}
| description = Description of your script.
| intro       = is a ...
}}