Extension:Narayam

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  under   Note: $IP stands for the root directory of your MediaWiki installation, the same directory that holds LocalSettings.php.

Installation
To install this extension, add the following to LocalSettings.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


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


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

Indic scripts

 * Assamese [as]
 * Avro (Phonetic)
 * InScript
 * Bornona
 * Transliteration
 * Bengali [bn]
 * Avro (Phonetic)
 * InScript
 * National Keyboard
 * 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
 * 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])

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: You do not need to add $ to the end of either of the regexes so they match at the end, this is done automagically.
 * 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).

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.

In this map

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:

Let's analyze it:
 * : This is the description of a block of tests that will appear when you run them in Special:JavaScriptTest/qunit.
 * : 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.
 * : This is the name of the scheme. It is the same as the first parameter to the  function. It must also appear in the id field in the   line.

Each test consists of:
 * : The characters which are expected to be typed. This is either a string (for non-extended input) or an array of arrays (see below).
 * : 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 'ዷ'.
 * : This is a description of the test that will appear in Special:JavaScriptTest/qunit.

For extended keys specify the characters like this:

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

 * Assamese, Malayalam, Odiya, Sanskrit, Sinhala and Tamil Wikimedia projects
 * Meta-wiki, Incubator, Wikimedia Commons, MediaWiki wiki.

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: 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.

Related documents

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