User:Jack who built the house/Convenient Discussions

From Wikimedia Commons, the free media repository
Jump to navigation Jump to search
Other languages:
English • ‎français • ‎русский • ‎ગુજરાતી

The script's logo. The colors represent the backgrounds of comments of different types

A screenshot of a page that uses Convenient Discussions
Convenient Discussions adds a number of elements to the watchlist: the "CD" button group to the left of the watchlist settings button and the "comment" links to the left of edit summaries.

Convenient Discussions (CD) is a JavaScript tool providing a shell over the existing MediaWiki discussion system that allows the user to post and edit comments without switching to a separate page.

The full set of the script features includes much more:

  • creating topics and subsections;
  • @mentions, [[#comment links]], [[wikilinks]], {{templates}}, and <tags> autocomplete;
  • highlighting and navigating new comments (via the navigation panel or the table of contents);
  • highlighting own comments;
  • desktop notifications about replies to the user's comments and comments in watched sections on open pages (opt-in);
  • watching sections, which affects notifications and highlighting edits on pages that list revisions;
  • jumping to a specific comment from the watchlist and other pages that list revisions;
  • moving topics between talk pages;
  • autofilling the edit summary with the indication of the addressee of the comment;
  • saving comment drafts to restore the forms' content after unexpected events such as browser crashes;
  • thanking for and copying links to edits that added comments;
  • slightly redesigned discussion threads that make it easier to follow which comment replies to which.

The script makes the user forget about:

  • the need to search the code for a place for a comment, count colons, type tildes and other markup;
  • edit conflicts;
  • reading talk pages through diffs;
  • the need to completely reload the page and look for new comments with eyes, or even check the watchlist.

A limitation of the script is that it works only in modern browsers, i.e., doesn't support Internet Explorer.

Convenient Discussions is being developed by Jack who built the house since 2017, enriched by the contributions and feedback from the Russian Wikipedia tech community and users. It also borrows the code for parsing timestamps in different formats from Matma Rex and uses solutions and ideas from the Wikimedia engineering and design teams.

Installation[edit]

To install the script for all Wikimedia wikis, add this to your global.js on Meta:

mw.loader.load('https://commons.wikimedia.org/w/index.php?title=User:Jack_who_built_the_house/convenientDiscussions.js&action=raw&ctype=text/javascript');

To install the script on a specific wiki where it's not a gadget, add this code to your common.js. Every wiki has its own peculiarities that the script can address in a configuration file. Those are individual for each wiki and created by volunteers. If you know JavaScript and your wiki doesn't have one, see § Configuring for a wiki. Having a configuration file for the wiki will also speed up the execution of the script.

Compatibility[edit]

To make the script compatible with the script displaying time in the local time zone (en:User:Gary/comments in local time.js), call the latter like this:

mw.hook('convenientDiscussions.commentsReady').add(function () {
	// comments in local time.js import code
});

Usage[edit]

You can adjust the script according to your preferences in the settings dialog. It is available at the click of the gear icon OOjs UI icon advanced which can be found in the "CD" section of the watchlist and in the "Settings" section under any comment form.

The hotkeys can be found at the click of the "?" button under any comment form and on hover over the navigation panel buttons.

Comment background colors[edit]

  • Hovered comment
  • Target comment (opened by a link or being jumped to)
  • New comment (a comment is considered new if the page was loaded within 15 minutes since the comment was loaded first time)
  • Own comment

Navigation panel[edit]

Convenient Discussions navigation panel info en.svg


FAQ[edit]

The script doesn't work on a page where it should work / works on a page where it shouldn't work. How to fix it?
The script uses a number of factors to determine whether it should process a certain page. The simplest way to make it process/not process a page is to click "Enable/Disable Convenient Discussions on this page" in the page footer. But that will work only for one time. You should write to the user supporting the configuration file on your wiki or create your own configuration file according to the instructions below. In that file, regular expressions to match page names should be added to/removed from the pageWhitelist / pageBlacklist values. A worse way to deal with it is to add an element with class="cd-talkPage" or class="cd-notTalkPage" to the source code of the page. In this case, the page will still be classified incorrectly on log pages (watchlist, history pages etc.).
What does "(-)" after the comment text in an edit summary mean?
It means that the whole text of the comment is displayed in the edit summary, and there is no more text in the comment other than that is displayed, so no point to open the page if you only want to see the contents of this edit. It's a notation that was used on some old Internet forums.
How to change the comments' background colors?
Add the following code to your personal CSS and change the color values (the CodeEditor linter shows errors, ignore them):
:root:root {
	/* Hovered messages — blue */
	--cd-comment-underlay-focused-color: #eaf3ff;

	/* Target messages — orange */
	--cd-comment-underlay-target-color: #ffedb8;

	/* New messages — green */
	--cd-comment-underlay-new-color: #e8ffd1;

	/* Own messages — purple */
	--cd-comment-underlay-own-color: #f7ebff;
}
The comment links block (Reply/Edit/Thank/...) overlaps a user link, and I can't click it.
Make a right click on the block, it will disappear.
How to set settings for one wiki, not for all wikis?
Use let cdLocalSettingName = value; in your common.js on that wiki. You can get the names of the settings here (the first letter should be in upper case, for example autopreviewcdLocalAutopreview).
I would like to have inserted after a user mention like in the {{Ping}} template.
Hold Ctrl while choosing the name you want to mention. You can also press the mention icon while holding Ctrl—if you're replying to a comment, a mention of the target comment's author with will appear at the beginning of your comment.

Data[edit]

Here's what the script stores, why, how, and how to delete the data. Note that you can delete all the data associated with the script in one click, by opening the script settings and pressing the button "Remove all script data" on the "Data removal" tab. Note that while the settings (except for a few) are global, the visits and watched sections are stored individually for each wiki, so you'll have to remove them separately.

What Why How How to delete
Settings To allow tuning the script according to the user's preferences. On the Wikimedia servers as a user option named userjs-convenientDiscussions-settings.

Global settings (the highlighted line will not be needed after the bug preventing deletion of global preferences is resolved):

new mw.Api().postWithEditToken({
  action: 'globalpreferences',
  optionname: 'userjs-convenientDiscussions-settings',
  optionvalue: '',
});
Local settings:
new mw.Api().saveOption('userjs-convenientDiscussions-localSettings', null);
Last talk page visits To detect new comments on talk pages. In a compressed form, on the Wikimedia servers as a user option named userjs-convenientDiscussions-visits.
new mw.Api().saveOption('userjs-convenientDiscussions-visits', null);
Watched sections To show notifications and highlight comments on pages that list revisions: the watchlist, recent changes page, history pages, user contributions pages. In a compressed form, on the Wikimedia servers as a user option named userjs-convenientDiscussions-watchedSections.

Using the "Edit watched sections" dialog accessible from the watchlist, or

new mw.Api().saveOption('userjs-convenientDiscussions-watchedSections', null);
Unsent comment forms' content To restore comment drafts after page reloads, browser crashes, accidental jumps to a different page etc. For no longer than 30 days, in the browser's local storage.
localStorage.removeItem('convenientDiscussions-commentForms');
Edits thanked via CD To reflect in the interface that a comment has already been thanked for. For no longer than 60 days, in the browser's local storage.
localStorage.removeItem('convenientDiscussions-thanks');

In ruwiki, for historical reasons, the option names use cd instead of convenientDiscussions, and userjs-cd-watchedTopics is used for the watched sections option.

Note that other scripts that you use on wiki pages, as well as side-wide scripts, can have access to this data too.

To execute the code in the "How to delete" column, open the browser's developer tools (done by pressing F12 in most browsers), switch to the "Console" tab, paste the code into the input and press Enter.

Feedback[edit]

It's best to post bug reports and proposals on Phabricator under the "convenient-discussions" tag. If you don't have an account there and don't want to create one, post to the talk page (please ping Jack who built the house).

Configuring for a wiki[edit]

Structure of the project

The scheme of loading the script on a wiki is the following: There is the main script file on Commons and a configuration file on the wiki (if somebody has created it). The configuration file can be a gadget or a user script (a gadget will load faster). The configuration file requests the main script file if it is not loaded yet. Conversely, if the main file is loaded first, it requests the configuration file if the URL of the configuration script is specified in it, so there is no difference which file is loaded first.

To configure the script for a wiki, you can use one of the two options below. In any of these cases, if you want the configuration file to be loaded when a user loads the script from Commons, you should inform the repository owner that the configuration file for your project is ready. He will add the URL of the configuration to config/urls.json (you can make a pull request too).

1. Using Node.js and Git[edit]

Recommended, but requires some skills. If you're familiar with Node.js and Git and have them installed (or can install them), clone the script's git repository, run npm install while in the script's directory to install dependencies, create a .js file in the config folder named using pattern project_code[-language_code].js, for example w-en.js or wikt-de.js or mw.js, and put the following code into it:

export default {
  // List of properties
};

// Any additional code, for example hooks

Then you will need to add configuration properties and any additional code if needed. After the configuration is ready, you will need to build an actual configuration file that you will put in your wiki. Do it by running npm run configs. The resultant file will be named dist/convenientDiscussions-config/filename.

Note that you can test your configuration file in the browser's development tools (Chrome DevTools has a handy "Snippets" feature for that in the "Sources" tab) by running npm run snippet --lang=language_code --project=project_code and running the code of the resultant snippet file (dist/convenientDiscussions-snippet-...) in the development tools.

It will be best if you make a pull request to include your configuration in the CD repository. This way, if something in the script environment changes that affects your configuration file (the format of a property changes, for instance, or a default value, that your value is based on, is updated), other people including the author of the script would be able to notice it and inform you and/or make changes themselves.

2. Copypaste[edit]

You can also just copypaste any existent configuration file like ru:Участник:Jack who built the house/convenientDiscussions-ru.js and replace everything between /* BEGINNING OF THE CONFIGURATION */ and /* END OF THE CONFIGURATION */ with

convenientDiscussions.config = {
  // List of properties
};

// Any additional code, for example hooks

The downside of this method is that you won't be able to test the configuration in the browser's development tools, and if anything changes in the configuration structure, your file may become outdated with nobody noticing it and being able to inform you.

Configuration properties[edit]

The properties are documented here with default values, alphabetically. The source code of that documentation has them in a more logical order.

You can start adding properties by running this helper script in your browser's console. It will generate a stringified object containing values that can be automatically retrieved (system messages, some site info, template names). You can copypaste it to your configuration file. In particular, that would allow to avoid making additional requests after loading the script, thus speeding up its execution.

It is recommended to keep only those properties that differ from the default ones.

Examples[edit]

Development[edit]

  • GitHub repository is used to store code. GitHub Actions is used to build and deploy the resultant files to wikis, as well as docs to Toolforge.
  • Phabricator tag is used to coordinate efforts. (Post bug reports and proposals there, not at GitHub.)
  • Toolforge has an automatically generated code documentation.
  • Translatewiki has localization strings. Please suggest improvements to the English source through a pull request to en.json.

Your contributions are welcome! Some notes:

  • The main script object is convenientDiscussions (the modules use the cd alias).
  • convenientDiscussions.s() is an analog of mw.msg() for the script's language strings. convenientDiscussions.sParse() is an analog of mw.message(...).parse(). Please make sure all strings that have their raw HTML inserted into the page use convenientDiscussions.sParse() to prevent introducing XSS vulnerabilities. (All code from untrusted sources is sanitized on earlier stages, but a double check won't hurt.)
  • "Events" in the left panel of the documentation correspond to names used by mw.hook. For example, to attach a handler to the mw.hook('convenientDiscussions.commentFormCreated').add(handler); event, you need the code mw.hook('convenientDiscussions.commentFormCreated').add(handler);
  • To see message names instead of messages themselves on a page, add the uselang=qqx parameter to the end of the URL (just like with MediaWiki).
  • So far there are no automatic tests (though it would be great to have them); all testing should be carried out manually. Some common test cases for comment detection and adding/editing comments are collected at User talk:Jack who built the house/CD test cases.

Building[edit]

Use:

  • npm run snippet --lang=language_code --project=project_code to build the script as a single file for testing in your browser (for example, as a snippet in Chrome DevTools).
  • npm run build to build the main file, source maps, project configuration files, and also the license. Use --dev to build the files with the -dev postfix.
  • npm run docs to generate documentation from JSDoc comments.
  • npm run configs to generate project configuration files. Use --dev to generate the files with the -dev postfix.
  • npm run deploy to deploy the built files (except for project configuration) to the central wiki (currently Commons), as configured in config.json5. Use --dev to deploy the development versions.

See also[edit]