Support LESS stylesheets in ResourceLoader
authorOri Livneh <ori@wikimedia.org>
Sun, 11 Aug 2013 16:40:20 +0000 (00:40 +0800)
committerOri Livneh <ori@wikimedia.org>
Mon, 23 Sep 2013 19:55:19 +0000 (12:55 -0700)
commitb67b9e1b488f564b2d3337bef4e90cce8a297ca5
tree49169bbd1f5349017e2edb5ee30d6a643825c906
parent8c74b6bebfdf76adf8c80a27becaa784cb9805db
Support LESS stylesheets in ResourceLoader

This patch adds support for the LESS stylesheet language to ResourceLoader.
LESS is a stylesheet language that compiles into CSS. The patch includes
lessphp, a LESS compiler implemented in PHP. The rationale for choosing LESS is
explained in a MediaWiki RFC which accompanies this patch, available at
<https://www.mediawiki.org/wiki/Requests_for_comment/LESS>.

LESS support is provided for ResourceLoader file modules. It is triggered by
the presence of the '.less' extension in stylesheet filenames. LESS files are
compiled by lessc, and the resultant CSS is subjected to the standard set of
transformations (CSSJanus & CSSMin). The immediate result of LESS compilation
is encoded as an array, which includes the list of LESS files that were
compiled and their mtimes. This array is cached. Cache invalidation is
performed by comparing the cached mtimes with the mtimes of the files on disk.
If the compiler itself throws an exception, ResourceLoader constructs a
compilation result which consists of the error message encoded as a CSS
comment. Failed compilation results are cached too, but with an expiration time
of five minutes. The expiration time is required because the full list of
referenced files is not known.

Three configuration variables configure the global environment for LESS
modules: $wgResourceLoaderLESSVars, $wgResourceLoaderLESSFunctions, and
$wgResourceLoaderLESSImportPaths. $wgResourceLoaderLESSVars maps variable names
to CSS values, specified as strings. Variables declared in this array are
available in all LESS files. $wgResourceLoaderLESSFunctions is similar, except
it maps custom function names to PHP callables. These functions can be called
from within LESS to transform values. Read more about custom functions at
<http://leafo.net/lessphp/docs/#custom_functions>. Finally,
$wgResourceLoaderLESSImportPaths specifies file system paths in addition to the
current module's path where the LESS compiler should look up files referenced
in @import statements.

The issue of handling of /* @embed */ and /* @noflip */ annotations is left
unresolved. Earlier versions of this patch included an @embed analog
implemented as a LESS custom function, but there was enough ambiguity about
whether the strategy it took was optimal to merit discussing it in a separate,
follow-up patch.

Bug: 40964
Change-Id: Id052a04dd2f76a1f4aef39fbd454bd67f5fd282f
12 files changed:
RELEASE-NOTES-1.22
includes/AutoLoader.php
includes/DefaultSettings.php
includes/libs/lessc.inc.php [new file with mode: 0644]
includes/resourceloader/ResourceLoaderFileModule.php
includes/resourceloader/ResourceLoaderModule.php
resources/mediawiki.less/mediawiki.mixins.less [new file with mode: 0644]
tests/phpunit/data/less/common/test.common.mixins.less [new file with mode: 0644]
tests/phpunit/data/less/module/dependency.less [new file with mode: 0644]
tests/phpunit/data/less/module/styles.css [new file with mode: 0644]
tests/phpunit/data/less/module/styles.less [new file with mode: 0644]
tests/phpunit/includes/ResourceLoaderTest.php