Make window.kolibri object available to Hashi iframe context

packages/hashi/src/hashiBase.js

@@ -4,6 +4,10 @@ export const events = {
   IFRAMEREADY: 'iframeready',
   STATEUPDATE: 'stateupdate',
   USERDATAUPDATE: 'userdataupdate',
+  DATAREQUESTED: 'datarequested',
+  DATARETURNED: 'datareturned',
+  NAVIGATETO: 'navigateto',
+  CONTEXT: 'context',
 };
 
 export const nameSpace = 'hashi';

packages/hashi/src/iframeClient.js

@@ -3,6 +3,7 @@ import LocalStorage from './localStorage';
 import SessionStorage from './sessionStorage';
 import Cookie from './cookie';
 import SCORM from './SCORM';
+import Kolibri from './kolibri';
 import patchIndexedDB from './patchIndexedDB';
 import { events, nameSpace } from './hashiBase';
 
@@ -25,6 +26,8 @@ export default class SandboxEnvironment {
 
     this.cookie = new Cookie(this.mediator);
 
+    this.kolibri = new Kolibri(this.mediator);
+
     this.SCORM = new SCORM(this.mediator);
 
     // We initialize SCORM here, as the usual place for SCORM
@@ -66,6 +69,7 @@ export default class SandboxEnvironment {
         this.localStorage.iframeInitialize(this.iframe.contentWindow);
         this.sessionStorage.iframeInitialize(this.iframe.contentWindow);
         this.cookie.iframeInitialize(this.iframe.contentWindow);
+        this.kolibri.iframeInitialize(this.iframe.contentWindow);
         patchIndexedDB(this.contentNamespace, this.iframe.contentWindow);
       } catch (e) {
         console.log('Shimming storage APIs failed, data will not persist'); // eslint-disable-line no-console

packages/hashi/src/kolibri.js

@@ -0,0 +1,192 @@
+/**
+ * This class offers an API interface for interacting directly with the Kolibri app
+ * that the HTML5 app is embedded within
+ */
+import BaseShim from './baseShim';
+import Mediator from './mediator';
+import { events, nameSpace } from './hashiBase';
+
+/**
+ * Type definition for Language metadata
+ * @typedef {Object} Language
+ * @property {string} id - an IETF language tag
+ * @property {string} lang_code - the ISO 639‑1 language code
+ * @property {string} lang_subcode - the regional identifier
+ * @property {string} lang_name - the name of the language in that language
+ * @property {('ltr'|'rtl'|)} lang_direction - Direction of the language's script,
+ * top to bottom is not supported currently
+ */
+
+/**
+ * Type definition for ContentNode metadata
+ * @typedef {Object} ContentNode
+ * @property {string} id - unique id of the ContentNode
+ * @property {string} channel_id - unique channel_id of the channel that the ContentNode is in
+ * @property {string} content_id - identifier that is common across all instances of this resource
+ * @property {string} title - A title that summarizes this ContentNode for the user
+ * @property {string} description - detailed description of the ContentNode
+ * @property {string} author - author of the ContentNode
+ * @property {string} thumbnail_url - URL for the thumbnail for this ContentNode,
+ * this may be any valid URL format including base64 encoded or blob URL
+ * @property {boolean} available - Whether the ContentNode has all necessary files for rendering
+ * @property {boolean} coach_content - Whether the ContentNode is intended only for coach users
+ * @property {Language} lang - The primary language of the ContentNode
+ * @property {string} license_description - The description of the license, which may be localized
+ * @property {string} license_name - The human readable name of the license, localized
+ * @property {string} license_owner - The name of the person or organization that holds copyright
+ * @property {number} num_coach_contents - Number of coach contents that are descendants of this
+ * @property {string} parent - The unique id of the parent of this ContentNode
+ * @property {number} sort_order - The order of display for this node in its channel
+ * if depth recursion was not deep enough
+ */
+
+/**
+ * Type definition for pagination object
+ * @typedef {Object} PageResult
+ * @property {number} page - the page that this pagination object represents
+ * @property {number} pageSize - the page size for this pagination object
+ * @property {ContentNode[]} results - the array of ContentNodes for this page
+ */
+
+/**
+ * Type definition for Theme options
+ * properties TBD
+ * @typedef {Object} Theme
+ */
+
+/**
+ * Type definition for NavigationContext
+ * This can have arbitrary properties as defined
+ * by the navigating app that it uses to resume its state
+ * Should be able to be encoded down to <1600 characters using
+ * an encoding function something like 'encode context' above
+ * @typedef {Object} NavigationContext
+ * @property {string} node_id - The current node_id that is being displayed,
+ * custom apps should handle this as it may be used to
+ * generate links externally to jump to this state
+ */
+
+export default class Kolibri extends BaseShim {
+  constructor(mediator) {
+    super(mediator);
+    this.data = {};
+    this.nameSpace = 'kolibri';
+    this.mediator = new Mediator(window.parent);
+  }
+
+  encodeContext(context) {
+    return encodeURI(Object.entries(context).map(([k, v]) => `${k}:${v}`));
+  }
+
+  iframeInitialize(contentWindow) {
+    this.__setShimInterface();
+    Object.defineProperty(contentWindow, this.nameSpace, {
+      value: this.shim,
+      configurable: true,
+    });
+  }
+
+  __setShimInterface() {
+    const self = this;
+
+    class Shim {
+      /*
+       * Method to query contentnodes from Kolibri and return
+       * an array of matching metadata
+       * @param {Object} options - The different options to filter by
+       * @param {string=} options.parent - id of the parent node to filter by, or 'self'
+       * @param {string[]} options.ids - an array of ids to filter by
+       * @param {number} [options.page=1] - which page to return from the result set
+       * @param {number} [options.pageSize=50] - the page size for pagination
+       * @return {Promise<PageResult>} - a Promise that resolves to an array of ContentNodes
+       */
+      getContentByFilter(options) {
+        return self.mediator.sendMessageAwaitReply({
+          event: events.DATAREQUESTED,
+          data: { options, dataType: 'Collection' },
+          nameSpace,
+        });
+      }
+      /*
+       * Method to query a single contentnode from Kolibri and return
+       * a metadata object
+       * @param {string} id - id of the ContentNode
+       * @return {Promise<ContentNode>} - a Promise that resolves to a ContentNode
+       */
+      getContentById(id) {
+        return self.mediator.sendMessageAwaitReply({
+          event: events.DATAREQUESTED,
+          data: { id, dataType: 'Model' },
+          nameSpace,
+        });
+      }
+      /*
+       * Method to search for contentnodes on Kolibri and return
+       * an array of matching metadata
+       * @param {Object} options - The different options to search by
+       * @param {string=} options.keyword - search term for key word search
+       * @param {string=} options.under - id of topic to search under, or 'self'
+       * @param {number} [options.page=1] - which page to return from the result set
+       * @param {number} [options.pageSize=50] - the page size for pagination
+       * @return {Promise<PageResult>} - a Promise that resolves to an array of ContentNodes
+       */
+      searchContent() {}
+
+      /*
+       * Method to set a default theme for any content rendering initiated by this app
+       * @param {Theme} options - The different options for custom themeing
+       * @return {Promise} - a Promise that resolves when the theme has been applied
+       */
+      themeRenderer() {}
+
+      /*
+       * Method to allow navigation to or rendering of a specific node
+       * has optional parameter context that can update the URL for a custom context.
+       * When this is called for a resource node in the custom navigation context
+       * this will launch a renderer overlay to maintain the current state, and update the
+       * query parameters for the URL of the custom context to indicate the change
+       * If called for a topic in a custom context or outside of a custom context
+       * this will simply prompt navigation to that node in Kolibri.
+       * @param {string} nodeId - id of the parent node to navigate to
+       * @param {NavigationContext=} context - optional context describing the state update
+       * if node_id is missing from the context, it will be automatically filled in by this method
+       * @return {Promise} - a Promise that resolves when the navigation has completed
+       */
+      navigateTo(nodeId, context) {
+        return self.mediator.sendMessageAwaitReply({
+          event: events.NAVIGATETO,
+          data: { nodeId, context },
+          nameSpace,
+        });
+      }
+
+      /*
+       * Method to allow updating of stored state in the URL
+       * @param {NavigationContext} context - context describing the state update
+       * @return {Promise} - a Promise that resolves when the context has been updated
+       */
+      updateContext(context) {
+        return self.mediator.sendMessageAwaitReply({
+          event: events.CONTEXT,
+          data: { context },
+          nameSpace,
+        });
+      }
+
+      /*
+       * Method to request the current context state
+       * @return {Promise<NavigationContext>} - a Promise that resolves
+       * when the context has been updated
+       */
+      getContext() {
+        return self.mediator.sendMessageAwaitReply({
+          event: events.CONTEXT,
+          data: {},
+          nameSpace,
+        });
+      }
+    }
+    this.shim = new Shim();
+    return this.shim;
+  }
+}

packages/hashi/src/mainClient.js

@@ -3,6 +3,7 @@ import LocalStorage from './localStorage';
 import Cookie from './cookie';
 import SCORM from './SCORM';
 import { events, nameSpace } from './hashiBase';
+import Kolibri from './kolibri';
 
 /*
  * This is the main entry point for interacting with the Hashi library.
@@ -22,6 +23,7 @@ export default class MainClient {
       cookie: new Cookie(this.mediator),
       SCORM: new SCORM(this.mediator),
     };
+    this.kolibri = new Kolibri(this.mediator);
     this.now = now;
     this.ready = false;
     this.contentNamespace = null;
@@ -59,6 +61,29 @@ export default class MainClient {
       });
     });
     this.mediator.sendMessage({ nameSpace, event: events.READYCHECK, data: true });
+
+    // This group of functions and events is for the custom channels work
+    // They each fetch data from the kolibri database and return it to
+    // the iframe
+    this.on(this.events.DATAREQUESTED, message => {
+      if (message.dataType === 'Collection') {
+        this.__fetchContentCollection = this.kolibri.__fetchContentCollection;
+        this.__fetchContentCollection(message);
+      } else if (message.dataType === 'Model') {
+        this.__fetchContentModel = this.kolibri.__fetchContentModel;
+        this.kolibri.__fetchContentModel(message);
+      }
+    });
+
+    this.on(this.events.NAVIGATETO, message => {
+      this.__navigateTo = this.kolibri.__navigateTo;
+      this.__navigateTo(message);
+    });
+
+    this.on(this.events.CONTEXT, message => {
+      this.__getOrUpdateContext = this.kolibri.__na__getOrUpdateContextvigateTo;
+      this.__getOrUpdateContext(message);
+    });
   }
 
   updateData({ contentState, userData }) {
@@ -104,6 +129,7 @@ export default class MainClient {
       });
     });
   }
+
   get data() {
     const data = {};
     Object.keys(this.storage).forEach(key => {
@@ -114,6 +140,7 @@ export default class MainClient {
     });
     return data;
   }
+
   on(event, callback) {
     if (!Object.values(events).includes(event)) {
       throw ReferenceError(`${event} is not a valid event name for ${nameSpace}`);

packages/hashi/src/mediator.js

@@ -1,3 +1,5 @@
+import uuidv4 from 'uuid/v4';
+
 /*
  * This class manages all message listening and sending from the postMessage
  * layer. All interfaces that need to message via the postMessage layer should
@@ -50,6 +52,38 @@ class Mediator {
     this.remote.postMessage(message, '*');
   }
 
+  // a function to manage messages for kolibri.js,
+  // when most messages require a response, to minimize redundancy
+  sendMessageAwaitReply({ event, data, nameSpace }) {
+    return new Promise((resolve, reject) => {
+      const msgId = uuidv4();
+      function handler(message) {
+        if (message.message_id === msgId && message.type === 'response') {
+          this.removeMessageHandler({
+            nameSpace,
+            event: 'datareturned',
+            callback: handler,
+          });
+          if (message.status === 'success') {
+            console.log(message.data);
+            return resolve(message.data);
+          } else if (message.status === 'failure' && message.err) {
+            return reject(message.err);
+          }
+          // Otherwise something unspecified happened
+          return reject();
+        }
+      }
+      this.registerMessageHandler({
+        nameSpace,
+        event: 'datareturned',
+        callback: handler,
+      });
+      data.message_id = msgId;
+      this.sendMessage({ event, data, nameSpace });
+    });
+  }
+
   registerMessageHandler({ event, nameSpace, callback } = {}) {
     if (
       typeof callback !== 'function' ||