JKO Content Development Kit

Transcription

1 Handset Developer Guide Version 2.1 JKO Content Development Kit JKO Content Development Kit JKO Content Development Kit JKO Content Development Kit 12 November %20library%2F8%2E0%20Corporate%20functions%2F8%2E01%20Business%20development %20library%2F8%2E0%20Corporate%20functions%2F8%2E01%20Business%20development

2 Revision history Author Version Date Comments Ben Smith Feb Pre- release draft for review by course authors. Ben Smith Mar Changes from version 0.1: Changed document styling to JKO format. Fixed typos. Removed references to checklist resource- type. This resource will not be used in the JKO CDK. Ben Smith Mar Changes from version 0.2: Added section on reserved native storage keys and the sync() method with the m- Learning Suite. Added initialize() and terminate() methods. Revised some drafting for clarity. Ben Smith Apr Changes from version 0.3: Updated for clarity and fixed typos. Added detail on API method callbacks. Ben Smith May Changes from version 1.0: Amended name to Developer Guide. Revised mandatory JavaScript includes. Added methods to support native plugins. Revised drafting for clarity. Ben Smith Nov Changes from version 2.0: Revised mandatory JavaScript includes to address compatibility issues with test environments.

3 Prepared By Ben Smith Tribal Group, Lincoln House, The Paddocks, 347 Cherry Hinton Road, Cambridge CB1 8DH UK T: F:

4 Contents 1. Background JavaScript Handset API Prerequisites API Methods Native Storage (setvalue / getvalue) Native Storage Reserved Keys Opening Menu Items (openmenuitem) Opening Resources (openresource) Getting / Setting Device Settings Getting Information About The User (getuserusername) Getting Information About The Device Custom Tracking (track) Synchronizing Data (sync) Recording User Time (initialize / terminate) Retrieving the file- system path of the current package (getcurrentcourselocalpathroot) Initializing and clearing a temporary folder for the currently opened course Extending the API Example Callbacks No Value Returned Value Returned Example HTML Resource JavaScript Resources Example API Calls... 12

5 1. Background The JKO Mobile Learning Application provides a framework on which content developers can create multi- platform content for use by the JKO community. Content developers can provide learning content to users in two ways: Static resources such as video or ebooks are displayed to the user and consumed without interaction. For these resources a user s entry to and exit from the content is recorded by the JKO application, but no interaction is possible with the content directly. Interactive Resources such as HTML offer elements on pages for users to interact with and / or can include JavaScript written by the content author that manipulates, tracks or extend the content. Content developers can also interact directly with the JKO application via the handset API. Content developers may if they wish use third- party JavaScript frameworks such as jquery Mobile or Sencha Touch to develop enhanced interactivity features. These operate well with the JKO app and can be included in packages (referenced from HTML resources).

6 2. JavaScript Handset API 2.1. Prerequisites Content utilizing the API methods in this document should be created in HTML form and packaged as an HTML resource. Each HTML document must including the following scripts in the document head to enable the API and for correct operation of user activity tracking: <script type="text/javascript" charset="utf-8"> function getmlearningpath(){var IS_ANDROID=(navigator.appVersion.indexOf("Android")!=- 1);var IS_IOS=(navigator.userAgent.indexOf("iPhone")!=- 1 navigator.useragent.indexof("ipod")!=- 1 navigator.appversion.indexof("ipad")!=-1);var href=window.location.href;href=href.split("#")[0];var courses=null;if(is_android){var regex="([a-za-z]+(.)){2}[a- Za-z]+/courses";var match=href.match(regex);if(match!=null&&match.length>0){cou rses=match[0]}else{courses="android_asset"}}else{if(is_ios) {courses="documents/packages/downloads"}else{return}}var pos=href.indexof(courses)+courses.length;var base=href.substring(0,pos);var path=href.substring(pos+1);path=path.split("/");base=base+" /"+path[0]+"/";return base}(function(){if(typeof(phonegap)!="undefined"){return}v ar path=getmlearningpath();var os=(navigator.appversion.indexof("android")!=- 1)?"android":"ios";document.write('<script src="'+path+"phonegap-"+os+' js" type="text/javascript" charset="utf- 8"><\/script>');document.write('<script src="'+path+'framework.min.js" type="text/javascript" charset="utf-8"><\/script>')})(); </script>

7 It is not necessary to include the files referenced in this code within a package they are provided automatically by the application API Methods API methods for the JKO application are provided via a PhoneGap plugin clientplugin. Calls are made using the syntax: window.plugins.clientplugin.method(parameters) Native Storage (setvalue / getvalue) Native storage offers a way to store data that can be accessed by the JKO application or from a native- code plugin to the application. Typically it is used to store data that requires synchronization with the m- Learning Suite via a set of reserved keys. For routine storage of data where no access by native code is required - JavaScript variables (for use within a single page) or HTML5 DB (flexible SQL- based storage that persists between pages) is recommended. These techniques do not require the Handset API. Using native storage, data can be stored in two contexts as key / value pairs: Global Data in this store can be read / written- to by any resource in any package. Content- specific Data in this store is available only to the current resource in the current package. The same key- name may be in- use by other resources, but the values are unrelated. Two methods are provided: clientplugin.setvalue(type, key, value, callback) Stores values. clientplugin.getvalue(type, key, callback) Retrieves values. type - The type of the native storage: MFStoreType.GLOBAL For global storage. MFStoreType.SPECIFIC - For resource- specific storage. key - The key name. value - The value to be stored.

8 callback - The callback function to confirm the operation: For setvalue: A callback is optional. If a function is provided it will be called on completion without any parameters. For getvalue: A callback is required. The function provided will be called on completion with the retrieved value as the only parameter Native Storage Reserved Keys The following key names are reserved in the specified storage- type for special purposes: Content developer s access to keys is noted in squared brackets and Sync indicates the value will be copied to the m- Learning Suite when the user leaves the resource or the sync() method is called. cmi.completion_status in MFStoreType.SPECIFIC [read, write and sync] Records the user s progress for the current resource as a string. Values can be as follows (other values can be used but will not be interpreted by the m- Learning Suite): completed incomplete not attempted unknown cmi.success_status in MFStoreType.SPECIFIC [read, write and sync] Records whether the user has mastered the content in the resource as a string. Values can be as follows (other values can be used but will not be interpreted by the m- Learning Suite): passed failed unknown cmi.total_time in MFStoreType.SPECIFIC [read and sync] Records the accumulated time in milliseconds (as an integer) spent by the user on this resource. Time is accumulated from when the user opens the current resource (or from the last call to the initialize() method). The value is updated to include the current session s duration when the user leaves the resource or when a call to the terminate() method is made. cmi.suspend_data in MFStoreType.SPECIFIC [read and write] Provides a store for data to be persisted between sessions as a string. Provided for legacy compatibility with the SCORM standard use of HTML5 DB is recommended for persistent local storage for newly- developed packages.

9 Opening Menu Items (openmenuitem) Content developers can provide links to a menu from within HTML resources via JavaScript. The menu called can be contained in the current package or another package, but is referenced with its full name in both cases. The following method is provided: clientplugin.openmenuitem(menuitemid, callback) Opens the specified menu. menuitemid - The full ID of the menu as named in the package s package.xml file, starting with the package ID. For example: example.gettingstarted.faq the menu faq within the menu gettingstarted within the package example. callback (optional) - The function specified will be called on completion without any parameters Opening Resources (openresource) Content developers can provide links to a resource from within HTML resources via JavaScript. The resource called can be contained in the current package or another package, but is referenced with its full name in both cases. The following method is provided: clientplugin.openresource(resourceid, callback) Opens the specified resource. resourceid - The full ID of the resource as named in the package s package.xml file, starting with the package ID. For example: example.welcome_page_html the resource welcome_page_html within the package example. callback (optional) - The function specified will be called on completion without any parameters.

10 Getting / Setting Device Settings This section is included as a place- holder. This feature is not currently supported in the JKO Mobile Learning Applications Getting Information About The User (getuserusername) Content developers can retrieve the name of the current user via JavaScript. The following method is provided: clientplugin.getuserusername(callback) Retrieves the current user username. callback - The method specified will be called on completion with one parameter containing the user s PIN Getting Information About The Device At this release retrieving device information is not supported Custom Tracking (track) To augment the data stored automatically as a user accesses resources, content developers can pass additional data to the m- Learning Suite. Typically this method will be bound to an element within an HTML resource to record its state. The following method is provided: clientplugin.track(info, callback) Stores any value. info The value to be stored. String. callback (optional) - The method specified will be called on completion without any parameters.

11 Synchronizing Data (sync) All data to be synchronized to the m- Learning Suite are placed in the native storage keys defined in section When operating online synchronization occurs at the frequency defined in the device settings and each time a user leaves a package. When operating offline data are retained until network connectivity is re- established (whilst offline downloaded packages continue to function). A content developer may also force a device synchronization from within a resource. The following method is provided: clientplugin.sync(callback) Forces a synchronization with the m- learning suite. callback (optional) - The method specified will be called on completion without any parameters Recording User Time (initialize / terminate) The time spent by a user accessing a resource is automatically tracked on entry and exit. However, where a resource contains material that is not learning content (such as usage instructions or custom menus) content developers may wish to start and stop the timer programmatically. Two methods are provided: clientplugin.initialize(callback) Resets the current session s usage time to zero. Re- starts the timer if has previously been stopped. clientplugin.terminate(callback) Stops the timer (if it is running) and adds the current session s usage time to the cumulative total stored in the cmi.total_time key in MFStoreType.SPECIFIC native storage. callback (optional) - The method specified will be called on completion without any parameters Retrieving the file- system path of the current package (getcurrentcourselocalpathroot) This method provides support for content developers utilizing native plug- ins.

12 When using a native plug- in it may be necessary to directly access the file- system of a package. To do this a method is provided to return the full path to the root folder of the current package. The following method is provided: clientplugin.getcurrentcourselocalpathroot (callback, errorcallback) Returns the path to the root of the current package. callback - The method specified will be called on completion and will return a JSON object with the following parameters: courseid The name of the course localpathroot The full local path to the root folder of the course errorcallback - The method specified will be called if an error occurs and will return a JSON object with the following parameters: error An error string to determine why the error occurred The path will be presented differently between ios and Android, due to the file- system, differences between the two platforms: For Android, the path returned will follow this structure: /mnt/sdcard/android/data/com.tribal.jko/ courses/{uniquefolderhashid} For ios, the path returned will follow this structure: /Documents/Packages/Downloads/{uniqueFolderHashId} Initializing and clearing a temporary folder for the currently opened course This method provides support for content developers utilizing native plug- ins. When using a native plug- in it may be necessary to create and remove temporary files. To do this a dedicated location is provided for each package. Two methods are provided for this purpose:

13 clientplugin.initializecurrentcourselocaltempfolder(callback, errorcallback) Creates (or resets if already in existence) a temporary file store location for the current package. clientplugin.clearcurrentcourselocaltempfolder(callback, errorcallback) Removes the temporary file store location for the current package. callback (for initialize method) - The method specified will be called on completion and will return a JSON object with the following parameters: tempfolderpath The full local path to the temporary folder callback (for clear method) - The method specified will be called on completion and will not return any parameters. errorcallback - The method specified will be called if an error occurs and will return a JSON object with the following parameters: error An error string to determine why the error occurred 2.3. Extending the API The JKO app uses the PhoneGap framework to provide a multi- platform JavaScript environment, including the API methods described in this document. Content developers may extend their content using any part of the PhoneGap API (version 1.3.0). Full documentation of the standard is at: Notes: Only methods described in this document will be supported by Tribal, but content developers with the technical capability to use the wider framework are welcome to. Where a JKO- provided method offers the same functionality as a PhoneGap method content developers should use the JKO version as this will be supported and may be customized for the JKO environment Example Callbacks No Value Returned window.plugins.clientplugin.openmenuitem( menuitemid, function() {

14 }); alert( Open menu item was invoked. ); Value Returned window.plugins.clientplugin.getuserusername( function(pin) { alert( The current user s PIN is + pin); });

15 3. Content Development 3.1. Video The following format is recommended for any video for content for Mobile Learning Application conten: Video Codec: H.264 File format: MP4 (with.mp4 extension) Audio codec: AAC Web optimized: on Modulus: 16 Size: 480x272 pixels Average Bitrate: 960 kbps The free application Handbrake is recommended as a tool capable of converting other media- types to this format. It is available from: Video in HTML Resources Due to inconsistencies in support and user experience between devices and platforms the following approach to including video in HTML is recommended: Link directly to files in MP4 format (with.mp4 extensions) using normal HTML links: <a href= a-video-file.mp4 >Watch this video</a> To provide a preview thumbnail place the link around an image: <a href= a-video-file.mp4 > <img src= video-thumbnail.jpg /></a> Style thumbnail images with an appropriate visual cue such as a play icon. Design content so that video content does not require surrounding content (such as instructions, transcriptions or questions) whilst the user is watching the video. When a link to an MP4 video linked in this way is followed, the application passes it to the device s native video player to provide the best playback experience.

16 4. Example Resources 4.1. JavaScript Resources The following example HTML shows the required JavaScript references in the document header. <!DOCTYPE html> <html> <head> <script src="phonegap.js" type="text/javascript" charset="utf-8"></script> <script type="text/javascript"> addphonegapfile( );</script> <script src="app.js" type="text/javascript" charset="utf-8"></script> </head> <body></body> </html> 4.2. Example API Calls The following HTML shows links providing sample calls to a range of API methods. Dummy data is used and a null object is passed for callbacks as they are not used in this case. <a href="javascript:;" onclick="window.plugins.clientplugin.openmenuitem('module1. training', null);">openmenuitem</a> <a href="javascript:;" onclick="window.plugins.clientplugin.openresource('module1. training.introduction', null);">openresource</a> <a href="javascript:;" onclick="window.plugins.clientplugin.setvalue(mfstoretype.g LOBAL, 'globalsetting', 'somevalue', null);">setvalue (global)</a>

17 <a href="javascript:;" onclick="window.plugins.clientplugin.setvalue(mfstoretype.s PECIFIC, 'lastaccessedsection', 'demographicentry', null);">setvalue (specific)</a> <a href="javascript:;" onclick="window.plugins.clientplugin.getuserusername(null); ">getuserusername</a> <a href="javascript:;" onclick="window.plugins.clientplugin.sync(null);">sync</a> <a href="javascript:;" onclick="window.plugins.clientplugin.track('additional tracking info', null);">track</a> <a href="javascript:;" onclick="window.plugins.clientplugin.getuserusername(null); ">getuserusername</a>