Using JavaScript in HTML5 Builds

Making a dummy wrapper for Simulator

It can be bothersome to develop plugins that are getting errors all the time since JS code doesn’t work in simulator. For that purpose we recommend making a Lua wrapper. It should check if JavaScript can be executed, and do so if possible.

For that you would create two files: demo_plugin.lua:

if system.getInfo("platform") == 'html5' then
    return require "demo_plugin_js"
else
    local lib = {}
    setmetatable( lib, {__index = function( t, k )
        return function() 
            print( "WARNING: Placeholder is called for " .. k )
        end
    end} )
    return lib
end

This simple Lua wrapper would return a dummy function for all requests, unless it is running on html5 platform. In that case, it would return real plugin contained in demo_plugin_js.js file:

demo_plugin_js = {
    init: function() { 
        console.log( "Init was called" );
    }
}

Note that module’s object has to be renamed to demo_plugin_js as well.

Passing functions to JavaScript

We have already seen that it is very straightforward to call JavaScript functions from Lua. But it is often required to do the reverse - invoke a callback to Lua when some JavaScript async operations is finished. This is tricky, since JavaScript doesn’t provide any mechanisms to interact with its garbage collector. Simpler, value types like strings, numbers or event tables can be copied between Lua and JavaScript, so memory leaks are not a problem because copies are handled separately on each side. Functions on other hand, must maintain connection to their environment in order to perform expected tasks. Nevertheless, Solar2D provides two ways that allow Lua functions can be passed to Javascript:

local function callbackFunction( message )
    print( message )
end
local demo = require "demo_plugin"
demo.callback = callbackFunction
demo.execute()

demo_plugin_js = {
    execute: function() { 
        this.callback( "Hello World" );
    }
}

local function callbackFunction( message )
    print( message )
end
local demo = require "demo_plugin"
demo.execute( callbackFunction )

demo_plugin_js = {
    execute: function( callbackReference ) {
        if( LuaIsFunction( callbackReference ) ) {
            var f = LuaCreateFunction( callbackReference );
            f( "Hello World" );
            LuaReleaseFunction( f );
        }
    }
}

demo_plugin_js = {
    execute: function( callbackReference ) {
        if( LuaIsFunction( callbackReference ) ) {
            var f = LuaCreateFunction( callbackReference );
            setTimeout( function() {
                f( "Hello World" );
                LuaReleaseFunction( f );
            }, 1000 )
        }
    }
}

init()

Function init() is most interesting. It has 2 parts. First - it remembers callback to dispatch events to:

        LuaReleaseFunction( this.callback );
        if ( LuaIsFunction( callback ) ) {
            this.callback = LuaCreateFunction( callback );
        } else {
            this.callback = function(){};
        }

The first line releases an existing callback if there is one. Then it creates new callback from reference and assigns it to a callback property. If the new callback is not set, we just use empty function as a callback to prevent runtime errors and excessive checks.

Second part:

        if ( this.init_internal ) {
            this.init_internal();
            this.init_internal = null;
        }

It calls the method init_internal then sets it to null so it won’t be called again. This is simple way to make sure init_internal is called only once.

init_internal()

VK Direct Games is a third party integration. We have to use an external JavaScript library to use it. The library loaded and initialized in init_internal() method. Lets take a look:

    init_internal: function()
    {
        var script = document.createElement('script');
        script.setAttribute('src', 'https://vk.com/js/api/mobile_sdk.js');
        script.setAttribute('type', 'text/javascript');
        script.setAttribute('charset', 'utf-8');

        script.onerror = function()
        {
            // ...
        };

        script.onload = function()
        {
            // ... initOK = ... initFail = ...
            VK.init(initOK, initFail, '5.60');
        };
        document.head.appendChild(script);
    }

In this code, we programmatically create a <script/> element and attach it to our HTML page. We also set onerror and onload handlers where we dispatch messages. Also, we call VK.init when the script is loaded to initialize VK APIs. Check out original code for more details.