This project contains code samples that can be used as data-driven content within a SAS Visual Analytics (VA) report. For additional information, see Programming Considerations for Data-Driven Visualizations.
It contains the functions you need to send/receive messages to/from SAS Visual Analytics. You must include the following line in the <head> of the web page:
<script type="text/javascript" src="../util/messagingUtil.js"></script>Sets a callback function to handle messages received from VA.
Usage:
va.messagingUtil.setOnDataReceivedCallback(callback)callbackis the callback function name that you must define.
Sends back to VA a message containing selections made in the third-party visualization. VA will use that information to either filter or select (brush) other report objects, depending on the Actions defined between the data-driven object and other VA report objects.
Usage:
va.messagingUtil.postSelectionMessage(resultName, selectedRows)resultNameis the name of the associated query result, which is obtained from the message received from VA (event.data.resultName).selectedRowsis an array of numbers (e.g.[0, 3, 4]) or objects (e.g.[{row: 0}, {row: 3}, {row: 4}]) that contains the indexes of the selected rows, as they appear in event.data.data.
Sends back to VA an instructional message. This message is displayed in the data-driven content object in the VA report and is useful for sending text messages back to report authors informing required roles, their assignment order, types, etc.
Usage:
va.messagingUtil.postInstructionalMessage(resultName, strMessage)resultNameis the name of the associated query result, which is obtained from the message received from VA (event.data.resultName).strMessageis the text message to be sent.
It contains the functions you need to validate the data received from VA. You must include the following line in the <head> of the web page:
<script type="text/javascript" src="../util/contentUtil.js"></script>Sets a callback function to handle window resizing events.
Usage:
va.contentUtil.setupResizeListeners(callback)callbackis the callback function name that you must define. That's normally the function that re-draws the chart.
Checks if the data received from VA have all the columns (number, sequence, and type) required for the visualization.
Usage:
isValid = va.contentUtil.validateRoles(resultData, expectedTypes, optionalTypes)resultDatais the message received from VA (event.data).expectedTypesis an array describing the types of the columns that are required. The order is important and indicates the sequence that columns are assigned in the Roles tab in VA. Example: ["string", "number", "number"]. Valid types are "string", "number", and "date".optionalTypesis an array describing the types of the columns that are optional. The order is important and indicates the sequence that columns are assigned in the Roles tab in VA, after the required columns. Example: ["string", "number", "number"]. Because they are optional, the number of optional columns and optional types provided don't need to match. Type comparison will be made while there is still a column and a type to be compared, and the rest will be ignored. One or more optional columns of same type can be represented as a single type instead of an array, for example: "number" indicates that all optional columns, if existent, must be numeric columns. An empty array [] indicates their types can be anything. A value null indicates no optional columns are accepted. Valid types are "string", "number", and "date".- Returns true or false.
Uses the message received from VA to extract information about selections made in VA objects. After extracting selection information, the "brush" column is removed from the message.
Usage:
selections = va.contentUtil.initializeSelections(resultData)resultDatais the message received from VA (event.data).- Returns
selections, an array of objects containing the indexes of the selected rows (e.g.[{row: 2}, {row: 5}])
Transforms the message received from VA so that date values (represented as strings) are converted to Date objects. This standardizes date representation and might be helpful to support further transformations and formatting on dates.
Usage:
va.contentUtil.convertDateColumns(resultData)resultDatais the message received from VA (event.data).
It contains helper functions you most likely need with Google Charts. You must include the following lines in the <head> of the web page:
<script type="text/javascript" src="https://www.gstatic.com/charts/loader.js"></script>
<script type="text/javascript" src="../thirdPartyHelpers/google.js"></script>Uses the data and columns keys from the VA message to create a DataTable object. Google Charts take DataTable as input data for its charts, but in addition to that, DataTable offers a series of methods that can help with table manipulation. More information on DataTable can be found here.
Usage:
dataTable = va.googleHelper.createDataTable(resultData)resultDatais the message received from VA (event.data).- Returns
dataTable, the input data as a DataTable object.
Uses the columns metadata within the message received from VA to update column formats in a DataTable object. Only numeric and date columns are affected. Supported formats are: DOLLAR, COMMA, F, BEST, and PERCENT for numeric, and MONYY, MMYY, MMDDYY, DATE, DDMMYY, WORDDATE, YYMMDD, and DATETIME for dates. Other column formats are kept unchanged.
Usage:
va.googleHelper.formatData(dataTable, resultData)dataTableis the input data as a DataTable object.resultDatais the message received from VA (event.data).
Uses the columns metadata within the message received from VA to update/add a vAxis.format or a hAxis.format in the Google Charts options variable. Only numeric columns are affected. Supported VA formats are: DOLLAR, COMMA, F, BEST, and PERCENT. Other column formats are kept unchanged.
Usage:
va.googleHelper.formatAxis(axis, options, resultData)axisis a string that indicates a vertical or horizontal axis. Valid axis values are'vAxis'and'hAxis'.optionsis the JSON object that holds Google Charts options.resultDatais the message received from VA (event.data).
It contains helper functions you most likely need with D3 charts. You must include the following line in the <head> of the web page:
<script type="text/javascript" src="../thirdPartyHelpers/d3.js"></script>Uses the columns metadata within the message received from VA to configure D3 formats. Only numeric columns are affected. Supported VA formats are: DOLLAR, COMMA, F, BEST, and PERCENT. Other columns formats are kept unchanged.
Usage:
formatter = va.d3Helper.configureFormatter(resultData)resultDatais the message received from VA (event.data).- Returns
formatter, an object containing key/value pairs where the key is the column label and the value is a d3.format function for each one of the supported numeric columns (e.g.{'Average Sales': d3.format('$6,.2f'), 'Percent Comparison': d3.format('4,.1%')})
Uses the columns metadata within the message received from VA to configure D3 formats. This function is similar to va.d3Helper.configureFormatter, but the format returned doesn't have any decimal places. Only numeric columns are affected. Supported VA formats are: DOLLAR, COMMA, F, BEST, and PERCENT. Other columns formats are kept unchanged.
Usage:
axisFormatter = va.d3Helper.configureAxisFormatter(resultData)resultDatais the message received from VA (event.data).- Returns
axisFormatter, an object containing key/value pairs where the key is the column label and the value is a d3.format function for each one of the supported numeric columns (e.g.{'Average Sales': d3.format('$6,f'), 'Percent Comparison': d3.format('4,%')})
It contains helper functions you most likely need with C3 charts. You must include the following line in the <head> of the web page:
<script type="text/javascript" src="../thirdPartyHelpers/c3.js"></script>Uses the data and columns keys from the VA message to create the chart data JSON object, necessary to draw the C3 chart. If necessary, this function also sets the appropriate configuration to unload the existing chart prior to re-drawing it.
Usage:
chartData = va.c3Helper.configureChartData(resultData, chartType, previousConfig)resultDatais the message received from VA (event.data).chartTypeis the chart type string as defined in C3 documentation.previousConfigis the previouschartDataJSON object that was assigned to thedatakey in functionc3.generate({... , data: , ...})to draw the C3 chart. Information frompreviousConfigis compared with the information fromresultDatato determine if the existing chart must be unload due to changes in the new data received from VA.nullindicates there is no previous configuration (chart was never drawn).- Returns
chartData, a JSON object to be assigned to thedatakey when calling the functionc3.generate({... , data: chartData, ...})to draw the C3 chart. It has the following structure:
{
type: <chartType parameter>,
x: <label of category column>,
rows:[
<array of column labels>,
<array of row1 values>,
... ,
<array of rowN values>
]
keys:{
x: <label of category column>,
value: <array of all numeric columns labels>
}
}