MediaWiki:Gadget-relativetime.js

"use strict";

// Don't load CommentsInLocalTime for namespaces it is disabled for.
if ([-1, 0, 8].indexOf(mw.config.get("wgNamespaceNumber")) === -1) {
  // [[w:en:User:Mxn/CommentsInLocalTime]]
  // en.wikipedia.org/wiki/User:Mxn/CommentsInLocalTime.js

  /**
   * Comments in local time
   * [[User:Mxn/CommentsInLocalTime]]
   * 
   * Adjust timestamps in comment signatures to use easy-to-understand, relative
   * local time instead of absolute UTC time.
   * 
   * Inspired by [[Wikipedia:Comments in Local Time]].
   * 
   * @author [[User:Mxn]]
   */

  /**
   * Default settings for this gadget.
   */
  window.LocalComments = $.extend({
    // USER OPTIONS ////////////////////////////////////////////////////////////

    /**
     * When false, this gadget does nothing.
     */
    enabled: true,
    /**
     * Formats to display inline for each timestamp, keyed by a few common
     * cases.
     * 
     * If a property of this object is set to a string, the timestamp is
     * formatted according to the documentation at
     * <http://momentjs.com/docs/#/displaying/format/>.
     * 
     * If a property of this object is set to a function, it is called to
     * retrieve the formatted timestamp string. See
     * <http://momentjs.com/docs/#/displaying/> for the various things you can
     * do with the passed-in moment object.
     */
    formats: {
      /**
       * Within a day, show a relative time that’s easy to relate to.
       */
      day: function day(then) {
        return then.fromNow();
      },
      /**
       * Within a week, show a relative date and specific time, still helpful
       * if the user doesn’t remember today’s date. Don’t show just a relative
       * time, because a discussion may need more context than “Last Friday”
       * on every comment.
       */
      week: function week(then) {
        return then.calendar();
      },
      /**
       * The calendar() method uses an ambiguous “MM/DD/YYYY” format for
       * faraway dates; spell things out for this international audience.
       */
      other: "LLL"
    },
    /**
     * Formats to display in each timestamp’s tooltip, one per line.
     * 
     * If an element of this array is a string, the timestamp is formatted
     * according to the documentation at
     * <http://momentjs.com/docs/#/displaying/format/>.
     * 
     * If an element of this array is a function, it is called to retrieve the
     * formatted timestamp string. See <http://momentjs.com/docs/#/displaying/>
     * for the various things you can do with the passed-in moment object.
     */
    tooltipFormats: [function (then) {
      return then.fromNow();
    }, "LLLL", "YYYY-MM-DDTHH:mmZ"],
    /**
     * When true, this gadget refreshes timestamps periodically.
     */
    dynamic: true
  }, {
    // SITE OPTIONS ////////////////////////////////////////////////////////////

    /**
     * Numbers of namespaces to completely ignore. See [[Wikipedia:Namespace]].
     */
    excludeNamespaces: [-1, 0, 8, 100, 108, 118],
    /**
     * 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.
     */
    proseTags: ["dd", "li", "p", "td"],
    /**
     * Names of tags that don’t contain timestamps either directly or
     * indirectly.
     */
    codeTags: ["code", "input", "pre", "textarea"],
    /**
     * Expected format or formats of the timestamps in existing wikitext. If
     * very different formats have been used over the course of the wiki’s
     * history, specify an array of formats.
     * 
     * This option expects parsing format strings
     * <http://momentjs.com/docs/#/parsing/string-format/>.
     */
    parseFormat: "H:m, D MMM YYYY",
    /**
     * Regular expression matching all the timestamps inserted by this MediaWiki
     * installation over the years. This regular expression should more or less
     * agree with the parseFormat option.
     * 
     * Until 2005:
     * 	18:16, 23 Dec 2004 (UTC)
     * 2005–present:
     * 	08:51, 23 November 2015 (UTC)
     */
    parseRegExp: /\d\d:\d\d, \d\d? (?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)\w* \d{4} \(UTC\)/,
    /**
     * UTC offset of the wiki's default local timezone. See
     * [[mw:Manual:Timezone]].
     */
    utcOffset: 0
  }, window.LocalComments);
  $(function () {
    if (!LocalComments.enabled || LocalComments.excludeNamespaces.indexOf(mw.config.get("wgNamespaceNumber")) !== -1 || ["view", "submit"].indexOf(mw.config.get("wgAction")) === -1 || mw.util.getParamValue("disable") === "loco") {
      return;
    }
    var proseTags = LocalComments.proseTags.join("\n").toUpperCase().split("\n");
    // Exclude <time> to avoid an infinite loop when iterating over text nodes.
    var codeTags = $.merge(LocalComments.codeTags, ["time"]).join(", ");

    // Look in the content body for DOM text nodes that may contain timestamps.
    // The wiki software has already localized other parts of the page.
    var root = $("#wikiPreview, #mw-content-text")[0];
    if (!root || !("createNodeIterator" in document)) return;
    var iter = document.createNodeIterator(root, NodeFilter.SHOW_TEXT, {
      acceptNode: function acceptNode(node) {
        // We can’t just check the node’s direct parent, because templates
        // like [[Template:Talkback]] and [[Template:Resolved]] may place a
        // signature inside a nondescript <span>.
        var isInProse = proseTags.indexOf(node.parentElement.nodeName) !== -1 || !$(node).parents(codeTags).length;
        var isDateNode = isInProse && LocalComments.parseRegExp.test(node.data);
        return isDateNode ? NodeFilter.FILTER_ACCEPT : NodeFilter.FILTER_REJECT;
      }
    });

    // Mark up each timestamp found.
    function wrapTimestamps() {
      var prefixNode;
      while (prefixNode = iter.nextNode()) {
        var result = LocalComments.parseRegExp.exec(prefixNode.data);
        if (!result) continue;

        // Split out the timestamp into a separate text node.
        var dateNode = prefixNode.splitText(result.index);
        var suffixNode = dateNode.splitText(result[0].length);

        // Determine the represented time.
        var then = moment.utc(result[0], LocalComments.parseFormat);
        if (!then.isValid()) {
          // Many Wikipedias started out with English as the default
          // localization, so fall back to English.
          then = moment.utc(result[0], "H:m, D MMM YYYY", "en");
        }
        if (!then.isValid()) continue;
        then.utcOffset(-LocalComments.utcOffset);

        // Wrap the timestamp inside a <time> element for findability.
        var timeElt = $("<time />");
        // MediaWiki core styles .explain[title] the same way as
        // abbr[title], guiding the user to the tooltip.
        timeElt.addClass("localcomments explain");
        timeElt.attr("datetime", then.toISOString());
        $(dateNode).wrap(timeElt);
      }
    }

    /**
     * Returns a formatted string for the given moment object.
     * 
     * @param {Moment} then The moment object to format.
     * @param {String} fmt A format string or function.
     * @returns {String} A formatted string.
     */
    function formatMoment(then, fmt) {
      return fmt instanceof Function ? fmt(then) : then.format(fmt);
    }

    /**
     * Reformats a timestamp marked up with the <time> element.
     * 
     * @param {Number} idx Unused.
     * @param {Element} elt The <time> element.
     */
    function formatTimestamp(idx, elt) {
      var iso = $(elt).attr("datetime");
      var then = moment(iso, moment.ISO_8601);
      var now = moment();
      var withinHours = Math.abs(then.diff(now, "hours", true)) <= moment.relativeTimeThreshold("h");
      var formats = LocalComments.formats;
      var text;
      if (withinHours) {
        text = formatMoment(then, formats.day || formats.other);
      } else {
        var dayDiff = then.diff(moment().startOf("day"), "days", true);
        if (dayDiff > -6 && dayDiff < 7) {
          text = formatMoment(then, formats.week || formats.other);
        } else text = formatMoment(then, formats.other);
      }
      $(elt).text(text);

      // Add a tooltip with multiple formats.
      elt.title = $.map(LocalComments.tooltipFormats, function (fmt, idx) {
        return formatMoment(then, fmt);
      }).join("\n");

      // Register for periodic updates.
      var withinMinutes = withinHours && Math.abs(then.diff(now, "minutes", true)) <= moment.relativeTimeThreshold("m");
      var withinSeconds = withinMinutes && Math.abs(then.diff(now, "seconds", true)) <= moment.relativeTimeThreshold("s");
      var unit = withinSeconds ? "seconds" : withinMinutes ? "minutes" : withinHours ? "hours" : "days";
      $(elt).attr("data-localcomments-unit", unit);
    }

    /**
     * Reformat all marked-up timestamps and start updating timestamps on an
     * interval as necessary.
     */
    function formatTimestamps() {
      wrapTimestamps();
      $(".localcomments").each(function (idx, elt) {
        // Update every timestamp at least this once.
        formatTimestamp(idx, elt);
        if (!LocalComments.dynamic) return;

        // Update this minute’s timestamps every second.
        if ($("[data-localcomments-unit='seconds']").length) {
          setInterval(function () {
            $("[data-localcomments-unit='seconds']").each(formatTimestamp);
          }, 1000 /* ms */);
        }
        // Update this hour’s timestamps every minute.
        setInterval(function () {
          $("[data-localcomments-unit='minutes']").each(formatTimestamp);
        }, 60 /* s */ * 1000 /* ms */);
        // Update today’s timestamps every hour.
        setInterval(function () {
          $("[data-localcomments-unit='hours']").each(formatTimestamp);
        }, 60 /* min */ * 60 /* s */ * 1000 /* ms */);
      });
    }
    mw.loader.using("moment", function () {
      wrapTimestamps();
      formatTimestamps();
    });
  });
}