Difference between revisions of "Wiki Monkey"

From ArchWiki
Jump to: navigation, search
(simplify)
(Tour of the features: update for 1.13.1)
(42 intermediate revisions by 3 users not shown)
Line 1: Line 1:
[https://github.com/kynikos/wiki-monkey/ Wiki Monkey] is a MediaWiki-compatible bot and editor assistant that can be used directly within wiki pages in the browser. Wiki Monkey is run as a [http://www.scriptish.org/ Scriptish] script for [[Firefox]] and can be easily extended through the creation of plugins, exploiting its high-level API.
+
[[Category:Internet Applications]]
 +
[https://github.com/kynikos/wiki-monkey/wiki Wiki Monkey] is a MediaWiki-compatible bot and editor assistant that can be used directly within wiki pages in the browser as a user script. Currently it is tested on [[Firefox]], [[Chromium]] and [[Opera]], but it is very likely to work also on other browsers out of the box or with minor adaptations. Wiki Monkey can also be easily extended through the creation of plugins, exploiting its API.
 +
 
 +
The project is currently focused on ArchWiki, and as such most plugins address ArchWiki-specific problems.
  
 
==Installation==
 
==Installation==
Make sure you have installed [https://addons.mozilla.org/en-US/firefox/addon/scriptish/ Scriptish] for [[Firefox]].
 
  
{{Note|[[Chromium|Chrome/Chromium]] users can try [http://code.google.com/p/tampermonkey/ Tampermonkey], but Wiki Monkey is not tested against it and does not currently support it.}}
+
Follow [https://github.com/kynikos/wiki-monkey/wiki/Getting-started the upstream documentation].
  
Now just click on the link of one of the following Wiki Monkey configurations and Firefox should ask you to install it:
+
{{Note|since the ArchWiki is served through HTTPS, Opera users will have to follow the instructions in the related note.}}
*[https://raw.github.com/kynikos/wiki-monkey/master/src/configurations/WikiMonkey-editor.user.js Editor]: provides only manual-editing aid functions in editor pages
+
*[https://raw.github.com/kynikos/wiki-monkey/master/src/configurations/WikiMonkey-patrol.user.js Patrol]: Editor + quick-report functions in diff pages
+
*[https://raw.github.com/kynikos/wiki-monkey/master/src/configurations/WikiMonkey-bot.user.js Bot]: Patrol + automatic operations on list pages (currently only [[Special:WhatLinksHere]])
+
*[https://raw.github.com/kynikos/wiki-monkey/development/src/configurations/WikiMonkey-editor.user.js Dev-Editor]: latest Editor development release (unstable)
+
*[https://raw.github.com/kynikos/wiki-monkey/development/src/configurations/WikiMonkey-patrol.user.js Dev-Patrol]: latest Patrol development release (unstable)
+
*[https://raw.github.com/kynikos/wiki-monkey/development/src/configurations/WikiMonkey-bot.user.js Dev-Bot]: latest Bot development release (unstable)
+
  
Otherwise [[#Custom configuration|create your own configuration]].
+
{{Tip|the names of ArchWiki-specific configurations appear in the configurations table with an "ArchWiki-" prefix.}}
  
{{Warning|Although it is possible to keep multiple configurations of Wiki Monkey installed together, make sure to enable only one at a time.}}
+
==Tour of the features==
  
==Updates==
+
Discover the features of Wiki Monkey by following this tour. See [https://github.com/kynikos/wiki-monkey/wiki/Bundled-plugins Bundled plugins] for more detailed information.
Open Firefox's ''Add-ons Manager'' (''Tools -> Add-ons''), select ''User Scripts'', right-click on Wiki Monkey and choose ''Find Updates''.
+
  
If you want to enable automatic updates, choose ''Show More Information'' instead, then set ''Automatic Updates'' to ''On''.
+
{{Tip|at the bottom of Wiki Monkey's interface you will always find a log area, on dark background, where Wiki Monkey and its plugins will output their messages.}}
 
+
==Bundled plugins==
+
{{Warning|Always preview and verify the correctness of the edited text before saving the page. Also examine the messages in the log at the bottom of Wiki Monkey's interface.}}
+
  
 
===Editor pages===
 
===Editor pages===
These functions will automate some repetitive modifications of the source text of the article open for editing, as if you were performing them manually, so you will still be able to preview the changes and do other modifications before saving the page manually.
 
  
====Update templates====
+
If you have installed the ''ArchWiki-Editor'', ''ArchWiki-Patrol'' or ''ArchWiki-Bot'' configuration, in every ''editor'' page (e.g. [https://wiki.archlinux.org/index.php?title=ArchWiki:Sandbox&action=submit ArchWiki:Sandbox's]) you will find Wiki Monkey's interface right below the ''Save page'' button row. As you can see there are some buttons, each of which will execute a plugin action:
This function tries to fulfil [[ArchWiki:Requests#Updating templates]], also turning {{ic|<pre>}} into [[Template:bc]], and {{ic|<code>}} and {{ic|<tt>}} into [[Template:ic]].
+
  
See [https://github.com/kynikos/wiki-monkey/blob/master/src/plugins/ArchWikiNewTemplates.js the source code] for more information.
+
* ''Fix header'' reorders the elements in the header, warns about possible problems (e.g. lack of category) and tries to fix some.
 +
* ''Fix headings'' tries to fix the levels of section headings so that they start from level 2 and do not increase by more than 1 level with relation to the parent section.
 +
* ''Fix external links'' tries to turn external links into proper internal/interwiki links (e.g. Wikipedia), or templates (e.g. [[Template:Pkg]]).
 +
* ''Fix section links'' checks links to sections ({{ic|<nowiki>[[#Section]]</nowiki>}}) and tries to fix them if broken.
 +
* ''Use code templates'' replaces {{ic|&lt;pre>}}, {{ic|&lt;code>}} and {{ic|&lt;tt>}} with [[Template:bc]] and [[Template:ic]], taking care of adding numbered parameters or {{ic|&lt;nowiki>}} tags when necessary.
 +
* ''Expand contractions'' expands some common English contractions, e.g. "don't" becomes "do not".
 +
* ''Squash multiple line breaks'' compresses multiple empty lines into one.
 +
* ''RegExp substitution'' lets you perform a regular expression substitution.
 +
* ''Sync interlanguage links'' synchronizes the interlanguage links of the edited page with those of its translations (the Chromium-native, Opera and standalone configurations can only synchronize local languages).
 +
* ''Fix old AUR links'' converts direct AUR-1.x package links to instances of [[Template:AUR]] (or [[Template:Pkg]] if the package has been moved to the official repositories) (available only for the Scriptish/Greasemonkey/Tampermonkey configurations).
 +
* ''Update package templates'' checks the existence of the packages and groups linked through [[Template:Pkg]], [[Template:AUR]] and [[Template:Grp]] and tries to update any broken template (available only for the Scriptish/Greasemonkey/Tampermonkey configurations).
  
====Expand contractions====
+
By pressing one of them, the text in the editor will be modified, but note that the page will not be saved, so you will still be able to see the diff or the preview and perform other modifications manually. The ''Execute row'' and ''Execute all'' buttons are used to execute more plugins one after the other, thus saving some clicks.
This function tries to replace some common English contractions with their expanded form.
+
 
+
See [https://github.com/kynikos/wiki-monkey/blob/master/src/plugins/ExpandContractions.js the source code] for more information.
+
 
+
====Multiple line breaks====
+
This function replaces multiple empty lines with only one, complying with [[Help:Style#Blank lines]].
+
 
+
{{Note|Multiple empty lines can sometimes be found inside code samples: in these cases you will have to restore them manually.}}
+
 
+
See [https://github.com/kynikos/wiki-monkey/blob/master/src/plugins/MultipleLineBreaks.js the source code] for more information.
+
  
 
===Diff pages===
 
===Diff pages===
These functions base their actions on diff pages.
 
 
====Quick report====
 
{{Expansion}}
 
This function can be useful to Recent Changes patrollers, and adds a quick report to a properly-initialized table in [[User:USERNAME/RC Patrol]], where {{ic|USERNAME}} is your user name. The input field next to the button can be used to accompany the report with a note. See [[User:Kynikos/RC Patrol]] for an example.
 
 
See [https://github.com/kynikos/wiki-monkey/blob/master/src/plugins/ArchWikiQuickReport.js the source code] for more information.
 
 
====Save discussion====
 
{{Expansion}}
 
 
==List pages==
 
{{Expansion}}
 
 
===Bot===
 
{{Expansion}}
 
 
==Troubleshooting==
 
===Clicking on the configuration link does not trigger the installation===
 
If clicking on the [[#Installation|configuration links]] does not trigger the installation, save the target of the link into a {{ic|WikiMonkey.user.js}} file, then drag and drop it in a browser window, or open it with ''File → Open File...'': this time you should get the installation popup.
 
 
===Updating does not work===
 
If you notice that Wiki Monkey has been updated upstream but for some reason you cannot [[#Updates|update]] your local installation, just [[#Installation|re-install]] the script.
 
 
==Bug reports, feature requests==
 
Please use the bug tracker at https://github.com/kynikos/wiki-monkey/issues.
 
 
==Help, ideas==
 
Use the [[User talk:Kynikos/Wiki Monkey|talk page]].
 
 
==Custom configuration==
 
{{Out of date}}
 
 
===Tutorial===
 
{{Expansion}}
 
 
# Open Firefox's ''Add-ons manager &rarr; User Scripts''.
 
# Click on Wiki Monkey's ''Edit'' button (if it is the first time you are doing this it will ask you to choose a text editor).
 
# Add the module with a {{ic|@require}} tag in the header of the main script, as shown in the example below; for local files use the {{ic|file}} protocol, for remote files use {{ic|https}}.
 
# Add the module to {{ic|WM.main()}}, which requires two arguments: the first one is used for editor pages, the second one is used for diff pages. Each of these arguments is a 3-dimensional array with the following structure:
 
#*Level 1: this level separates the various rows of buttons that will be created.
 
#*Level 2: this level separates the various functions in a row. When using the shortcut buttons, the modules in each row are executed in the order they are added here.
 
#*Level 3: this level is where the module is actually installed: its first element is the module namespace, as a string; the second element is the label displayed on the button; the third element is passed as the argument for the module's {{ic|main}} and {{ic|makeUI}} methods.
 
# Save and exit the editor.
 
# The newly-added module will work at the next page reload.
 
 
{{hc|WikiMonkey.user.js|2=
 
// ==UserScript==
 
 
...
 
 
// @require file:///home/user/path/to/ModuleExample1.js
 
// ==/UserScript==
 
 
WM.main(
 
    [
 
        [
 
            ["ModuleExample1", "Button example 1", null]
 
        ]
 
    ],
 
    [
 
        []
 
    ]
 
);
 
}}
 
 
 
{{hc|WikiMonkey.user.js|2=
 
// ==UserScript==
 
 
...
 
 
// @require file:///home/user/path/to/ModuleExample2.js
 
// ==/UserScript==
 
 
WM.main(
 
    [
 
        [
 
            ["ModuleExample2", "Button example 2", "Hello World"]
 
        ]
 
    ],
 
    [
 
        []
 
    ]
 
);
 
}}
 
 
 
{{hc|WikiMonkey.user.js|2=
 
// ==UserScript==
 
 
...
 
 
// @require file:///home/user/path/to/ModuleExample3.js
 
// ==/UserScript==
 
 
WM.main(
 
    [
 
        [
 
            ["ModuleExample3", "Button example 3", ["ExampleID", "Hello World"]]
 
        ]
 
    ],
 
    [
 
        []
 
    ]
 
);
 
}}
 
 
 
{{hc|WikiMonkey.user.js|2=
 
// ==UserScript==
 
 
...
 
 
// @require file:///home/user/path/to/ModuleExample5.js
 
// @require file:///home/user/path/to/ModuleExample6.js
 
// @require file:///home/user/path/to/ModuleExample7.js
 
// @require file:///home/user/path/to/ModuleExample8.js
 
// ==/UserScript==
 
 
WM.main(
 
    [
 
        [
 
            ["ModuleExample5", "Button example 5", ["ExampleID5", "Hello World 5"]],
 
            ["ModuleExample6", "Button example 6", ["ExampleID6", "Hello World 6"]]
 
        ],
 
        [
 
            ["ModuleExample7", "Button example 7", ["ExampleID7", "Hello World 7"]],
 
            ["ModuleExample8", "Button example 8", ["ExampleID8", "Hello World 8"]]
 
        ]
 
    ],
 
    [
 
        [
 
            ["ModuleExample9", "Button example 9", ["ExampleID9", "Hello World 9"]],
 
            ["ModuleExample10", "Button example 10", ["ExampleID10", "Hello World 10"]]
 
        ],
 
        [
 
            ["ModuleExample11", "Button example 11", ["ExampleID11", "Hello World 11"]],
 
            ["ModuleExample12", "Button example 12", ["ExampleID12", "Hello World 12"]]
 
        ]
 
    ]
 
);
 
}}
 
 
==Plugin development==
 
{{Out of date}}
 
This section explains how to develop plugins for Wiki Monkey.
 
 
===Tutorial===
 
{{Expansion}}
 
 
{{hc|ModuleTemplate1.js|2=
 
var ModuleTemplate1 = new function () {
 
    this.main = function () {
 
      // put your code here
 
    };
 
};
 
}}
 
 
{{hc|ModuleExample1.js|2=
 
var ModuleExample1 = new function () {
 
    this.main = function () {
 
        alert("Hello World");
 
    };
 
};
 
}}
 
 
 
{{hc|ModuleTemplate2.js|2=
 
var ModuleTemplate2 = new function () {
 
    this.main = function (arg) {
 
      // put your code here
 
    };
 
};
 
}}
 
 
{{hc|ModuleExample2.js|2=
 
var ModuleExample2 = new function () {
 
    this.main = function (arg) {
 
        alert(arg);
 
    };
 
};
 
}}
 
 
 
{{hc|ModuleTemplate3.js|2=
 
var ModuleTemplate3 = new function (args) {
 
    this.makeUI = function () {
 
        // create and return a DOM element
 
    };
 
 
    this.main = function (args) {
 
      // put your code here
 
    };
 
};
 
}}
 
 
{{hc|ModuleExample3.js|2=
 
var ModuleExample3 = new function () {
 
    this.makeUI = function (args) {
 
        id = args[0];
 
 
        input = document.createElement('input');
 
        input.setAttribute('type', 'text');
 
        input.id = id;
 
     
 
        return input;
 
    };
 
 
    this.main = function (args) {
 
        id = args[0];
 
        msg = args[1];
 
 
        text = document.getElementById(id).value;
 
        alert(msg);
 
    };
 
};
 
}}
 
 
 
{{hc|ModuleTemplate4.js|2=
 
var ModuleTemplate4 = new function () {
 
    var privateVariable = null;
 
 
    var privateFunction = function (args) {
 
        // put your code here
 
    };
 
 
    this.publicVariable = null;
 
 
    this.publicFunction = function (args) {
 
        // put your code here
 
    };
 
   
 
    this.makeUI = function (args) {
 
        // create and return a DOM element
 
    };
 
 
    this.main = function (args) {
 
      // put your code here
 
    };
 
};
 
}}
 
 
==API==
 
{{Out of date}}
 
{{Expansion}}
 
 
===WM===
 
 
====getURIParameter(name)====
 
 
====getLongTextNode(element)====
 
 
===WM.Diff===
 
 
====getEndTimestamp()====
 
 
===WM.Editor===
 
 
====getTitle()====
 
 
====isSection()====
 
 
====readSource()====
 
 
====writeSource(text)====
 
 
====readSummary()====
 
 
====writeSummary(text)====
 
 
====appendToSummary(text)====
 
 
===WM.HTTP===
 
 
====sendGetAsyncRequest(url, cfunc)====
 
 
====sendGetSyncRequest(url)====
 
 
====sendPostAsyncRequest(url, cfunc, string, header, headervalue)====
 
 
====sendPostSyncRequest(url, string, header, headervalue)====
 
 
====getResponseText(id)====
 
 
===WM.Log===
 
  
====logDebug(text)====
+
If you have installed the ''ArchWiki-Patrol-Lite'', ''ArchWiki-Patrol'' or ''ArchWiki-Bot'' configuration, in every ''diff'' page (e.g. [https://wiki.archlinux.org/index.php?title=ArchWiki:Sandbox&diff=262475&oldid=261738 one from ArchWiki:Sandbox's history]) you will find Wiki Monkey's interface right below the two diff panes. Here the only bundled plugin is ''Quick report'', which adds a row with a link to the visited diff in the specialized table of [[ArchWiki:Reports]]. See also [[ArchWiki:Maintenance Team]].
  
====logInfo(text)====
+
===Page lists (Bot)===
  
====logWarning(text)====
+
If you have installed the ''ArchWiki-Bot'' configuration you will find Wiki Monkey's Bot interface in many pages that show lists of pages (e.g. [[Special:Categories|Category pages]], [[Special:WhatLinksHere|What Links Here pages]] and many [[Special:SpecialPages|Special pages]]; see [[:Category:Sandbox]] for a specific example). The usage of the Bot interface is explained in [https://github.com/kynikos/wiki-monkey/wiki/Bot-interface the upstream documentation].
  
====logError(text)====
+
{{Note|the Bot interface is hidden by default, you will have to show it by clicking on the dedicated link.}}
  
===WM.MW===
+
The available plugins for the Bot are a regular expression substitution function and a tool for synchronizing the interlanguage links of the pages with those of their translations (the Chromium-native, Opera and standalone configurations can only synchronize local languages).
  
====callAPIGet(params)====
+
[[Special:WhatLinksHere]] also provides a plugin that checks and tries to fix any broken links to specific sections of the target article; it also provides  a plugin that checks the existence of the packages and groups linked through [[Template:Pkg]], [[Template:AUR]] and [[Template:Grp]] and tries to update any broken template (available only for the Scriptish/Greasemonkey/Tampermonkey configurations).
  
====callAPIPost(params)====
+
[[Special:LinkSearch]] also provides a plugin for converting direct AUR-1.x package links to instances of [[Template:AUR]] (or [[Template:Pkg]] if the package has been moved to the official repositories) (the Bot is shown only if there is at least one item in the list; available only for the Scriptish/Greasemonkey/Tampermonkey configurations).
  
====getUserName()====
+
===Special functions===
  
===WM.Tables===
+
If you have installed the ''ArchWiki-Bot'' configuration you will also find Wiki Monkey's interface at the top of [[Special:SpecialPages]]: here you will find those plugins that have a generic purpose and are not based on a specific page. The available plugins are a function to update [[Table of Contents]] pages, and a function to fix [[Special:DoubleRedirects|double redirects]].
  
====appendRow(title, mark, values, summary)====
+
===Recent Changes===
  
===WM.UI===
+
If you have installed the ''ArchWiki-Patrol-Lite'', ''ArchWiki-Patrol'' or ''ArchWiki-Bot'' configuration, at the top of [[Special:RecentChanges]] you will find Wiki Monkey's Recent Changes filter. Currently the bundled filter only groups the changes by the language of the affected article.
  
====setEditor(rows)====
+
{{Note|the default filter is designed to work on top of MediaWiki's Recent Changes filter, which can be enabled in [[Special:Preferences#mw-prefsection-rc]]. This also means that you must be logged on in order to use it.}}
  
====setDiff(rows)====
+
==See also==
 +
* [https://github.com/kynikos/wiki-monkey/wiki/Troubleshooting Troubleshooting]
 +
* [https://github.com/kynikos/wiki-monkey/issues Bug reports, feature requests, questions]

Revision as of 04:52, 27 October 2013

Wiki Monkey is a MediaWiki-compatible bot and editor assistant that can be used directly within wiki pages in the browser as a user script. Currently it is tested on Firefox, Chromium and Opera, but it is very likely to work also on other browsers out of the box or with minor adaptations. Wiki Monkey can also be easily extended through the creation of plugins, exploiting its API.

The project is currently focused on ArchWiki, and as such most plugins address ArchWiki-specific problems.

Installation

Follow the upstream documentation.

Note: since the ArchWiki is served through HTTPS, Opera users will have to follow the instructions in the related note.
Tip: the names of ArchWiki-specific configurations appear in the configurations table with an "ArchWiki-" prefix.

Tour of the features

Discover the features of Wiki Monkey by following this tour. See Bundled plugins for more detailed information.

Tip: at the bottom of Wiki Monkey's interface you will always find a log area, on dark background, where Wiki Monkey and its plugins will output their messages.

Editor pages

If you have installed the ArchWiki-Editor, ArchWiki-Patrol or ArchWiki-Bot configuration, in every editor page (e.g. ArchWiki:Sandbox's) you will find Wiki Monkey's interface right below the Save page button row. As you can see there are some buttons, each of which will execute a plugin action:

  • Fix header reorders the elements in the header, warns about possible problems (e.g. lack of category) and tries to fix some.
  • Fix headings tries to fix the levels of section headings so that they start from level 2 and do not increase by more than 1 level with relation to the parent section.
  • Fix external links tries to turn external links into proper internal/interwiki links (e.g. Wikipedia), or templates (e.g. Template:Pkg).
  • Fix section links checks links to sections ([[#Section]]) and tries to fix them if broken.
  • Use code templates replaces <pre>, <code> and <tt> with Template:bc and Template:ic, taking care of adding numbered parameters or <nowiki> tags when necessary.
  • Expand contractions expands some common English contractions, e.g. "don't" becomes "do not".
  • Squash multiple line breaks compresses multiple empty lines into one.
  • RegExp substitution lets you perform a regular expression substitution.
  • Sync interlanguage links synchronizes the interlanguage links of the edited page with those of its translations (the Chromium-native, Opera and standalone configurations can only synchronize local languages).
  • Fix old AUR links converts direct AUR-1.x package links to instances of Template:AUR (or Template:Pkg if the package has been moved to the official repositories) (available only for the Scriptish/Greasemonkey/Tampermonkey configurations).
  • Update package templates checks the existence of the packages and groups linked through Template:Pkg, Template:AUR and Template:Grp and tries to update any broken template (available only for the Scriptish/Greasemonkey/Tampermonkey configurations).

By pressing one of them, the text in the editor will be modified, but note that the page will not be saved, so you will still be able to see the diff or the preview and perform other modifications manually. The Execute row and Execute all buttons are used to execute more plugins one after the other, thus saving some clicks.

Diff pages

If you have installed the ArchWiki-Patrol-Lite, ArchWiki-Patrol or ArchWiki-Bot configuration, in every diff page (e.g. one from ArchWiki:Sandbox's history) you will find Wiki Monkey's interface right below the two diff panes. Here the only bundled plugin is Quick report, which adds a row with a link to the visited diff in the specialized table of ArchWiki:Reports. See also ArchWiki:Maintenance Team.

Page lists (Bot)

If you have installed the ArchWiki-Bot configuration you will find Wiki Monkey's Bot interface in many pages that show lists of pages (e.g. Category pages, What Links Here pages and many Special pages; see Category:Sandbox for a specific example). The usage of the Bot interface is explained in the upstream documentation.

Note: the Bot interface is hidden by default, you will have to show it by clicking on the dedicated link.

The available plugins for the Bot are a regular expression substitution function and a tool for synchronizing the interlanguage links of the pages with those of their translations (the Chromium-native, Opera and standalone configurations can only synchronize local languages).

Special:WhatLinksHere also provides a plugin that checks and tries to fix any broken links to specific sections of the target article; it also provides a plugin that checks the existence of the packages and groups linked through Template:Pkg, Template:AUR and Template:Grp and tries to update any broken template (available only for the Scriptish/Greasemonkey/Tampermonkey configurations).

Special:LinkSearch also provides a plugin for converting direct AUR-1.x package links to instances of Template:AUR (or Template:Pkg if the package has been moved to the official repositories) (the Bot is shown only if there is at least one item in the list; available only for the Scriptish/Greasemonkey/Tampermonkey configurations).

Special functions

If you have installed the ArchWiki-Bot configuration you will also find Wiki Monkey's interface at the top of Special:SpecialPages: here you will find those plugins that have a generic purpose and are not based on a specific page. The available plugins are a function to update Table of Contents pages, and a function to fix double redirects.

Recent Changes

If you have installed the ArchWiki-Patrol-Lite, ArchWiki-Patrol or ArchWiki-Bot configuration, at the top of Special:RecentChanges you will find Wiki Monkey's Recent Changes filter. Currently the bundled filter only groups the changes by the language of the affected article.

Note: the default filter is designed to work on top of MediaWiki's Recent Changes filter, which can be enabled in Special:Preferences#mw-prefsection-rc. This also means that you must be logged on in order to use it.

See also