Skip to content

Latest commit

 

History

History
131 lines (97 loc) · 5.15 KB

customization.md

File metadata and controls

131 lines (97 loc) · 5.15 KB

Customization

The Chameleon skin can be highly customized. There are two main areas that you can change:

  1. Layout (defined by a XML file)
  2. Styles (defined by LESS files and/or LESS variables)

Layout of page elements

The layout of the page elements (nav bar, logo, search bar, etc.) is defined in an XML file. There are currently five pre-defined layouts available:

They can be activated by setting the variable $egChameleonLayoutFile in LocalSettings.php. E.g. to activate the fixedhead layout you could add

$egChameleonLayoutFile= __DIR__ . '/skins/chameleon/layouts/fixedhead.xml';

Selecting the layout from the browser address bar

To select a specific layout different from the one defined in $egChameleonLayoutFile you can add the uselayout parameter to the URL. However for some wikis it might not be desirable to have this feature. So to make this work you have to define the available layouts in LocalSettings.php. E.g. to include all layouts delivered with Chameleon add

$egChameleonAvailableLayoutFiles = array(
	'standard'   => __DIR__ . '/skins/chameleon/layouts/standard.xml',
	'navhead'    => __DIR__ . '/skins/chameleon/layouts/navhead.xml',
	'fixedhead'  => __DIR__ . '/skins/chameleon/layouts/fixedhead.xml',
	'stickyhead' => __DIR__ . '/skins/chameleon/layouts/stickyhead.xml',
	'clean'      => __DIR__ . '/skins/chameleon/layouts/clean.xml',
);

Creating a custom layout

You can of course also define and use your own layout. To start have a look at the documentation of the components and at the exisiting layout description files.

Changing styles: Fonts, Colors, Padding etc.

You can customize the styles of the skin by

  • importing additional LESS files (for example existing Bootstrap themes)
  • and/or by changing existing LESS variables.

Regardless of the order of the calls, variables will always override imported files.

Importing additional LESS files

To import additional LESS files, add them to the array $egChameleonExternalStyleModules in LocalSettings.php:

$egChameleonExternalStyleModules = array(
    $localPathToLESSFile1 => $remotePathToLESSFile1Directory,
    $localPathToLESSFile2 => $remotePathToLESSFile2Directory,
    ...
);

If your LESS file does not reference any other files (fonts, images, ...), you may omit the remote path. Just write:

$egChameleonExternalStyleModules = array( $localPathToLESSFile1, $localPathToLESSFile2, ... );

Example:

To use the Amelia theme from Bootswatch you could download the variables.less and the bootswatch.less file to your MediaWiki installation directory, rename them to amelia-variables.less and amelia-bootswatch.less and then add the following code to your LocalSettings.php:

$egChameleonExternalStyleModules = array(
    __DIR__ . '/amelia-variables.less' => $wgScriptPath,
    __DIR__ . '/amelia-bootswatch.less' => $wgScriptPath,
);

You can of course define your own LESS file too: Just place it in your MediaWiki installation directory and import it like shown above.

Changing existing LESS variables

Chameleon comes with many LESS variables (see this list). All of them have a default value. To change those values you should not edit the LESS files that come with Chameleon, because if you update Chameleon your changes will be overridden. Instead change the values of the LESS variables in your LocalSettings.php by adding them to the array $egChameleonExternalLessVariables:

$egChameleonExternalLessVariables = array(
    'key1' => 'value1',
    'key2' => 'value2',
    ...
);

If you add variables to the array (to change them), make sure you omit the @ before the variable name.

Apart from the LESS variables defined in Chameleon itself, you can also change LESS variables of LESS files that you imported yourself.

Example:

To make the navigation bar a bit narrower you could add

$egChameleonExternalLessVariables = array(
    'navbar-height' => '30px',
);

Triggering a cache update

Compiling the style files is time-consuming. For this reason the styles are not compiled on every page request. Instead they are cached after being compiled. For changes to the styles to become effective it is necessary to trigger an update of the style cache. There are two ways to do that:

  1. A cache update is triggered when the LocalSettings.php file has a modification time later than the last cache update time. So you have to resave the LocalSettings.php to trigger a cache update. This can be achieved by using the touch utility on UNIX and friends or by using copy /b LocalSettings.php +,, from the MediaWiki installation directory on Windows. Alternatively, just open the file and re-save it.

  2. If the above becomes to cumbersome, you could add the following to your LocalSettings.php:
    \Bootstrap\BootstrapManager::getInstance()->addCacheTriggerFile( __DIR__ . '/your-less-file.less' );.