This is the workshop support page for the user script OutlineViewConventional.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 functional

When completed, this script will change the viewed formatting of the current outline into that of a conventionally indented outline, without headings. A textual tree; that is, an indented item list.

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

This script is under development, and is not yet functional

When completed, this script will change the viewed formatting of the current outline into that of a conventionally indented outline, without headings. A textual tree; that is, an indented item list.

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/OutlineViewConventional.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.

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 goes here)

More specifically, starting at the beginning...

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...

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

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.

Completed features are marked with  Done

Article format has headings, conventional outline format does not. The challenge is to convert back and forth. Therefore, the heading information must be saved somehow so that headings can be restored as needed. That could be done by adding class names during the initial regex operation. Also, there are the opening and closing tags.

The heading/lead item pairs are a problem, because they have to be integrated into one for the conventional view, and restored to duality for the article view.

This script needs to work with the other view mode scripts.

Change <h1>, <h2>, ..., <h6> tags to <ul class=h1>, <ul class=h2>, ..., <ul class=h6>

To do this, use regex with outerhtml to change the whole item. That way, you can get the closing tag in the same search/replace.

Reversing it will be the same type of operation.

This is similar to injecting <span> tags, like in OutlineViewAnnotationToggler.js:

var cont = document.getElementById('mw-content-text');
// wrap the annotations in spans with class "anno"
cont.outerHTML = cont.outerHTML.replace(/(<li>.*?)( –.*)/g,'$1<span class="anno">$2</span>');

Like this:

var cont = document.getElementById('mw-content-text');
// change the heading wrappers to classed ul wrappers
cont.outerHTML = cont.outerHTML.replace(/(<h>)(.*?)(<\/h>)/g,'<ul class=$1>$2</ul>');

To change them back, you reverse the process:

// change the classed ul wrappers back to heading wrappers
cont.outerHTML = cont.outerHTML.replace(/<ul class=(h)>(.*?)<\/ul>/g,'<$1>$2<\/$1>');

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

Outlines (e.g., Outline of Japan) are essentially big long bullet lists broken up by headings.

I'd like a viewing script (that does not edit the page's saved wikicode), that does the following to viewed outlines:

On "Outline of" pages only, I'd like a menu item toggle that converts the headings so that they are integrated into the overall bullet list on the page, as list items. Clicking the menu item again would turn the page back to normal (to heading format). Like my other scripts, the status should be remembered between pages (so that all outlines get viewed the same way).

When turned on, the page's content will be one long indented bullet list. H2 headings would be converted to list items with one bullet, H3 with two bullets, etc. The subsection edit link should be retained.

Any bullet item trees beneath a converted heading would have to also be adjusted to start out with one more bullet than the heading they belong to, otherwise, the level indications will be off.

I started picking away at this project in User:The Transhumanist/OutlineViewConventional.js, but have realized it is way beyond my skill level. The Transhumanist 23:34, 3 December 2017 (UTC)

@The Transhumanist: That does seem a bit complicated. If I understand correctly, you want to do the following sort of transformation to the page html:

<h2>Some heading</h2>
<ul>
<li>List item 1</li>
<li>List item 2</li>
<li>
List item 3 with sub-list
<ul>
<li>Sub-list item 3.1</li>
<li>Sub-list item 3.2</li>
</li>
</ul>
<h3>A sub-heading</h3>
<ul>
<li>Sub-heading list item 1</li>
<li>Sub-heading list item 2</li>
</ul>
<h2>Next heading</h2>
...more lists...

<ul><li>Some heading
<ul>
<li>List item 1</li>
<li>List item 2</li>
<li>
List item 3 with sub-list
<ul>
<li>Sub-list item 3.1</li>
<li>Sub-list item 3.2</li>
</li>
</ul>
<ul><li>A sub-heading
<ul>
<li>Sub-heading list item 1</li>
<li>Sub-heading list item 2</li>
</ul>
</li></ul>
</li></ul>
<ul><li>Next heading

...more lists...
</li></ul>

If so, then the basic approach would be to get all the content between heading tags of the same level, and wrap it inside list tags like <ul class="h2"><li>heading text and </li></ul> (doing the same for all headings on the page). Going back would be a matter of moving the heading text back into appropriate heading tags, and removing the added <ul> and <li> tags (but not the original content). Does that give you some ideas? - Evad37  08:52, 5 December 2017 (UTC)

I missed the li part. Thank you. By the way, what about the rest of the bullets? Will their indents be adjusted automatically? The Transhumanist 05:04, 6 December 2017 (UTC)

Yes, indentation is automatic - Evad37  05:52, 6 December 2017 (UTC)

Thank you. The Transhumanist 12:05, 7 December 2017 (UTC)