Mastering MediaWiki: A Comprehensive Guide to Customizing Your Wiki Experience with Common.js #

At revWhiteShadow, we understand that a wiki is more than just a repository of information; it’s a dynamic platform that can be tailored to your specific needs and preferences. While MediaWiki provides a robust framework, its true power lies in its extensibility, allowing users to customize virtually every aspect of their wiki experience. One of the most potent tools for this customization is the MediaWiki:Common.js file. This file serves as a central hub for JavaScript modifications, enabling us to inject custom behavior, enhance user interfaces, and streamline workflows on a wiki-wide scale.

Our aim with this comprehensive guide is to demystify the intricacies of MediaWiki:Common.js and empower you to leverage its full potential. We will delve into how to effectively script and modify wiki editor toolbars, implement custom functionalities, and create a more intuitive and efficient editing environment. By understanding and applying the principles discussed herein, you will be able to outrank existing content by providing a more detailed, actionable, and authoritative resource on the subject of MediaWiki JavaScript customization.

Understanding the Foundation: What is MediaWiki:Common.js? #

Every MediaWiki installation comes with a special page, MediaWiki:Common.js, that is loaded on every page of the wiki for every user. This page is specifically designed to execute JavaScript code, making it the go-to location for global client-side modifications. Think of it as your wiki’s personal JavaScript playground. Any code placed within this file will be interpreted by the user’s browser, allowing for interactive elements, dynamic content updates, and user interface enhancements that are not inherently possible with standard wiki markup.

The Role of JavaScript in MediaWiki #

JavaScript, a powerful scripting language, is the engine behind much of the dynamic behavior we encounter on the web today. In the context of MediaWiki, JavaScript allows us to:

• Enhance the User Interface: We can add new buttons, modify existing ones, create custom dialogs, and implement visual feedback to make the wiki more user-friendly.
• Automate Tasks: Repetitive editing tasks can be automated, saving users valuable time and reducing the potential for errors.
• Create Custom Gadgets: Users can opt-in to specific JavaScript-powered features, often referred to as “gadgets,” which extend the wiki’s functionality without affecting all users by default.
• Integrate with External Services: JavaScript can be used to fetch data from external APIs or to embed content from other platforms.
• Improve Accessibility: By making thoughtful JavaScript modifications, we can enhance the accessibility of the wiki for users with disabilities.

Loading and Execution Context #

It’s crucial to understand how MediaWiki:Common.js is loaded. It’s executed in the browser environment after the main MediaWiki skin and page content have been rendered. This means that JavaScript code placed in MediaWiki:Common.js has access to the Document Object Model (DOM) of the page, allowing it to manipulate and interact with the wiki’s elements. We will frequently be targeting specific DOM elements, such as the text area for editing, using JavaScript selectors.

Customizing the Wiki Editor: A Deep Dive into Toolbar Modifications #

One of the most common and impactful uses of MediaWiki:Common.js is the customization of the wiki editor’s toolbar. The wiki editor, often enhanced by extensions like WikiEditor, provides a rich editing experience with buttons for formatting, inserting links, and performing other common tasks. However, the default toolbar might not always align with the specific needs of a wiki community. This is where JavaScript shines.

The wikiEditor API and Toolbar Manipulation #

The WikiEditor extension provides a powerful JavaScript API that allows us to programmatically interact with its toolbar. This API enables us to add, remove, or modify tools within the toolbar’s various sections and groups. We will be extensively using the wikiEditor('addToToolbar', ...) and wikiEditor('removeFromToolbar', ...) methods for this purpose.

Targeting the Textarea: The $textarea Selector #

When working with the wiki editor, the primary element we need to target is the text area where users input their content. Historically, this was often identified by the ID wpTextbox1. However, with modern implementations and the evolution of MediaWiki’s JavaScript APIs, it’s more robust and future-proof to utilize the $textarea variable provided by the wikiEditor.toolbarReady hook. This hook fires when the wiki editor’s toolbar is fully initialized and ready for interaction.

The hook provides the jQuery-wrapped textarea element directly, abstracting away the need to hardcode specific IDs. This makes our scripts more adaptable to different MediaWiki versions and configurations. So, instead of $( '#wpTextbox1' ), we will consistently use $textarea within the context of this hook for efficient and reliable toolbar manipulation.

Removing Unnecessary Tools #

In many wikis, certain default tools on the toolbar might be redundant, confusing, or simply not aligned with the community’s editing practices. For instance, you might want to remove the “reference” button if your wiki primarily uses a different method for citations, or if you want to guide users towards a more specific reference management system.

Let’s examine a practical example of how to remove the reference button and its associated help page:

mw.hook( 'wikiEditor.toolbarReady' ).add( function ( $textarea ) {
    // Remove the reference button from the 'main' section and 'insert' group
    $textarea.wikiEditor( 'removeFromToolbar', {
        'section': 'main',
        'group': 'insert',
        'tool': 'reference'
    });

    // Remove the help page associated with the reference tool
    $textarea.wikiEditor( 'removeFromToolbar', {
        'section': 'help',
        'page': 'reference'
    });

    // Further demonstrate removal of other tools
    // Remove big text button from 'advanced' section and 'size' group
    $textarea.wikiEditor( 'removeFromToolbar', {
        'section': 'advanced',
        'group': 'size',
        'tool': 'big'
    });

    // Remove small text button from 'advanced' section and 'size' group
    $textarea.wikiEditor( 'removeFromToolbar', {
        'section': 'advanced',
        'group': 'size',
        'tool': 'small' // Assuming 'small' is also a tool in the 'size' group
    });

    // Remove insert file button from 'main' section and 'insert' group
    $textarea.wikiEditor( 'removeFromToolbar', {
        'section': 'main',
        'group': 'insert',
        'tool': 'file' // Common identifier for insert file tool
    });

    // Remove picture gallery button from 'advanced' section and 'insert' group
    $textarea.wikiEditor( 'removeFromToolbar', {
        'section': 'advanced',
        'group': 'insert',
        'tool': 'gallery' // Common identifier for picture gallery tool
    });
});

In this snippet, we are targeting specific tools within predefined sections and groups of the wiki editor’s toolbar. By specifying the section, group, and tool parameters, we precisely isolate and remove the desired elements. This meticulous approach ensures that only the intended buttons are affected, maintaining the integrity of the rest of the toolbar.

Key Parameters for removeFromToolbar #

• section: This refers to the major organizational divisions of the toolbar, such as main (for common editing functions), advanced (for less frequently used features), or custom sections you might have defined.
• group: Within a section, tools are often grouped by functionality. Examples include insert, textstyle, formatting, or size.
• tool: This is the specific identifier for the button or function you wish to remove. These identifiers are usually descriptive, like reference, bold, italic, link, file, or gallery.

Adding New Custom Tools #

Beyond removal, MediaWiki:Common.js empowers us to add entirely new tools to the wiki editor’s toolbar. This is invaluable for introducing custom macros, frequently used templates, or shortcuts for complex wiki markup.

To add a tool, we use the wikiEditor('addToToolbar', ...) method, providing details about the tool’s appearance, functionality, and its placement within the toolbar.

Let’s illustrate how we might add a custom button to insert a specific wiki template:

mw.hook( 'wikiEditor.toolbarReady' ).add( function ( $textarea ) {
    // Add a custom button to insert a "callout box" template
    $textarea.wikiEditor( 'addToToolbar', {
        'section': 'main', // Placing it in the main section
        'group': 'insert', // Within the insert group
        'tool': {
            'name': 'callout', // Unique name for our tool
            'label': 'Insert Callout', // Text displayed on the button
            'type': 'button', // It's a clickable button
            'icon': 'https://example.com/path/to/custom-icon.png', // Optional: custom icon
            'action': {
                'type': 'callback', // The action is defined by a JavaScript callback
                'callback': function () {
                    // This function is executed when the button is clicked
                    $textarea.textSelection( 'encapsulate', {
                        'pre': '{{Infobox\n| name = \n| data = \n}}', // Markup to insert
                        'peri': '', // No characters around the selection
                        'post': '' // No characters after the insertion
                    });
                }
            }
        }
    });

    // Add another button for a common link format
    $textarea.wikiEditor( 'addToToolbar', {
        'section': 'main',
        'group': 'insert',
        'tool': {
            'name': 'customlink',
            'label': 'Insert Custom Link',
            'type': 'button',
            'action': {
                'type': 'callback',
                'callback': function () {
                    $textarea.textSelection( 'encapsulate', {
                        'pre': '[[',
                        'post': '|'
                    });
                    // Optionally, trigger the link dialog or a prompt
                    // For a more advanced scenario, you might open a dialog here
                }
            }
        }
    });
});

In this example:

• We define a new tool object.
• name: A unique identifier for our tool.
• label: The text that will appear on the button.
• type: We specify button for a standard clickable button. Other types like toggle or list are also available.
• icon: An optional URL to an image that will serve as the button’s icon, providing a visual cue.
• action: This defines what happens when the button is clicked.
  • type: 'callback': Indicates that our action is defined by a custom JavaScript function.
  • callback: The function itself. Here, we use $textarea.textSelection() to encapsulate the currently selected text or insert new text. The pre, peri, and post parameters control what text is inserted before, around, and after the selection.

This ability to define custom actions opens up a universe of possibilities. You can insert complex templates, apply specific formatting, trigger custom dialogs, or even interact with other wiki features.

Key Parameters for addToToolbar #

• section, group: As with removal, these parameters define where your new tool will be placed in the toolbar hierarchy.
• tool: This is an object containing the definition of your new tool:
  • name: A unique identifier for your tool.
  • label: The text that will appear on the button in the toolbar.
  • type: The type of UI element for the tool (e.g., button, toggle, list).
  • icon: The URL of an icon image.
  • action: An object describing the action when the tool is activated. This can be a callback function, a predefined type (like encapsulate or insert), or a URL to open.

Modifying Existing Tools #

While less common than adding or removing, it