User talk:The Transhumanist/QuickPortal.js

This is the workshop support page for the user script QuickPortal.js. Comments and requests concerning the program are most welcome. Please post discussion threads below the section titled Discussions. Thank you. By the way, the various scripts I have written are listed at the bottom of the page.

This script is under development, and is not yet fully functional

This script is on once you install it. Anytime you click a redlink that is a portal, it creates the portal, putting it into preview mode. The new portal isn't saved until you click on the save button. In addition to this capability, the script provides 2 menu items: "Restart portal" and "Matching portal". See below for details.

Script's workshop

This is the work area for developing the script and its documentation. Even though this documentation is in user space, feel free to edit it. The talk page portion of this page starts at #Discussions, below.

Description & instruction manual for QuickPortal.js

This script is under development, and is not yet fully functional

This script is on once you install it. Anytime you click a redlink that is a portal, it creates the portal, putting it into preview mode. The new portal isn't saved until you click on the save button.

QuickPortal.js is intended to apply \{\{subst:bpsp\}\} to create a portal, or overwrite an existing portal. (note: bpsp is a shortcut to Template:Basic portal start page, which creates a single-page portal)

IMPORTANT: BEFORE YOU RUN THIS SCRIPT, DEACTIVATE wikEd. QuickPortal WILL NOT RUN RIGHT OTHERWISE.

When you ctrl-click on a portal redlink (in Firefox or Chrome), a new portal is created in a new tab in preview mode waiting to be saved. So, if you ctrl-click on 20 such redlinks, you get 20 tabs each with a new portal in preview mode waiting for inspection. Regular clicking on a portal redlink creates a new portal for that subject in the current window.

The script also presents two menu items:

The "Restart portal" menu item appears when a portal base page is displayed. Clicking on that puts the portal in edit mode. Clicking it again (or when a portal is already in edit mode) will replace the portal's content with the new portal design, same as the feature that creates a new portal above.)

The "Matching portal" menu item jumps to the like-named portal title. (Development note: if there isn't an existing portal, create it. See the page creation url.)

How to install this script

Important: this script was developed for use with the Vector skin (it's Wikipedia's default skin), and might not work with other skins. See the top of your Preferences appearance page, to be sure Vector is the chosen skin for your account.

To install this script, add this line to your vector.js page:

importScript("User:The Transhumanist/QuickPortal.js");

Save the page and bypass your cache to make sure the changes take effect. By the way, only logged-in users can install scripts.

Explanatory notes (source code walk-through)

This section explains the source code, in detail. It is for JavaScript programmers, and for those who want to learn how to program in JavaScript. Hopefully, this will enable you to adapt existing source code into new user scripts with greater ease, and perhaps even compose user scripts from scratch.

You can only use so many comments in the source code before you start to choke or bury the programming itself. So, I've put short summaries in the source code, and have provided in-depth explanations here.

My intention is Threefold:

1. to thoroughly document the script so that even relatively new JavaScript programmers can understand what it does and how it works, including the underlying programming conventions. This is so that the components and approaches can be modified, or used again and again elsewhere, with confidence. (I often build scripts by copying and pasting code that I don't fully understand, which often leads to getting stuck). To prevent getting stuck, the notes below include extensive interpretations, explanations, instructions, examples, and links to relevant documentation and tutorials, etc. Hopefully, this will help both you and I grok the source code and the language it is written in (JavaScript).
2. to refresh my memory of exactly how the script works, in case I don't look at the source code for weeks or months.
3. to document my understanding, so that it can be corrected. If you see that I have a misconception about something, please let me know!

In addition to plain vanilla JavaScript code, this script relies heavily on the jQuery library.

If you have any comments or questions, feel free to post them at the bottom of this page under Discussions. Be sure to {{ping}} me when you do.

General approach

The core program creates 2 menu items, and checks for a blank creation page. It calls a different subroutine for each of these.

The insertQuickPortal subroutine inserts {{subst:bpsp}} onto the blank page, and then autoclicks page preview.

More specifically, starting at the beginning...

Aliases

An alias is one string defined to mean another. Another term for "alias" is "shortcut". In the script, the following aliases are used:

$ is the alias for jQuery (the jQuery library)

mw is the alias for mediawiki (the mediawiki library)

These two aliases are set up like this:

( function ( mw, $ ) {}( mediaWiki, jQuery ) );

That also happens to be a "bodyguard function", which is explained in the section below...

Bodyguard function

The bodyguard function assigns an alias for a name within the function, and reserves that alias for that purpose only. For example, if you want "t" to be interpreted only as "transhumanist".

Since the script uses jQuery, we want to defend jQuery's alias, the "$". The bodyguard function makes it so that "$" means only "jQuery" inside the function, even if it means something else outside the function. That is, it prevents other javascript libraries from overwriting the $() shortcut for jQuery within the function. It does this via scoping.

The bodyguard function is used like a wrapper, with the alias-containing source code inside it, typically, wrapping the whole rest of the script. Here's what a jQuery bodyguard function looks like:

1 ( function($) {
2     // you put the body of the script here
3 } ) ( jQuery );

See also: bodyguard function solution.

To extend that to lock in "mw" to mean "mediawiki", use the following (this is what the script uses):

1 ( function(mw, $) {
2     // you put the body of the script here
3 } ) (mediawiki, jQuery);

For the best explanation of the bodyguard function I've found so far, see: Solving "$(document).ready is not a function" and other problems   (Long live Spartacus!)

Load dependencies

Many of my scripts create menu items using mw.util.addPortletLink, which is provided in a resource module. Therefore, in those scripts it is necessary to make sure the supporting resource module (mediawiki.util) is loaded, otherwise the script could fail (though it could still work if the module happened to already be loaded by some other script). To load the module, use mw.loader, like this:

// For support of mw.util.addPortletLink
mw.loader.using( ['mediawiki.util'], function () {
// Body of script goes here.
} );

mw.loader.using is explained at mw:ResourceLoader/Core modules#mw.loader.using.

For more information, see the API Documentation for mw.loader.

The ready() event listener/handler

The ready() event listener/handler makes the rest of the script wait until the page (and its DOM) is loaded and ready to be worked on. If the script tries to do its thing before the page is loaded, there won't be anything there for the script to work on (such as with scripts that will have nowhere to place the menu item mw.util.addPortletLink), and the script will fail.

In jQuery, it looks like this: $( document ).ready(function() {});

You can do that in jQuery shorthand, like this:

$().ready( function() {} );

Or even like this:

$(function() {});

The part of the script that is being made to wait goes inside the curly brackets. But you would generally start that on the next line, and put the ending curly bracket, closing parenthesis, and semicolon following that on a line of their own), like this:

1 $(function() {
2     // Body of function (or even the rest of the script) goes here, such as a click handler.
3 });

This is all explained further at the jQuery page for .ready()

For the plain vanilla version see: http://docs.jquery.com/Tutorials:Introducing_$(document).ready()

Only activate for vector skin

Initially each script I write is made to work only on the vector skin, the skin under which I developed it, and by default the only skin for which it is initially tested with. To limit the script to working for vector only, I use the following if control structure:

if ( mw.config.get( 'skin' ) === 'vector' ) {
}

To test it with another skin, remove or comment out the above code from the script.

Deactivation filters

Many scripts are written to work on a particular page or page type, and might have unexpected results if run on some other page. So a deactivation filter is used so the program does not run for the wrong pages.

For example:

    if (document.title.indexOf("Watchlist - Wikipedia") == -1) {
        // use a return statement to end the local function and hence the program's body
        // important: this approach does not work outside of a function
        return;
    }

What this if statement does is checks that the current page is not the one we want, and if that is true, we end the program via a return statement.

What return; does when alone like this (without any parameters), is to end the highest-level function which it is within. And since the body of the program is also within that function, if the if statement isn't true, the program ends.

You could do something similar with a straight if construct without "return;", checking for a page match, but then you'd have to have your whole script body inside the construct, which adds a level of indentation. The more filters, the more levels of indentation. The above approach avoids unnecessary indentation, and makes it easier to keep track of the curly brackets, as the closing bracket isn't way off at the end of the program.

var

This is the reserved word var, which is used to declare variables. A variable is a container you can put a value in. To declare the variable portletlink, write this:

var portletlink

A declared variable has no value, until you assign it one, such as like this:

portletlink = "yo mama";

You can combine declaration and assignment in the same statement, like this:

var portletlink = mw.util.addPortletLink('p-tb', '#', 'Remove red links');

Caveat: if you assign a value to a variable that does not exist, the variable will be created automatically. If it is created outside of a function, it will have global scope. For user scripts used on Wikipedia, having a variable of global scope means the variable may affect other scripts that are running, as the scripts are technically part of the same program, being called via import from a .js page (.js pages are programs). So, be careful. Here are some scope-related resources:

• The Horror of Implicit Globals
• Scope in JavaScript

Change log for QuickPortal.js

• 2018-08-26
  • Started script
• 2018
  • Main function
  • Restart menu item
  • Matching portal menu item
• 2019-02-18
  • Started this Change log
  • Added guard clause so that Restart menu item shows up only when portal has a "Selected article" section

Task list

Bug reports

• 2019-01-29 – This program does not work right when WikEd is turned on. When activated by Ctrl+click, thus creating a new page in a tab, the script goes into an endless loop, creating the page in each tab over and over again. It works normally when WikEd is turned off.

Desired/completed features

Completed features are marked with  Done

• Have Matching portal work from a template page.

Development notes for QuickPortal.js

Using this script gets portal creation down to about a minute, 5 minutes if you include link placement. The development goal is to get this down to seconds.

The most time consuming steps in portal creation now are:

1. Topic selection (in order to become a portal, the topic needs adequate support in the form of a navbox template.
2. Inspection
   1. Check for errors
   2. Check number of articles displaying in excerpt slideshow(s). Stubs don't show up, reducing the number displayed.
3. Adjustment, by
   1. Changing templates (after save)
   2. Adding alternate content/parameters, like a different navbox template name
   3. Swapping out the main template for an alternate configuration in the event there are empty sections (before save)
   4. Or a combination of the above (different sections)
4. Deorphanization, by placing links to the portal

Rough rough talk-through

Further information: Pseudocode

The script generates a portal by inserting {{subst:bpsp}} onto a blank page. Then it loads a preview page (i.e., starts over).

Restart portal

Menu item "Restart portal" starts a process that replaces an existing portal with a new one.

It's a multi-page process.

First it invokes an edit page.

The script starts over on the edit page. Therefore, the script must be able to differentiate the intended edit page from all others. It also needs to be able to work independently of other instances of the same script being used, like when run in multiple tabs at the same time.

Tracking

localStorage.setItem('myCat', 'Tom');

var cat = localStorage.getItem('myCat');

localStorage.removeItem('myCat');

To make sure that instances don't clash, they have to use different localStorage items. Such as naming the item based on the page's title.

I've solved this problem for now, but it requires using the menu item twice: once to get to the page, and once while on the page.

Read up on this

https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API/Using_the_Web_Storage_API

It kind of works

The script will restart a portal, but it totally replaces what was there, rather than make use of it.

I'd like to figure out how to make use of what's there, one element at a time.

Add link placement functionality

After portal is saved, place links to the portal from:
1) Cooresponding root article's See also section, but only if it does not already exist
2) Cooresponding category page, but only if it does not already exist
3) The bottom of the corresponding navigation footer template, but only if it does not already exist

Under development as P-link.js.

Discussions

This is where the actual talk page starts for QuickPortal.js. Please post your discussion threads below...