BookmarkSubscribeRSS Feed

Using the Data-Driven Content Object in Visual Analytics to Display Product Photos: Validating Data

Started ‎09-18-2023 by
Modified ‎11-20-2023 by
Views 1,168

This is the second part of a four-part series that discusses how to display product photos in SAS Visual Analytics.

 

 

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.

 

01_niball_ddc2_data_messages.png

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.

 

02_niball_ddc2_instructional_messages.png

 

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.

 

03_niball_ddc2_selection_messages.png

 

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.

 

04_niball_ddc2_declaring_variable.png

 

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.

 

05_niball_ddc2_initializing_variable.png

 

 

Validate Roles

 

Next, the data passed from Visual Analytics can be validated using the validateRoles function from the contentUtil.js utility.

 

06_niball_ddc2_validate_roles.png

 

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.

 

07_niball_ddc2_post_instructional_message.png

 

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.

 

08_niball_ddc2_instructional_message_VA.png

 

 

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.

Comments

Thanks for the information!

@melissa69 hope you can find ways to use the Data-driven content object!

Thanks for the info

@Cayden any time!

Version history
Last update:
‎11-20-2023 10:34 AM
Updated by:
Contributors

SAS Innovate 2025: Save the Date

 SAS Innovate 2025 is scheduled for May 6-9 in Orlando, FL. Sign up to be first to learn about the agenda and registration!

Save the date!

Free course: Data Literacy Essentials

Data Literacy is for all, even absolute beginners. Jump on board with this free e-learning  and boost your career prospects.

Get Started

Article Tags