.. sectionauthor:: malte
.. _ref-infrastruktur:

###############################################################################
Messages - Maongo kommuniziert mit der Umwelt
###############################################################################


Kommunikation zwischen Maongo und der einbindenden Host-Umgebung
==============================================================================

Häufig wird eine Maongo-Anwendung innerhalb einer anderen Anwendung ausgeführt. Dies kann eine HTML-Seite sein,
eine Flex-Anwendung oder eine Java-Anwendung. Um die Kommunikation zwischen der Host-Umgebung und der Maongo-Anwendung 
zu ermöglichen, stellt Maongo definierte Schnittstellen zur Übermittlung von Nachrichten bereit. Diese ``Messages`` bestehen 
aus einem ``MessageName`` und einer beliebigen Anzahl von Parametern als Nutzlast. Dabei dient der ``MessageName`` zur 
Identifizierung der Nachricht und kann genutzt werden um die Nachricht in der Maongo-Anwendung bzw. der Host-Umgebung an die richtige
Stelle weiterzugeben. 



Setup der Host-Umgebung
===============================================================================
Um diese Funktionalität nutzen zu können muss die Host-Umgebung entsprechende Funktionen (Javascript bzw. Java) implementieren. Die Funktionen 
werden bspw. von den Maongo-Compilern für HTML und Flash schon in die generierten HTML-Seiten integriert.

**HTML-Ausspielung** 

Der folgende Code-Abschnitt erlaubt den Zugriff auf die Maongo-Anwendung über die Kurzfassung ``document.mymaongoapp`` indem eine Referenz auf die erzeugte 
Applikation an der entsprechenden Stelle im DOM-Tree abgelegt wird.
::
  ...
  var app = new mymaongoapp(...);
  // setup for messaging
  document.mymaongoapp = app;
  ...
	
Hiermit wird eine Javascript-Funktion als Handler für ``Messages`` aus der Maongo-Anwendung registriert.
::
  ...
  // setup message handler
  document.mymaongoapp.onMessage = messageCallback;
  ...


**in HTML eingebundener Flashfilm**
  
Der folgende Javascript-Code-Abschnitt erlaubt den Zugriff auf die Maongo-Anwendung über die Kurzfassung ``document.mymaongoapp`` indem eine Referenz 
auf das eingebundene SWF-File an der entsprechenden Stelle im DOM-Tree abgelegt wird.
::
  
  ...
  //allow external messaging to app
  document.mymaongoapp = document.getElementById("mymaongoapp");
  ...
  
Da der Handler für ``Messages`` aus der Maongo-Anwendung erst auf dem Flashfilm registriert werden kann, wenn dieser geladen ist und das Javascript-API
initialisiert hat, wird eine definierte Funktion in der HTML-Seite angelegt, welche den Namen des Handlers zurückliefert. Diese Funktion wird vom
Flashfilm aufgerufen, sobald dieser vollständig geladen ist. 
::

  //called from maongo after loading
  function sendMessageHandler(){
    document.mymaongoapp.registerMessageHandler("messageCallback");
  } 
  
Der Zugriff des Flashfilms auf die HTML-Seite mittels Javascript wird über den Parameter ``allowScriptAccess`` in der HTML-Einbindung gesteuert.
Dieser ist per default mit dem Wert ``sameDomain`` gesetzt. Dies bedeutet das der Zugriff nur erlaubt ist, wenn Flashfilm und HTML-Dokument von
der gleichen Domain ausgeliefert werden. Sollte dies nicht der Fall sein, so kann der Wert auf ``always`` gesetzt werden.
:: 
  
  <param name="allowScriptAccess" value="sameDomain"/>
  
bzw. 
::
  
  <param name="allowScriptAccess" value="always"/>
  
**Flex-Anwendung**

Um Nachrichten aus der Maongo-Anwendung in der Flex-Umgebung zu erhalten, muss eine Funktion der Flex-Umgebung als Message-Handler registriert werden
::
  
  maongoComponent.registerMessageCallback(messageCallback);


**Java-Anwendung**

*TODO*




Nachrichten an eine Maongo-Anwendung schicken
===============================================================================
Nachrichten werden an die Maongo-Anwendung geschickt, indem auf der Anwendung die Funktion ``message(messageName, parameterList)`` aufgerufen wird. 
Dabei ist die Anzahl der Parameter beliebig. Diese müssen allerdings in einen Array verpackt werden. 


**HTML-Ausspielung** 
::
  
  <a href="javascript:document.mymaongoapp.message('myMessageName', ['klaus', 56, 'hans'])">send Message to Maongo</a>

**in HTML eingebundener Flashfilm**
::
  
  <a href="javascript:document.mymaongoapp.message('myMessageName', ['klaus', 56, 'hans'])">send Message to Maongo</a>
  

**Flex-Anwendung**
Aus einer Flex-Anwendung werden Nachrichten an die Maongo-Anwendung geschickt, indem die MaongoFlexComponent genutzt wird.
::

  maongoComponent.message("messageName",["hallo welt,"klaus",23]);


**Java-Anwendung**

*TODO*




Nachrichten aus einer Maongo-Anwendung empfangen
===============================================================================
Wenn Nachrichten aus Maongo verschickt werden sollen, so kann dieses innerhalb des MAD-Dokument auf jedem Widget mittels einer Action geschehen. 
::
  
  <action trigger="button-pressed">
    this.externalMessage("externalMessageName", ["dieter", 56]);
  </action>
  
Die Nachricht wird in der Host-Umgebung an den  registrierten Message-Handler weitergegeben und kann dort entsprechend weiterverarbeitet werden.

**HTML/in HTML eingebundener Flashfilm**
::
  
  // sample implementation for messageCallback
  function messageCallback(messageName, args){
    alert("callback: " + messageName + " arguments: " + args);
  }



**Flex**
::

  public function messageCallback(...rest):void{
    trace("Message from Maongo: " + rest);
  }

**Java-Anwendung**

*TODO*



Beispiel
===============================================================================
**MAD-Dokument**

:: 

  <?xml version="1.0" encoding="ISO-8859-1"?>
  <presentation width="800" height="800">
  
  <widget type="Button" x="20" y="20">
  	<property name="Shape" value="R 80 20"/>
  	<property name="Text" value="reset"/>
  	<action trigger="button-pressed">
  		this.parent.Display.Text = "reset"; 
  	</action>
  </widget>
  
  <widget type="Button" x="20" y="50">
  	<property name="Shape" value="R 80 20"/>
  	<property name="Text" value="ext. Mess."/>
  	<action trigger="button-pressed">
  		this.externalMessage("externalMessage", ["parameter1",56]);
  	</action>
  </widget>
  
  <widget type="Text" name="Display" x="20" y="100">
  	<property name="Text" value="nix"/>
  	<property name="BorderWidth" value="1"/>
  	<property name="Shape" value="R 400 20"/>
  </widget>
  
  <!-- dieser Trigger wird ausgeloest wenn von extern eine Nachricht mit dem Namen "messageName" ankommt -->
  <action trigger="messageName" arguments="arg1, arg2">
  	this.Display.Text = "Message received: " + args; 
  </action>
  
  </presentation>

**HTML Ausspielung**
::
    <html xmlns="http://www.w3.org/1999/xhtml" xmlns:svg="http://www.w3.org/2000/svg">
    <head>
      <title>No Title</title>
      <link rel="stylesheet" type="text/css" media="screen" href="./mp_messagesfonts.css" />
      <link rel="stylesheet" type="text/css" media="screen" href="./mp_reset.css" />
      <script src="./mymaongoapp-assets/mp_maongomp.js" type="text/javascript"></script>
      <script src="./mymaongoapp-assets/mp_descriptors.js" type="text/javascript"></script>
      <script src="./mymaongoapp.js" type="text/javascript"></script>
      <script type="text/javascript">
      
      // <![CDATA[
      
      
      window.onload = function () {
        var ellapsed = new Date().getTime() - startTime;
        var body = document.body;
        var projector = document.getElementById('projector');
        var rc = new maongo.render.dom.RenderContext(projector);
        var app = new mymaongoapp(rc);
        app.setDefaultRenderer("dom");
        app.addListener(
          {
          onPreloadComplete: function () {
            projector.appendChild( app.getDisplayObject() );
          }
          }
        );
      
      
      // setup for messaging
      document.mymaongoapp = app;
      document.mymaongoapp.onMessage = messageCallback;
      
      app.start();
      ellapsed = new Date().getTime() - startTime;
      }
    
      // sample implementation for messageCallback - replace with your own implementation
      function messageCallback(messageName, args){
        alert("callback: " + messageName + " arguments: " + args);
      }
    
      // ]]>
      </script>
    </head>
    <body>
      <a href="javascript:document.mymaongoapp.message('testMessage', ['para1', 56])">send message to Maongo</a>
      <div id="projector"></div>
    </body>
    </html>



  
**Einbindung der Flash-Ausspielung**
::
  
 <html xmlns="http://www.w3.org/1999/xhtml">
 <head>
  <title>No Title</title>
  <meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
  <script type="text/javascript">
  //[ ... ]

  // sample implementation for messageCallback - replace with your own implementation
   function messageCallback(messageName, args){
    alert("callback: " + messageName + " arguments: " + args);
  }

 </script>


 </head>
 <body style="padding:0px;margin:0px;overflow:hidden;height=100%">

 <a href="javascript:document.mymaongoapp.message('testMessage', ['para1', 56])">send message to Maongo</a>

 <div style="height:800px; width:800px;">
  <object id="mymaongoapp"  type="application/x-shockwave-flash" data="messages.swf?" style="width:800px; height:800px;" width="100%" height="100%" align="middle">
    <param name="movie" value="messages.swf?" />
    <param name="scale" value="noscale" />
    <param name="salign" value="LT" />
    <param name="FlashVars" value="" />
    <param name="bgcolor" value="#" />
    <param name="allowFullScreen" value="true"/>
    <param name="allowScriptAccess" value="always"/>
    <div>Dieser Inhalt ist nur mit dem Adobe-Flash-Plugin sichtbar.</div>
  </object>
 </div>
 <script>
   //allow external messaging to app
   document.mymaongoapp = document.getElementById("mymaongoapp");

   //called from maongoflash
  function sendMessageHandler(){
    document.mymaongoapp.registerMessageHandler("messageCallback");
  }

 </script>
 </body>
 </html><