¶ Visualization framework messaging system
Work in progress: other informations on the visualization framework can be found here
¶ Principle
The dialog between the host page and the iframe relies on HTML5 window messaging system
¶ Initialisation
The initialisation follows this workflow:
- the host page affects the src attribute of the iframe
- the iframe loads
- when the iframe is loaded, it sends a
loadevent to the host page - the host page can send the graph data and settings to the iframe.
¶ Operation
After the initialization, the host page and the viewer iframe can exchange messages.
¶ Messages from host page to iframe
¶ Message for initialising or resetting the viewer
¶ set
set message allows to initialize or reset the visualization.
message format:
{ type: 'set',
settings: {...},
graph: {...} | request: {...} | domainToFollow: {...} | timeline: {...},
highlightGraph: {...}
}
See Map_and_graph_viewers for the complete format of the message.
¶ Messages for changing data
The host page can update the data shown in the viewer through replace, update and delete messages.
¶ replace
replace message allows to replace avatars and links in the visualization. The other settings are unchanged.
message format:
{ type: 'replace',
data: {
nodes:[],
links:[],
}
}
¶ update
update message allows to add or modify avatars and links in the visualization.
Existing avatars will be replaced by the provided node.
message format:
{ type: 'update',
data: {
nodes:[],
links:[],
}
}
response: none
¶ delete
delete message allows to remove avatars and links in the visualization.
For nodes (avatars), only the _uuid field is mandatory.
message format:
{ type: 'delete',
data: {
nodes:[
{_uuid: <UUID>},
{_uuid: <UUID2>},
{_uuid: <UUID3>},
...
],
links:[],
}
}
response: none
¶ Messages for controlling supervision mode
¶ supervision
A supervision message allows to start or stop the supervision.
message format:
{ type: 'supervision',
action: 'start' | 'stop'
}
response: none, a message will be sent back when the supervision will be effectively started or stopped.
¶ Messages for updating the visualization
¶ updateSettings
updateSettings allows to change the settings of the visualization.
¶ selectAvatar
selectAvatar allows to select an avatar in the visualization, knowing its uuid
message format:
{ type: 'selectAvatar',
data: {
uuid: "<AVATAR_UUID>"
}
}
response: none
¶ Messages for requesting informations from iframe
¶ getFetchedNodesAndLinks
Through the visualization, the user can follow links and 'discover' new avatars and links.
The getFetchedNodesAndLinks command is intented to ask the visualization for those avatars and links that were not in the initial data or are newer since the last getFetchedNodesAndLinks command.
The format is:
{ type: "getFetchedNodesAndLinks" }
For the response, the visualization answers with a FetchedNodesAndLinks message. See below.
¶ get2DPositions
In 2D viewers, the avatars positions are computed by the viewer and then could be rearranged by the user.
The get2DPositions message allows the host page to fetch those 2D positions.
The format is:
{ type: "get2DPositions" }
For the response, the visualization answers with a 2DPositions message. See below.
¶ Messages from iframe to host page
¶ "System" messages
¶ load event
The load event is not really a message but an event send to the host page when the iframe code is loaded. It's time for the host page to send data to the iframe.
¶ warn
A warn message is sent every time the visualization encounters a problem. It is mostly intended for debuging purpose.
The format is:
{
type: "warn",
msg : "<message>",
}
¶ Supervision message
¶ supervision
A supervison message is sent in supervision mode when the supervision is effectily started or stopped
{
type: "supervision",
msg: 'started' | 'stopped'
}
¶ Messages to report user's interaction
The visualization can report some user's interactions.
¶ rearm
The rearm message is send to the host page when the user clicks on "reset graph" in the context menu. The host page can send back the initial data with the set message.
This message has no data.
¶ nodeSelected or nodeUnselected
The nodeSelected or nodeUnselected message is send to the host page when the user clicks on an avatar. For this, set canFireNodeSelected to truein the settings.
This can be used with canShowDetails to false if you want to implement your own treatment when an avatar is clicked.
The format is:
{
type: "nodeSelected",
params: {
_uuid: id
}
}
¶ linkSelected
The linkSelected message is send to the host page when the user clicks on a link. For this, set canFireNodeSelected to truein the settings.
This can be used with canShowDetails to false if you want to implement your own treatment when a link is clicked.
The format is:
{
type: "linkSelected",
params: {
id: id
}
}
¶ customAction
The customAction message is send to the host page when the user clicks on a button in a custom menu of an avatar.
The format is:
{
type: "customAction",
params: {
_uuid: <uuid of the targeted avatar>,
actionId: <actionId>
}
}
¶ Responses to host page commands
¶ 2DPositions
This is the response to the get2DPositions command.
The format is:
{
type: "2DPositions",
msg: {
<node_uuid1>: {x:<x> , y: <y>},
<node_uuid2>: {x:<x> , y: <y>},
...
}
}
¶ FetchedNodesAndLinks
This is the response to the getFetchedNodesAndLinks command.
The format is:
{
type: "FetchedNodesAndLinks",
msg: {
nodes:[...],
links:[...],
}
}