Keyboard mapping - Part 1

As of version 3.0.6. we added improved keyboard mapping system to support different languages and keyboard layouts. This is important for languages which uses two scripts like Hebrew and English.

Browsers can't change OS input language when changing input from LTR to RTL, so we have to create our own key mapping system. Web terminal depend on those mappings. For example, all Hebrew chars will be mapped to English if you have Hebrew keyboard layout and typing in LTR mode.

One of technical issues to support various language modes are different keyboard layouts for laptop and desktop computer. This can cause invalid characters to show up.

Even we have support for most common used layouts, we can't support all of them as it will make a large overhead to web terminal. Instead, it is easy to create custom mappings.

Here we will show you how to do it.

1. Prepare OS to support two keyboard layouts. For example, Hebrew and English.

2. Open web terminal and browser console where we will type few instructions to start/stop key recording.

3. When recording is started to record keys follow the steps:

   • type all keyboard keys which produce characters
   • then repeat the step with shift key pressed
   • and finally stop recording
   • switch to another keyboard layout and repeat step 3.

   // start recording with english layout
   Tn5250.KeyMap.record();
   
   // press all character keys with 
   // and withouth shift pressed
   
   //stop recording
   var eng = Tn5250.KeyMap.record();
   
   // start recording with hebrew layout
   Tn5250.KeyMap.record();
   
   // press all character keys with 
   // and withouth shift pressed
   
   //stop recording
   Tn5250.KeyMap.record();
   var heb = Tn5250.KeyMap.record();
   

4. Set new layout to web terminal and test if all keys are working as it should

   // save recorded layout
   Tn5250.KeyMap.setMap('eng', eng);
   Tn5250.KeyMap.setMap('heb', heb);
   
   //map layouts to terminal codepage
   Tn5250.KeyMap.setMap('424', {rtl:'heb', ltr:'eng', isRTL:true});
   

5. Convert recorded data into JSON for later reuse

   JSON.stringify(eng);
   JSON.stringify(heb);
   

6. Open web terminal admin console customization screen. Add following code to the footer tab. This code will initialize new keyboard layout on web terminal startup.

   For example, if you want to add custom mapping to different branches create HOST configurations with different UUID. Use that UUID to differentiate between setups. Active codepage can also be used to setup different mappings instead of UUID.

   To add RTL support for specific language to other code pages which does not require RLT by default can be done with following example.

   // Add Hebrew to Multilingual Central European Codepage
   Tn5250.KeyMap.setMap('870', {ltr:null, rtl:'heb', isRTL:true});
   

   Final Example...

   <script>
   $(window).on('greenscreens', function(){
       var cfg = Tn5250.Application.getConfig();
       if (cfg.uuid === 'IL') {
           var heb = {}; // data from step 5.
           var eng = {}; // data from step 5.
           Tn5250.KeyMap.setMap('eng', eng);
           Tn5250.KeyMap.setMap('heb', heb);
           Tn5250.KeyMap.setMap('424', {rtl:'heb', ltr:'eng', isRTL:true});        
       }
       if (cfg.uuid === 'HR') {
           Tn5250.KeyMap.setMap('870', {ltr:null, rtl:'heb', isRTL:true});
       }
       
       // check current web terminal codepage
       if (Tn5250.KeyMap.getCodePage() === '420') {
          // add arabic mapping
       }
   });
   </script>
   

Remote load

If mapping does not exist for specific codepage, we added feature to save keymapping into a file in [USER]/io.greenscreens/etl/data to be loaded by web terminal.

For example, create 900.json file in [USER]/io.greenscreens/etl/data and save mapping created in step 5. Web terminal will load 900.json character mapping file if your host configuration is set to code page 900.

To forcibly load custom mapping use Tn5250.KeyMap.load('900').

Conclusion

Keyboard mapping engine is simple to use and increase already great customization capabilities to our web terminal. Every company IT administration department now can easily create custom mappings. This comes in handy very much especially to companies which operates in multiple countries and need to add custom support for different departments or branches.