Help:Including additional CSS and JS/technical

This help page covers the more technical ways to include CSS and JavaScript on your community.

importArticles
The global JavaScript method  provides a common interface for including articles that contain scripts or styles on a community. It's most useful for importing scripts and styles conditionally.

The functionality is similar to the existing methods  and. However,  can import articles from external communities, bundle several articles into one, minify them and serve them as a single request. This reduces both file size and web traffic, effectively making a community with a large number of additional files load a lot faster.

Usage
The  method relies on module definitions to load articles. Modules are essentially a JavaScript object with key/value properties. The following properties are used in most modules:
 * type (optional) - This property denotes the type of articles this module will contain. If omitted, the type will be guessed for each article based on its extension. The supported types are:
 * script - An article containing JavaScript (for example "MediaWiki:Common.js").
 * style - An article containing CSS (for example "MediaWiki:Common.css").
 * articles - The articles you wish to import. See the locating articles section below for more information on what to put here.

Any number of modules can be passed into.

Locating articles
Simple syntax is used to locate the articles you're trying to import. It is very similar to, and compatible with, interwiki links:

Anything in parentheses above is optional, and anything in brackets above denotes user input. The colon character is used to separate the string into different segments for parsing. Prefixes tell us how you want to look up the article and are generally followed by a community name, except in the case of a local community.

Local articles
Articles on the local community can be located by title in the same way that you would link to them normally. They do not require a prefix or community name. For example, if you wanted to import the article MediaWiki:Common.js, the following would work inside an  statement:

External articles
Articles from external communities can also be located the same way that you would link to them normally. However, unlike local articles, external articles require the use of a prefix and community name to determine which community you will be importing them from and how you will identify that community. Fandom supports looking up communities by their URL. URL lookups are performed for the u prefix. For example, if you wanted to import the article Highlight.css from the Dev Wiki, the following would work inside an  statement:

This syntax will also work for wikis in other languages. For example, if you wanted to import the article MediaWiki:Common.js from the Italian version of One Piece Wiki:

Raw URLs must not be used with.

Advanced usage
Behind the scenes, the  method performs a number of necessary tasks:
 * 1) Encodes the article names with mw.util.wikiUrlencode.
 * 2) Enables test versions of scripts when test mode is enabled (by prepending the article name with  ).
 * 3) Registers the article as a module with ResourceLoader (assuming it is not already registered), which keeps track of its state and allows it to be used with mw.loader methods.
 * 4) Provides the user feedback in the case of an error.

It wraps, which performs much of the actual work:
 * 1) Generates a properly formatted URL for use with ResourceLoader.
 * 2) Ensures that the module is not already loaded, or in the process of loading, before loading it.
 * 3) Performs sanity checks on the article names provided to assure they are properly formatted.
 * 4) Batches all imports together into a single request, and normalizes the request so that it can be more reliably cached.
 * 5) Creates a   element with the created URL, appending it to the document head, which initiates the load and script execution.
 * 6) Creates and returns a promise which is resolved on the "load" event of the created.

Article registration
One of the most important roles of  is registering the article (i.e. a page on the wiki) as a module for use with ResourceLoader, so that it may be used with functions like. You may use  directly, but not with articles before they have been registered as a module with , or with.

ImportJS, unlike importArticles, does not register articles as modules (only the ImportJS script itself, as ). This means that a script present in both ImportJS and in calls to  will be downloaded and executed twice.

Depending on an imported article or module
importArticles returns a promise object that is resolved once all modules specified in the call have been loaded and executed, which may be used when you need to execute code that depends on the imported modules.

The promise is resolved with a single argument, a  function that, when passed the module name, returns the exported value of a module (typically an object may be used to control the module). Exported values are used so that scripts can expose functions and values to be used outside of the module, without littering the global scope. Despite this, most user scripts don't implement exports and instead opt to store methods in. Any functions that the module does not export or expose globally typically cannot be accessed.

Following the first call to, if you need to run code that depends on an imported article, you can call either   or   with the module names as many times as you wish. If you have already called either of these methods with a particular module, or another imported script/module already depended on it, the module will not be re-downloaded or re-executed and the Promise will resolve either immediately (if the module has already been loaded and executed), or as soon as possible once this occurs.

Examples
Importing multiple script articles, one from the local community and one from an external:

Importing multiple style articles, one from the local community and one from an external:

Importing multiple modules of different types in a single method call:

Importing multiple modules in a single method call (in a single object, without the "type" property):

The  method also supports a simplified, alternate syntax for common use cases. For convenience, the method  is also defined.

Including a single file from the local community using a module definition:

Importing CSS and JS manually
However, use of the  method is not strictly required to gain the benefits of combining and minifying multiple articles into one request. If you'd like, you can generate a URL manually, and load the assets using other means, such as @import statements in CSS or jQuery.getScript, mw.loader.load, or by manually injecting the script in JavaScript.

Using load.php
The  endpoint may be used to combine multiple articles into a single request, and is part of ResourceLoader. This is the preferred URL as it reduces bandwidth consumption by batching and minification, and the returned code automatically implements any articles passed as a module. and  (the client-side part of ResourceLoader) constructs requests using this endpoint.

While there are many parameters you can include in the URL, the following are probably the most useful:

In the end, you should end up with a URL that looks something like this. This is a relative URL, and refers to resources kept locally on the wiki:

If the resource is hosted on another Fandom community, you can use an absolute URL, including the domain name and protocol:

...or alternatively use the  syntax described above:

If the resource is hosted or websites outside of Fandom such as Dropbox, you should use the full url, like this asset file for example.

Using index.php
The  endpoint may be used to request a single unaltered, non-linted, non-minified script or stylesheet. This may be useful for debugging, or if you need to bypass ResourceLoader for some reason (i.e. implementing ES6 user scripts).

index.php cannot be used to fetch modules specifically, only pages. Additionally interwiki links and  syntax is not supported when   is specified, so an absolute URL is needed to get scripts/stylesheets from other communities. For JavaScript, using external third party sites may open up a security risk and should only be imported from a site inside Fandom.

While there are many parameters you can include in the URL, the following are probably the most useful:

In the end, you should end up with a URL that looks something like this:

Implementing
Once you have your URL, it may be used with the following methods:


 * : If type is "text/javascript" or unspecified, creates a element with a src attribute of the URL specified in the first argument, then appends it to the document head. If type is "text/css", creates a element with a ref attribute of "stylesheet" and a href attribute of the URL specified in the first argument, then appends it to the document head. If module names are specified instead of URLs (when the string isn't prefixed with "http://" or "/"), this function acts like  .  The argument modules cannot be an array when using URLs. You should batch multiple modules in the same request using load.php, or have a separate call for each URL when using index.php.  When specifying   in the load.php URL, calling this function multiple times with the same module URL will cause it to be executed again on each call, as the module won't be self-registering and aware that it has already been loaded.


 * : See @import method.


 * Manual injection: If you don't want to rely on any libraries, you can inject the script yourself with the following code:


 * And for a stylesheet:

Legacy loading methods
The following legacy methods are provided automatically in the global scope.
 * : Constructs a relative URL with a title, then calls  with it, which appends a element to the document head:


 * : Calls, passing it a url, which appends a element to the document head, as follows.


 * : Constructs an absolute URL to a script on a Fandom wiki given a title, then calls  with it, which appends a element to the document head, as follows. If wiki is null, this is the same as importScript.


 * : Constructs a relative URL to a local stylesheet with a title, then creates and appends a element to the document head, as follows.


 * : Constructs a  element with a url, and appends it to the document head, as follows.


 * : Constructs an absolute URL to a stylesheet on a Fandom wiki given a title, then creates and appends a element to the document head, as follows. If wiki is null, this is the same as importStylesheet.


 * : Constructs a element containing your css rules directly, and appends it to the document head.

Further help and feedback
de:Hilfe:Einbinden von zusätzlichem CSS und JS/technisch es:Ayuda:Incluyendo JavaScript y CSS adicional/técnico fi:Ohje:Ylimääräisen JavaScriptin ja CSS:n lisääminen/tekninen fr:Aide:Inclure du CSS et JS supplémentaire/technique it:Aiuto:Includere CSS e JS aggiuntivi/avanzato ja:ヘルプ:追加のJavaScriptとCSSをインクルードする/技術情報 ko:도움말:자바 스크립트 및 CSS 불러오기/importArticles pl:Pomoc:Importowanie CSS i JS/techniczne pt:Ajuda:Como incluir JavaScript e CSS adicionais/Técnico ru:Справка:Включение дополнительных JS и CSS/Техническая часть tr:Yardım:Ek CSS ve JS dahil/teknik uk:Довідка:Включення додаткових JS і CSS/Технічна частина vi:Trợ giúp:Bao gồm JavaScript và CSS bổ sung/kỹ thuật zh:Help:導入更多JavaScript與CSS/技術