Extension:ThemeToggle
ThemeToggle Release status: stable |
|
---|---|
Implementation | User interface |
Author(s) | alex4401 (Alex44019talk) |
Latest version | 1.0.0 |
MediaWiki | v0.4+: MediaWiki 1.39+ v0.1 - v0.3: MediaWiki 1.37+ |
Database changes | No |
License | GNU General Public License 3.0 or later |
Download | GitHub: Note: |
Example | ARK: Survival Evolved Wiki Temtem Wiki |
The ThemeToggle extension that allows for themes with minimal flash of wrongly styled content. This is achieved by delivering the script responsible for theme loading earlier and separately from other scripts (bypassing the requirement on MediaWiki's ResourceLoader client and having to wait for other modules such as TabberNeue, skin scripts, and so on).
Enabling
[edit]- Download and place the file(s) in a directory called
ThemeToggle
in yourextensions/
folder. - Add the following code at the bottom of your LocalSettings.php file:
wfLoadExtension( 'ThemeToggle' );
- If running a wiki farm or a network and themes are to be shared, adjust
$wgThemeToggleLoadScriptOverride
and$wgThemeTogglePreferenceGroup
appropriately. - On aggressively cached setups, you might want to wait (until you're done trying the extension out) with toggling
$wgThemeToggleEnableForAnonymousUsers
on and having the HTML cache purged. - Done – Navigate to Special:Version on your wiki to verify that the extension is successfully installed.
Wikis on wiki.gg have this extension enabled by default. You can prepare the theme CSS and definitions before the deployment is done.
Configuration
[edit]Variables
[edit]- $wgThemeToggleSwitcherStyle
- Controls which theme switcher module is used. If
auto
, usessimple
when there's two or less themes, anddropdown
otherwise. - Accepted values:
auto
,simple
,dropdown
,custom
. - Default:
auto
- $wgThemeToggleEnableForAnonymousUsers
- Controls whether the extension will be enabled for anonymous visitors.
- Changing this requires the HTML cache (Cloudflare level) to be purged for your wiki, as the
- Default:
true
- $wgThemeTogglePreferenceGroup
- Overrides the suffix used for server-side user's theme preference ID. The suffix exists because wiki.gg shares user preferences between all the wikis in the whole network, and so it is used to avoid poisoning the preference values for other wikis, and causing issues.
- If
null
, the wiki ID is used - on wiki.gg it consists of the wiki and the language, for exampleark_en
. - Changing this setting to a single, unique value allows for sharing the preference between your English wiki and its translations. It's recommended that you simply chop off the language code from the wiki ID: for ARK: Survival Evolved Wiki this would be
ark
. However, all of those wikis should have their theme definitions and styles kept in sync (while there is currently no definition sharing implemented, the$wgThemeToggleLoadScriptOverride
variable can be used to share the CSS). - Warning: Previous theme preferences are not migrated when the value is changed, and registered users will lose their theme choices. Old entries are also not removed from the database.
- Default:
null
- $wgThemeToggleLoadScriptOverride
- Overrides the ResourceLoader endpoint that will be used to load theme styles from. This may be used to share theme styles between multiple wikis by choosing a single one as the "authority" - which will act as the sole style provider.
- If
null
, defaults to the wiki's ownload.php
path. - Default:
null
- Example: to have the theme CSS loaded from your English wiki, set to
/load.php
on all translations.
Defining themes
[edit]Themes can be defined at MediaWiki:Theme-definitions, with format resembling the Gadgets extension.
Each line is a new theme definition, and must begin with an asterisk (*
), followed by an internal theme ID (which must be a single alphanumerical word / not contain any characters other than letters or numbers), and optionally options inside square brackets. For example:
* light[bundled] * dark
or
* blue[bundled|default] * red[bundled] * purple
The square brackets can be omitted if empty.
Names to be displayed in the theme switcher, or Special:Preferences, can be set by creating a system message titled MediaWiki:Theme-ID.
Definitions are bundled with the JavaScript sent to the browser. You may need to refresh your browser's cache before changes to the definitions list (or theme CSS) become visible.
Options
[edit]Option | Description |
---|---|
bundled |
Indicates the theme CSS is already included within MediaWiki:Vector.css (or another skin's) or MediaWiki:Common.css, and no extra needs to be loaded. The default theme of choice should have this option set. |
default |
Indicates this theme should be enabled by default for new users. If multiple themes have this flag set, only the first one matters. If no theme has this flag set, the first defined is assumed. If there is a light and a dark theme defined and there is no theme with this flag set, the script will try to detect the user's preference automatically.
|
Theme CSS
[edit]Themes without the bundled
flag have their CSS loaded from a system message titled MediaWiki:Theme-ID.css (for example MediaWiki:Theme-dark.css).
Monitoring theme usage
[edit]Special:ThemeUsage shows the number of registered users with each theme set as their preferred.
Users with preferences that are no longer valid (because the theme was removed from the definitions list) are shown in a separate row.
Translating
[edit]Please submit translations via the project's Weblate panel (log in with Discord).
See also
[edit]- Documentation on wiki.gg's support site
- GitHub repository
- Issues and planned features
- The extension's guide on wiki.gg's support wiki
- Example wikis:
This extension is included in the following wiki farms/hosts and/or packages: This is not an authoritative list. Some wiki farms/hosts and/or packages may contain this extension even if they are not listed here. Always check with your wiki farms/hosts or bundle to confirm. |
- Stable extensions
- User interface extensions
- GPL licensed extensions
- Extensions in GitHub version control
- PageDeleteComplete extensions
- PageSaveComplete extensions
- BeforePageDisplay extensions
- ResourceLoaderRegisterModules extensions
- GetPreferences extensions
- UserGetDefaultOptions extensions
- All extensions
- Extensions included in wiki.gg