Merge pull request #12601 from keymanapp/refactor/web/12347-move-engi…

…ne-web-into-app-repo

refactor(web): move web engine help to app repo

resources/build/help-keyman-com.sh

@@ -90,6 +90,9 @@ function upload_keyman_help {
     mac)
       upload mac/docs/help products/mac/$VERSION_RELEASE
       ;;
+    web)
+      upload web/docs/engine developer/engine/web/$VERSION_RELEASE
+      ;;
     windows)
       # Note: `/windows/src/desktop/help/build.sh web` must be run first
       upload windows/bin/help/md/desktop products/windows/$VERSION_RELEASE
@@ -120,7 +123,7 @@ while [[ $# -gt 0 ]] ; do
       display_usage
       exit 0
       ;;
-    android | ios | linux | mac | windows | developer)
+    android | ios | linux | mac | windows | developer | web)
       platform=$key
       ;;
     *)

web/build.sh

@@ -14,6 +14,9 @@ THIS_SCRIPT="$(readlink -f "${BASH_SOURCE[0]}")"
 
 builder_set_child_base src
 builder_describe "Builds engine modules for Keyman Engine for Web (KMW)." \
+  \
+  "@/resources/tools/check-markdown  test:help" \
+  \
   "clean" \
   "configure" \
   "build" \
@@ -33,9 +36,11 @@ builder_describe "Builds engine modules for Keyman Engine for Web (KMW)." \
   ":engine/main              Builds all common code used by KMW's app/-level targets" \
   ":engine/osk               Builds the Web OSK module" \
   ":engine/predictive-text=src/engine/predictive-text/worker-main     Builds KMW's predictive text module" \
+  ":help                     Online documentation" \
   ":samples                  Builds all needed resources for the KMW sample-page set" \
   ":tools                    Builds engine-related development resources" \
   ":test-pages=src/test/manual   Builds resources needed for the KMW manual testing pages" \
+  ":_all                     (Meta build target used when targets are not specified)" \
   "--ci+                     Set to utilize CI-based test configurations & reporting."
 
 # Possible TODO?
@@ -182,11 +187,17 @@ builder_run_child_actions build:tools
 builder_run_child_actions build:test-pages
 
 # Build tests
-builder_run_action build build_action
+builder_run_action build:_all build_action
 
 # Run tests
-builder_run_child_actions test
-builder_run_action test test_action
+# builder_run_child_actions test
+builder_run_action test:_all test_action
+
+function do_test_help() {
+  check-markdown  "$KEYMAN_ROOT/web/docs/engine"
+}
+
+builder_run_action test:help do_test_help
 
 # Create coverage report
-builder_run_action coverage coverage_action
+builder_run_action coverage:_all coverage_action

web/docs/engine/guide/adding-keyboards.md

@@ -0,0 +1,59 @@
+---
+title: Adding Keyboards
+---
+
+There are multiple ways to add and install keyboards into your KeymanWeb installation.
+
+In the examples that follow, please note the use of variable `kmw` as shorthand for the `keyman` object.
+
+## Directly linking a local copy
+
+The most efficient way to utilize a keyboard is to obtain a local copy of it and place this copy in a static location on your website. Once this is done, it can be directly linked into KeymanWeb as follows.
+
+```c
+keyman.addKeyboards({
+    id:'us',                  // The keyboard's unique identification code.
+    name:'English',           // The keyboard's user-readable name.
+    language:{
+      id:'en',                // A BCP 47 code uniquely identifying the language.
+      name:'English (US)'     // The language's name.
+    },
+    filename:'./us-1.0.js'    // A valid path to the compiled *.js file representing the keyboard.
+});
+```
+Custom fonts may also be utilized via the `language.font` property. For example:
+
+```c
+font:{
+    family:'LaoWeb',
+    source:['../font/saysettha_web.ttf','../font/saysettha_web.woff','../font/saysettha_web.eot']
+}
+```
+
+## Requested from the CDN by language name
+
+To obtain the default Keyman keyboard for a given language, call the following function.
+
+```c
+keyman.addKeyboardsForLanguage('Dzongkha');
+```
+
+This example would find the default keyboard for the Dzongkha language. This method will fail if the name doesn't perfectly match any language found in the CDN's repository.
+
+Alternatively, languages may be looked up via their BCP 47 language code as follows:
+
+```c
+keyman.addKeyboards('@he')
+```
+
+The `@` prefix indicates the use of the BCP 47 language code, which in this case corresponds with Hebrew.
+
+## Requested from the CDN by keyboard name
+
+To obtain a specific keyboard by name or by keyboard name and language code as a pair, see the following:
+
+```c
+keyman.addKeyboards('french','european2@sv','european2@no')
+```
+
+This will install three keyboards - one for French (named, quite simply, "French") and two copies of the EuroLatin2 keyboard - one for Swedish and one for Norwegian.

web/docs/engine/guide/examples/__auto-control.html

@@ -0,0 +1,28 @@
+<html>
+<head>
+  <script src='https://s.keyman.com/kmw/engine/17.0.331/keymanweb.js'></script>
+  <script>var kmw = keyman;</script>
+
+  <script>
+    window.addEventListener('load', function () {
+      keyman.init().then(function() {
+        keyman.addKeyboards({
+          id:'laokeys',
+          name:'Lao (Phonetic)',
+          languages:{
+            id:'lo',
+            name:'Lao'
+          },
+          filename:'./js/laokeys.js'
+        });
+      });
+    });
+  </script>
+</head>
+<body>
+<form action='.' method='post'>
+<p><input type='text' id='multilingual' name='multilingual' size="40" /></p>
+<p><textarea cols='40' rows='5'></textarea></p>
+</form>
+</body>
+</html>

web/docs/engine/guide/examples/__control-by-control.html

@@ -0,0 +1,47 @@
+<html>
+<head>
+
+<script src='https://s.keyman.com/kmw/engine/17.0.331/keymanweb.js'></script>
+<script>var kmw = keyman;</script>
+<script src='https://s.keyman.com/kmw/engine/17.0.331/kmwuitoggle.js'></script>
+
+<script type='text/javascript' src='js/unified_loader.js'></script>
+
+<script type="text/javascript">
+  function SetupDocument() {
+    keyman.init({
+      root: './',  // Note - if drawing the latest version of KeymanWeb from the CDN, this will
+                   // default to the source folder on our servers.
+      ui: 'toggle',
+      resources: './'
+    }).then(function() {
+      // Load the keyboards of your choice here.
+      loadKeyboards();
+
+      /* Disable KeymanWeb interaction on the 'Email to' TEXT control */
+      keyman.disableControl(document.f.address);
+      /* Set the default keyboard for the 'Subject' TEXT control to 'off' (i.e. default browser keyboard) */
+      /* As KeymanWeb relies on the on-screen keyboard to change languages for touch-based devices, this will
+       * not work for them and will default to the first language added to KeymanWeb after initialization. */
+      keyman.setKeyboardForControl(document.f.subject, '', '');
+      /* Set the default keyboard for the 'Message body' TEXTAREA to the LaoKeys keyboard */
+      keyman.setKeyboardForControl(document.f.text, 'Keyboard_laokeys', 'lo');
+    });
+  }
+
+  window.addEventListener( 'load' , SetupDocument );
+</script>
+</head>
+<body>
+<form name='f' action='.' method='post'>
+
+<p>Email to <span class='note'>(KeymanWeb not enabled)</span><br /><input type='text' name='address' size="40" placeholder="id = address"/></p>
+
+<p>Subject <span class='note'>(Defaults to 'English' or 'off' unless on a touch-based device)</span><br /><input type='text' name='subject' size="40" placeholder="id = subject"/></p>
+
+<p>Message body <span class='note'>(Defaults to 'LaoKeys')</span><br /><textarea name='text' cols='40' rows='10' placeholder="id = text"></textarea></p>
+
+</form>
+
+</body>
+</html>

web/docs/engine/guide/examples/__first-example.html

@@ -0,0 +1,23 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>KeymanWeb - A First Example</title>
+
+  <!-- Start of Code -->
+  <script src='https://s.keyman.com/kmw/engine/17.0.331/keymanweb.js'></script>
+  <script>var kmw = keyman;</script>
+  <script src='https://s.keyman.com/kmw/engine/17.0.331/kmwuitoggle.js'></script>
+  <script>
+    (function() {
+      keyman.init({attachType:'auto'}).then(function() {
+        keyman.addKeyboards('@en'); // Loads default English keyboard from Keyman Cloud (CDN)
+        keyman.addKeyboards('@th'); // Loads default Thai keyboard from Keyman Cloud (CDN)
+      });
+    })(keyman);
+  </script>
+</head>
+<body>
+<p>Click me and type: <input placeholder="Hello World"/></p>
+</body>
+</html>

web/docs/engine/guide/examples/__full-manual-control.html

@@ -0,0 +1,55 @@
+<html>
+<head>
+
+<script src='https://s.keyman.com/kmw/engine/17.0.331/keymanweb.js'></script>
+<script>var kmw = keyman;</script>
+
+<script type='text/javascript' src='js/unified_loader.js'></script>
+<script type="text/javascript">
+
+var KWControl = null;
+
+function SetupDocument()
+{
+  keyman.init().then(function(){
+    // Load the keyboards of your choice here.
+    loadKeyboards();
+
+    KWControl = document.getElementById('KWControl');
+    var kbds = keyman.getKeyboards();
+    for(var kbd in kbds)
+    {
+      var opt = document.createElement('OPTION');
+      opt.value = kbds[kbd].InternalName + "$$" + kbds[kbd].LanguageCode;
+      opt.innerHTML = kbds[kbd].Name;
+      KWControl.appendChild(opt);
+    }
+    document.f.multilingual.focus();
+
+    keyman.setActiveKeyboard('', '');
+  });
+}
+
+function KWControlChange()
+{
+  var name = KWControl.value.substr(0, KWControl.value.indexOf("$$"));
+  var languageCode = KWControl.value.substr(KWControl.value.indexOf("$$") + 2);
+  keyman.setActiveKeyboard(name, languageCode);
+  document.f.multilingual.focus();
+}
+
+window.addEventListener( 'load' , SetupDocument );
+
+</script>
+</head>
+<body>
+
+<form name='f' action='.' method='post'>
+
+  <p>Keyboard: <select id='KWControl' onchange='KWControlChange()'><option value=''>English</option></select></p>
+
+<p><input type='text' id='multilingual' name='multilingual' size="40" placeholder="id='multilingual'"/></p>
+</form>
+
+</body>
+</html>

web/docs/engine/guide/examples/__manual-control.html

@@ -0,0 +1,45 @@
+<html>
+<head>
+  <script src='https://s.keyman.com/kmw/engine/17.0.331/keymanweb.js'></script>
+  <script>var kmw = keyman;</script>
+
+  <script type='text/javascript' src='js/laokeys_load.js'></script>
+
+  <script type="text/javascript">
+
+    var KWControl = null;
+
+    function SetupDocument()
+    {
+      keyman.init();
+      KWControl = document.getElementById('KWControl');
+      keyman.setActiveKeyboard('laokeys');
+      keyman.osk.hide();
+    }
+
+    function KWControlClick()
+    {
+      var KWControl = document.getElementById('KWControl');
+
+      if(keyman.osk.isEnabled()) {
+        keyman.osk.hide();
+      } else {
+        keyman.osk.show(true); // Specifies that the OSK should display whenever a valid control has focus, re-enabling the default behavior.
+      }
+    }
+
+    window.addEventListener('load', SetupDocument);
+  </script>
+</head>
+<body>
+
+<form action='.' method='post'>
+
+<p><img style="border: solid 1px black; padding: 2px 2px 3px 2px" src='js/kmicon.png' alt='KeymanWeb' onclick='KWControlClick()' id='KWControl' /></p>
+
+<p><input type='text' id='multilingual' name='multilingual' size="40" /></p>
+<p><textarea cols='40' rows='5'></textarea></p>
+
+</form>
+</body>
+</html>

web/docs/engine/guide/examples/automatic-control.md

@@ -0,0 +1,44 @@
+---
+title: Automatic Mode Example
+---
+
+This page shows how to include a local keyboard from an arbitrary location in your website's file structure.
+
+In this example, we use only the LaoKey keyboard. Please click [this link](./__auto-control.html) to open the test page.
+
+## Code Walkthrough
+
+```html
+<head>
+  <!-- Start of Code -->
+  <script src="js/keymanweb.js" type="text/javascript"></script>
+  <script>
+    window.addEventListener('load', function () {
+      keyman.init().then(function() {
+        keyman.addKeyboards({
+          id:'laokeys',
+          name:'Lao (Phonetic)',
+          languages:{
+            id:'lo',
+            name:'Lao'
+          },
+          filename:'./js/laokeys.js'
+        });
+      });
+    });
+  </script>
+  <!-- End of Code -->
+</head>
+```
+
+As you can see above, the second line in the code snippet above references the LaoKey keyboard loader JavaScript file. This is a small stub file, typically less than 200 bytes, that defines the name and actual location of the real keyboard file (in this case, **laokeys.js**). When a page may reference many keyboards, this saves downloading potentially hundreds of kilobytes of unused Javascript keyboards - the keyboard is downloaded when it is first selected by the user.
+
+## API References
+
+On initialization: [`keyman.init()`](../../reference/core/init).
+
+On including keyboards: [`keyman.addKeyboards()`](../../reference/core/addKeyboards).
+
+------------------------------------------------------------------------
+
+[On to Manual Control Example](manual-control)