Adding support for non-US Keyboard for Console Proxy

Main Files (Present in directory mentioned next to them)

[1] ajaxkeys.js : /usr/share/cloudstack-common/systemvm/js/

[2] ajaxkviewer.js : /usr/share/cloudstack-common/systemvm/js/

[3] consoleKeyboardOptions.jsp : /usr/share/cloudstack-management/webapps/client/

References

[1] Support for non-US keyboards in Console Proxy

Note : Bold Italic designates added/modified values

After the framework changes as mentioned in [1], It is easier to add support for non-US keyboard for console proxy. To do so one has to just add the mappings for their locale keyboard in one designated file.

Glossary:

RAW keyboard

    Primarily translates KeyDown/KeyUp event, either as is (if there is no mapping entry) or through mapped result.
    For KeyPress event, it translates it only if there exist a mapping entry in jsX11KeysymMap map and the entry meets the condition 

Example of this kind of keyboard are JP

COOKED keyboard 

       Primarily translates KeyPress event, either as is or through mapped result.

       It translates KeyDown/KeyUp only there exists a mapping entry,

       or if there is no mapping entry, translate when certain modifier key is pressed (i.e., CTRL or ALT key)

Example for this type of keyboard are US, UK, FR

 Mapping entry types
    direct    :  will be directly mapped into the entry value with the same event type
    boolean       :  only valid for jsX11KeysymMap, existence of this type, no matter true or false
                in value, corresponding KeyDown/KeyUp event will be masked
    array     :  contains a set of conditional mapping entry
    
 Conditional mapping entry

    { 
       type: <event type>, code: <mapped key code>, modifiers: <modifiers>,
       shift : <shift state match condition>,    -- match on shift state
       guestos : <guest os match condition>,     -- match on guestos type
       browser: <browser type match condition>,   -- match on browser
       browserVersion: <brower version match condition>   -- match on browser version
       guestosDisplayName: <guest os display name condition>  -- matches on specific version of guest os
                      provide the guest os display name substring to uniquely identify version
                      for example if guestosDisplayName CentOS 5.2 (32-bit), then to match this condition
                      give unique substring to identify like 5.2 or CentOS 5.2 etc.
       hypervisor: <hypervisor match condition>   --match on hypervisor
       hypervisorVersion: <hypervisor version match condition>    --match on hypervisor version
    }

Changes needs to be done in consoleKeyboardOptions.jsp

To add new keyboard for console proxy add the corresponding parameters in  file [3] consoleKeyboardOptions.jsp. Option added here will be displayed while deploying VM.

for example say  file [3] consoleKeyboardOptions.jsp is looking like below

Then to add keyboard for simplified chinese add the line as follows

Changes needs to be done in ajaxkeys.js

Add the keyboard in  file [1] ajaxkeys.js also. Where to add the keyboard option in file [1] ajaxkeys.js will depend upon your keyboard layout.

We divide the keyboard layout into two categories cooked keyboard and raw keyboard as mentioned in glossary

To add the cooked keyboard type, add in below section in ajakeys.js

var cookedKeyboardTypes = {"us":"Standard (US) keyboard",

                                                                 "uk":"UK keyboard",

                                              "fr":"French AZERTY keyboard"}

and to add the raw keyboard type add in section 

 var rawKeyboardTypes = {"jp":"Japanese keyboard"}

Make sure key is same as value in consoleKeyboardOptions.jsp

Say if you consider simplified Chinese of type raw keyboard then add it as follow

var rawKeyboardTypes = {"jp":"Japanese keyboard",

                                          "sc":"Simplified Chinese keyboard"}

Make a note "sc" key is same as value in file [3] consoleKeyboardOptions.jsp

It will be good practice to add the constant for your keyboard. To do so add constant in below section. For example to add constant for simplified Chinese add it as shown below

Add the constant for your keyboard type in section.

KEYBOARD_TYPE_COOKED = "us";

KEYBOARD_TYPE_JP = "jp";

KEYBOARD_TYPE_UK = "uk";

KEYBOARD_TYPE_FR = "fr";

KEYBOARD_TYPE_SC = "sc";

After the adding keyboard in one of above categories its time to define the key mappings. Focus should be on those keys which are not working by default.

To do so create index for your keyboard as shown below

Say your ajaxkeys.js looks like as shown below,

var keyboardTables = [
           {tindex: 0, keyboardType: KEYBOARD_TYPE_COOKED, mappingTable:
               {X11: [ .............
                     ],
                keyPress: [ ...........
                        ]
               }
           },

{tindex: 1, keyboardType: KEYBOARD_TYPE_UK, mappingTable:
               {X11: [ .............
                     ],
                keyPress: [ ...........
                        ]
               }
           },

{tindex: 2, keyboardType: KEYBOARD_TYPE_JP, mappingTable:
               {X11: [ .............
                     ],
                keyPress: [ ...........
                        ]
               }
           }

] 

Then after modification it will look like

var keyboardTables = [
           {tindex: 0, keyboardType: KEYBOARD_TYPE_COOKED, mappingTable:
               {X11: [ .............
                     ],
                keyPress: [ ...........
                        ]
               }
           },

{tindex: 1, keyboardType: KEYBOARD_TYPE_UK, mappingTable:
               {X11: [ .............
                     ],
                keyPress: [ ...........
                        ]
               }
           },

{tindex: 2, keyboardType: KEYBOARD_TYPE_JP, mappingTable:
               {X11: [ .............
                     ],
                keyPress: [ ...........
                        ]
               }
           },

{tindex: 3, keyboardType: KEYBOARD_TYPE_SC, mappingTable:

               {X11: [ .............

                     ],

                keyPress: [ ...........

                        ]

               }

           }

]

Here KEYBOARD_TYPE_SC is constant "sc" as defined above.

After creating index its time to add the conditional map entries into X11 and keyPress array. It will depend on your keyboard in which you want to put your conditional entries.

Conditional map entries looks like

{keycode: 34,      entry: 0x40,   guestos: "windows"},

{keycode: 160,  entry : 0x5e,  guestos: "windows",    browser: "Firefox"},

Here keycode is input keycode and entry is output which will determine the key shown on VM console. This entry will only applied if it matches condition which are mentioned next to it.

Here in first entry condition is guestos: "windows" i.e. match only if guestos is windows while in second conditional map entry one more condition is added that match only if guestos is windows and browser is firefox. 

Conditional mapping entries can be defined on the conditions which are mentioned in glossary conditional mapping entry.

Possible values for conditional mapping entry conditions

guestos : CentOS, Debian, Oracle, RedHat, SUSE, Windows, Other, Novel, Unix, Ubuntu, None