|
== Explanatory notes (source code walk-through) ==
{{User:The Transhumanist/Workshop boilerplate/Explanatory notes}}
This section explains the source code, in detail.
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 twofold:
# to thoroughly document the script so that even relatively new JavaScript beginners can understand what it does.
# to refresh my memory of exactly how the script works, in case I don't look at the source code (or any JavaScript) for weeks or months.
The explanatory notes include examples, and links to relevant documentation pages, tutorials, etc.
In addition to some standard [[JavaScript]] code, this script also relies heavily on the [[jQuery]] library.
If you have any questions, feel free to ask me ''[[#Discussions|at the bottom of this page under '''Discussions''']]''. Trying to answer them will help me learn JavaScript better.
=== General approach ===
Learn about .hide at http://api.jquery.com/hide/
{{User:The Transhumanist/Workshop boilerplate/Aliases}}
=== aliases ===
An alias is one string defined to mean another. Another term for "alias" is "shortcut". In the script, the following aliases are used:
<code>$</code> is the alias for jQuery
<code>mw</code> is the alias for mediawiki
These two aliases are set up like this:
<syntaxhighlight lang="javascript">
( function ( mw, $ ) {}( mediaWiki, jQuery ) );
</syntaxhighlight>
That is a "bodyguard function", and 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. It does this via [[scoping]].
The bodyguard function is used like a wrapper, with the alias-containing source code inside it. Here's what a jQuery bodyguard function looks like:
<syntaxhighlight lang="javascript">
1 ( function($) {
2 // you put the body of the script here
3 } ) ( jQuery );
</syntaxhighlight>
''See also: [http://stackoverflow.com/questions/8666467/how-to-declare-this-function-in-jquery-document-ready-is-not-working bodyguard function solution].''
To extend that to lock in "mw" to mean "mediawiki", use the following (this is what the script uses):
<syntaxhighlight lang="javascript">
1 ( function(mw, $) {
2 // you put the body of the script here
3 } ) (mediawiki, jQuery);
</syntaxhighlight>
''For the best explanation of the bodyguard function I've found so far, see: [http://codeimpossible.com/2010/01/13/solving-document-ready-is-not-a-function-and-other-problems/ Solving "$(document).ready is not a function" and other problems]''
=== The ready() event listener/handler ===
The ready() event listener/handler makes the rest of the script wait until the page (and its [[Document Object Model|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 anywhere for it to place the menu item (mw.util.addPortletLink), and the script will fail.
In jQuery, it looks like this: [http://learn.jquery.com/using-j\query-core/document-ready/ <code>$( document ).ready() {});</code>]
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:
<syntaxhighlight lang="javascript">
1 $(function() {<br>
2 // Body of function (or even the rest of the script) goes here, such as a click handler.<br>
3 });
</syntaxhighlight>
{{User:The Transhumanist/Workshop boilerplate/Bodyguard function}}
''This is all explained further at [https://api.jquery.com/ready/ the jQuery page for <code>.ready()</code>]''
{{User:The Transhumanist/Workshop boilerplate/The ready event listener-handler}}
For the plain vanilla version see: http://docs.jquery.com/Tutorials:Introducing_$(document).ready()
=== Activation filters ===
| 