User:Evad37/Module/extra.js

/**
 * @module extra
 * @description Library of little helper functions. Derived from https://en.wikipedia.org/wiki/User:Evad37/extra.js
 * @author User:Evad37
 * @version 1.0.0
 * @requires mediawiki.util
 * @exports {Object} extra
 *   @property {Function} extra.makeApiErrorMsg
 *   @property {Function} extra.makeLink
 *   @property {Function} extra.makeTooltip
 *   @property {Function} extra.toSentenceCase
 *   @property {Function} extra.uniqueArray
 *   @property {Function} extra.val2key
 */
Window.exportScriptModule('extra', (function(){ // <nowiki> LEAVE THIS LINE AT THE TOP
	return mw.loader.using('mediawiki.util').then(function() {
		var extra = {};
		
		/**
		 * makeApiErrorMsg
		 *
		 * Makes an error message, suitable for displaying to a user, from the values
		 * that the MediaWiki Api passes to the failure callback function, e.g.
		 * `new mw.Api.get(queryObject}).done(successCallback).fail(failureCallback)`
		 *
		 * @param {String} code
		 *  First paramater passed to failure callback function.
		 * @param {jQuery.jqXHR} jqxhr
		 *  Second paramater passed to failure callback function.
		 * @return {String} Error message details, with in a format like
		 *  "(API|HTTP) error: details"
		 */
		extra.makeErrorMsg = function(code, jqxhr) {
			var details = '';
			if ( code === 'http' && jqxhr.textStatus === 'error' ) {
				details = 'HTTP error ' + jqxhr.xhr.status;
			} else if ( code === 'http' ) {
				details = 'HTTP error: ' + jqxhr.textStatus;
			} else if ( code === 'ok-but-empty' ) {
				details = 'Error: Got an empty response from the server';
			} else {
				details = 'API error: ' + code;
			}
			return details;
		};
		
		/**
		 * makeLink
		 *
		 * Makes a link to a en.Wikipedia page that opens in a new tab/window.
		 * 
		 * @param {string} linktarget
		 *  The target page.
		 * @param {string} linktext
		 *  Text to display in the link. Optional, if not provided the target will be used.
		 * @return {jQuery} jQuery object containing the `<a>` element.
		 */
		extra.makeLink = function(linktarget, linktext) {
			return $('<a>').attr({
				'href':'https://en.wikipedia.org/wiki/'+mw.util.wikiUrlencode(linktarget),
				'target':'_blank'
			}).text(linktext || linktarget);
		};
		
		/**
		 * makeTooltip
		 *
		 * Make a question mark in a circle that shows a 'tooltip' when hovered over
		 *
		 * @param {String} tipText
		 *  The text for the tooltip.
		 * @return {jQuery} jQuery object containing the tooltip (<span> element)
		 */
		extra.makeTooltip = function(tipText) {
			// Add css rule, if not already added
			if ( !extra.tooltipStyle ) {
				var s = mw.loader.addStyleTag('.ejs-tooltip { border:1px solid #33a; border-radius:10px; '+
				'font-weight:bold; font-size:80%; color:#22a; padding:0px; cursor:help }');
				extra.tooltipStyle = s.sheet || s.styleSheet || s;
			}
			return $('<span>').attr({'title':tipText, 'class':'ejs-tooltip'}).html('&thinsp;?&thinsp;');
		};
		
		/**
		 * toSentenceCase
		 *
		 * Capitalises the first letter of a string.
		 *
		 * @param {String} input
		 *  The string to be transformed.
		 * @param {Boolean} lc
		 *  Transform the characters following the first character to lowercase
		 * @returns {String} Transformed string.
		 */
		extra.toSentenceCase = function(input, lc) {
			return input.slice(0,1).toUpperCase() +
				(( lc ) ? input.slice(1).toLowerCase() : input.slice(1));
		};
		
		/**
		 * uniqueArray
		 *
		 * Filters out possible duplicate values from an array.
		 *
		 * @param {array} a
		 *  Array to be filtered.
		 * @return {array} Filtered array.
		 */
		extra.uniqueArray = function(a) {
			return a.filter(function(val, i, arr){ return arr.indexOf(val) === i; });
		};
		
		/**
		 * val2key
		 *
		 * For an object `obj` with key:value pairs, return a value's corresponding key.
		 *
		 * @param {String|Number} val
		 *  Value to seach for.
		 * @param {Object} obj
		 *  Object to search in.
		 * @return {String|Number|undefined} Key corresponding to the input value, 
		 *  or undefined if the value was not found.
		 */
		extra.val2key = function(val, obj) {
		    for ( var k in obj ) {
		        if ( obj[k] === val ) {
		            return k;
		        }
		    }
		};
	
		return extra;
	});
		
})()); // </nowiki> LEAVE THIS LINE AT THE BOTTOM OF THE SCRIPT MODULE