User:Mxn/CommentsInLocalTime

Comments in local time is a user script that reformats talk page timestamps – the ones inserted by ~~~~ and ~~~~~ – to use a combination of relative date and time formats where appropriate. It is a rewrite of Wikipedia:Comments in Local Time with a focus on greater customizability and easier localization.

A sample user signature roster without the "Comments in local time" user script (left) and with the user script (right). Every timestamp is given a tooltip with an unlimited number of alternative formats.

Features

Recent timestamps are replaced by a relative time such as "3 hours ago" or "Last Tuesday at 5:51 PM". Older timestamps are displayed in full. Both relative and absolute date formats are included in the default tooltip, as is an ISO 8601 timestamp. Relative timestamps refresh automatically.

In all cases, the time is expressed in your computer's local time rather than the wiki's default time zone. This may differ from the time zone used in the MediaWiki interface if your Time offset preference is set to something other than your computer's local time. If your timezone observes daylight saving time during the summer, summertime timestamps are expressed in daylight saving time even if you are currently in the middle of winter:

• 00:00, 1 July 2015 (UTC)
• 00:00, 1 December 2015 (UTC)

This user script recognizes both the timestamp format currently used by the English Wikipedia and the abbreviated one used here until 2005:

• 18:16, 23 Dec 2004 (UTC)
• 08:51, 23 November 2015 (UTC)

By default, the display format is determined by two user preferences that you can set:

• Interface language
• Date format

Installation

On this wiki, append the following code to your user script:

{{subst:iusc|1=User:Mxn/CommentsInLocalTime.js}}

On another Wikimedia wiki, use the following code instead:

// [[w:en:User:Mxn/CommentsInLocalTime]]
mw.loader.load( '//en.wiki.x.io/w/index.php?title=User:Mxn/CommentsInLocalTime.js&action=raw&ctype=text/javascript' );

However, note that the version of the user script on this wiki is only capable of parsing date formats produced by MediaWiki's English localization. If your wiki uses a different language or timezone by default, you may need to take some additional steps.

Compatibility

This user script should in principle work in the following browsers:

• Firefox 3.5 or above
• Google Chrome
• Internet Explorer 9 or above
• Opera 9 or above
• Safari 3 or above

However, it has only been tested in a subset of these browsers. Your help is appreciated in verifying the accuracy of the list above.

Customization

You can customize various aspects of this user script by defining a global LocalComments object in your user script. A completely customized LocalComments looks like this, but don't be intimidated: all of the top-level options are optional. See the section of User:Mxn/CommentsInLocalTime.js labeled User Options for the default values:

window.LocalComments = $.extend(window.LocalComments, {
	formats: {
		day: function (then) { return then.fromNow(); },
		week: function (then) { return then.calendar(); },
		other: "LLL",
	},
	tooltipFormats: [
		function (then) { return then.fromNow(); },
		"LLLL",
		"YYYY-MM-DDTHH:mmZ",
	],
});

None of the original Comments in Local Time gadget is applicable to this user script, so none of them is supported.

User options

This user script relies on Moment.js for nearly all date and calendar logic. Most of the options simply expose options available through that library.

Option		Type	Description
enabled		Boolean	When false, the user script does nothing.
formats		{Object}	An object containing formats to display inline for each timestamp. If you specify this option, the user script will only use the suboptions you specify. Three suboptions are supported:
	day	Format	The format to use when the timestamp falls within roughly a day of the current time.
	week	Format	The format to use when the timestamp falls within a week of the current time but more than a day from now.
	other	Format	The format to use for all other timestamps.
tooltipFormats		[Format]	An array of formats to display in each timestamp's tooltip, one per line. If you specify this option, the user script will only use the formats you specify.
dynamic		Boolean	When true, this gadget refreshes timestamps periodically.

Formats

A format can take either of two forms:

• A string causes the user script to format the timestamp according to the Moment.js format syntax. In particular, you can place arbitrary text in the format by surrounding it in [square brackets].
• A function is called once per timestamp to retrieve the formatted string. A moment object is passed in, and the return value should be a string. See the Moment.js documentation for the myriad things you can do with a moment object. There is no requirement that the return value have anything to do with the moment object.

Some common formats:

function (then) { return then.fromNow(); }  // 5 months ago
function (then) { return then.calendar(); } // Today, Yesterday, Last Monday... at 12:34 AM
"lll"                                       // Sep 4 1986 8:30 PM
"LLLL"                                      // Thursday, 4 September 1986 8:30 PM
"LL [at] LT"                                // 4 September 1986 at 8:30 PM

Style

This user script wraps each timestamp in a <time> tag and applies the explain class. MediaWiki styles this class with a dotted underline to indicate the existence of a tooltip. You can easily customize the timestamp style from the comfort of your user stylesheet. For instance, this style rule italicizes each timestamp and reduces its font size to 90% of the surrounding text:

.localcomments {
	font-size: 90%;
	font-style: italic;
}

How it works

Tracked in Phabricator
Task T122759
Open

This user script finds all promising DOM text nodes in the document using NodeIterator. Then it uses the Moment.js library to parse and reformat each timestamp. The NodeIterator is potentially the most expensive part of the script; a fix for T122759 would make it unnecessary.

Porting to other wikis

On a wiki that uses MediaWiki's English localization and UTC by default, you can simply install the existing user script without any additional steps. If you're an administrator, you can install it as a gadget for all the wiki's users:

1. Add the following line to MediaWiki:Gadgets-definition:

   * CommentsInLocalTime[ResourceLoader|dependencies=mediawiki.util,moment]|CommentsInLocalTime.js

2. Create MediaWiki:Gadget-CommentsInLocalTime.js with the following code:

   mw.loader.load("//en.wiki.x.io/w/index.php?title=User:Mxn/CommentsInLocalTime.js&action=raw&ctype=text/javascript");
   

Site options

If your wiki uses another localization or timezone by default, you may also need to customize some options that help the user script parse timestamps out of wikitext. See the section of User:Mxn/CommentsInLocalTime.js labeled Site Options for the default values. Again, extend the LocalComments object:

window.LocalComments = $.extend(window.LocalComments, {
	excludeNamespaces: [-1, 0, 8, 100, 108, 118],
	formatOptions: {
		// https://doc.wikimedia.org/mediawiki-core/1.34.0/php/MessagesEn_8php.html#a2fc93ea5327f655d3ed306e221ee33f0
		"mdy": "HH:mm, MMMM D, YYYY", // H:i, F j, Y
		"dmy": "HH:mm, D MMMM YYYY", // H:i, j F Y
		"ymd": "HH:mm, YYYY MMMM D", // H:i, Y F j
		"ISO 8601": "YYYY-MM-DDTHH:mm:ss", // xnY-xnm-xnd"T"xnH:xni:xns
	},
	parseFormat: "H:m, D MMM YYYY",
	parseRegExp: /\d\d:\d\d, \d\d? (?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)\w* \d{4} \(UTC\)/,
	utcOffset: 0,
});

Each of the following options is optional:

Option		Type	Description
excludeNamespaces		[Number]	An array of numbers of namespaces to completely ignore. See Wikipedia:Namespace. The default value includes the namespaces typically considered "content namespaces". If you specify this option, the user script will only ignore the namespaces you specify.
proseTags		[String]	Names of tags that often directly contain timestamps. This is merely a performance optimization. This gadget will look at text nodes in any tag other than the codeTags, but adding a tag here ensures that it gets processed the most efficient way possible.
codeTags		[String]	Names of HTML tags that the user script should never parse for timestamps – it won't parse these tags' children or ancestors.
formatOptions		[Object]	An object mapping the date format user options provided by the MediaWiki installation to corresponding Moment.js format strings. See mw:Manual:Date formatting. When customizing these formats for content language other than English, consult the language’s corresponding message file's $dateFormats variable. Use only the messages with the both suffix, and remove that suffix from each key. (The key will typically begin with an ISO 639 language code.) The messages are in MediaWiki date format syntax, which need to be manually converted to Moment.js syntax.
parseFormat		String or [String]	Expected format or formats of the timestamps in existing wikitext. This option expects parsing format strings. Moment.js can be lenient with the format, so for instance distinguishing between abbreviated and spelled-out month names isn't usually necessary. If very different formats have been used over the course of the wiki's history, specify an array of formats. If the formats specified in this option don't result in a valid timestamp, the user script falls back on English, but only if parseRegExp also matches English timestamps.
parseRegExp		RegExp	Regular expression matching all the timestamps inserted by the MediaWiki installation over the years. This regular expression should more or less agree with the parseFormat option. It doesn't need capture groups and doesn't have to be very strict.
utcOffset		Number	UTC offset of the wiki's default local timezone. See mw:Manual:Timezone. If the wiki's default local timezone is UTC, you don't need to specify this option.

The per-wiki configuration affects parsing only. The actual display is determined by the user's current interface language, which can be configured using Special:Preferences or the uselang and setlang URL parameters. The default date and time formats are determined by the Moment.js library. In the somewhat unlikely event that your language is not yet supported by Moment.js, consider contributing a pull request to that project on GitHub. Contributions to Moment.js improve time display across the Web, not just at Wikipedia.

See also

• This user script's source code
• Serendipity – another user script by mxn

User:Mxn/CommentsInLocalTime.js

script