top

Using the Message Template Generator

This guide shows how to easily create messages for JavaScript - NaCl communication using the Message Template Generator which is provided in the Tizen Studio.

Every NaCl application needs to provide communication routines between its JavaScript and NaCl parts. Normally this is done by writing functions containing the proper communication logic. On the JavaScript side, the code utilizes the JavaScript messaging API. On the NaCl side, it is necessary call the PostMessage() method for sending messages and override the HandleMessage() method for receiving. While it’s perfectly valid to write this logic by hand, the Tizen Studio provides a tool that automatically generates and inserts stubs for messaging functions. That way, the developer is left with the task of implementing the functions’ logic and does not need to worry about registering handlers and making typos while referring to message properties.

Note

For details on implementing messages in NaCl modules, please consult the following resources:

  1. The guide to the NaCl messaging system
  2. pp::Instance class reference
  3. pp::MessageHandler class reference

The Message template generator can be run on any existing NaCl project. In order to invoke it select “NaCl Development" -> "Add messages” from the the main Smart TV IDE menu bar:


If any resource belonging to a NaCl project has been selected in the “Project Explorer” view or a file from a NaCl project is opened in the currently active editor page, the “NaCl module source code file” and “JavaScript file” fields will be automatically filled. These fields hold the paths to the source files that will be modified by the message generation process. The paths can be changed by clicking the respective “Browse” buttons. The source code language should be automatically detected based on the NaCl module’s file extension, however it may be changed manually if needed.

In the “NaCl module name” field the name of the current NaCl module should be entered. This must correspond to the id attribute of the <embed> element that holds the NaCl module.

For example, in the “Empty Project” template, the <embed> tag is created in the createNaclModule() function in the common.js file:

var nacl_elem = document.createElement("embed");
nacl_elem.setAttribute("name", "nacl_module");
nacl_elem.setAttribute("id", "nacl_module");
nacl_elem.setAttribute("type", "application/x-nacl");
nacl_elem.setAttribute("src", nmf_path_name);
nacl_elem.setAttribute("width", width);
nacl_elem.setAttribute("height", height);

var listenerDiv = document.getElementById("listener");
listenerDiv.appendChild(nacl_elem);

Here, the <embed> element is created within a <div> element that has the id='listener' attribute. The newly created element will have the id='nacl_module'attribute. The above is roughly equivalent to the following plain HTML content:

<div id="listener">
  <embed name="nacl_module" id="nacl_module" type="application/x-nacl" src="path/to/nmf" width="800" height="600" />
</div>

The default name for the NaCl module is is “nacl_module”, which matches the source code generated by the NaCl project wizard.

Important

If, for any reason, you have changed the id attribute of the NaCl module's `` element, remember to change the "*NaCl module name*" accordingly. If not, the generated code will not work.

The main part of the “Add messages” dialog window is a list of messages for which code will be generated. To add and define a new message, click the “Add” button. Defined messages can be deleted by selecting them and clicking the “Delete” button.

After the “Add” button is clicked, a new dialog window appears:

The “Message properties” window is used for defining new messages. The name of the message is mandatory and it is set in the “Message name” field. The message name must be unique among all defined messages. In the “From” drop down list select the end point, from which the message is to be sent: either the NaCl module or the JavaScript code.

The “Message parameters” list can be empty, although it is quite unusual to send empty messages. To add a new parameter, fill the “Parameter name", "Parameter type” and, optionally, “Parameter description” fields, then click the “Add” button:

The newly created parameter will be added to the “Message parameters” list. The “Parameter name”, “Parameter type” and “Parameter description” fields retain their values after the parameter addition to ease adding several parameters similar to each other.
To edit a parameter, select it on the “Message parameters” list. Its values will be visible in the “Parameter name”, “Parameter type” and “Parameter description” fields. Then change the needed values and click the “Update” button.
To delete a parameter, select it on the “Message parameters” list and click the “Delete” button.
After all the parameters are properly set, click the “OK” button to confirm the message definition. The newly created message appears on the “Messages” list of the “Add messages” dialog:

After all needed messages are added click the “Generate” button to generate the source code. If the generation succeeds the “Add messages” window will close and an informational message will appear:

If the generation fails an error message will appear and the “Add messages” window will remain open.

The generated code contains fragments responsible for:

  1. Handling received messages on NaCl and JavaScript side: for each message a function HandleMessage_<message_name> (NaCl code) and onReceive_<message_name> (JavaScript code) is added. The code calling the functions is automatically added so in order to handle the data received with the messages the user only needs to fill in the body of these functions.
  2. Sending the messages: for each message a function PostMessage_<message_name> (NaCl code) and send_<message_name>(JavaScript code) is added. The functions are not called anywhere – the user needs to call the functions where it is needed.

Additionally some supporting code is generated. This includes Doxygen- and JSDoc-style comments for the generated functions and definitions of data used in the messages. For example, for the message presented in this guide, the following data structure is generated (NaCl code):

/**
 * Struct holding data for the 'nMessage' message.
 */
struct nMessage_Data {
  int numberParam; // Holds the data for the number
};

To know how to deal with the data sent in the messages it is therefore always needed to examine the generated data definitions.