Javascript integration has been much improved in the upcoming release of Awesomium! You can now create global Javascript objects and manipulate them directly from C++, call Javascript functions with native C++ variables, and evaluate arbitrary Unicode strings of Javascript. What’s more, the workhorse of our Javascript/C++ integration, the JSValue class, has been extended to support Objects, Arrays, and Unicode Strings in addition to its existing support for Booleans, Standard Strings, Numbers, and Null!

Global Javascript Objects

In previous versions, you could manipulate the ‘Client’ object by setting properties and registering callbacks via WebView::setProperty and WebView::setCallback, respectively, and access it via Javascript as a global object. This concept has now been extended so that you can create as many global Javascript objects as you like per WebView—you’re no longer limited to working with a single ‘Client’ object. These objects are linked to the lifetime of the WebView so this feature is quite useful for specifying persistent data for each WebView.

Creating, manipulating, and accessing these objects is very simple in the new API. To create an object, simply call WebView::createObject with the name that you want the object to appear as in Javascript.

For example:

myWebView->createObject(L"MyObject");

The above would create a global Javascript object that you can access as “MyObject” from any web page loaded into your WebView. Note that WebView::createObject accepts a wide string (hence ‘L’, the wide string literal prefix).

Of course, creating objects alone isn’t very useful– to give the object some properties, you can use WebView::setObjectProperty:

myWebView->setObjectProperty(L"MyObject", L"name", "foobar");
myWebView->setObjectProperty(L"MyObject", L"color", "Blue");
myWebView->setObjectProperty(L"MyObject", L"level", 25);

You can set as many properties as you want, setting a property more than once will replace the previous value. Notice that the last parameter to setObjectProperty accepts a JSValue (more on that later).

Another nifty feature of these global Javascript objects is that you can bind C++ callbacks to them and invoke events from Javascript. For example:

myWebView->setObjectCallback(L"MyObject", L"myCallback");

The above code would add a new method, “myCallback”, to “MyObject” that, when called from any page via Javascript, will invoke WebViewListener::onCallback with the name of the object, the name of the callback, and the arguments passed, if any.

For example, say you made a button that calls “myCallback” with a single string argument (”hello!”) when clicked:

<input type="button" value="Click Me!"
    onclick="MyObject.myCallback('hello!')" />

You could then intercept this callback in WebViewListener::onCallback (you’ll need to register your WebViewListener first via WebView::setListener):

void MyListener::onCallback(const std::wstring& objectName, const
    std::wstring& callbackName, const Awesomium::JSArguments& args)
{
    if(objectName == L"MyObject" && callbackName == L"myCallback")
        std::wstring value = args[0].toString(); // value is 'hello!'
}

JSValue Improvements

The JSValue class has also undergone some major improvements with its new support for Objects, Arrays, and Unicode Strings. The JSValue class is used as an intermediary to translate C++ types into Javascript variables and vice-versa. To get a better understanding of how this relationship works, here’s how types are mapped between Javascript and C++ using JSValue:

JSValue Type: Unicode Strings

The support for wide strings was added as part of the initiative to improve Unicode support in Awesomium; almost every bit of relevant API now supports Unicode strings. This change also affects JSValue::toString, which now returns a wide string instead of a standard string.

JSValue Type: Objects

Support for passing Javascript Objects to/from C++ is one of the biggest new features in Awesomium v1.5. As specified in the table above, these Objects are modeled in C++ as a std::map with a string key and a JSValue for a value (typedef’d as JSValue::Object).

For example, say you had an object ‘Person’ in Javascript:

var Person = {
   name: 'Bob',
   age: 22,
};

You could then retrieve a copy of this object in C++:

JSValue myValue = myWebView->executeJavascriptWithResult("Person").get();

if(myValue.isObject())
{
   JSValue::Object person = myValue.getObject();

   std::wstring name = person[L"name"].toString(); // value is 'Bob'
   int age = person[L"age"].toInteger(); // value is '22'
}

JSValue Type: Arrays

JSValue also now supports Javascript Arrays! On the C++ side, Arrays are modeled as a std::vector of JSValues (typedef’d as JSValue::Array).

So, for example, if you had the following array in Javascript:

var myArray = [1, 2, "three", 4, "five"];

You could access it in C++ like so:

JSValue myValue = myWebView->executeJavascriptWithResult("myArray").get();

if(myValue.isArray())
{
   JSValue::Array myArray = myValue.getArray();

   int first = myArray[0].toInteger(); // value is '1'
   int second = myArray[1].toInteger();  // value is '2'
   std::wstring third = myArray[2].toString(); // value is 'three'
}

Compositions of JSValues

It is also worthy to note that JSValue is flexible enough to accommodate compositions of arrays, objects, and other types. It supports arrays of arrays, arrays of objects, objects with array values, and all other nested permutations along this line.

For example, say you wanted to create a JSValue that is functionally equivalent to the following Javascript Object:

var Player = {
   name: 'Rex',
   HP: 1000,
   items: ['Armor', 'Sword', 'Gauntlets'],
   stats: {
      strength: 57,
      defense: 90,
      dexterity: 24
   }
};

You could model this Object in C++ as so:

JSValue::Object player;

player[L"name"] = "Rex";
player[L"HP"] = 1000;

JSValue::Array items;
items.push_back("Armor");
items.push_back("Sword");
items.push_back("Gauntlets");

player[L"items"] = items;

JSValue::Object stats;
stats[L"strength"] = 57;
stats[L"defense"] = 90;
stats[L"dexterity"] = 24;

player[L"stats"] = stats;

Direct Calling of Javascript Functions

You can now call a Javascript function directly with JSValues as parameters!

The only way to emulate this behavior previously was to create several temporary properties using the ‘Client’ object for your parameters and then call your function with the referenced properties via WebView::executeJavascript. This cumbersome method has been deprecated in favor of the new “quick-path” WebView::callJavascriptFunction.

Say you had the following function in Javascript:

function addChatMessage(nickname, message) {
   chat = document.getElementById('chat');
   chat.innerText = nickname + ": " + message;
}

You can now call it directly from C++ like so:

JSArguments args;
args.push_back("Bob");
args.push_back("Hello world!");

myWebView->callJavascriptFunction(L"", L"addChatMessage", args);

Calling Functions Contained Within An Object

As you may have noticed above, I’ve specified an empty wide string (L”") as the first parameter of WebView::callJavascriptFunction. This is because the first parameter allows you to specify the Object that contains the function. In the above example, I’ve specified an empty string to indicate that this function is in the global scope (and thus is not contained within any object).

Here’s an example of how to call a function contained within an Object; say you had the following defined in Javascript:

var MusicBox = {
   currentTrack: '',
   isPlaying: false,
   play: function(track) {
      this.isPlaying = true;
      this.currentTrack = track;
      displayMsg = document.getElementById('display');
      displayMsg.innerText = "Now playing: " + this.currentTrack;
   }
};

You could call this function from C++ by the following:

JSArguments args;
args.push_back("Moonlight Sonata");

myWebView->callJavascriptFunction(L"MusicBox", L"play", args);

Conclusion

It is now easier than ever to pass data between Javascript and C++ using Awesomium v1.5. The new “Global Javascript Objects” feature simplifies the task of exposing data in your application to Javascript, JSValue’s new support for Array and Object types makes it a snap to share complex structures, and direct calling of Javascript functions with JSValue parameters is faster and easier to use than existing methods.

I hope you’ll enjoy some of these new enhancements to Awesomium! More features and details of the upcoming release will be announced soon, so stay tuned to this blog.