the userscript tour

:rocket: A guided tour that helps users learn about userscripts and how they are created using ResourceLoader, MediaWiki Action API, and OOUI.

thedevyansh
2
2
JavaScript

Google Summer of Code 2021 Final Work Product

Student Devyansh Chawla
Organisation Wikimedia Foundation
Project Develop a Userscript/Gadget tutorial on mediaWiki.org

The Userscript Tour

Userscripts are the JavaScript programs that provide Wikimedia users the ability to customize and change the behavior of their user accounts. This project is a guided adventure tour on mediawiki.org to give users insight on How to create a userscript on Wikimedia projects?

Table of contents

About the project

The Userscript Tour facilitates users to learn about userscripts and how they are created using ResourceLoader, MediaWiki Action API, and Object-Oriented User Interface, consistently. The workflow is carried out using four missions:

Landing page of The Userscript Tour

Mission 1 (Let’s begin the journey)

The users will gain practical knowledge of what userscripts/gadgets are and how the existing userscripts are loaded in common.js. They will be made to write a basic yet interesting userscript and import it into their common.js page.

Userscripts involved:

  • Invert.js: Adds an Invert link to the top toolbar. It allows inverting the page color and the color of images.

  • zoom.js: Adds two buttons (to zoom-in and zoom-out) on the right of the page heading.

Mission 1 starts

Mission 2 (Developing with ResourceLoader)

In this mission, the users will gain practical knowledge of ResourceLoader and the core modules available.

Userscripts involved:

  • toggleFontColor.js: Adds a link to the p-personal portlet area, which when clicked toggles the font color of the content. It is created to depict the use of mediawiki.util module.

  • userEditCount.js: Shows the count of edits made by the logged-in user on the current wiki beside the username.

Mission 2 starts

Mission 3 (Strengths of the Action API)

In this mission, the users will gain practical knowledge of MediaWiki Action API, endpoints, modules, submodules, parameters, and API Sandbox.

Userscripts involved:

  • basicPageInfo.js: Shows the basic information about the current page (number of bytes/characters) at the top of the content area. This userscript is written to help users get started with making API calls to the Wikimedia servers.

  • quickChangeLog.js: Adds a link to the Toolbox portlet area, that when clicked shows the 25 most recent changes on MediaWiki in the form of a jQuery dialog box.

Mission 3 starts

Mission 4 (Novelty of OOUI)

In the final mission, the users will gain practical knowledge of Object-Oriented User Interface (OOUI), OOUI elements, widgets, dialogs, custom user interface, etc.

Userscripts involved:

  • showAlertBox.js: Appends an OOUI button to the portlet area that when clicked, shows an OOUI Message Dialog (a simple alert box).

  • guessRandomNumber.js: One of the cool userscripts which makes use of custom widgets. It prepends a tiny random game at the top of the wiki page. The OOUI widgets used are: MessageWidget, LabelWidget, TextInputWidget, ButtonWidget and Simple Message Dialog Box.

Mission 4 starts

Mission 4 ends

NOTE: The missions are constructed such that each one of them builds on the concepts introduced in the preceding missions.

Other highlights

  • A welcome message is sent to the Talk page when the user initiates The Userscript Tour (Mission 1).

Welcome message on Talk page

  • For further engagement, the user is awarded badges for small accomplishments; for example, a badge for loading the first userscript, another badge for completing a Mission, etc.

A badge awarded in Mission 1

  • The badges are sent to a subpage of the user. The user consent is taken before writing anything to the pages of the User namespace.

All badges awarded in The Userscript Tour

Code Example: Create a guider

tour.step( {
		name: '3',
		title: 'Put title here',
		description: 'Put description here',
		onShow: gt.parseDescription,
		overlay: true,
		closeOnClickOutside: false,
		buttons: [ {
			name: 'Button 1',
			action: 'externalLink',
			url: mw.util.getUrl( 'TUT/1/Start' ) + '?tour=tut1&step=2'
		}, {
			name: 'Button 2',
			action: 'next',
		} ],
		allowAutomaticOkay: false

	} )
	.next( '4' );

Benefit of The Userscript Tour

The project primarily focuses on newbie developers and existing Wikimedia community members who have a little bit of JavaScript knowledge. If someone does outreach then every participant would go in the same flow.

How to run it locally?

Prerequisites:

I used the MediaWiki-Docker for setting up my development environment.

  1. Enable JavaScript on your MediaWiki by appending $wgAllowUserJs = true; to the LocalSettings.php file.
  2. Create the templates present in the Templates directory and the wiki pages present in respective directories - mission-1, mission-2, mission-3, and mission-4.
  3. The naming of templates and wiki pages should follow the convention: Replace the - (hyphen) delimiter with / (slash). For example, the template TUT-Background-1 should be named TUT/Background/1 on your local installation of MediaWiki.
  4. The media files used in the guided tour are uploaded on Wikimedia Commons. You can download them first and upload them on your wiki.
  5. Register a new account on your wiki (User:Novusistic) and create subpages under it for userscripts present in the userscripts directory of the respective missions.
  6. Find the tour scripts in directories of respective missions and create the following pages in the MediaWiki namespace:
    • MediaWiki:Guidedtour-tour-tut1.js
    • MediaWiki:Guidedtour-tour-tut2.js
    • MediaWiki:Guidedtour-tour-tut3.js
    • MediaWiki:Guidedtour-tour-tut4.js
  7. Navigate to /The_Userscript_Tour on your MediaWiki.

LIMITATIONS:

  • This tour only uses the Source Editor. If you use the Visual Editor or have it enabled it won’t work yet.
  • You need JavaScript enabled for the tour to work properly.
  • The tour is not supported on tablets and smaller mobile devices.

Bug report

Feel free to open an issue if you find any bug.

Feature request

Feel free to open an issue to request any additional features you might need for your use case.

License

Distributed under the GPL-3.0 License. See LICENSE for more information.

Blog posts

All of my blog posts related to the project can be found here.

Special note

This project is created as part of Google Summer of Code 2021 with my mentoring organization being Wikimedia Foundation. Once deployed on mediawiki.org, I’ll update the deployed link in the repository.

GSoC with WMF