Community Central
Register
Community Central
mNo edit summary
Tag: Help
m (+ {{UCP unavailable}})
(2 intermediate revisions by 2 users not shown)
Line 1: Line 1:
  +
{{UCP unavailable}}
 
The global JavaScript method <code>importArticles()</code> provides a common interface for including articles that contain scripts or styles on a community.
 
The global JavaScript method <code>importArticles()</code> provides a common interface for including articles that contain scripts or styles on a community.
   
Line 76: Line 77:
 
|}
 
|}
   
In the end, you should end up with a URL that looks something like this:
+
In the end, you should end up with a URL that looks something like this:
  +
 
<source lang="text" style="margin-left:2em;">
 
<source lang="text" style="margin-left:2em;">
 
/load.php?mode=articles&articles=One.css|Two.css&only=styles
 
/load.php?mode=articles&articles=One.css|Two.css&only=styles
 
</source>
 
</source>
   
Which can be used in conjunction with <code>@import</code>, like so:
+
Which can be used in conjunction with <code>@import</code>, like so:
  +
 
<source lang="css" style="margin-left:2em;">
 
<source lang="css" style="margin-left:2em;">
 
@import url("/load.php?mode=articles&articles=One.css|Two.css&only=styles");
 
@import url("/load.php?mode=articles&articles=One.css|Two.css&only=styles");
Line 87: Line 90:
   
 
If the CSS is hosted on another community or websites outside of Fandom such as Dropbox, the url should have the http:// or https:// like this asset file for example:
 
If the CSS is hosted on another community or websites outside of Fandom such as Dropbox, the url should have the http:// or https:// like this asset file for example:
  +
 
<source lang="css" style="margin-left:2em;">
 
<source lang="css" style="margin-left:2em;">
 
@import url("https://dl.dropboxusercontent.com/s/0p9ay0nqibx2wr7/manga_list.css");
 
@import url("https://dl.dropboxusercontent.com/s/0p9ay0nqibx2wr7/manga_list.css");
Line 96: Line 100:
   
 
== Examples ==
 
== Examples ==
Importing multiple script articles, one from the local community and one from an external:
+
Importing multiple script articles, one from the local community and one from an external:
  +
 
<syntaxhighlight lang="javascript" style="margin-left:2em;">
 
<syntaxhighlight lang="javascript" style="margin-left:2em;">
 
importArticles({
 
importArticles({
Line 107: Line 112:
 
</syntaxhighlight>
 
</syntaxhighlight>
   
Importing multiple style 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:
  +
 
<syntaxhighlight lang="javascript" style="margin-left:2em;">
 
<syntaxhighlight lang="javascript" style="margin-left:2em;">
 
importArticles({
 
importArticles({
Line 118: Line 124:
 
</syntaxhighlight>
 
</syntaxhighlight>
   
Importing multiple modules in a single method call:
+
Importing multiple modules in a single method call:
  +
 
<syntaxhighlight lang="javascript" style="margin-left:2em;">
 
<syntaxhighlight lang="javascript" style="margin-left:2em;">
 
importArticles({
 
importArticles({
Line 135: Line 142:
 
The <code>importArticles()</code> method also supports a simplified, alternate syntax for common use cases. For convenience, the method <code>importArticle()</code> is also defined.
 
The <code>importArticles()</code> method also supports a simplified, alternate syntax for common use cases. For convenience, the method <code>importArticle()</code> is also defined.
   
Including a single file from the local community using a module definition:
+
Including a single file from the local community using a module definition:
  +
 
<syntaxhighlight lang="javascript" style="margin-left:2em;">
 
<syntaxhighlight lang="javascript" style="margin-left:2em;">
 
importArticle({
 
importArticle({
Line 150: Line 158:
 
==Further help and feedback==
 
==Further help and feedback==
 
{{Help and feedback section}}
 
{{Help and feedback section}}
 
 
 
[[de:Hilfe:Einbinden von zusätzlichem CSS und JS/technisch]]
 
[[de:Hilfe:Einbinden von zusätzlichem CSS und JS/technisch]]
 
[[es:Ayuda:Incluyendo JavaScript y CSS adicional/técnico]]
 
[[es:Ayuda:Incluyendo JavaScript y CSS adicional/técnico]]
Line 161: Line 167:
 
[[pt:Ajuda:Como incluir JavaScript e CSS adicionais/Técnico]]
 
[[pt:Ajuda:Como incluir JavaScript e CSS adicionais/Técnico]]
 
[[ru:Справка:Включение дополнительных JS и CSS/Техническая часть]]
 
[[ru:Справка:Включение дополнительных JS и CSS/Техническая часть]]
  +
[[tr:Yardım:Ek CSS ve JS dahil/teknik]]
 
[[vi:Trợ giúp:Bao gồm JavaScript và CSS bổ sung/kỹ thuật]]
 
[[vi:Trợ giúp:Bao gồm JavaScript và CSS bổ sung/kỹ thuật]]
 
[[zh:Help:導入更多JavaScript與CSS/技術]]
 
[[zh:Help:導入更多JavaScript與CSS/技術]]

Revision as of 16:36, 2 April 2020

This feature is not currently available on wikis which use the new Unified Community Platform (UCP).
See this page for more information on the new platform.

The global JavaScript method importArticles() provides a common interface for including articles that contain scripts or styles on a community.

The functionality is similar to the existing methods importScriptPage and importStylesheetPage. However, importArticles() 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 importArticles() method relies on module definitions to load articles. Modules are essentially a JavaScript object with key/value properties. The following properties are required in every module:

  • type - This property denotes the type of articles this module will contain. The supported types are:
    • script - An article containing JavaScript (for example "MediaWiki:Common.js").
    • style - An article containing CSS (for example "MediaWiki:Wikia.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 importArticles(). However, all of the articles within a module must be of the same type.

Caching
Links generated by importArticles() (and the advanced techniques described below) are cached for a maximum of 10 minutes. So whenever you make a change you can assume that after 10 minutes all the users coming to your community will be served the updated version of JS and CSS files if importArticles() is used.

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:

(Prefix:<WikiName>:)<Article>

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 importArticles statement:

MediaWiki:Common.js

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/code.css from the Dev Wiki, the following would work inside an importArticles statement:

u:dev:Highlight/code.css

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:

u:it.onepiece:MediaWiki:Common.js

Advanced usage

Behind the scenes, the importArticles() method performs three necessary tasks:

  1. Generating a properly formatted URL for use with ResourceLoader,
  2. Performing sanity checks on the modules provided to assure they are properly formatted
  3. Providing the user feedback in the case of an error.

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 the URL manually and load the assets using other means, such as @import statements in CSS or jQuery.getScript in JavaScript.

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

Parameter Parameter Description
mode Tells ResourceLoader that we will be loading articles. Should be set to "articles."
articles The list of articles. If multiple articles are provided, they should be separated by a pipe "|" character.
only The type of articles to import. Should be set to either "scripts" or "styles."
debug This parameter is not necessary by default but can be set to "true" to disable minification to allow for easier debugging of problems within the imported articles.

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

/load.php?mode=articles&articles=One.css|Two.css&only=styles

Which can be used in conjunction with @import, like so:

@import url("/load.php?mode=articles&articles=One.css|Two.css&only=styles");

If the CSS is hosted on another community or websites outside of Fandom such as Dropbox, the url should have the http:// or https:// like this asset file for example:

@import url("https://dl.dropboxusercontent.com/s/0p9ay0nqibx2wr7/manga_list.css");

It will use the CSS file from the source website to import to whatever CSS page it's been put on. If the style sheet file is edited outside of Fandom and an import syntax with the raw file is in use, an immediate change will occur. CSS pages that have been edited with the import used will have the waiting state before taking effect. They should have the codes that customize the Fandom interface in-order to take effect if the imported CSS comes from another internet source not hosted on Fandom.

For Javascript, using external third party sites may open up a security risk and should only be imported from a site inside Fandom.

Examples

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

importArticles({
    type: "script",
    articles: [
        "MediaWiki:MyCustomJavaScript.js",
        "u:dev:MediaWiki:External_include.js"
    ]
});

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

importArticles({
    type: "style",
    articles: [
        "MediaWiki:Common.css",
        "u:starwars:MediaWiki:External_include.css"
    ]
});

Importing multiple modules in a single method call:

importArticles({
    type: "script",
    articles: [
        "MediaWiki:MyCustomJavaScript.js",
        "u:dev:MediaWiki:External_include.js"
    ]
}, {
    type: "style",
    article: "MediaWiki:Common.css"
});

Alternate Syntax Examples

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

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

importArticle({
    type: "style",
    article: "MediaWiki:Common.css"
});

See also

Further help and feedback