Changes: Less

Revision as of 21:17, 4 August 2018

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 FANDOM themselves, but LESS allows us to compile the stylesheet with javascript making this script possible.

A demonstration of this script can be found at MediaWiki:Custom-Less/test.less and MediaWiki:Custom-Less/test.css.

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:Custom-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:Custom-common.less'
    ],
    // this is the page that contains the comment header for the target page
    // all other comments are stripped during compilation
    header: 'MediaWiki:Custom-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 user groups 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: Template:ImportArticles

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:Custom-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:Custom-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 on 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:Custom-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:Custom-common.less, MediaWiki:Wikia.css and MediaWiki:Custom-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 pop up. 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.

Updates

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

13th June 2018

Added i18n-js integration to make translating easier.

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 caused duplicated messages to be output to the GUI.

12th December 2014

Upgraded less source to v2.1.1.

31st July 2014

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 FANDOM 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 FANDOM for things like button colour 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 FANDOM'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")

@@ Line 12: / Line 12: @@
 [[MediaWiki:Less/less.js|less.js]] (less source)
 | Languages = auto
-| Status = stable
+| Status = unmaintained
 }}
 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.