Using the Data-Driven Content Object in Visual Analytics to Display Product Photos: Validating Data
This is the second part of a four-part series that discusses how to display product photos in SAS Visual Analytics.
- Basics
- Validating Data (this article!)
- Debugging
- Viewing Multiple Photos
Scenario
Recall from the previous post that you would like to display an image of a selected product in a report. In this post, we will see how to add code to validate the data received from Visual Analytics and send a message back to Visual Analytics about required roles if the data is not valid (or no data is assigned to the data-driven content object).
Note: More detail about the requirements and steps for using the data-driven content object in Visual Analytics can be found in the previous post.
Note: The entire code is available at the end of this post.
Communication
Before we discuss validating the data received from Visual Analytics, it’s important to understand how Visual Analytics and the third-party visualization communicate. Three types of messages are sent between Visual Analytics and the third-party visualization: data messages, instructional messages, and selection messages.
Select any image to see a larger version.
Mobile users: If you do not see this image, scroll to the bottom of the page and select the "Full" version of this post.
Data messages are sent from Visual Analytics to the data-driven content object. This message is sent in JSON format and includes the data assigned to the data-driven content object (in the Roles pane) and metadata information about that data. The data are stored in an array type structure and at the end of the array, Visual Analytics sends an additional column (named brush) that indicates whether a row of data is selected when the data-driven content object is the target of a linked selection action. The SAS GitHub repository for third-party visualizations includes a visualization (jsonDataViewer.html) that can be used to display your data as a JSON object.
Note: In this example, because the data-driven content object is not the target of a linked selection action, we are not using the brush column in our JavaScript code.
Instructional messages are sent from the third-party visualization to Visual Analytics. These messages typically contain details about the type, number, and order of data items required for the visualization.
Recall, to send messages back to SAS Visual Analytics, SAS Viya must be accessed using the HTTPS protocol, a secure version of HTTP that is encrypted to increase the security of the data transferred between the web client and the server.
Selection messages are sent from the third-party visualization to Visual Analytics. These messages include details about any selection made in the third-party visualization. This enables the third-party visualization to be used as the source of an action.
Note: In this example, selection messages are not used.
Declaring and Initializing an Additional Variable
It’s a best practice to validate the data being passed from Visual Analytics before executing any JavaScript code. If the data is not valid (or no data is assigned), a message will be sent back to Visual Analytics with details about what roles are required. To pass messages back to the data-driven content object in Visual Analytics, we need to create a dynamic data variable that holds the internal name of the object.
In the callback function created to get the data from Visual Analytics (onDataReceived), that data from Visual Analytics (messageFromVA) is used to initialize the vaResult variable with the internal name of the data-driven content object.
Validate Roles
Next, the data passed from Visual Analytics can be validated using the validateRoles function from the contentUtil.js utility.
The if statement checks if the roles are not valid. Notice the exclamation point in front of the !va.contentUtil.validateRoles() function, the ! means not.
The validateRoles function uses the data received from Visual Analytics (messageFromVA), checks if the required column is a string, and checks if the optional column (the brush column) is a number. The brush column is automatically added to the data received from Visual Analytics to indicate if a row is selected when the data-driven content object is the target of a linked selection action. For this example, this column is not needed.
Note: Utilities can be found on the SAS GitHub repository for third-party visualizations. For the utilities to be available in the visualization, a link to the utilities must be included in the head element of the web page.
Adding Instructions
If the data passed from Visual Analytics is not valid (or no data is assigned to the object), then a message describing the required roles can be sent back to Visual Analytics using the postInstructionalMessage function from the messagingUtil.js utility.
The postInstructionalMessage function uses the internal name of the data-driven content object (vaResult) to send a message back to Visual Analytics about the required roles for the object (Item), their assignment order, and the types of data items required (string).
Recall that HTTPS needs to be configured to send messages back to Visual Analytics.
Note: Utilities can be found on the SAS GitHub repository for third-party visualizations. For the utilities to be available in the visualization, a link to the utilities must be included in the head element of the web page.
Testing
When the code is complete, you can test it in Visual Analytics. If invalid data (or no data) is assigned to the data-driven content object, a message appears stating what data is required, the assignment order, and the types of data items. It’s a best practice to send an instructional information with this information so the report designer knows how to use the visualization.
Summary
You can use this code to validate data for any third-party visualization and to send messages about required roles back to Visual Analytics.
In the next part of this series, we will discuss how to debug your code using sample data.
References
Documentation: Working with Data-Driven Content
Documentation: Programming Considerations for Data-Driven Visualizations
Resource: SAS GitHub repository for third-party visualizations
Book: Interactive Reports in SAS Visual Analytics
Code
Below is the code in its entirety.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Document</title>
<!-- Bootstrap -->
<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.0.2/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-EVSTQN3/azprG1Anm3QDgpJLIm9Nao0Yz1ztcQTwFspd3yD65VohhpuuCOmLASjC" crossorigin="anonymous">
<!-- Utilities for DDC -->
<script type="text/javascript" src="util/messagingUtil.js"></script>
<script type="text/javascript" src="util/contentUtil.js"></script>
</head>
<body>
<!-- Container for Photo -->
<div class="container" id="photo">
</div>
<!-- Custom JavaScript -->
<script>
// Listening for HTML document completely loaded and parsed, best practice
document.addEventListener("DOMContentLoaded", function() {
/******************************* Declare variables ***************************************/
// Dynamic data variables
let vaMessage; // Data message from VA
let vaResult; // Name of DDC object, required to send messages back to VA
let rowCount; // Number of rows passed from VA
// Selection variables
let photoDiv; // Div for photo
let itemPhoto; // Element for photo
/******************************* Setup Callback Functions ***************************************/
// Attach event for data message from VA
va.messagingUtil.setOnDataReceivedCallback(onDataReceived);
// Take action on received data
function onDataReceived(messageFromVA) {
// Initialize data variables
vaMessage = messageFromVA;
vaResult = messageFromVA.resultName;
rowCount = messageFromVA.rowCount;
// Validate data roles
if (
!va.contentUtil.validateRoles(
messageFromVA,
["string"], // data from DDC object
["number"] // additional field for brush column (not needed in this example)
)
) {
// If roles are invalid or no data is being passed, display a message in VA about required roles (requires https)
va.messagingUtil.postInstructionalMessage(
vaResult,
"Display Photo expects columns to be assigned in this order:\n" +
" 1. Item (string)"
);
}
// Add photo to DOM
const photoDiv = document.getElementById("photo");
photoDiv.innerText = "";
// Display photo for selected item
if (
rowCount == 1
) {
itemPhoto = document.createElement("img");
itemPhoto.src="images/"+vaMessage.data[0][0].toLowerCase()+".jpg";
itemPhoto.alt = vaMessage.data[0][0];
itemPhoto.classList.add("img-fluid");
photoDiv.appendChild(itemPhoto);
} else {
itemPhoto = document.createElement("img");
itemPhoto.src="images/insight_toys_logo.png";
itemPhoto.alt = "Insight Toys Logo";
itemPhoto.classList.add("img-fluid");
photoDiv.appendChild(itemPhoto);
};
};
});
</script>
</body>
</html>
Find more articles from SAS Global Enablement and Learning here.
