User talk:The Transhumanist/ViewAsOutline-CategoryTree.js

This is the workshop support page for the user script ViewAsOutline-CategoryTree.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 operational: its main features work; it is under further development

The purpose of this script is to make it easy to copy/paste portions of the Category tree into a list or outline article that you are editing. The CatTree expand menu item expands every branch of the tree (it's like clicking on them all at once). When you click CT wikicodify, list item wikiformatting (* [[]]) is provided right on the screen, so you don't have to type it in after you copy and paste.

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

This script is operational: its main features work; it is under further development

The purpose of this script is to make it easy to copy/paste portions of the Category tree into a list or outline article that you are editing. The CatTree expand menu item expands every branch of the tree (it's like clicking on them all at once). When you click CT wikicodify, list item wikiformatting (* [[]]) is provided right on the screen, so you don't have to type it in after you copy and paste.

When completed, this script will provide 4 menu items to affect a displayed category tree: one for expanding, one for collapsing, one for turning wikicodification on, and another for turning wikicodification off. Wikicodification means adding the heading delimiters and list item wikicoding that you would see in an editor (even though we're not in an editor), for easy copying/pasting into an editor.

Currently, expanding and the bullet/link formatting feature work. Very useful for copying/pasting linked list items. Eventually, it will also provide heading formatting.

When you are on the CategoryTree page, it provides 4 menu items in the sidebar:

CatTree expand

CatTree collapse

CT wikicodify

CT dewikicodify

The script is useful for when you have mode set to "pages except files" or "all pages".

After selecting the mode, you expand the tree to show more of it. To help speed that up, the "CatTree expand" menu item expands all the categories in the tree at the same time, one level each time you click it. Click on the triangles in the tree for fine-tuned control.

Once you are done expanding the tree to the way you want it, click on "CT Wikicodify".

That adds link formatting to the links for easy copying/pasting into outlines.

Don't hit CT wikicodify until you are ready to prepare the links for copying/pasting, because further expanding doesn't work after you do (a bug).

Then you copy/paste links to your heart's content. :)

Very useful for working on outlines, such as city outlines.

Just put the name of the city in the category box, select pages except files or all pages under mode, and then press Show tree. Then expand the tree, and when you are ready, click CT wikicodify.

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/ViewAsOutline-CategoryTree.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 main trick is adding spans to the HTML using regex. Inside those spans are the wikicode for links. The spans are classed to enable use of .hide and .show.

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.

Change log

• 2017/12/13 - Started script
• 2017/12/13 - Added menu item to expand unexpanded categories
• 2017/12/13 - Added menu item to collapse expanded categories
  • This does it all-at-once, rather than one-level at a time like the expand menu item does
• 2017/12/13 - Added CT Wikicodify menu item (empty - not operational)
• 2017/12/13 - Added CT Dewikicodify menu item (empty - not operational)
• 2017/12/15 - Added functionality to CT Dewikicodify (hides the inserted wikicodes)
• 2017/12/16 - Added partial functionality to CT Wikicodify (adds wikicodes without differentiating entries that already have them)
• 2017/12/16 - Now differentiates entries that have the link brackets, by inserting the class "Brackets" at the same time. But, now interactive use of expanding and collapsing doesn't work after wikicodification. You can get it the way you want it, and then wikicodify, but then you have to start over (reload current page) if you want to change which categories are expanded or collapsed.

Task list

• add class to appearing categories, based on the highest heading-level class present (counter?), to facilitate wikicodification

Bug reports

• 2017/12/16 - CT Wikicodify adds bullet and brackets to entries that it already added a bullet and brackets to.  Fixed
• 2017/12/16 - Expand and collapse stop working after CT Wikicodify is clicked.

Desired/Completed features

Completed features are marked as  Done

• Menu item that expands tree  Done
• Menu item that collapses tree  Done
• Menu item to wikicodify the currently displaying tree
  • Add (spanned & classed) wikicode heading delimiters based on class
  • Add (spanned & classed) list item formatting = bullet and link delimiters (double square brackets)  Done
• Menu item to turn wikicodification off (bullets and link brackets only)  Done

Development notes

Rough rough talk-through

Further information: Pseudocode

Here, I "talk-through" the design, in order to help program it. This comes one step before pseudocoding...

Each time the expander is activated, new page names appear.

When CT wikicodify is clicked, those need to be modified without modifying the pre-existing ones, though the existing ones need to be shown if hidden. Inserting an additional class name does the trick, but also makes it so that no further expanding or collapsing can take place.

Discussions

Adding wikicode to CategoryTree display

In StripSearchSorted.js we added bullets and double square brackets for copying linked items straight off the page for pasting into an editor.

Now I've started ViewAsOutline-CategoryTree.js to do that in the Special:CategoryTree utility. But, the display starts out collapsed, with very few article names showing. Clicking on each category to expand them is very tedious, so I included a menu item to expand all of the categories at the same time (one level at a time) and another to collapse them (so far, all at once). There is also a menu item for adding wikilink formatting, and another to hide it.

The problem I've run into is, once you click on the Wikicodify menu item, further expanding and collapsing do not work. If you get the categories you want showing before you Wikicodify, you're fine. But if you don't, you have to reload the page and start all over again.

I think it has something to do with the "Brackets" class I added in this version. I stuck that class in there so that Wikicodify wouldn't match the entries that it already inserted link formatting into, so that it wouldn't insert it again. I was expecting to be able to further expand the category tree after the insert operation, but unexpectedly nothing happens when you click on the expand or collapse menu items after that.

When you have time, please take a look under the hood, and let me know what you make of it.

To help get the gist of the program, user instructions are posted at User_talk:The_Transhumanist/ViewAsOutline-CategoryTree.js#Description_/_instruction_manual

The Transhumanist 17:40, 16 December 2017 (UTC)

The category tree page works through javascript. You can see the source code here: https://phabricator.wikimedia.org/diffusion/ECTR/browse/master/modules/ext.categoryTree.js

I've only taken a quick look, but I'd say the problem is with the cont.outerHTML = cont.outerHTML.replace... line. Rewriting the <a> tags is definitely not something the categoryTree.js expects. You might want to try only modifying the text within the <a> tags, and not the tags themselves. Or only adding stuff before and after the tags (i.e. with jQuery methods) and not rewriting the tags using regex. - Evad37 [talk] 15:07, 1 January 2018 (UTC)