AVIM for Firefox

Version 20080728.306 (Saturday, February 14^th, 2009) by Minh Nguyễn

AVIM is a change-around for Firefox and similar applications that provides an input method editor for Vietnamese, based on Hiếu Đặng’s embeddable script of the same name. Hiếu was the original developer of this change-around; Minh Nguyễn is currently the lead developer.

Features

The AVIM change-around brings you modern Vietnamese typing with one of the fastest, most full-featured Vietnamese IMEs around:

AVIM supports four standard input methods (Telex, VNI, and two varieties of VIQR), as well as a default “Auto” input method, a combination of Telex and VNI.
Unlike ordinary keyboard layouts, AVIM allows you to enter a diacritical mark anywhere after the letter it belongs to, and diacritical marks can be entered in any order. Various auto-corrections result in well-formed Vietnamese words. So if you use the VIQR input method, ddu+o+`ng, dduo+`ng, dduo+ng`, ddu+`ong+, duon`g+d, and even dduong+'?~.` all produce đường.
AVIM doesn’t provide complete spell checking – you need Vietnamese Dictionary for that – but its rule-based spell checking helps keep your writing free of errors. When AVIM encounters a word that doesn’t follow Vietnamese spelling rules, it treats additional keys literally, so a key that would normally add a diacritical mark to the word instead produces the original character for that key. This behavior is useful when using foreign words in your Vietnamese writing.
AVIM understands both styles of placing diacritical marks – old (e.g., xóa) and new (xoá) – and auto-corrects your input to be consistent with your preference.
Input editing bugs are uncommon, because AVIM is well-tested in a wide variety of situations. It has even been tested against the entire word list of the Free Vietnamese Dictionary Project. The script version, already in development by 2005, is used on websites throughout the Internet. Thousands of Firefox users have installed the change-around.

The change-around comes with a complete user interface, giving you much more control over your typing than webpage-based IMEs:

A compact panel on Firefox’s status bar, much like the panels along Microsoft Word’s status bar, displays the current input method. Left-clicking on the panel reveals a menu for disabling and customizing AVIM. The status bar panel can be hidden.
A similar menu under the Edit menu provides access to AVIM’s basic options even if you hide the status bar panel or your entire status bar.
If you’re used to the row of radio buttons and checkboxes that most webpage-based IME include, the change-around provides a set of toolbar buttons that you can add individually (View ▸ Toolbars ▸ Customize…). If you don’t use all five input methods, you can add just the ones you do use.
A preferences dialog box, accessible through the Add-ons window (Tools ▸ Add-ons), allows you to configure AVIM’s behavior in detail.
Several keyboard shortcuts keep you from having to reach for the mouse. AVIM can be quickly enabled or disabled by toggling the Enabled option of either menu, or by pressing Ctrl+Alt+V (⌥⌘V on the Mac). This shortcut is useful when entering foreign words or source code into a webpage.
AVIM is available in five languages – English, Chinese (simplified and traditional), French, Spanish, and Vietnamese – all in one small download. The change-around automatically selects its interface language based on the Firefox localization that you’re using; if AVIM isn’t available in that language, it defaults to English.

Unlike other IME change-arounds for Firefox, AVIM works everywhere:

AVIM recognizes every textbox in every webpage you visit. (Although AVIM ignores password boxes by default.)
The change-around also recognizes every textbox in Firefox itself, including those in built-in windows such as the Library (formerly known as the Bookmarks Organizer), any window opened by an change-around, and any dialog box that a webpage displays using JavaScript.
AVIM fully supports any webpage written in HTML, including Gmail and Google Docs. It can handle rich text editors like FCKeditor and TinyMCE.
The change-around supports the Flock browser and the Songbird media player, as well as experimental, pre-release versions of Mozilla Thunderbird, Firefox’s companion e-mail client.

AVIM goes through great lengths to bring you an experience without surprises:

Any change to AVIM’s configuration is immediately applied to any Firefox windows you have open, and is automatically applied to any Firefox windows you open from that point on.
AVIM’s keyboard shortcuts don’t interfere with any of Firefox’s built-in shortcuts and also don’t interfere with shortcuts used by known change-arounds.
Textboxes don’t scroll to the top or jump to the beginning every time you add a diacritical mark, and the caret stays in place when you undo.
The preferences dialog box detects if the Mudim change-around is also installed and turned on and offers to turn it off for you, preventing conflicts between the two change-arounds. AVIM doesn’t actually disable Mudim, but rather sets it to its Off mode.
Similarly, a script monitor automatically disables in-page IME scripts that could interfere with AVIM.
AVIM uses a completely standard user interface, so it looks like part of Firefox, no matter which Firefox theme you use.

Compared to Mudim, CHIM, and Vietnamese Portable, AVIM is by far the most powerful Vietnamese typing tool you can download.

Screenshots

System requirements

The AVIM change-around can be used with any of the following applications:

Mozilla Firefox, version 3.0 and above
Mozilla Thunderbird, version 3.0 (alpha)
SeaMonkey, version 2.0 (alpha)
Fennec, version 1.0 (alpha)
Mozilla Prism, version 0.9 and above
Flock, version 2.0
Songbird, version 0.3 and above (beta)
Postbox, version 1.0 (beta)
Eudora, version 8.0 (beta)
Komodo IDE or Komodo Edit, version 5.0
Spicebird, version 0.7 (beta)
Instantbird, version 0.1.2 and above
BlueGriffon, version 0.1 (alpha)
Any other application based on Mozilla 1.9 or above.

You’ll also need a compatible keyboard. The included input methods assume a standard U.S. English keyboard, but any keyboard that includes the required keys will suffice. The specific keys required depend on which input method you end up using, but all the input methods require the alphabetic keys (A–Z), and the change-around’s keyboard shortcuts also require the colon (:) and semicolon (;).

The VNI input method additionally requires the numeric keys (0–9), and the VIQR input method requires the following keys: left parenthesis ((), plus (+), backtick (`), apostrophe ('), question mark (?), tilde (~), period (.), backslash (\), and hyphen (-). The VIQR* variant substitutes the asterisk (*) for plus (+).

Finally, to properly display the accented text, you’ll need fonts capable of displaying the various Vietnamese characters. Most modern operating systems now come with Vietnamese font support.

Installation

avim-20080728.306.xpi

(XPInstall package, 43.3 kB)

If you’re planning to use AVIM in Firefox, left-click on the link above. You’ll see a banner (typically yellow) indicating that Firefox has blocked the installation. Click Allow, then click Install Now in the dialog box that appears. Restart Firefox.

If you’re downloading AVIM for another application, such as Thunderbird, right-click on the link above and select Save Link As. After saving the installer, open the destination application’s Add-ons window (usually by going to Tools ▸ Add-ons). Drag the installer into that window, click Install Now in the dialog box that appears, and restart the application.

The change-around installer is also available at the official Firefox Change-arounds website.

Usage

Typing in Vietnamese

Once you install the change-around and restart Firefox, the Auto input method is automatically enabled. To switch to a different input method, go to Edit ▸ Vietnamese Input or click on the panel labeled “Auto” on the status bar. You can also use Ctrl+: and Ctrl+; (⌘: and ⌘; on the Mac) to cycle back and forth between the input methods. The input methods use the following key mappings:

Input methods in AVIM
Mark	Example	Keys pressed
Mark	Example	Auto¹	Telex	VNI	VIQR	VIQR*
Tone marks
Acute (sắc)	á	`as` or `a1`	`as`	`a1`	`a'`
Grave (huyền)	à	`af` or `a2`	`af`	`a2`	a`
Hook (hỏi)	ả	`ar` or `a3`	`ar`	`a3`	`a?`
Tilde (ngã)	ã	`ax` or `a4`	`ax`	`a4`	`a~`
Dot below (nặng)	ạ	`aj` or `a5`	`aj`	`a5`	`a.`
Other diacritical marks
Circumflex (mũ)	â	`aa` or `a6`	`aa`	`a6`	`a^`
Circumflex (mũ)	ê	`ee` or `e6`	`ee`	`e6`	`e^`
Horn (móc)	ơ	`ow` or `o7`	`ow`	`o7`	`o+`	`o*`
Breve (trăng)	ă	`aw` or `a8`	`aw`	`a8`	`a(`
Stroke (gạch ngang)	đ	`dd` or `d9`	`dd`	`d9`	`dd`
Special shortcuts
Escape a dead key	a.				`a\.`²
Remove a diacritic		`z` or `0`	`z`	`0`	`-`
Configurable. To enter an actual backslash, use two backslashes (`\\`).

As an example, here are the opening lines of the Vietnamese epic poem Truyện Kiều:

Trăm năm trong cõi người ta,
Chữ tài chữ mệnh khéo là ghét nhau
Trải qua một cuộc bể dâu,
Những điều trông thấy mà đau đớn lòng.
Lạ gì bỉ sắc tư phong
Trời xanh quen thói má hồng đánh ghen.

And here are ways to type them in using the provided input methods (which can vary, since AVIM is so flexible with dead keys):

Telex: Trawm nawm trong coxi nguwowfi ta, Chuux tafi chuwx meejnh kheso laf ghest nhau Trari qua moojt cuoojc beer daau, Nhuwxng ddieefu troong thaasy maaf ddau ddowsn lofng. Laj gif bir sawsc tuw phong Trowfi xanh quen thosi mas hoofng ddasnh ghen.
VNI: Tra8m na8m trong co4i ngu7o72i ta, Chu74 ta2i chu72 me65nh khe1o la2 ghe1t nhau Tra3i qua mo65t cuo65c be63 da6u, Nhu74ng d9ie62u tro6ng tha61y ma2 d9au d9o71n lo2ng. La5 gi2 bi3 sa81c tu7 phong Tro71i xanh quen tho1i ma1 ho62ng d9a1nh ghen.
VIQR: Tra(m na(m trong co~i ngu+o+`i ta, Chu+~ ta`i chu+~ me^.nh khe'o la` ghe't nhau Tra?i qua mo^.t cuo^.c be^? da^u, Nhu+~ng ddie^`u tro^ng tha^'y ma` ddau ddo+'n lo`ng\. La. gi` bi? sa('c tu+ phong Tro+`i xanh quen tho'i ma' ho^`ng dda'nh ghen\.
VIQR*: Tra(m na(m trong co~i ngu*o*`i ta, Chu*~ ta`i chu*~ me^.nh khe'o la` ghe't nhau Tra?i qua mo^.t cuo^.c be^? da^u, Nhu*~ng ddie^`u tro^ng tha^'y ma` ddau ddo*'n lo`ng\. La. gi` bi? sa('c tu* phong Tro*`i xanh quen tho'i ma' ho^`ng dda'nh ghen\.

Try out typing with AVIM at the test page.

Customizing AVIM

By default, the Auto input method accepts both the Telex and VNI input methods. You can change this behavior, as well as several other options, using AVIM’s preferences dialog box.

The available options are:

Enable AVIM for Vietnamese input

If checked, AVIM is enabled. Otherwise, it’s disabled, so that typing proceeds as if the change-around has not been installed. By default, it’s checked (enabled). This option is equivalent to the extensions.avim.enabled preference.

Input method

Selects the input method that is applied to your keyboard input. By default, it’s set to Auto. This option is equivalent to the extensions.avim.method preference, which accepts the following values:

Auto
Telex
VNI
VIQR
VIQR*

Enforce Vietnamese spelling rules

If checked, AVIM works as a spell checker of sorts. Consider a word that doesn’t conform to Vietnamese spelling rules – which typically means it’s a foreign word or name. If you have chosen the Telex input method, as normally comes out as á, but if this option is checked and you type in Washington, you’ll get Washington; if the option is unchecked, you’ll get Wáhington. By default, this option is checked (enforced). This option is equivalent to the extensions.avim.ignoreMalformed preference.

Allow dz and f at the beginning of a word

If checked, AVIM allows you to place accent marks on words that start with dz (equivalent to d) or f (equivalent to ph), even when spelling rules are being enforced. Such spellings aren’t acceptable in formal writing but are common in online forums. By default, this option is unchecked (not allowed). It’s equivalent to the extensions.avim.informal preference.

Place tone marks on the first vowel in a final diphthong (old-style accent marks)

If checked, AVIM ensures that you place tone marks on diphthongs the traditional way, so that both xo'a and xoa' produce xóa (using the VIQR input method). If unchecked, AVIM uses the newer style, so that both produce xoá. By default, it’s checked (old style). This option is equivalent to the extensions.avim.oldAccents preference.

Accept keystrokes from the following input methods when Auto is selected

If any of the options under this heading is checked, that input method’s keystrokes are accepted by the Auto input method. By default, Telex and VNI contribute to the Auto input method. These options are equivalent to the preferences beginning with extensions.avim.auto.

Disable input editing scripts inside web pages

If checked, the script monitor is enabled. As soon as you type into a webpage, the extension automatically disables any IME scripts on that page that could interfere with AVIM. By default, this option is checked, so the AVIM/HIM, MViet, VietTyping, and VietUni scripts are disabled. This option is equivalent to the extensions.avim.scriptMonitor.enabled preference. You can customize which scripts are disabled using the remaining preferences beginning with extensions.avim.scriptMonitor. The script monitor is capable of disabling the following scripts: AVIM/HIM, CHIM/Mudim, MViet, VietIMEW, VietTyping, VietUni, and Vinova.

Allow diacritics in password boxes

If checked, AVIM allows you to add diacritics to passwords, both on webpages and in the application’s user interface. By default, it’s unchecked (unaccented passwords). This option is equivalent to the extensions.avim.passwords preference. Use caution when using accented passwords on a website: the website may not handle Unicode passwords properly; additionally, you might not be able to enter your password correctly when you use a different computer.

Show in status bar

If checked, the status bar panel is displayed; otherwise, it’s hidden. By default, it’s checked (displayed). This option is equivalent to the extensions.avim.statusBarPanel preference.

Ignored Textboxes tab

A case-insensitive list of field IDs. Textboxes with these IDs are ignored by AVIM. By default, the list consists of the following IDs:

colorzilla-textbox-hex – hexadecimal color textbox, ColorZilla extension
email and e-mail
E-mail addresses rarely contain non-ASCII characters
TextboxEval – the Code bar, Error Console
tx_tagName – Tag Name box, Insert Node dialog, DOM Inspector
Tag names very rarely contain non-ASCII characters.

Here are some commonly-used IDs in Firefox’s user interface:

urlbar – Location Bar
Ignoring the Location Bar is not recommended, because AVIM is useful when entering URLs of Vietnamese Wikipedia articles, for instance. However, you should ignore it if you’ve enabled the network.IDN_show_punycode option in about:config.
searchbar – Web Search Bar
FindToolbar – Find in Page Bar

And in Thunderbird:

ColorInput – custom color textbox, Text Color and Block Background Color dialogs, Compose window
If you use Telex, you may want to prevent yourself from accidentally entering diacritics instead of a hexadecimal code (for example, #èfe instead of #efefef).

This option is equivalent to the extensions.avim.ignoredFieldIds preference.

Using AVIM in Vietnamese

By default, AVIM’s interface uses the same language that Firefox does on your system. Vietnamese language packs are available for Firefox 2, 3.0, and 3.1 beta 2. If you prefer to use just your change-arounds in Vietnamese:

Using Firefox’s Location Bar, navigate to about:config. (Or in Thunderbird, go to Tools ▸ Options, switch to the Advanced tab, and press the Config Editor button.)
Click the “I’ll be careful, I promise!” button to continue. (If you follow these steps, everything should be fine.)
Type general.useragent.locale into the Filter bar and wait a second.
Double-click on the preference labeled general.useragent.locale.
Type vi (meaning Vietnamese) into the dialog box that appears and press OK.
Restart Firefox.

To undo the locale change, follow the above instructions, but instead of double-clicking on the preference, right-click on it and select Reset. Then restart Firefox.

Thanks to Trần Xuân Huy for the tip.

Known issues

AVIM registers too many undo levels (about one per letter).
In rich text editors, tone marks are lost when shifted to the last character in the word. For example, xo'a becomes “xoa”, instead of “xoá”, when the Old Accents option is disabled.
Also in rich text editors, the caret may briefly appear in the wrong position after redoing.
When editing a bookmark’s tags, Firefox 3.1 automatically suggests (“autofills”) tags and highlights those suggestions, interfering with AVIM.
In some of SeaMonkey’s windows, the Vietnamese Input menu doesn’t appear.
The Silvermel theme places extra padding around the preference dialog box, hiding the Show in Status Bar option.
Due to a bug in BlueGriffon, AVIM is unable to remember preferences across sessions.

What’s new

Version 20080728.306 (Saturday, February 14^th, 2009)

Older releases…

How to help

AVIM makes a good effort to recognize every textbox in every webpage that Firefox loads. However, some webpages make it difficult to do so. If you encounter a publicly-accessible website that is not supported by AVIM, please let Minh know. (Note that for technical reasons it isn’t possible to support textboxes in Flash webpages or Java applets.)
If you’re proficient in Vietnamese, help Minh and Hiếu find words that AVIM doesn’t handle correctly.
If you’re proficient in a language that AVIM isn’t available in, help translate AVIM into that language. It’s not much work, and you can translate online at BabelZilla.

License

This change-around is powered by Hiếu Đặng’s AVIM script, which is available under the following permissive license:

AVIM JavaScript Vietnamese Input Method Source File

Copyright © 2004–2008 Hieu Tran Dang <lt2hieu2004 (at) users (dot) sf (dot) net> Website: http://noname00.com/hieu

You are allowed to use this software in any way you want providing:

You must retain this copyright notice at all time

You must not claim that you or any other third party is the author of this software in any way.

The script file has been modified pursuant to this license and with Hiếu’s written permission. The included image files are in the public domain. All other files distributed with this change-around are available under the MIT license:

Copyright © 2007–2008 Minh Nguyen.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

The Software is provided “AS IS”, without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the software or the use or other dealings in the Software.

In short, do pretty much whatever you want with this software, as long as you keep the copyright notices included with AVIM intact and don’t sue Minh or Hiếu if anything goes wrong.

Building it yourself

If you’d like to keep up with the latest development code, you can use the following command (which requires Subversion) in a command line window, to check out the change-around’s current source code:

svn co http://version.1ec5.org/avim/trunk/ avim

To package the code as an change-around yourself, you can use the included build script, which requires Python 2.5 or above. In a command line window, navigate to the avim/ directory and execute the following command:

python build.py

Two installable archives, avim.xpi and avim-version.xpi, should now reside in that directory.

Build options

To streamline the release process, the build script supports several options:

-m --amo: Produce an unminified build for the Firefox Change-arounds site. The package will be significantly larger.
--babelzilla: Produce a BabelZilla-compatible build, to aid in localizing the change-around. <em:localized> tags in the change-around’s install manifest are removed, and included localizations are renamed according to BabelZilla’s predefined locale codes.
-d --debug: Produce a testing build. The test suite is included, to aid in finding regressions.
-h --help: Print this help message to the command line.
--songbird: Produce a build compatible with the Songbird Add-ons website. The installer package will be significantly larger, because optional metadata is included with each file in the package.
--use-name name: Override the package name. The default is avim.
--use-version version: Override the version string. The default is based on the Subversion revision that you’ve checked out.
-v --version: Print the build script’s version to the command line.

Using the test suite

When you build a non-release (debug or localization) version of the change-around, it includes an automated test suite. Although it’s still quite rudimentary, the test suite makes it quite easy to spot regressions in AVIM’s core functions.

To use the test suite:

Install the debug build into a supported application.
Open the application’s Add-ons Manager (Tools ▸ Add-ons) and select AVIM from the list of change-arounds.
Click the Preferences button to open AVIM’s preferences panel and click the Open Test Suite button.
Click the Browse button to specify the file to use as input. The plain text file should consist of a whitespace-separated list of well-formed Vietnamese words.
Click the Run Tests button.

AVIM enters the specified words using the currently activated input method. As each test runs, the tester updates a multi-column list with the original word, the keystrokes used to input the word, and the resulting text. The final column indicates whether the outputted text matched the expected output. Each row is highlighted in green or red, so that it’s easy to skim the list for any regressions.

The test suite currently tests the selected input method, moving all dead keys to the end of the word. It accounts for automatic duplication of the horn diacritic (ơ and ư). Future improvements to the tester will allow you to verify that diacritical marks aren’t placed on malformed words.