Universal Language Selector/Developing with ULS

Universal Language Selector provides several features that can be used by other extensions. This page guides developers for that.

Using MediaWiki language selector to select language

The ResourceLoader module to be used is ext.uls.mediawiki. This module provides the jquery.uls javascript plugin along with MediaWiki defaults like language list being languages supported in MW, language search API etc.

If you don't need this customization and need only the language selection features provided by jquery.uls use jquery.uls as RL module dependency. Note that you will have to specify the list of languages to show in the list if you don't want ULS's default list, which is a superset of languages supported by MW.

The jQuery.uls provides the jQuery extension $.fn.uls that can be attached to a trigger element. After it's attached, when the user clicks the trigger, the language selector opens up.

The trigger can be a link, a button or any valid jQuery element.

Example:

$( '.uls-trigger' ).uls();

To use the selected language, you need define a selection Handler as shown below

$( '.uls-trigger' ).uls( {
	onSelect : function( language ) {
		// language is an ISO 639 language code. eg: en, hi, fi, he etc
		// Your selection handler code goes here.
	}
} );

The module can be used by a delayed loading too (lazy-loading)

$foo.on( 'click', function () { 
	mw.loader.using( 'ext.uls.mediawiki', function () {
		$foo.uls(/* options */); 
	} ); 
} );

For more examples see the documentation of the upstream jquery.uls library.

Client side language directionality

In javascript, with the help of jquery.uls we can get the directionality of the languages - whether the language is written left to right or right to left. For this, $.uls.data.getDir( languageCode ) can be used.

Example $.uls.data.getDir( 'he' ) will give "rtl" as output.

ResourceLoader module 'jquery.uls.data' should be used as a dependency for this.

Language autonyms

In javascript, with the help of jquery.uls we can get the language autonyms - language names written in its own script using $.uls.data.getAutonym( languageCode ) method.

Example:

$.uls.data.getAutonym( 'hi' ) will give "हिन्दी" as output.

ResourceLoader module 'jquery.uls.data' should be used for this.

Webfonts

By specifying font-family

Inside the wiki text <span style="font-family: 'YourFontName';">YourText</span>, webfonts extension will check whether the font is available with the extension, if so it will download it to the client. So the reader will not face any difficulty in reading the text even if the font specified is not available in their computer.

Examples:

<span style="font-family: 'UnifrakturMaguntia';">

gives Example text shown in UnifrakturMaguntia font

<span style="font-family: 'OpenDyslexic';">

gives Example text shown in OpenDyslexic font

By specifying language

Inside the wiki text <span lang="my">YourText</span>, the jquery.webfonts library will check whether it provides any font for the given language, and it if does, then it will download it to the client. Consequently, the reader will not face any difficulty in reading the text even if the font specified is not available in their computer. If there are multiple fonts for the language, the default font will be used. If the default font is not preferred, use the font-family approach to specify the font. If the tag has both lang and font-family definitions, font-family get precedence.

Example:

<span lang=sux>𒄖𒉈𒅁𒌨𒅎</span>

gives the text rendered in Cuneiform using the Akkadian font:

𒄖𒉈𒅁𒌨𒅎

Language autonyms

If we want to show many language names in a page, each with lang attributes, webfonts will start downloading for each language. This is not optimal and bandwidth consuming. To address the special case of language name listing, ULS provides another mechanism. Note that by language names we refer language autonyms. By adding a css class autonym to such elements, we can use the special font 'Autonym' for rendering it. Note that the class 'autonym' should not be used with a large scope: eg applying to a parent node, because there can be text that are not language names and the font does not have enough glyphs for such general text. So apply the class to the closest html element containing language name.

You can see the font in action at the interlanguage links of say, English wikipedia.

Providing additional language settings

By default ULS gives 2 language settings -input and display settings. But extensions or gadgets can add more language settings module so that ULS language settings screen shows them along with other language settings. The language settings module take care of persisting the preferences for both anonymous and logged in users.

An example module is given below

( function ( $, mw ) {
	'use strict';

	var template = '<div class="uls-example-settings"></div>';

	/**
	 * @param {Object} param
	 */
	function ExampleSettings( parent ) {
		this.name = 'Example'
		this.description = 'Example Settings';
		this.$template = $( template );
		this.parent = parent;
	}

	ExampleSettings.prototype = {

		constructor: ExampleSettings,

		/**
		 * Render the module into a given target
		 */
		render: function () {
			this.parent.$settingsPanel.empty();
		},

		/**
		 * Register general event listeners
		 */
		listen: function () {
		},

		/**
		 * Hide this window.
		 * Used while navigating to language selector and need coming back
		 */
		hide: function () {
			this.parent.hide();
		},

		/**
		 * Close the language settings window.
		 * Depending on the context, actions vary.
		 */
		close: function () {
			this.parent.close();
		},

		/**
		 * Callback for save preferences
		 *
		 * @param success
		 */
		onSave: function ( success ) {
		},

		/**
		 * Handle the apply button press
		 */
		apply: function () {
		},

		/**
		 * Cancel the changes done by user for display settings
		 */
		cancel: function () {
		}
	};

	// Register this module to language settings modules
	$.fn.languagesettings.modules = $.extend( $.fn.languagesettings.modules, {
		example: ExampleSettings
	} );
}( jQuery, mediaWiki ) );