View source for Halopedia:Skins/Onyx

<center>'''''PARDON OUR DUST!''' This page is still under construction.''</center>

'''Onyx''' is a [[Wikipedia:MediaWiki|MediaWiki]] [[mw:Manual:Skins|skin]] designed to emulate and improve upon Oasis, the desktop skin used on wikis hosted by [[Wikipedia:Wikia|Wikia/FANDOM]]. It was primarily written by [[User:Dab1001|Dab1001]] with help from [[User:Jack Phoenix|Jack Phoenix]], and is maintained by the Halopedia team. It is free and open-source under the [[Wikipedia:GNU General Public License|GPL v2 license]], and its source code can be found [https://github.com/Halopedia/Onyx here.]

Since its inception, the scope of the Onyx skin has expanded beyond just Halopedia, now aiming to provide a fully-featured, general-purpose skin for use on any wiki. Although primarily a surrogate for Oasis, Onyx hopes to improve upon its progenitor wherever possible, with the inclusion of minor improvements and refinements, like a wide page width for more article space, and quality-of-life features like a scrolling table of contents.

__TOC__

==History==
First conceived in late 2018 while planning the merger of Halo Nation into Halopedia, Onyx's original aim was to ease the transition to Halopedia, for users going from Wikia's service to an independently-hosted wiki. Christened "Onyx" after the eponymous Forerunner shield world in the ''Halo'' universe, development began on the project, and its sister project [[Halopedia:Skins/Trove|Trove]] (then named Trevelyan), in January 2019. Progress was slow throughout most of the year, but the skin was released on Halopedia in a beta state in the fourth quarter of 2019.

Onyx was originally planned to be one of a pair of skins, the other being Trevelyan, a mobile skin loosely based on Wikia/FANDOM's mobile skin, Mercury. In April 2020, however, it became clear that Halopedia's then-default skin, [[mw:Skin:Nimbus|Nimbus]], would need to be retired due to lack of support for extensions such as [[mw:Extension:Echo|Echo]], and a desire to modernise the site's frontend. Consequently, this pair of skins was expanded into the Maginot skin family project, and now includes Onyx, [[Halopedia:Skins/Trove|Trove]] (a newly renamed Trevelyan), [[Halopedia:Skins/Requiem|Requiem]] and [[Halopedia:Skins/Noble|Noble]]. This project is still in its infancy, however, and is far from complete.

==Installation==
# Make sure that your wiki is using a compatible version of MediaWiki (basically whatever Halopedia is currently using; see [[Special:Version]])
# Check out the source code via git into your wiki's <code>skins</code> directory: <code>git clone https://github.com/Halopedia/Onyx.git</code>
# Add the following to your wiki's <code>LocalSettings.php</code> file to initialize the skin: <code>wfLoadSkin( 'Onyx' );</code>
# Configure at will ([[#Configuration options|see below for details]])
# Visit your wiki's <code>Special:Version</code> page to verify that the skin has been correctly installed
# That's it!

==Configuration options==
Onyx features a large number of configuration options, to allow wikis to customise it to their exact needs. As part of the Maginot skin family, Onyx will also inherit configuration settings set for that family, so that consistency . However, configuration options set specifically for Onyx will override those set for Maginot family as a whole. So, for instance, if the options <code>$wgOnyxBannerLogo</code> and <code>$wgMaginotBannerLogo</code> are both set, the skin will favour the value of <code>$wgOnyxBannerLogo</code>.

If any are left unset, the skin will use a sensible default value instead. Despite this, however, it is ''strongly'' recommended that you at least set <code>$wgBannerLogo</code> and <code>$wgHeaderLogo</code>, as these default to the value of <code>[[mw:Manual:$wgLogo|$wgLogo]]</code>, which typically points to a square image ill-suited to the Onyx skin.

===Example===
This is an example Onyx configuration setup.

<pre>
$wgOnyxNavigationSource = 'MediaWiki:Onyx/Navigation';
$wgOnyxToolboxSource = 'MediaWiki:Onyx/Toolbox';
$wgOnyxBannerLogo = $wgScriptPath . '/images/4/47/myBannerLogo.png';
$wgOnyxHeaderLogo = $wgScriptPath . '/images/6/3A/myHeaderLogo.png';
</pre>

===List===
The following is a list of all configuration options currently supported by Onyx. Each option is also supported by the entire Maginot skin family, and a configuration option can be set for all Maginot skins by replacing the <code>Onyx</code> in <code>$wgOnyx...</code> with <code>Maginot</code>.

{| width=100% class="wikitable"
|-
! width=20% | Option name
! width=10% | Type
! width=20% | Default value
! width=45% | Description
! width=5% | Version
|-
| <code>$wgOnyxNavigationSource</code>
| string
| ''"MediaWiki:NavigationSource"''
| The full page name (including namespace) from which the navigation menus should be drawn. If the specified page does not exist, the skin will default to the content of [[MediaWiki:Sidebar]] instead. ''It is strongly advised that you protect this page from general editing!''
| 1.0.0≤
|-
| <code>$wgOnyxBannerLogo</code>
| string
| ''$wgLogo''
| The URL of the image that should be used for the logo on the banner. Set it in the same manner as you would [[mw:Manual:$wgLogo|$wgLogo]]. The recommended dimensions for the image are 300px by 45px, and the maximum dimensions are 350px by 45px. Any images larger than this in either axis will be scaled down to fit and centred vertically. ''It is strongly advised that you protect this file from general editing/replacement!''
| 1.0.0≤
|-
| <code>$wgOnyxUseBannerLogoImage</code>
| boolean
| ''true''
| This decides whether an image logo should be displayed in the banner, or if it should instead be replaced by the wiki's title in plain text. True corresponds to displaying the logo image, and false to displaying the title as text.
| 1.0.0≤
|-
| <code>$wgOnyxHeaderLogo</code>
| string
| ''$wgLogo''
| The URL of the image that should be used for the logo on the page header. Set it in the same manner as you would $wgLogo. The recommended dimensions for the image are 350px by 135px, and the maximum dimensions are 400px by 135px. Any images larger than this in either axis will be scaled down to fit and centred vertically. ''It is strongly advised that you protect this file from general editing/replacement!''
| 1.0.0≤
|-
| <code>$wgOnyxShowUsernameOnBanner</code>
| boolean
| ''true''
| Whether or not the skin should display the user's username beside their avatar image on the banner.
| 1.0.0≤
|-
| <code>$wgOnyxShowUsernameOnBannerForAnons</code>
| boolean
| ''true''
| Whether or not the skin should display the message "Anonymous" next to the default avatar image on the banner, for anonymous readers and users.
| 1.0.0≤
|-
| <code>$wgOnyxSiteNoticeCookieExpiryTime</code>
| integer
| ''7''
| The amount of time, in days, before the cookie remembering that the user has closed the site notice will expire. This, in essence, will ensure that the site notice is always presented to the user at least once every time this duration elapses. If the site notice content is changed, the cookie will be ignored and the site notice will still be presented, so new site notices will always be seen immediately.
| 1.0.0≤
|-
| <code>$wgOnyxSidebarCookieExpiryTime</code>
| integer
| ''30''
| The amount of time, in days, before cookies storing the user's preferred sidebar state (expanded or collapsed) will expire. These cookies will refresh every time the user visits the site, so the value will only reset if the user does not visit the wiki for more than this period of time.
| 1.0.0≤
|-
| <code>$wgOnyxShowSidebarByDefault</code>
| boolean
| ''true''
| Determines whether the sidebar should be collapsed or expanded upon initial page load, if there are no saved cookies indicating the user's preference.
| 1.0.0≤
|-
| <code>$wgOnyxShowSidebarByDefaultOnEdit</code>
| boolean
| ''false''
| Determines whether the sidebar should be collapsed or expanded by default when editing, if there are no saved cookies indicating the user's preference.
| 1.0.0≤
|-
| <code>$wgOnyxShowSidebarByDefaultOnMainPage</code>
| boolean
| ''false''
| Determines whether the sidebar should be collapsed or expanded by default on the wiki's main page, if there are no saved cookies indicating the user's preference.
| 1.0.0≤
|-
| <code>$wgOnyxEnableRecentChangesModule</code>
| boolean
| ''true''
| Enables or disables the recent changes module on the sidebar, with true corresponding to enabled. Disabling recent changes may have a minor performance increase, as it removes the need for another database read on page load. However, the results are cached, so the hit to performance should be minimal.
| 1.0.0≤
|-
| <code>$wgOnyxRecentChangesCacheExpiryTime</code>
| integer
| ''30''
| The time, in seconds, before the cached information used by the recent changes sidebar module should be considered expired, and hence refreshed.
| 1.0.0≤
|-
| <code>$wgOnyxRecentChangesAmount</code>
| integer
| ''7''
| The number of recent changes that should be displayed on the recent changes sidebar module.
| 1.0.0≤
|-
| <code>$wgOnyxEnablePageContentsModule</code>
| boolean
| ''true''
| Determines whether or not the page contents sidebar module should be displayed. This has no impact on server-side performance, as the contents list is populated using client-side JavaScript.
| 1.0.0≤
|-
| <code>$wgOnyxPageContentsMinHeadings</code>
| integer
| ''3''
| The minimum number of headings the page needs to include in order for the page contents sidebar module to be displayed. Values of zero or less will cause the page contents module to always appear, even if empty.
| 1.0.0≤
|-
| <code>$wgOnyxPageContentsEnableHighlighting</code>
| boolean
| ''true''
| Toggles the page contents module's auto-highlighting feature, where sections of the contents table are automatically highlighted and expanded when the user is currently reading that section. Enabling this can have an impact on client-side performance, but this impact has been minimised as much as possible.
| 1.0.0≤
|-
| <code>$wgOnyxEnableCustomStaticSidebarModule</code>
| boolean
| ''true''
| Determines whether or not the static custom sidebar module should be displayed or not. Disabling this may give a minor boost to server-side performance, as the sidebar module will not need to be read from the database and parsed. However, the results are cached, meaning the performance impact should be minimal.
| 1.0.0≤
|-
| <code>$wgOnyxCustomStaticSidebarModuleSource</code>
| string
| ''"MediaWiki:Custom-sidebar-module-static"''
| The full page name (including namespace) of the page from which the static custom sidebar module content should be drawn. The static custom module sits at the very top of the sidebar and will ''not'' follow the user as they scroll along the page. ''It is strongly advised that you protect this page from general editing!''
| 1.0.0≤
|-
| <code>$wgOnyxEnableCustomStickySidebarModule</code>
| boolean
| ''true''
| Determines whether or not the sticky custom sidebar module should be displayed or not. Disabling this may give a minor boost to server-side performance, as the sidebar module will not need to be read from the database and parsed. However, the results are cached, meaning the performance impact should be minimal.
| 1.0.0≤
|-
| <code>$wgOnyxCustomStickySidebarModuleSource</code>
| string
| ''"MediaWiki:Custom-sidebar-module-sticky"''
| The full page name (including namespace) of the page from which the sticky custom sidebar module content should be drawn. The sticky custom module sits at the bottom of the sidebar and ''will'' follow the user as they scroll along the page. ''It is strongly advised that you protect this page from general editing!''
| 1.0.0≤
|}

===Navigation and Toolbox===
For the navigation and toolbox lists, Onyx implements a superset of the standard MediaWiki:Sidebar syntax. Firstly, it supports nested lists, which will manifest as dropdown menus. These can be up to two levels deep. For example, the following content would create a dropdown list labelled "Lorem", with three options: "Ipsum", "Dolor" and "Consectetur", where "Dolor" is itself a dropdown list with options "Sit" and "Amet".

<pre>
* Lorem
** Ipsum
** Dolor
*** Sit
*** Amet
** Consectetur
</pre>

In addition, the navigation list supports assigning 14x14 icons to the options. These either use the id of any icon in the [[#Icons|the Maginot family's shared icon set]], in which case the icons will be displayed as inline SVGs and can hence be styled using CSS, or can be the page name of a file on the wiki, in which case the corresponding image will be scaled to the appropriate size. The syntax to assign these icons to the navigation options is as follows:

<pre>
* PAGE_TITLE <icon_id> | LINK_TEXT
* PAGE_TITLE {File:FILENAME} | LINK_TEXT
</pre>

Because '<', '>', '{' and '}' are not valid characters in page titles, this syntax will never conflict with page names. However, it is not compatible with other skins, and so it is strongly advised that you do not use this syntax on any navigation list pages shared by other skins.

===Icons===
{{Expand-section}}
Onyx and the other Maginot skins share a set of icons for consistency with one another. These icons are used in a number of areas on the skins, but can be used to augment the navigation list elements with a CSS-styleable inline SVG beside their labels (see [[#Navigation and Toolbox|the Navigation and Toolbox section]]). The following is a list of all of the icons currently included: