Help:Gadget-Cat-a-lot/Local Development

This page outlines the steps required to set up a local development environment for Cat-a-lot gadget. The on-wiki development guide is on page Help:Gadget-Cat-a-lot/Developing and Beta Commons guide is on page Help:Gadget-Cat-a-lot/Beta Commons Development.

Install MediaWiki locally

Follow the official installation Guide

Begin by installing MediaWiki on your local machine. You can use the official installation documentation as a reference:

You can also follow this quickstart guide:

Verify Your local instance

After installation, ensure your local wiki is running correctly by accessing its main page.

Enable the Gadgets extension

Clone Gadgets extension

If you installed MediaWiki from the .zip or .tar.gz file, this is unnecessary as MediaWiki versions 1.18 and above include the Gadgets extension by default. If you installed MediaWiki from Git (or the extension is missing for any other reason):

  • Clone the Gadgets extension into the extensions folder of your MediaWiki root directory.

Configure LocalSettings.php

Open your LocalSettings.php file located in your MediaWiki root directory and add the following lines at the end to load the extension and to increase the allowed wikipage size and to enable file uploads:

wfLoadExtension('Gadgets');
$wgMaxArticleSize = 500;
wgEnableUploads = true;
$wgGroupPermissions['user']['upload_by_url'] = true;
$wgUploadSizeWarning = 20000000;
$wgMaxUploadSize = 20000000;
$wgAllowCopyUploads = true;
$wgCopyUploadsFromSpecialUpload = true;

Confirm activation

Visit Special:Version on your local wiki to ensure the Gadgets extension is listed among the active extensions.

Create admin user

php maintenance/run.php createAndPromote --bureaucrat --sysop --interface-admin NewUsername NewPassword

Create required gadget pages

To develop "Cat-a-lot" as a gadget, you need to create several pages in your local MediaWiki instance:

1.) Gadget definition page

Create this page to list all available gadgets:

Edit this page to include an entry for your gadget. For example:

Cat-a-lot[ResourceLoader|dependencies=mediawiki.util|type=general]|Cat-a-lot.js|Cat-a-lot.css

2.) Gadget description page

Create this page to provide a description of the "Cat-a-lot" gadget:

3.) Gadget code pages

Create the following pages and copy the respective code in these pages:

4.) Dependencies

Also, create these pages as they are necessary dependencies for the gadget to function smoothly:

These pages can be created by copying the code from the official pages on Wikimedia Commons.

Helper script for copying files

There is helper script to automate steps 1 - 4. Ie. it copies gadget definition lines, JavaScript, and CSS files from Wikimedia Commons to a MediaWiki instance hosted on localhost. It also copies some test images.

Develop and test your gadget code

1. Edit Your gadget pages

Open your MediaWiki:Gadget-Cat-a-lot.js and modify the functionality of your "Cat-a-lot" gadget by editing the code and saving the changes. Do the same in your MediaWiki:Gadget-Cat-a-lot.css for any styling modifications.

2. Include dependency code

Ensure that MediaWiki:Gadget-libAPI.js, MediaWiki:Gadget-SettingsManager.js, and MediaWiki:Gadget-SettingsUI.js are populated for the gadget to function flawlessly.

3. Clear local cache

After every modification, purge your local wiki’s cache by appending ?action=purge to the page URL to reflect the latest changes.

4. Local testing

Log in to your local wiki and navigate to Special:Preferences → Appearance. You should see the "Gadgets" section with "Cat-a-lot" listed as an option.

5. Enable the gadget

Check the box next to "Cat-a-lot" to enable it. Verify its functionality on local pages where it is expected to run, such as "Category:Images".

Debug and update

Debugging

Use your browser’s developer tools (console, network inspector) to catch any errors and ensure that all dependencies load properly.

Update

Ensure that all your dependency and other pages remain up-to-date with the latest code available on official pages.

FAQ

Remote access from laptop to dev machine using port forwarding

If you are running a MediaWiki development environment on a separate machine (e.g., a Linux home server, Raspberry Pi, etc.) and want to access it from your laptop while MediaWiki only allows connections from localhost, you can use SSH port forwarding.

The following command forwards port 4000 from the development machine to your laptop:

 ssh username@192.168.1.123 -L 4000:localhost:4000

Changing settings doesnt seem to affect

Try to run update to flush caches

php maintenance/run.php update
Category:Cat-a-lot Category:Wikimedia software development tutorials
Category:Cat-a-lot Category:Wikimedia software development tutorials