Documente Academic
Documente Profesional
Documente Cultură
Abstract
This white paper explains how to use external widgets to extend
the capabilities of D2. It also documents the APIs provided by
D2 to allow communication between external widgets and the
rest of the D2 UI.
March 2013
Copyright 2013 EMC Corporation. All Rights Reserved.
For the most up-to-date listing of EMC product names, see EMC
Corporation Trademarks on EMC.com.
Audience
This white paper is intended for developers wishing to create extensions to the D2
interface. Basic familiarity with the D2 product and JavaScript development practices
is assumed.
Portal Communication
D2 is composed of several components:
- D2 portal and its widgets communicate which each other by sending and receiving
messages on dedicated communication channels.
D2 portal is composed of internal widgets and displays various workspaces.
- Each workspace has a unique container ID (uid) used to identify it and can contain
several widgets. Each widget contained in a workspace is aware of this uid. When a
widget communicates, only widgets inside the same workspace are aware of this. This is
the default behavior and it can be overridden. The portal itself is a container with
portal as uid.
- Widgets register themselves on a communication channel to be able to receive
messages published on this channel by other widgets (or even by itself). Widgets can
publish any message on any communication channel. A widget has a type and an id.
When a widget publishes a message, the ID of this widget is sent with the message.
- Communication channels are dedicated to specific tasks like Opening a document.
Messages contain various data such as the ID of a document.
- Messages are sent through the channels. They contain a map of string information that
can be easily analyzed / set using the provided API.
Message Settings
Here is the list of message settings that define which widgets, registered on the communication
channel, receive a message.
- Container UID: By default, you can only receive messages from widget sharing the same
container UID (i.e.: in the same workspace) automatically set to widgets current
container uid.
- Global: true or false When a message is defined as global, itll be sent to every
container default is false.
- Sender: The ID of the widget that send the message - automatically set.
- Target widget type: The type of widget to target with this message. The value is the same
as the Widget Type field in D2-Config (ex: BrowserWidget) default is null.
- Target widget ID: The ID of the widget to target. The value is the name of the widget
configuration in D2-Config. default is null.
- Excluded widget type: The type of widget to exclude. The value is the same as the
Widget Type field in D2-Config (ex: BrowserWidget) default is null.
- Excluded widget ID: The ID of the widget to exclude. The value is the name of the widget
configuration in D2-Config. default is null.
- Volatile: true or false. A volatile message is not saved by widgets to be replayed
when widget is set active- default is false.
Key Details
oam_id The object id, convenient field
oam_cuid The container uid of the sending widget
oam_global Set the message as global or not
oam_sender id of the sending widget
oam_value A value, convenient field
oam_target_type type of the target widget
oam_target_id id of the target widget
oam_excluded_type type of the excluded widget
oam_excluded_id id of the excluded widget
oam_volatile set the message volatile or not
Widgets
Widget Types
There are 4 types of widget in D2:
- Portal Widgets: These are internal widgets, instantiated by the portal only. They are not
listed in D2-Config as available widget types.
- D2 Internal Widgets: These are the widgets available in D2-Config minus the external
widgets.
- External widgets without bidirectional communication: Basically, these are iframes for
which the URL is refreshed (and resolved if containing $values) when it receives a
message.
- External widgets with bidirectional communication: These widgets are iframes too but
they communicate with the portal and other widgets in the same way as internal widgets
do, using messages and communication channel with the provided API.
Widget States
When a widget is not displayed, its state is set as inactive. This happens when the widget is
embedded in a tab container or an accordion container. The widget state changes to active
when the tab of the widget is displayed.
For performance reasons, the widgets that are not active dont handle the messages they
receive. This is the default behavior and it can be overridden in case of specific needs.
When an inactive widget receives a message, this message is stored by the widget for later use.
There is only one stored message, the latest one received. When the widget becomes active,
Communication Channels
The portal uses two types of channels to communicate:
- Event: these channels are used when an event happens. Its often used after an action
has been performed. For example, D2_EVENT_OBJECT_DESTROYED is the channel used
to publish message when an object has been destroyed. Messages sent through Events
channel contain information about the event that just happened. For example, it will
contain the ID of the destroyed document.
- Action: these channels are used to request to perform certain actions from the portal.
For example, the D2_ACTION_CONTENT_VIEW is used to request a document to be
downloaded and opened on the desktop. Messages sent through Actions channels
contain information about the action to be performed. For example, it will contain the ID
of the document to view.
The channel naming is just a convention used to easily understand what the purpose of each
channel is. With the API we provide you can use any channel name you want.
Event Channels
When receiving a message on an event channel, this message will contain information about
the event that just happened. Several widgets can send a message in the same channel and
sometimes the content of the message can be slightly different, with less or more parameters.
Almost every message has data filled in its built-in parameters. For example, the oam_id
parameter that specifies the ID of the object involved in the event. We will not specify those
parameters in the following list for readability.
Not every event channels are listed here. Some channels are only technical channels used by
the portal and should not be used for any other purpose.
D2OpenAjaxHub Object
The D2OpenAjaxHub object is the main object youll have to use to connect to the Open Ajax
Hub, send and receive messages.
When calling the connectHub function, you have to specify 3 callback functions :
fOnConnectCompleted(oHubClient, bSuccess, bError). This function is called at the end
of the hub connection.
o oHubClient: the Open Ajax Hub Client object created
o bSuccess: true if the hub is connected
o bError: true if an error occured
fOnInit(oMessage): This function is called when the widget is connected with the portal
and received some initialization data.
2. Registering on a channel
To register a channel, you must use the function subscribeToChannel
D2OpenAjaxHub.subscribeToChannel = function(sChannel, fCallbackDataReceived,
bHandleMessageIfInactive)
When calling the subscribeToChannel function, you have to specify 3 parameters:
sChannel: The channel to which your widget will register
fOnConnectCompleted(sChannel, oMessage). This function is called when the widget
receives a message(according to message broadcasting rules).
o sChannel: the channel where the message has been received.
o oMessage: the received message.
bHandleMessageIfInactive: True to make messages handled even if the widget is
inactive.
OpenAjaxMessage Object
The Open Ajax Message is used to transfer data on the hub. Basically its a map of key/values.
When its transferred on a channel, it is serialized to a String form.
The JavaScript object we provided helps to serialize/deserialize it, to get and put data inside and
to specify the message broadcasting rules.
Conclusion
As we have seen, D2 4.1 includes an extensive interface for sending and receiving UI
events from an external widget. Using the information in this white paper, it should
be possible to create widgets that are well coupled with the rest of the user interface.