Fandom

Wikia Developers Wiki

Less

889pages on
this wiki
Add New Page
Talk18 Share
This page documents version 2 of the related code. If you are still using version 1, it is advised to update to the newer version as soon as possible. For documentation on version 1, see here (no longer updated).

Wiki stylesheets can fast become too large to easily maintain. They can contain anything and everything from skin customisations to template styles to username highlights. For the Oasis skin, this may be worsened for some wikis which do not use Common.css by default, as opposed the normal two used in every other MediaWiki skin. This script seeks to make your wiki's CSS that little bit easier to maintain.

LESS is a dynamic stylesheet language. Its many features, such as variables, mixins and nesting, exist to make your CSS easier to maintain. With it you can make your stylesheets shorter, easier to follow and easier to maintain. It's very similar to the Sass stylesheets used by Wikia themselves, but LESS allows us to compile the stylesheet with javascript making this script possible.

Installing

Add the following to your wiki's importArticles array:

importArticles( {
    type: 'script',
    articles: [
        'u:dev:Less/code.2.js',
    ]
} );

You will also need to configure the installation. The configuration code must come before your importArticles statement.

// our config is stored in an array
window.lessOpts = window.lessOpts || [];
 
// each target page needs separate configuration
window.lessOpts.push( {
    // this is the page that has the compiled CSS
    target: 'MediaWiki:Common.css',
    // this is the page that lists the LESS files to compile
    source: 'MediaWiki:Common.less',
    // these are the pages that you want to be able to update the target page from
    // note, you should not have more than one update button per page
    load: [
        'MediaWiki:Common.css',
        'MediaWiki:Common.less'
    ],
    // this is the page that contains the comment header for the target page
    // all other comments are stripped during compilation
    header: 'MediaWiki:Css-header/common'
} );

You can also add some extra optional configuration that will be shared across every target page. Again, this must come before your importArticles statement

window.lessConfig = {
    // reloads the page after the target page has successfully been updated
    // defaults to true
    reload: true,
    // wraps the parsed CSS in pre tags to prevent any unwanted links to templates, pages or files
    // defaults to true
    wrap: true,
    // for adding non-standard usergroups that can edit the mediawiki namespace
    // normally this is limited to staff, vstf, helpers and sysops/admins
    // but if there are other groups that can edit the namespace on your wiki
    // add them to the array here for the script to load for them
    allowed: []
};

If you want to use the defaults simply remove this optional configuration, or the option you don't want to change if you only want to change part of it.

For help with importArticles() see the below:

importArticles — Best Practices for installing JavaScript on Fandom
The importArticles statement is designed to combine multiple HTTP requests into a single data transfer, allowing multiple scripts to load and execute faster. If you've been installing several different scripts, your JavaScript file has probably accumulated unnecessary import statements. Click "Expand" to learn how to efficiently batch import scripts to speed up performance and make your code look cleaner. One other approach is by using the MediaWiki:ImportJS.
If your JavaScript file has several lines of code that say importScript, importScriptPage, or importArticles, you may be able to combine them! By batch importing a collection of scripts with a single import, your JavaScript code will load faster and look cleaner. Consider the example below. On the left is an example of what your JavaScript file might currently look like. On the right is how you could improve that code.
Multiple imports — messy and slow One import — clean and efficient
importScriptPage('AjaxRC/code.js','dev');
 
importScript('MediaWiki:localScript.js');
 
importArticle({
  type: 'script',
  article: 'u:dev:FloatingToc/code.js'
});
 
importScriptPage('page1.js', 'wikiname');
 
importScriptPage('page2.js', 'wikiname');
importArticles({
    type: 'script',
    articles: [
        'u:dev:AjaxRC/code.js',
        'MediaWiki:localScript.js',
        'u:dev:FloatingToc/code.js',
        'u:wikiname:page1.js',
        'u:wikiname:page2.js'
    ]
});
Note: In this example, pay close attention to the placement of commas and other punctuation. For people who aren't familiar with programming (and even those who are!), a common mistake when writing code is to accidentally delete, forget, or misplace critical symbols like commas or quotation marks. This can cause a syntax error that breaks the code. Carefully follow the convention shown here when using importArticles.
But there's much more to importArticles than just this! For more examples and advanced usage, see the help page at Help:Including additional JavaScript and CSS.

Setup

Firstly, you need to create the pages referenced in your configuration: target and source. As an example, MediaWiki:Common.css is our target page, which will be updated with the parsed LESS, and MediaWiki:Common.less is our source page, which contains the LESS to parse.

One of the best features of Less is that it allows you to split up a large CSS file into several smaller, more easily maintainable files. To take advantage of this, we might set up our source file to look something like this:

// <pre>
/**
 * The is the root LESS file for [[MediaWiki:Common.css]]
 *
 * To update [[MediaWiki:Common.css]] from this file:
 * - For Oasis users: Click the "Update CSS" button at the top of the page
 * - For Monobook users: Click the "Update CSS" link in your toolbox
 */

// directory, used in imports
@dir: 'MediaWiki:Common.less/';

// template styling
@import '@{dir}navbox.less';
@import '@{dir}forum.less';
@import '@{dir}messagebox.less';
@import '@{dir}infobox.less';

// page specific styling
@import '@{dir}mainpage.less';

// customisations
@import '@{dir}webfonts.less';


// </pre>

As you can see the example source page here is really a series of imports referencing a number of other LESS files found on subpages of our source page. This setup isn't required, but may help keep your CSS more manageable. If you want, you don't have to use imports and can keep all your LESS in the source page. Note, the imports, source and target page must be on the same wiki—you can't import CSS from other wikis, although it may be supported in the future.

Next, you can create a page which will be added to the compiled CSS page as a header comment. This is optional, but if you do not use it, you must remove the option from your configuration; if it is in your configuration but the page does not exist, it will cause an error.

This is the only comment that will be found on the page, as the comments on the original files are very unlikely to match up to the compiled CSS and are thus removed to reduce confusion. The page should be a CSS comment, such as:

/**
 * This is the header for MediaWiki:Common.css
 *
 * This page is compiled from LESS files listed in MediaWiki:Common.less and should not be edited directly.
 * For documentation, see [[Project:CSS]]
 */

Lastly, we need to check our load array, set in the configuration. Note, this will not load on a source or target page automatically so you will need to explicitly declare the pages you want an update button on. If your source page is a series of imports, you might want to set it to load on the imported pages as well, so when you are finished editing them you can simply update the page they're used on with a single click.

The main configuration is an array, meaning you can have multiple source and target pairs, say MediaWiki:Common.css and MediaWiki:Common.less, MediaWiki:Wikia.css and MediaWiki:Wikia.less, etc. However, make sure pages in the load array are only used once as only one button will load regardless of how many times it's referenced. This is because of the generic nature of the text on the update button. More than one update button per page may be supported in the future.

Usage

After you've set everything up, you're now ready to start using the script! To start, navigate to any page you've set to load the update CSS button on. If you're using Oasis, you'll see a button labelled "Update CSS" near the edit button. If you're a Monobook user, the update button can be found in your toolbox. If the button isn't appearing, check your configuration.

After clicking the button an interface will popup. This will keep you updated on how the updating is going and notify you of most errors encountered. If it discovers a page that doesn't exist or encounters an error when parsing the content of your LESS files, it will output the error and a link to the problem page.

On rare occasions, the update process will stop and no error will be output to the interface. Firstly, try reloading the page and trying again. If you have this problem repeatedly, please report the page(s) you see it on and how far into the update process you get on the talk page.

Extra features

  • Standard mixins, documented at Less/mixins
  • Integration with Colors, which provides the following theme designer values:
    • @theme-body which corresponds to the colour of the wiki's background (behind any background image)
    • @theme-buttons which corresponds to the background colour of the wiki's buttons and local wiki navigation
    • @theme-header which corresponds to the background colour of the wiki's global navigation and collapsible footer bar
    • @theme-links which corresponds the the colour of the links on the wiki
    • @theme-page which corresponds the the colour of the page background
    • @theme-contrast which corresponds to the colour of text used in the wiki's buttons
    • @theme-text which corresponds to the colour of text used in the wiki's content area
    • @theme-gradient which is a secondary colour to be used in conjuction with @theme-buttons to create gradients
    • @theme-border which corresponds to the colour of border elements
  • Other helpful variables:
    • @filepath which can be used to generate the file path of an image, e.g. background-image:url('@{filepath}/filename.jpg');.
  • Formats indentation and newlines in the resulting CSS for consistency

FAQ

Do I need to learn LESS to use this script?
  • No! Valid CSS is valid LESS. If you don't want to use LESS for whatever reason, you can use this to split up your CSS files as well.
Where can I learn LESS?
  • A guide to LESS can be found here.

Translations

You can help with the translation of this script! The messages that need to be translated are:

  • Update CSS
  • LESS Interface
  • Close
  • Debug mode enabled
  • Getting source file: [[$1]]
    • Where $1 is the source LESS file provided in the configuration
  • Getting standard mixins
  • Attempting to parse LESS
  • Imported $1 successfully
    • Where $1 is the LESS file that was imported
  • Failed to import $1
    • Where $1 is the LESS file that could not be imported
  • Formatting CSS
  • Getting header comment
  • Successfully updated [[$1]]
    • Where $1 is the target CSS page provided in the configuration
  • Updating CSS from [[$1]]
    • Where $1 is the source LESS file provided the the configuration
  • Internal error
  • Page not found, please check your configuration
  • One or more files could not be imported, please ensure all @import statements reference existing pages
  • Parse error on line $1 in [[$2]]
    • Where $1 is the line number where the error was found
    • Where $2 is a link to the file where the error was detected
  • An unknown error has occurred
  • If this error persists, please report it [[$1|here]]

Please post any translations on the talk page using the following template, replacing en with your language code (or your language name if you're unsure what the code is):

<pre>
en: {
	'update-css': 'Update CSS',
	'less-title': 'LESS Interface',
	'less-close': 'Close',
	'debug-enabled': 'Debug mode enabled',
	'getting-source': 'Getting source file: [[$1]]',
	'getting-mixins': 'Getting standard mixins',
	'attempt-parse': 'Attempting to parse LESS',
	'import-success': 'Imported $1 successfully',
	'import-error': 'Failed to import $1',
	'formatting-css': 'Formatting CSS',
	'edit-success': 'Successfully updated [[$1]]',
	'edit-summary': 'Updating CSS from [[$1]]',
	'internal-error': 'Internal error',
	'page-not-found': 'Page not found, please check your configuration',
	'check-imports': 'One or more files could not be imported, please ensure all @import statements reference existing pages',
	'parse-error-file': 'Parse error on line $1 in [[$2]]',
	'unknown-error': 'An unknown error has occurred',
	'error-persist': 'If this error persists, please report it [[$1|here]]'
}
</pre>

You can also find additional message documentation in the source code.

Unfortunately, some messages are unable to be translated, specifically those output by less.js itself (which handles all the parsing) and the mediawiki api (which submits the edit once everything is parsed and formatted).

Updates

This only documents major updates, so may not correlate with the latest update in the infobox.

18th November 2016
  • Added @filepath variable.
3rd November 2016
  • Integrated Colors into the script, providing more variables relating to a wiki's theme.
18th July 2015
  • Fixed bug that cause duplicated messages to be output to the GUI
12th December 2014
  • Upgraded less source to v2.1.1
31st July 2014 (diff)
  • Fixed various problems with error reporting
23rd July 2014
  • Version 2 released
    • Adds support for importing LESS files with @import
    • Reworked i18n support
    • Added standard mixins
    • Added some theme designer values for use in stylesheets
    • Added the option to wrap the CSS in pre tags
29th March 2014
  • Script released

@import behaviour

The following is notes on what less.js does when it encounters various @import statements

/**
 * doesn't attempt to import
 * won't work through normal css @import due to lack of action=raw&ctype=text/css
 */
@import url( 'MediaWiki:Foo.css' );
@import url( '/wiki/MediaWiki:Foo.css' );
@import url( 'http://dev.wikia.com/wiki/MediaWiki:Foo.css' );
@import url( 'http://dev.wikia.com/index.php?title=MediaWiki:Foo.css' );
 
/**
 * doesn't attempt to import
 * will work through normal css @import
 */
@import url( '/wiki/MediaWiki:Foo.css?action=raw&ctype=text/css' );
@import url( '/index.php?title=MediaWiki:Foo.css&action=raw&ctype=text/css' );
@import url( 'http://dev.wikia.com/wiki/MediaWiki:Foo.css?action=raw&ctype=text/css' );
@import url( 'http://dev.wikia.com/index.php?title=MediaWiki:Foo.css&action=raw&ctype=text/css' );
 
/**
 * attempts to import
 */
@import url( '/load.php?debug=false&lang=en&mode=articles&articles=MediaWiki:Foo.css&only=styles' );
 
/**
 * attempts to import
 * import url -> http://dev.wikia.com/wiki/PAGENAME
 * less.js has been altered to append ?action=raw&ctype=text/css
 */
@import url( 'MediaWiki:Bar' );
@import url( 'MediaWiki:Common.css/bar' );
 
/**
 * attempts to import
 * import url -> /wiki/PAGENAME
 * less.js has been altered to append ?action=raw&ctype=text/css
 */
@import url( '/wiki/MediaWiki:Common.css/foo' );
 
/**
 * attempts to import
 * less.js has been altered to append ?action=raw&ctype=text/css
 */
@import 'MediaWiki:Bar.less';
 
/**
 * attempts to import
 * less.js has been altered to append ?action=raw&ctype=text/css
 */
@import url( 'http://dev.wikia.com/wiki/MediaWiki:Foo' );
 
/**
 * attempts to import
 * won't currently import due to it being a cross-origin request
 * UI doesn't react when it encounters this error, it just stops with no explanation why
 */
@import url( 'http://camtest.wikia.com/wiki/MediaWiki:Foo' );

Known bugs

  • Use of calc() produces incorrect results (this is a bug in the less.js parser).
    • calc( 100% + 2px ) results in calc(102%) when parsed. To get around this bug, use ~"calc( 100% + 2px )" which parses to calc(100% + 2px)

Planned future updates

These may be subject to change and have no release schedule associated with them. If you would like to request something that isn't listed here, please do so on the talk page.
  • Add support for importing LESS files from other Wikia wikis. Importing files from other MediaWiki installations, e.g. https://www.mediawiki.org, is not planned.
    • Syntax might be something like u:dev:PAGENAME.less which is converted to a proper URL before importing.
    • This is currently possible using ResourceLoader /load.php?debug=false&lang=en&mode=articles&articles=u:c:MediaWiki:Foo.css&only=styles but long strings in code are ugly, so this should be handled internally so we can simply do @import 'u:c:MediaWiki:Foo.css';
      • Requires testing to discover what happens when importing other dependencies though this method.
  • Add more standard mixins similar to those used by Wikia for things like button color gradients, etc.
  • Add other theme-designer values
  • Add support for more than one update CSS button per page
  • Integrate the ace editor for syntax highlighting and linting as you type, similar to the codeeditor extension found on Wikimedia wikis
    • Source code found at github:ajaxorg/ace, with LESS support at 1 and 2.
    • Possibly try to extend wikia's code editor (which uses ace as well).
  • Add a small API for testing new ideas/debugging
    • LESS -> CSS, enable/disable mixins, sassparams, etc.
    • Use to test changes before saving, similar to scribunto's error saving thing.
  • Show diff (for approval) before submitting update
    • Also show diff as the default preview ("Preview as CSS") when editing (move normal preview to the dropdown and rename "preview as text")

Ad blocker interference detected!


Wikia is a free-to-use site that makes money from advertising. We have a modified experience for viewers using ad blockers

Wikia is not accessible if you’ve made further modifications. Remove the custom ad blocker rule(s) and the page will load as expected.