<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "../../Reference_Guide.ent">
%BOOK_ENTITIES;
]>
<section id="sect-Reference_Guide-JavaScript_Inter_Application_Communication">
	<title>JavaScript Inter Application Communication</title>
	<section id="sect-Reference_Guide-JavaScript_Inter_Application_Communication-Overview">
		<title>Overview</title>
		<para>
			JavaScript Inter Application Communication is designed to allow applications within a page to exchange data. This library is made for broadcasting messages on topic.
		</para>
		<para>
			It is based on 3 functions:
		</para>
		<itemizedlist>
			<listitem>
				<para>
					Subscribe.
				</para>
			</listitem>
			<listitem>
				<para>
					Publish.
				</para>
			</listitem>
			<listitem>
				<para>
					Unsubscribe.
				</para>
			</listitem>
		</itemizedlist>
		<para>
			A subscription to a topic will receive any subtopic messages. For example; An application subscribed to &#34;<literal>/eXo/application</literal>&#34; will receive messages sent on the &#34;<literal>/eXo/application/map</literal>&#34; topic. A message sent on &#34;<literal>/eXo</literal>&#34;, however, would not be received.
		</para>
		<variablelist id="vari-Reference_Guide-Overview-Subscription_Topics">
			<title>Subscription Topics</title>
			<varlistentry>
				<term>/eXo</term>
				<listitem>
					<para>
						This topic contains all the events generated by the platform.
					</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>/eXo/portal/notification</term>
				<listitem>
					<para>
						A message is sent on this topic will prompt a popup notification in the top right of the screen.
					</para>
				</listitem>
			</varlistentry>
		</variablelist>
	</section>
	
	<!--   
   <section
      id="sect-Reference_Guide-JavaScript_Inter_Application_Communication-GateInportalchangeTitle">
      <title>/GateIn/portal/changeTitle (not
         implemented yet)</title>
      <para>
         Send a message on this channel to change (and to be notified) the title
         of the portal.
		</para>
   </section>

   <section
      id="sect-Reference_Guide-JavaScript_Inter_Application_Communication-GateInportalpageLoaded">
      <title>/GateIn/portal/pageLoaded (not
         implemented yet)</title>
      <para>
         Receive a message when a page is loaded.
		</para>
   </section>

   <section
      id="sect-Reference_Guide-JavaScript_Inter_Application_Communication-GateInportalpageUnloaded">
      <title>/eXo/portal/pageUnloaded (not
         implemented yet)</title>
      <para>
         Receive a message when a page is unloaded.
		</para>
   </section>

   <section
      id="sect-Reference_Guide-JavaScript_Inter_Application_Communication-GateInapplicationapplicationLoaded">
      <title>/eXo/application/applicationLoaded
         (not implemented yet)</title>
      <para>
         Receive a message when an application is loaded in the page.
		</para>
   </section>

   <section
      id="sect-Reference_Guide-JavaScript_Inter_Application_Communication-GateInapplicationapplicationUnloaded">
      <title>/eXo/application/applicationUnloaded
         (not implemented yet)</title>
      <para>
         Receive a message when an application is unloaded in the page.
		</para>
   </section>
   -->
	<section id="sect-Reference_Guide-JavaScript_Inter_Application_Communication-Library">
		<title>Library</title>
		<para>
			The Inter Application Communication library is found in <filename>01eXoResources.war:/javascript/eXo/core/Topic.js</filename>
		</para>
		
<programlisting>/**
 * publish is used to publish an event to the other subscribers to the given channels
 * @param {Object} senderId is a string that identify the sender
 * @param {String} topic is the topic that the message will be published
 * @param {Object} message is the message that&#39;s going to be delivered to the subscribers to the topic
 */
Topic.prototype.publish = function(/*Object*/ senderId, /*String*/ topicName, /*Object*/ message ) { ... }

/**
 * isSubscribed is used to check if a function receive the events from a topic
 * @param {String} topic The topic.
 * @param {Function} func is the name of the function of obj to call when a message is received on the topic
 */
Topic.prototype.isSubscribed = function(/*String*/ topic, /*Function*/ func) { ... }

/**
 * subscribe is used to subscribe a callback to a topic
 * @param {String} topic is the topic that will be listened
 * @param {Function} func is the name of the function of obj to call when a message is received on the topic
 * 
 * func is a function that take a Object in parameter. the event received have this format:
 * {senderId:senderId, message:message, topic: topic}
 *
 */
Topic.prototype.subscribe = function(/*String*/ topic, /*Function*/ func) { ... }

/**
 * unsubscribe is used to unsubscribe a callback to a topic
 * @param {String} topic is the topic
 * @param {Object} id is the id of the listener we want to unsubscribe
 */
Topic.prototype.unsubscribe = function(/*String*/ topic, /*Object*/ id) { ... }

Topic.prototype.initCometdBridge = function() { ... }
</programlisting>
	</section>
	
	<section id="sect-Reference_Guide-JavaScript_Inter_Application_Communication-Syntax">
		<title>Syntax</title>
		<para>
			The three messaging functions require particular objects and definitions in their syntax:
		</para>
		<variablelist>
			<varlistentry>
				<term>Subscribe</term>
				<listitem>
					<para>
						The <literal>subscribe</literal> function is used to subscribe a callback to a topic. It uses the following parameters:
					</para>
					<variablelist>
						<varlistentry>
							<term>topic</term>
							<listitem>
								<para>
									The topic that will be listened for.
								</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>func</term>
							<listitem>
								<para>
									The name of the object function to call when a message is received on the topic. It has to be a function that takes an Object parameter. The event received will have this format: 
<programlisting>{
  senderId:senderId,
  message:message,
  topic: topic
}
</programlisting>
								</para>
							</listitem>
						</varlistentry>
					</variablelist>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>Publish</term>
				<listitem>
					<para>
						The <literal>publish</literal> function is used to publish an event to the other subscribered applications through the given channels. Its parameters are:
					</para>
					<variablelist>
						<varlistentry>
							<term>senderId</term>
							<listitem>
								<para>
									This is a string that identifies the sender.
								</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>topicName</term>
							<listitem>
								<para>
									The topic that the message will be published.
								</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>message</term>
							<listitem>
								<para>
									This is the message body to be delivered to the subscribers to the topic.
								</para>
							</listitem>
						</varlistentry>
					</variablelist>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>Unsubscribe</term>
				<listitem>
					<para>
						The <literal>unsubscribe</literal> function is used to unsubscribe a callback to a topic. The required parameters are:
					</para>
					<variablelist>
						<varlistentry>
							<term>topic</term>
							<listitem>
								<para>
									The topic that will is to be unsubscribed from.
								</para>
							</listitem>
						</varlistentry>
						<varlistentry>
							<term>id</term>
							<listitem>
								<para>
									This is the context object.
								</para>
							</listitem>
						</varlistentry>
					</variablelist>
				</listitem>
			</varlistentry>
		</variablelist>
	</section>
	
	<section id="sect-Reference_Guide-JavaScript_Inter_Application_Communication-Example_of_what">
		<title>Example of Javascript events usage</title>
		
<programlisting role="HTML">&#60;%@ taglib uri=&#34;http://java.sun.com/portlet&#34; prefix=&#34;portlet&#34; %&#62;
&#60;portlet:defineObjects/&#62;
&#60;div&#62;
  &#60;p&#62;
    Received messages:
    &#60;div id=&#34;received_&#60;portlet:namespace/&#62;&#34;&#62;
         
    &#60;/div&#62;
  &#60;/p&#62;
   
  &#60;p&#62;
    Send message:
    &#60;input type=&#34;text&#34; id=&#34;msg_&#60;portlet:namespace/&#62;&#34;/&#62; &#60;a href=&#34;#&#34; onclick=&#34;send_&#60;portlet:namespace/&#62;();&#34;&#62;send&#60;/a&#62;
  &#60;/p&#62;
&#60;/div&#62;

&#60;script type=&#34;text/javascript&#34;&#62;
   
  Function.prototype.bind = function(object) {
    var method = this;
      return function() {
      method.apply(object, arguments);
    }
  }
   
  function send_&#60;portlet:namespace/&#62;() {
    var msg = document.getElementById(&#34;msg_&#60;portlet:namespace/&#62;&#34;).value;
    eXo.core.Topic.publish(&#34;&#60;portlet:namespace/&#62;&#34;, &#34;/demo&#34;, msg);
  }
   
  function Listener_&#60;portlet:namespace/&#62;(){
      
  }
   
  Listener_&#60;portlet:namespace/&#62;.prototype.receiveMsg = function(event) {
    document.getElementById(&#34;received_&#60;portlet:namespace/&#62;&#34;).innerHTML = 
      document.getElementById(&#34;received_&#60;portlet:namespace/&#62;&#34;).innerHTML + &#34;&#60;br /&#62;* &#34; + 
      event.senderId + &#34;: &#34; + event.message;
  }
   
  function init_&#60;portlet:namespace/&#62;() {
    var listener_&#60;portlet:namespace/&#62; = new Listener_&#60;portlet:namespace/&#62;();
    eXo.core.Topic.subscribe(&#34;/demo&#34;, listener_&#60;portlet:namespace/&#62;.receiveMsg.bind(listener_&#60;portlet:namespace/&#62;));
  }
   
  init_&#60;portlet:namespace/&#62;();
&#60;/script&#62;
</programlisting>
	</section>

</section>


