HTML5 opens up some great opportunities for developers and one of those is plugin development using JavaScript.
While most Corona developers will only use Lua in a cross-platform manner like they are currently using, it’s super easy to add JavaScript features to extend your app.
You need two things: a .lua file that tests to see if your platform is HTML5 or some other platform and the actual JavaScript .js file. If you detect you are an HTML5 build, then you require the JavaScript plugin, else provide default functions that prevent those calls from creating errors for the non-HTML5 builds. Consider this code:
-- -- myplugin.lua -- Copyright (c) 2018 Corona Labs Inc. All rights reserved. -- local lib local platform = system.getInfo("platform") if platform == 'html5' then -- use native JS plugin lib = require("myplugin\_js") else -- wrapper for non web platforms local CoronaLibrary = require "CoronaLibrary" -- Create stub library for simulator lib = CoronaLibrary:new{ name='myplugin', publisherId='com.mydomainname' } -- Default implementations local function defaultFunction() print( "WARNING: The '" .. lib.name .. "' library is not available on this platform." ) end lib.set = defaultFunction lib.get = defaultFunction lib.addEventListener = defaultFunction end -- Return an instance return lib
If you’re on HTML5, it includes the JavaScript plugin. If not, it simply lets the app know the function isn’t available.
Plugins have to have a unique namespace and that’s accomplished by this line in the .lua file:
lib = CoronaLibrary:new{ name='myplugin', publisherId='com.mydomainname' }
Obviously if you intended to publish this to the Corona Marketplace, or if you want to use multiple plugins in your code, the name needs to be unique. Change “myplugin” to a proper name. Then set publisherId to the reverse domain name you use to publish with. For instance, Corona Labs made plugins would have a publisherId of “com.coronalabs“.
Then you create a plugin with the same name except with an _js as part of the name. For instance if your plugin is “awesometimer.lua“, you would create “awesometimer_js.js“. This file will contain your JavaScript code. Here is an example:
// // myplugin\_js.js // Copyright (c) 2018 Corona Labs Inc. All rights reserved. // // JS plugin is an child object of 'window' window.myplugin\_js = { // all the 1st-level functions are available to call from Lua // so 'get' and 'set' functions are available to call from Lua data:{}, // function may use up to 10 args; use Object or Array if you want to pass more than 10 args // arg maybe a Number, String, Boolean, Array or Object set: function(bool\_arg, number\_arg, string\_arg, table\_arg, array\_arg) { console.log('js set() is called'); var data = window.myplugin\_js.data; data.bool\_arg = bool\_arg; data.number\_arg = number\_arg; data.string\_arg = string\_arg; data.table\_arg = table\_arg; data.array\_arg = array\_arg; // Lua callback // you can pass to Lua a Number, String, Boolean, Array or Object args this.dispatchEvent({ name: 'onData', data: { arg1: bool\_arg, arg2: number\_arg, arg3: string\_arg, arg4: table\_arg, arg5: array\_arg }}) console.log(typeof(bool\_arg)); console.log(typeof(number\_arg)); console.log(typeof(string\_arg)); console.log(typeof(table\_arg)); console.log(typeof(array\_arg), array\_arg.length); }, get: function() { var data = window.myplugin\_js.data; console.log('js get() is called', data); return data; } }; console.log('myplugin\_js is loaded');
We of course can’t teach you JavaScript in this tutorial and there are plenty of examples on the Internet to see. The main point is that you add your plugin to the JavaScript window object, provide your functions as part of the plugin namespace and add your methods to your plugin object.
Then in your .lua modules, i.e. main.lua, you can require the plugin and call the functions as necessary.
-- -- main.lua -- Copyright (c) 2018 Corona Labs Inc. All rights reserved. -- -- A sample of using JS native plugin for Corona local widget = require( "widget" ) local json = require( "json" ) local myplugin = require("myplugin") local label = display.newText( "output", 50, 220, native.systemFont, 16 ) label.x = display.contentCenterX local data = native.newTextBox(160, 360, 320, 250) data.isEditable = false -- JS event listener. local function pluginListener( event ) local str = json.prettify(event) str = 'got event from JS plugin:n' .. str print(str) data.text = str end local setData = function() -- call JS native plugin -- arg value maybe boolean, number, string, table -- local bool\_arg = true local number\_arg = 123 local string\_arg = 'abc' local table\_arg = {key1='key1value', key2={1,2,3}} local array\_arg = {1,2,3,4,5,6,7} myplugin.set(bool\_arg, number\_arg, string\_arg, table\_arg, array\_arg) end local getData = function() -- call JS native plugin local tbl = myplugin.get() if tbl then local str = json.prettify(tbl) -- Important: use index-debug.html if you want to see print output print('Data: ', str) data.text = str end end -- event listener, it's an option myplugin.addEventListener(pluginListener) widget.newButton { onRelease = setData, left=60, top=60, width=200, height=50, label = "Save Data in JS", labelColor = { default={ 1, 1, 1 }, over={ 0.6, 0.6, 0.6 } } } widget.newButton { onRelease = getData, left=60, top=120, width=200, height=50, label = "Read Saved Data", labelColor = { default={ 1, 1, 1 }, over={ 0.6, 0.6, 0.6 } } } --
This example shows you how to call functions to get data, set data as well as dispatch events from JavaScript back to your Lua code.
You can download the complete sample project from our GitHub repository. If you have questions please reach out on our HTML5 forum!