User talk:The Transhumanist/ScriptCreator.js

I'm using this page as a workspace. The talk page portion of it starts at #Discussions, below.

(Script under development - not yet functional)

When completed, this script will prompt for a title, then it will create a script page and accompanying workshop page using that title, using standard templates via substitution.

Script's workshop

This is the work area for developing the script and its documentation. The talk page portion of this page starts at #Discussions, below.

Description / instruction manual

(Script under development - not yet functional)

CreateScript.js = Create new script page, and corresponding workshop page.

When completed, this script will prompt for a title, then it will create a script page and accompanying workshop page using that title, using standard templates via substitution.

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.

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!)

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.

Development notes

Trycatch needed

The Transhumanist, where you use local storage.getItem() or setItem() you should always wrap that in try catch, as it can fail at any moment (even if you checked previously). This can be due to the browser running out of storage space for the domain, or because the browser is running in privacy mode or with an ad blocker extensions or something. Also, your new RegExp() calls should be lifted outside of the for loops, so that they aren't continuously recreated. For wpTextbox1.value, realise that sometimes the content might be managed by an editor (The syntaxhighlighting beta does this for instance). We use the jquery.textSelection plugin to abstract way from these differences. Don't check document.title, check mw.config.get( 'wgTitle' ) or mw.config.get( 'wgPageName' ). And when you use mw.util.addPortlink, you have to ensure that the mediawiki.util plugin is loaded already, which you can do by using mw.loader.using. —TheDJ (talk • contribs) 14:47, 27 October 2017 (UTC)

Steps

• should not work if on an edit page - done
• should only work after a menu item is clicked - done
• Declare a variable for script's mode
• Declare a variable for script page title
• Declare a variable for script's talk page title
• Prompt for script title
  • Specify script title, then press enter.
• Set script title variable
• Set script talk page title variable
• If script page exists, skip this section
• Create script page in edit mode
• Add script template
• Manual save?
• If script talk page exists, clear local storage and terminate script
• Create script talk page in edit mode
• Add talk page template
• Manual save?

Rough rough talk-through

Further information: Pseudocode

The script runs on every page you open. It checks its localstorage for mode, to see what it should do.

The mode will tell it whether to create script page, create workshop page, or be in neutral mode.

In neutral mode, the menu item is available if you are not on an edit page. When you click the button, the script asks you for the name of the script you wish to create.

Once you've specified a title, the script then puts itself it into create script mode, and opens an edit page.

It detects it is in create script mode, and uses template substitution to insert the script.

When done, it changes to script inserted mode, and prompts user to check and save the page.

Once saved, it detects it is in script inserted mode, changes the mode to create workshop mode, and opens an edit page.

It detects it is in create workshop mode, and uses template substitution to insert the workshop.

When done, it changes to workshop inserted mode, and prompts user to check and save the page.

Once saved, it detects it is in workshop inserted mode, and changes to neutral mode.