Help:Manage blocks/Developers

The new manage blocks interface is a reactive single-page application that uses Vue.js and Codex. This means user scripts and gadgets written for Special:Block may no longer work.

DOM manipulation

Direct DOM manipulation is no longer safe to within the #mw-block-form element. Everything inside of the form tag is managed by Vue and its state, so DOM changes may be overridden or cause unexpected behaviour. If you need to add a widget or something similar, consider adding it either before or after the ‎<form id="mw-block-form">...‎</form> tag.

Changing values of form fields

Directly setting the values of form fields will require also emitting an input event so that Vue's reactivity kicks in.

In addition, you need to ensure they are visible. The new interface has a compact design where the body of the form is not always displayed. You can use the SpecialBlock.form hook to only run your code when the form is visible.

mw.hook( 'SpecialBlock.form' ).add( ( formVisible, _target, _blockId ) => {
    if ( !formVisible ) {
        return;
    }
    const reasonOther = document.querySelector( '[name=wpReason-other]' );
    reasonOther.value = 'My block summary';
    reasonOther.dispatchEvent( new InputEvent( 'input' ) );
} );

This is only guaranteed to work for checkboxes, radio buttons, and text fields. Changing the value of dropdowns and other interactive components is not yet supported.

Clientside hooks


Hook	Description
`SpecialBlock.block`	Fired after a successful (re-)block. Parameters: (`Object`) Value of the `block` key from the block API response. This contains for example the keys `user`, `expiry` and associated block parameters.
`SpecialBlock.form`	Fired when the visibility of the form changes. Parameters: (`boolean`) Whether the form is open or closed. (`string`) Username, IP, or IP range (may be blank) (`number\|null`) The block ID when editing an existing block.

A common need is to do something after a user is blocked. The new Special:Block is a single-page application, so you'll need to use the SpecialBlock.block hook to ensure your code is ran after a block has been made.

As noted above, DOM changes within the #mw-block-form element should not be considered safe. However, if you are only trying to change the success message (for example to include a link), this may work as its content is not continually updated after the message is shown. The block success message can be queried with .mw-block-success. It is still preferred however that any DOM changes be made outside the form.

const link = document.createElement( 'a' );
link.className = 'my-gadget-link';
link.textContent = 'Add a blocked message to the target\'s talk page';

mw.hook( 'SpecialBlock.block' ).add( ( blockObj ) => {
    document.getElementById( 'mw-block-form' ).before( link );
    link.on( 'click', () => 
        // Prevent double-clicking
        link.remove();

        // …
    } );
} );

// Remove the link when the sysop goes to make an additional block.
mw.hook( 'SpecialBlock.form' ).add( ( formVisible ) => {
    if ( link ) {
        link.remove();
    }
} );

API

API:Block works the same as it does without multiblocks, unless the target has multiple active blocks.

When using reblock=1 and the target has multiple blocks, the API will return an error. You must specify which block you want to reblock using the id parameter. Use API:Blocks to fetch the current active blocks.
To place an additional block on top of existing blocks, you must use newblock=1

These changes are in place to minimize breaking changes. This means that scripts that don't support multiblocks can break for mutli-blocked targets, but with the reassurance that no additional blocks are ever inadvertently added.

Unblocking

As of MediaWiki 1.44, unblocking via the API is still done with API:Unblock. Similar to the Block API, you must specify an id to remove specific blocks. It is currently not possible to remove all active blocks from a user in a single API request.