Skip to main content

​
Overview

Citizen provides hook handlers to integrate with MediaWiki’s hook system. Hook classes are located in includes/Hooks/ and handle both skin-specific and ResourceLoader-related functionality. Namespace: MediaWiki\Skins\Citizen\Hooks

​
SkinHooks

Handles skin-related hooks for modifying page display, navigation, and UI elements. Location: includes/Hooks/SkinHooks.php Implements:
  • BeforePageDisplayHook
  • OutputPageAfterGetHeadLinksArrayHook
  • SidebarBeforeOutputHook
  • SkinBuildSidebarHook
  • SkinPageReadyConfigHook

​
onBeforePageDisplay

Adds inline theme switcher script to page head for Citizen skin. 
public function onBeforePageDisplay( OutputPage $out, Skin $skin ): void
​
out
OutputPage
required
The OutputPage object
​
skin
Skin
required
The current skin instance
Behavior:
  • Only runs when $skin->getSkinName() is 'citizen'
  • Only adds script when CitizenEnablePreferences config is true
  • Minifies and caches the inline script from resources/skins.citizen.scripts/inline.js
Usage Example: 
// Hook is automatically called by MediaWiki
// To enable, ensure CitizenEnablePreferences is true in LocalSettings.php
$wgCitizenEnablePreferences = true;

​
onOutputPageAfterGetHeadLinksArray

Replaces the viewport meta tag with Citizen’s optimized version. 
public function onOutputPageAfterGetHeadLinksArray( array &$tags, OutputPage $out ): void
​
tags
array
required
Reference to array of HTML head tags
​
out
OutputPage
required
The OutputPage object
Changes from MediaWiki default:
  • Added: viewport-fit=cover for iOS notch support
  • Removed: user-scalable=yes (default behavior)
  • Removed: minimum-scale=0.25 (outdated iOS workaround)
  • Removed: maximum-scale=5.0 (outdated iOS workaround)
Resulting meta tag: 
<meta name="viewport" content="width=device-width,initial-scale=1,viewport-fit=cover">

​
onSidebarBeforeOutput

Modifies toolbox menu items before sidebar output. 
public function onSidebarBeforeOutput( Skin $skin, array &$sidebar ): void
​
skin
Skin
required
The current skin instance
​
sidebar
array
required
Reference to sidebar data array
Purpose: Adds icons and modifies toolbox menu items. This hook is used because onSkinBuildSidebar cannot access the toolbox reliably.

​
onSkinBuildSidebar

Modifies sidebar navigation links with icons and adds site tools. 
public function onSkinBuildSidebar( Skin $skin, array &$bar ): void
​
skin
Skin
required
The current skin instance
​
bar
array
required
Reference to sidebar navigation array
Features:
  • Adds Special:SpecialPages link (on MW < 1.44)
  • Adds Upload link if uploads are enabled
  • Maps icons to menu items:
    • n-specialpages → specialPages
    • t-specialpages → specialPages
    • t-upload → upload
  • Generates icon HTML for mapped items
Configuration: Use CitizenGlobalToolsPortlet to specify which portlet should contain site tools: 
// In LocalSettings.php
$wgCitizenGlobalToolsPortlet = 'navigation'; // Default is first portlet

​
onSkinPageReadyConfig

Tells MediaWiki’s page ready module not to wire up search (Citizen handles it). 
public function onSkinPageReadyConfig(
    ResourceLoader\Context $context,
    array &$config
): void
​
context
ResourceLoader\Context
required
ResourceLoader context
​
config
array
required
Reference to configuration array
Effect: Sets $config['search'] = false to prevent MediaWiki’s default search initialization.

​
onSkinTemplateNavigation (static)

Modifies navigation links for various menus with icons and styling. 
public static function onSkinTemplateNavigation(
    SkinTemplate $sktemplate,
    array &$links
): void
​
sktemplate
SkinTemplate
required
The skin template instance
​
links
array
required
Reference to navigation links array
Modifies these menus:
  • actions - Page action menu (delete, move, protect, purge, etc.)
  • associated-pages - Namespace tabs (article, talk, user, etc.)
  • TOOLBOX - Toolbox menu (related changes, print, etc.)
  • notifications - Echo notifications (if installed)
  • user-menu - User menu
  • user-interface-preferences - UI preference menu
  • views - View/edit menu
Icon mappings include: 
// Actions menu
'delete' => 'trash'
'move' => 'move'
'protect' => 'lock'
'purge' => 'reload'

// Views menu
'view' => 'eye'
'edit' => 'edit'
'history' => 'history'
've-edit' => 'edit'

// Associated pages
'main' => 'article'
'talk' => 'speechBubbles'
'user' => 'userAvatar'
Visual Editor handling: When both VE and source edit are present:
  • Adds citizen-ve-edit-merged class to both buttons
  • Changes source edit icon from edit to wikiText
  • Makes edit buttons progressive primary instead of quiet
Usage Example: 
// Hook is called automatically during navigation building
// Called from SkinCitizen::runOnSkinTemplateNavigationHooks()

​
ResourceLoaderHooks

Provides configuration data to ResourceLoader modules. Location: includes/Hooks/ResourceLoaderHooks.php

​
getCitizenResourceLoaderConfig (static)

Passes configuration to skins.citizen.scripts ResourceLoader module. 
public static function getCitizenResourceLoaderConfig(
    ResourceLoader\Context $context,
    Config $config
): array
​
context
ResourceLoader\Context
required
ResourceLoader context
​
config
Config
required
Configuration object
​
return
array
Configuration array with these keys:
  • wgCitizenEnablePreferences: bool
  • wgCitizenOverflowInheritedClasses: array
  • wgCitizenOverflowNowrapClasses: array
  • wgCitizenSearchModule: string
  • wgCitizenEnableCommandPalette: bool
Usage in JavaScript: 
const config = require( './config.json' );
if ( config.wgCitizenEnablePreferences ) {
    // Enable preferences UI
}

​
getCitizenPreferencesResourceLoaderConfig (static)

Passes configuration to skins.citizen.preferences ResourceLoader module. 
public static function getCitizenPreferencesResourceLoaderConfig(
    ResourceLoader\Context $context,
    Config $config
): array
​
context
ResourceLoader\Context
required
ResourceLoader context
​
config
Config
required
Configuration object
​
return
array
Configuration with wgCitizenThemeDefault key

​
getCitizenSearchResourceLoaderConfig (static)

Passes configuration to skins.citizen.search ResourceLoader module. 
public static function getCitizenSearchResourceLoaderConfig(
    ResourceLoader\Context $context,
    Config $config
): array
​
context
ResourceLoader\Context
required
ResourceLoader context
​
config
Config
required
Configuration object
​
return
array
Configuration array:
  • isAdvancedSearchExtensionEnabled: bool
  • isMediaSearchExtensionEnabled: bool
  • wgCitizenSearchGateway: string
  • wgCitizenSearchDescriptionSource: string
  • wgCitizenMaxSearchResults: int
  • wgScriptPath: string
  • wgSearchSuggestCacheExpiry: int

​
getCitizenCommandPaletteResourceLoaderConfig (static)

Passes configuration to skins.citizen.commandPalette ResourceLoader module. 
public static function getCitizenCommandPaletteResourceLoaderConfig(
    ResourceLoader\Context $context,
    Config $config
): array
​
context
ResourceLoader\Context
required
ResourceLoader context
​
config
Config
required
Configuration object
​
return
array
Configuration with extension status and cache settings:
  • isMediaSearchExtensionEnabled: bool
  • wgSearchSuggestCacheExpiry: int

​
getCitizenPreferencesOverrides (static)

Returns on-wiki preference overrides with resolved message texts. 
public static function getCitizenPreferencesOverrides(
    ResourceLoader\Context $context,
    Config $config
): array
​
context
ResourceLoader\Context
required
ResourceLoader context
​
config
Config
required
Configuration object
​
return
array
Preference overrides with structure:
[
    'overrides' => ?array,
    'messages' => stdClass|array<string, string>
]
Purpose: Allows on-wiki customization of preferences through MediaWiki pages.

​
Registering Hooks

Hooks are registered in skin.json under the Hooks section: 
{
  "Hooks": {
    "BeforePageDisplay": "MediaWiki\\Skins\\Citizen\\Hooks\\SkinHooks",
    "SkinBuildSidebar": "MediaWiki\\Skins\\Citizen\\Hooks\\SkinHooks"
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us