WP25EasterEggs Extension

This is an extension to celebrate Wikipedia's 25th birthday, featuring an animated page companion that appears on specific articles with theme-aware animations.

Features

• Animated Page Companion: An interactive character that appears on specific articles based on their Wikidata QIDs
• Multiple Companion States: Showing different animations based on the article's Wikidata QID and Community Configuration
• Theme Support: Automatic adaptation to light/dark themes and OS preferences
• Community Configuration: Fine-grained control over which pages show companions and which companion states to display
• User Preferences: Users can enable/disable the feature via client preferences

Requirements

This extension requires:

• CommunityConfiguration extension
• WikibaseClient extension

Installation

1. Install and enable the CommunityConfiguration extension

2. Install and enable the Wikibase Client extension

   Boilerplate local dev config

   # LocalSettings.php
   
   # Add this to your LocalSettings.php to configure Wikibase Repository and Client
   # for local development. This config imitates enwiki to some extent by setting
   # up a local entity source with the same site ID.
   
   wfLoadExtension( 'WikibaseRepository', "$IP/extensions/Wikibase/extension-repo.json" );
   wfLoadExtension( 'WikibaseClient', "$IP/extensions/Wikibase/extension-client.json" );
   
   require_once "$IP/extensions/Wikibase/repo/config/Wikibase.example.php";
   require_once "$IP/extensions/Wikibase/client/config/WikibaseClient.example.php";
   
   $entitySources = [
       'local' => [
         'repoDatabase' => $wgDBname,
         'baseUri' => $wgServer . '/entity/',
         'entityNamespaces' => [
           'item' => 120,
           'property' => 122,
         ],
         'rdfNodeNamespacePrefix' => 'wd',
         'rdfPredicateNamespacePrefix' => '',
         'interwikiPrefix' => '',
       ],
   ];
   
   $wgWBRepoSettings['entitySources'] = $entitySources;
   $wgWBRepoSettings['localEntitySourceName'] = 'local';
   $wgWBClientSettings['entitySources'] = $entitySources;
   $wgWBClientSettings['itemAndPropertySourceName'] = 'local';
   $wgWBClientSettings['siteGlobalID'] = 'enwiki';
   $wgWBClientSettings['siteLinkGroups'] = [ 'wikipedia' ];

   # Source: https://www.mediawiki.org/wiki/Wikibase/Installation#Run_maintenance_scripts
   
   php maintenance/run.php update
   php maintenance/run.php ./extensions/Wikibase/lib/maintenance/populateSitesTable.php
   php maintenance/run.php ./extensions/Wikibase/repo/maintenance/rebuildItemsPerSite.php
   php maintenance/run.php populateInterwiki

   -- Run these SQL queries to set up test data for the extension
   -- This registers the wikibase-item content model and creates site links
   -- for the test pages (Sleep, Nap, Birthday, Newspaper) with their Wikidata QIDs
   
   INSERT INTO content_models (model_id, model_name) VALUES (2, 'wikibase-item');
   INSERT INTO wb_items_per_site (ips_item_id, ips_site_id, ips_site_page) VALUES
       (202833, 'enwiki', 'Social media'),
       (17517, 'enwiki', 'Mobile phone'),
       (144334, 'enwiki', 'Printing press'),
       (5891, 'enwiki', 'Philosophy'),
       (2927074, 'enwiki', 'Internet meme'),
       (36348, 'enwiki', 'Dream'),
       (1, 'enwiki', 'Universe'),
       (638, 'enwiki', 'Music'),
       (183998, 'enwiki', 'Camera obscura'),
       (164444, 'enwiki', 'Funk'),
       (200538, 'enwiki', 'Party'),
       (47223, 'enwiki', 'Birthday');

3. Install this extension following the standard MediaWiki extension installation process: https://www.mediawiki.org/wiki/Manual:Extensions/Installation_and_upgrade

4. Visit Special:CommunityConfiguration/WP25EasterEggs to enable the extension

Project Structure

Backend (src/)

• CommunityConfigurationDefinitions.php - Provides reusable schema definitions (PageFilter)
• CommunityConfigurationSchema.php - Defines the configuration schema for extension and companion settings
• Hooks.php - MediaWiki hooks integration (adds HTML classes, registers modules, etc.)
• PageCompanionConfigResolver.php - Resolves companion states based on Wikidata QIDs, default configs, and community configuration filters
• PageCompanionService.php - Main service for determining which companion configs apply to a page

Frontend (resources/ext.wp25EasterEggs/)

• init.js - Entry point for the client-side module
• core/ClientPrefsHandler.js - Handles user preference changes and companion lifecycle
• utils/ColorSchemeResolver.js - Detects and tracks color scheme changes (light/dark/OS preference)
• default-companion-configs.json - Mapping of Wikibase Item IDs (QIDs) to companion configurations

How It Works

1. Page Detection: When a page loads, PageCompanionService checks if it's a viewable article in the main namespace.
2. State Resolution: PageCompanionConfigResolver determines which companion state to show by:
   • Checking the global companion filter (everywhere/allowFilter/blockFilter) via isCompanionEnabled()
   • Iterating through each state (phone, newspaper, book, etc.) to find the first match using getCurrentCompanionConfig()
   • For each state, checking filtering priority: block list (excludes page) > allow list (includes page) > defaultPages setting.
   • If Wikibase Client is enabled, defaultPages checks if the current page's QID maps to a companion state in default-companion-configs.json.
3. HTML Classes: Appropriate classes are added to the page (e.g., wp25eastereggs-companion-enabled, wp25eastereggs-companion-dreaming).
4. Client Initialization: init.js detects the companion config from HTML classes and initializes ClientPrefsHandler.
5. Color Scheme Management: ColorSchemeResolver detects the current color scheme and listens for changes via prefers-color-scheme media query and client preference radio buttons.

Community Configuration

The extension can be configured via Community Configuration with the following options:

• EnableExtension: Global enable/disable toggle for the entire extension
• EnableCompanion: Controls where companions appear:
  • everywhere - Show on all eligible pages
  • allowFilter - Only show on specified pages
  • blockFilter - Show everywhere except specified pages
• Per-companion-state settings: Each companion state (phone, newspaper, book, etc.) has individual configuration with:
  • defaultPages - Whether to use default QID mappings
  • allowPages - Additional pages to show this state
  • blockPages - Pages to exclude from this state

Configuration

The extension allows for the following configuration options in LocalSettings.php:

• $wgWp25EasterEggsEnable (bool): Controls whether the extension's visual interventions are enabled for end users.
  • true: The "Birthday Mode" appearance toggle switch and the Baby Globe companion are displayed (subject to Community Configuration "EnableExtension" setting).
  • false (default): The extension's functionality and visual interventions are disabled, but the extension is still loaded and available for configuration.
• $wgWp25EasterEggsEnableDefaultState (bool): Controls whether the default companion is shown on pages that do not have a specific companion configuration.
  • true: The default companion is shown on all configured pages (unless a specific configuration of the companion is displayed).
  • false (default): The companion is only shown on pages that have a specific configuration (via Community Configuration and predefined pages).