This is the second of a two-part article. If you haven’t done it yet, I’d recommend you checking the first one before proceeding. As a quick recap, VA and third-party visualizations communicate with each other through messages. As a developer of the third-party visualization, you must understand how those messages are formatted, and how to process them. This is what we are going to be discussing, in addition to best practices and examples.
As said before, there are three different types of messages, all in JSON format:
The message received from VA comes as event.data. This JSON object has a few elements, such as version, resultName, rowCount, data, columns, and more.
The data itself is provided as a two-dimensional array of rows and columns, like a table, and referenced as “data” in the message. For example:
Numeric data is not formatted. For example: $ 6,543,621 comes as 6543621. But dates and datetimes are formatted as strings, such as “Jan.” The actual format being used is provided as a column metadata. As a developer of the third-party visualization, you must use that information to make the necessary transformations in the data prior to visualizing it.
Data points (rows) of that table can be selected (brushed). Those selections are informed as an additional (optional) numeric column. Any value greater than 0 in this column indicates the row is being selected.
In the example above, if the last column is indicating selection, then the second row is being selected. Column metadata is responsible for telling if the column is indicating selection or not. Again, it’s the developer’s responsibility to interpret the information and make the appropriate selections in the third-party visualization.
Columns metadata is referenced as “columns” in the message and represented as an array of objects, where each object contains information or attributes about a column, such as name, label, type, format, usage, aggregation, etc. Except for name, label, and type, the other attributes are optional or vary according to the type of the column. If a column metadata contains the attribute called “usage” and it is set to “brush,” then that a column is not a real data column, but it’s used to indicate selection. There must be zero or one of those columns.
Another important piece of information found in the message received from VA is the “resultName.” This attribute is used when sending messages back to VA. There are other less common attributes that are not covered here, and additional information can be found in Programming Considerations for Data-Driven Visualizations.
Putting everything together, a typical message received from VA would look like this:
Both selection and instructional messages sent to VA are very simple JSON structures.
The selection message contains only two attributes:
The instructional message contains only two attributes as well:
To receive and send the messages discussed above, you must write code - yes, coding time has finally arrived, if you were wondering.
The following snippet of code is an example of an event listener that can be used to receive messages from VA. You can store it in a library and make it available as a function call for reusability as well as to hide the details of the implementation, but this is essentially what you need to do to get the message from VA.
To send a message back to VA you just need to send a post message, like in the snippet below. The message passed as parameter to the sendMessage function is a JSON object formatted as either a selection or an instructional message, as seen before:
Remember that a selection message should be sent when the report consumer interacts with the third-party visualization by clicking somewhere in the chart for example. This interaction is usually captured by an event and you must define the listener and handler for this event. The concept is the same as discussed here for receiving messages from VA, but the implementation is most likely different. Refer to your third-party visualization documentation to know more about the events it supports.
In the example above, the function eventHandlerFromVA is being called whenever a new message arrives. You are free to process those messages the way you want, but as a best practice, after integrating a few third-party visualizations with VA, these are some the steps that you should consider for your event handler function:
The code template below summarizes all those steps:
Again, this is just a suggestion. The order of those steps may be slightly changed, if you are careful enough. For example, validating assigned roles before extracting information about selections is possible, as long as you remember to ignore “brush” columns. I’ve also seen implementations where the developer (more advanced than me) decided to transform the two-dimensional array of data into a DataTable object as one of the first steps. DataTable offers a set of methods that operate on tables, instead of having to deal with arrays, indexes, and JSON objects explicitly throughout the rest of the code. I like that! DataTable is also how Google Charts expect input tables to be, so it makes a lot of sense to transform the data array into a DataTable right from the start.
Is this all? Certainly not. I’m sure you will find other things to add to your third-party visualization to make it shine, after all, the code is yours. One thing for sure will take the implementation a step further: resizing and/or scrollbars. Being able to resize and/or add scrollbars when necessary to your chart, depending on the size of the browser window and/or other factors, might be something to think about. I’ve also found useful to embed a small sample data in the code, so that a sample chart can be displayed, like a template, even before data gets assigned to the roles (see figure 07 in part 1 of 2 of this article).
Once the HTML file is ready and hosted in a Web Server, just add its URL under the DDC object’s Options pane.
As the number of third-party visualizations that you develop and are ready for DDC object increases, you can go to Edit administration settings in the top right menu and map their URLs. This allows quick access to third-party visualization via a dropdown in the DDC object’s Options pane:
Below is an example of a VA report with Google OrgChart. The List Table and DDC objects are connected by a selection (brush) action, so clicking in one object highlights the other:
Observe that we normally think about visualizations when dealing with Data-Driven Content objects, but it’s not restricted to this usage only. I’ve seen implementations that utilized DDC object to pass data and communicate with other applications and I’m sure people will come up with other interesting ideas. The sky is the limit!
To know more about Data-Driven Content please refer to Programming Considerations for Data-Driven Visualizations.
Full examples of third-party visualizations can be found in GitHub. There isn’t much there yet, but the idea is to get this library started so we all can contribute and benefit from new visualizations and samples. If you contribute with new visualizations, please let us know by leaving a note in the comments section. My Google OrgChart example should be there soon and I hope to see yours too!