Page Integration

From Emma

This article describes how to include Emma content in an HTML page, and how to communicate with it using Javascript. The content in this article was tested on Mozilla Firefox 1.5 and Microsoft Internet Explorer 6.0.

Contents 1 Embedding Emma into your HTML page 2 Communicating with Emma in Javascript 2.1 Calling into Emma (from the page) 2.2 Calling out of Emma (to the page) 2.3 Examples

Embedding Emma into your HTML page

This is an example of how you could embed an .ema file "pageComm.ema" into an HTML page:

<embed src="pageComm.ema" type="application/x-emma-ema" name="Emma"
       WIDTH="600" HEIGHT="400" id="Emma">

This example only works for Mozilla. To work in IE, you would do this:

<object id="Emma"
 CLASSID="CLSID:00A58EDC-19C9-452C-A69E-039090CB1B86" 
 codebase="http://www.emma3d.org/emma.cab#version=0,2,0,0"
 WIDTH="600" HEIGHT="400" >
   <Param name=SRC value="pageComm.ema">
</object>

Obviously, most authors will want their content to work in either browser. One way to solve this is to use document.write(), and write either of the above depending on the browser type:

<script type="text/javascript">
<!--
//
// Use document.write() to output the right Emma HTML object depending on 
// browser: 
//
var BrowserType = navigator.appName;
if ( BrowserType == "Netscape" || BrowserType == "Safari" ) {
  document.write('<embed src="pageComm.ema" type="application/x-emma-ema"\n');
  document.write('       name="Emma" WIDTH="600" HEIGHT="400" id="Emma">\n');
}
else if ( BrowserType == "Microsoft Internet Explorer" ) {
  var output = '<object id="Emma"\n';
  output +=    '        CLASSID="CLSID:00A58EDC-19C9-452C-A69E-039090CB1B86"\n';
  output +=    '        codebase="http://www.emma3d.org/emma.cab#version=0,2,0,0"\n';
  output +=    '        WIDTH="600" HEIGHT="400" >\n';
  output +=    '  <Param name=SRC value="pageComm.ema">\n';
  output +=    '</object>';
  document.write(output);
}
-->
</script>

(Author note: if someone knows of a better way to do this, please let me know! --Rick 15:29, 6 April 2006 (PDT))

Communicating with Emma in Javascript

Calling into Emma (from the page)

The Emma plug-in exposes a single generic function, eval( evalStr ), which may be called from Javascript on the HTML page. The following <script> tag sets up a "thunk" function called "callEmma()", which takes any number of arguments, and constructs an eval string to pass to Emma. Note this function is not required, but is handy:

<script>
<!--
function callEmma() {
    // Get the Emma plugin object
    var Emma = document.getElementById('Emma');
    
    // Next build the eval string.  Note callEmma.arguments[0] will be the
    // function name.
    var evalStr = callEmma.arguments[0] + "(";
    for ( var i = 1; i < callEmma.arguments.length; i++ ) {
        var a = callEmma.arguments[i];
        if ( i > 1 ) evalStr += ",";
        if ( typeof(a) == "string" ) {
            evalStr += "\"";
        }
        evalStr += callEmma.arguments[i];
        if ( typeof(a) == "string" ) {
            evalStr += "\"";
        }
    }
    evalStr += ")";

    // Call Emma's "eval()" function:
    Emma.eval(evalStr);
}
-->
</script>

Now, in the HTML, you can call a function doSomething() in the Emma content like so:

<form name="formname">
<input type=button value="callEmma('doSomething', 'text', 27, true)" onclick='callEmma("doSomething", "text", 27, true)'/>
</form>

In the Emma content, 'doSomething' must be registered with the 'root.page' object, e.g:

function initialize ( ) {
   root.page.doSomething = function(a,b,c)
       print("doSomething was called with ", a, ", ", b, ", ", c)
   end
}

Calling out of Emma (to the page)

You can call Javascript functions on the page from within Emma content by using root.page.call(). For instance, lets change our "doSomething()" function in the .ema file to call a function called "bar()" in the containing HTML page:

function initialize ( ) {
   root.page.doSomething = function(a,b,c)
       print("doSomething was called with ", a, ", ", b, ", ", c)
       root.page.call("bar", "got it!!!")
   end
}

Correspondingly, lets put a function in the HTML:

<script>
// this function is called from the embedded Emma content
function bar(arg)
{
  alert("function bar(" + arg + ") called!");
}
</script>

Examples

The above example are snippets from the example code in http://www.emma3d.org/b-0-5/content/tests/pages/mainPageComm.html.