Extension:Narayam

Development on this extension is discontinued. Please use Universal Language Selector instead. Critical support requests and addition of keymaps will continue as long as it is deployed in Wikimedia projects

MediaWiki extensions manual - list

Narayam Release status: stable
Implementation	Hook
Description	Allows to add custom input methods for input fields.
Author(s)	Junaid P V (Junaidpvtalk)
Last version	0.2 (2011-02-25)
MediaWiki	1.18 or later
PHP	5.1 or later
License	GPLv3
Download	Download snapshot (Git master) Git [?]: repo summary tree code changes
Example	http://ml.wikipedia.org/
Parameters $wgNarayamConfig['shortcut_controlkey'] = true; $wgNarayamConfig['shortcut_altkey'] = false; $wgNarayamConfig['shortcut_shiftkey'] = false; $wgNarayamConfig['shortcut_metakey'] = false; $wgNarayamConfig['shortcut_key'] = 'M'; $wgNarayamConfig['schemes'] = array('ml', 'ta99', 'ml_inscript'); $wgNarayamConfig['default_scheme_index'] = 0; $wgNarayamConfig['enabled'] = true;
Hooks used BeforePageDisplay GetPreferences
Check usage and version matrix
Bugs: list open list all report

Narayam is a Mediawiki extension that helps adding and managing different language input methods for the various text input fields easily. The primary users of this extension are wikis that use non-Latin scripts. Currently supported typing schemes are given below. You can file an enhancement bug in Mediawiki Bugzilla against Narayam extension for adding a new input method.

See also user help for this extension.

Usage

The primary aim is to allow users to input text in the wiki without the support of any external typing tools.

Download instructions

Download Narayam and put it in to a directory named Narayam under $IP/extensions/ Note: $IP stands for the root directory of your MediaWiki installation, the same directory that holds LocalSettings.php. This extension is supported only on Modern, Monobook, Vector skins.

Installation

To install this extension, add the following to LocalSettings.php:

require_once("$IP/extensions/Narayam/Narayam.php");

Configuration parameters

These are available configurations you can optionally specify on your LocalSettings.php.

• Whether the input method should be active as default or not

$wgNarayamEnabledByDefault = true;

• Number of recently used input methods to be shown in the menu.

$wgNarayamRecentItemsLength = 3;

• Whether the extension should load input methods in beta status. By default this false.

$wgNarayamUseBetaMapping = true;

Supported schemes

Indic scripts

• Assamese [as]
  • Avro (Phonetic)
  • InScript
  • Bornona
  • Transliteration
• Bengali [bn]
  • Avro (Phonetic)
  • InScript
  • National Keyboard
  • Probhat (beta)
• Bodo [brx]
  • InScript
• Gujarati [gu]
  • Transliteration
  • InScript
• Hindi [hi]
  • Transliteration
  • InScript
• Kannada [kn]
  • Transliteration
  • InScript
• Malayalam [ml]
  • Transliteration (Mozhi)
  • InScript
• Marathi [mr]
  • Transliteration
  • InScript
• Nepali [ne]
  • Transliteration
  • InScript
• Odia [or]
  • Transliteration
  • Lekhani
  • InScript
• Gurmukhi Punjabi [pa]
  • Phonetic
  • InScript
• Sanskrit [sa]
  • Transliteration
  • InScript
• Sinhala [si]
  • Singlish (Partial phonetic)
  • Wijesekara
• Tamil [ta]
  • Transliteration
  • Tamil99
  • InScript
• Telugu [te]
  • Transliteration
  • InScript

Arabic

• Urdu [ur]: Standard

Latin

• Esperanto [eo]: x-code transcription
• German [de]: umlauts and sz

Cyrillic

• Russian [ru]
• Sakha [sah]

Other

• Amharic [am] (experimental)
• Tifinagh for Berber (Tachelhit [shi] and Tarifit [rif])
• Javanese [jv] (experimental)

Developing a key mapping

More input methods can be added by writing scheme data in a particular format.

A scheme consists of rules used for transliteration. A rule is an array of three strings:

1. A regex that is matched against the input string (the last few characters before the cursor followed by the character the user entered).
2. A regex that is matched against the end of the key buffer (the last few keys the user pressed).
3. The replacement string (may contain placeholders like $1 for subexpressions).

You do not need to add $ to the end of either of the regexes so they match at the end, this is done automagically.

Note that the regexes are written as plain strings in the mapping file, so, for example, if you want to match the full stop character, you'll have to write '\\.' instead of '\.', to match one backslash you'll have to write '\\\\' and so on.

The transliteration algorithm processes the rules in the order they are specified, and applies the first rule that matches. For a rule to match, both the first and second regex have to match (the first for the input, the second for the key buffer). Most rules do not use the keybuffer and specify an empty string as the second regex.

The scheme data object must have the following keys:

• namemsg: Message key for the name of the scheme.
• extended_keyboard: Whether this scheme has an extended ruleset (bool).
• lookbackLength: Number of characters before the cursor to include when matching the first regex of each rule. This is usually the maximum number of characters a rule regex can match minus one.
• keyBufferLength: Length of the key buffer. May be zero if not needed.
• rules: Array of rules, which themselves are arrays of three strings.
• rules_x: Extended ruleset. This is used instead of the normal ruleset when Alt is held. This key is only required if extended_keyboard is true.

Let's consider sample parts from Sanskrit Transliteration scheme, since it utilizes most features of rules.

var rules = [
['क्h','c','च्'],
['\\\\([A-Za-z\\>_~\\.0-9])','\\\\','$1'],
['([क-ह]़?)्A', '','$1ा'],
['अa', '','आ'],
['a', '','अ'],
['b', '','ब्'],
['\\.', '','।'],
];
 
jQuery.narayam.addScheme( 'sa', {
        'namemsg': 'narayam-sa',
        'extended_keyboard': false,
        'lookbackLength': 4,
        'keyBufferLength': 1,
        'rules': rules
} );

In this map

['a', '','अ'],
['b', '','ब्'],

are direct maps, that is, when we type 'a' it will produce 'अ' in the text field.

Testing layouts

Narayam has a simple, but powerful, testing framework based on the standard MediaWiki JavaScript QUnit testing.

When you are developing a new layout or making changes in an existing one, begin by running the tests by opening the Special:JavaScriptTest/qunit page on your testing wiki. Check that all ext.narayam* tests pass. Note, that the tests will fail if there is no layout for your current interface language, so change it to a language that has one, probably the one for which you are developing a layout.

When you are adding or changing rules, edit the tests/qunit/ext.narayam.rules.tests.js file and add a test for every rule that you are adding or changing. If you are adding a brand new layout or a lot of similar rules, it may be enough to add tests that represent a sample of the rules.

Here's an example test block for a layout:

narayamTest ( {
        description: 'Amharic Transliteration test',
        tests: [
                { input: 'ka', output: 'ካ', description: 'Amharic ka -> ካ' },
                { input: 'dwa', output: 'ዷ', description: 'Amharic dwa -> ዷ' }
        ],
        scheme: 'am',
        $input: $( '<input>' ).attr( { id: 'am', type: 'text' } )
} );

Let's analyze it:

description

This is the description of a block of tests that will appear when you run them in Special:JavaScriptTest/qunit.

tests

These are the actual tests. Make sure to add a comma after each test except the last one, as it usually is with JavaScript. See below for more details about the tests.

scheme

This is the name of the scheme. It is the same as the first parameter to the jQuery.narayam.addScheme function. It must also appear in the id field in the $input line.

Each test consists of:

input

The characters which are expected to be typed. This is either a string (for non-extended input) or an array of arrays (see below).

output

This is the expected result: the string that is supposed to appear after the input is typed. In the first case, it is expected that typing 'ka' will yield the Amharic letter 'ካ' and in the second case it is expected that typing 'dwa' will yield 'ዷ'.

description

This is a description of the test that will appear in Special:JavaScriptTest/qunit.

For extended keys specify the characters like this:

narayamTest( {
        description: 'Hebrew Transliteration and extended keys test',
        tests: [
                { input: [ [ '-', false ] ], output: '-', description: 'Hebrew regular -' },
                { input: [ [ '-', true ]  ], output: '־', description: 'Hebrew extended -' }
        ],
        scheme: 'he-standard-2011-extonly',
        $input: $( '<input>' ).attr( { id: 'he-standard-2011-extonly', type: 'text' } )
} );

In this example, the first test checks typing the '-' character without pressing the key that makes it extended, and the second tests the same character, extended.

When you added the tests and the rules, go to the Special:JavaScriptTest/qunit page again and check that your new test ran successfully and that existing tests didn't fail.

Usage on Wikimedia projects

See also full information table

• Assamese, Hindi, Malayalam, Odiya, Sanskrit, Sinhala and Tamil Wikimedia projects
• Meta-wiki, Incubator, Wikimedia Commons, MediaWiki, Wikidata, Test wiki.

  Also non-Wikimedia wikis like translatewiki.net

Similar JavaScript keyboarding helpers are used at various Wikimedia wikis, for instance AVIM at Wikimedia's Vietnamese wikis.

User level customization

It is possible to override a set of rules in a Narayam scheme using a little private script. Here's an example:

mw.loader.using('ext.narayam.rules.ml', function () {
/*
 * mw.loader ensures that the required JavaScript  is loaded (and only once)
 * before the rest of the customization code is executed.
 * If you want to do customization on an input method, find out the resource
 * loader module name corresponding to that from Narayam.php.
 * This example uses Malayalam transliteration.
 */
var ml_scheme = $.narayam.getScheme( 'ml' );
var custom_rules = [
       ['4', '', '₹']
       // Rest of the rules you want to customize.
];
ml_scheme.rules.unshift.apply( ml_scheme.rules, custom_rules );
} );

With the above code snippet, we assign 4 to ₹ in Malayalam transliteration scheme. Note that any kind of JavaScript errors will make the extension unusable. Regular expression and complex rules are possible, but in those cases you know what you are doing. If you think a customization is useful for others too, please inform the developers.

Known issues

• Extended keyboards seem to do work only within Firefox. Also, browsers do not provide a way to differentiate normal Alt and AltGr key events.
• Narayam bugs are tracked on Bugzilla

Reporting bugs

Bugs should be reported in Bugzilla, by selecting "MediaWiki extensions" and "Narayam".

When you report a bug, please indicate a complete input string and the expected output. Example:

I expect that when I write 'kaI' in the Punjabi transliteration layout, the output will be 'ਕਈ'.

This helps the developers a lot in testing the layout.

See also

• Writing systems - information on writing systems in MediaWiki
• Help:Extension:Narayam
• Bug reports
• Translations

Related documents

• File:Narayam-proposal-annotated.pdf (implemented)
• File:Narayam-proposal.pdf (implemented)