Connecting to data
There are two required parameters for connecting to data: CSV_DataTypes.cells (specifies the data attributes) and tm.data_provider.info (specifies the location of the data). Both parameters are described in detail below. In addition, there are optional parameters for enabling live updates to the data (no page refresh).
CSV_DataTypes.cells
Description: Specifies the data type for each column of data. Entries do not have to be in the same order as those in the data source header row.
Value: {value_name1}|{data_type_definition},{value_name2}|{data_type_definition}, ... {value_nameN}|{data_type_definition}
| {value_name} | Any attribute from the dataset. |
|---|---|
| {data_type_definition} | There are four possible values, depending on how {value_name} will be used in the treemap: Value Description NUMBER Numeric data TEXT Text data TEXT|ENUM Enumerated text data, allows Flaremap to automatically create groups and filters. Required for any attribute that will be automatically grouped by Flaremap. DATE|{date_format} Date and time formatted data. See below for details on {date_format} |
{date_format}
Description: When using date/time formatted attributes, the date/time format used by the database (i.e. the input format) needs to be specified. Flaremap JS supports a wide range of date/time formats. To specify the date/time format use a pattern string made up of the following symbols.
| Symbol | Meaning | Presentation | Example |
|---|---|---|---|
| G | era designator | Text | AD |
| y | year | Number | 1996 |
| M | month in year | Text & Number | July & 07 |
| d | day in month | Number | 10 |
| h | hour in am/pm (1~12) | Number | 12 |
| H | hour in day (0~23) | Number | 0 |
| m | minute in hour | Number | 30 |
| s | second in minute | Number | 55 |
| S | millisecond | Number | 978 |
| E | day in week | Text | Tuesday |
| D | day in year | Number | 189 |
| F | day of week in month | Number | 2 (2nd Wed in July) |
| w | week in year | Number | 27 |
| W | week in month | Number | 2 |
| a | am/pm marker | Text | PM |
| k | hour in day (1~24) | Number | 24 |
| K | hour in am/pm (0~11) | Number | 0 |
Note: The pattern of symbols determine the format. For example:
| d | = | 2 |
|---|---|---|
| dd | = | 02 |
| M | = | 8 |
| MM | = | 08 |
| MMM | = | Aug |
| MMMM | = | August |
Example: "CSV_DataTypes.cells": "Sales_Rep|TEXT,Sales_Manager|TEXT|ENUM, Sales_Region|TEXT|ENUM,Total_Sales_Q4|NUMBER,Quota_Q4|NUMBER, Quota_Percent|NUMBER,Start_Date|DATE|yyyy-MM-dd",
tm.data_provider.info
Description: Specifies the type of data connection being made and the location of the data. For details on complying with the “Same-Origin” Policy, see the special note at the end of this section.
Value: The value will depend on the format of data being used. See below.
Value: For JS formatted data:
JS_URL={path_to_data}[|JS_VAR_NAME={js_var}]
| {path_to_data} | Path to JS formatted data. |
|---|---|
| {js_var} | Optional: Specifies the name of the variable used in the JS data file to define the data. If no variable is defined, the variable “flaremapData” is expected. |
Example: For JS formatted data:
"tm.data_provider.info": "JS_URL=salesforceData.js",
"tm.data_provider.info": "JS_URL=salesforceData.js| JS_VAR_NAME=myCustomDataVariable",
Value: For JSON formatted data:
JS_URL={path_to_data}
| {path_to_data} | Path to JS formatted data. |
|---|
Example: For JSON formatted data:
"tm.data_provider.info": "JS_URL=data/salesforce.json",
For JSON formatted data: Nested structures are supported by using a period to separate each level of the hierarchy. For example, the attributes present in the data below are: "Sales_Rep", "Sales_Manager.mgr1", "Sales_Manager.mgr2", "Sales_Manager.mgr3", "Quota_Q4" .
var flaremapData = [
{
'Sales_Rep': 'Vincent Iorio',
'Sales_Manager': {
'mgr1': 'Albert',
'mgr2': 'Dennis',
'mgr3': 'Jack',
},
'Quota_Q4': 535000,
},
];
Value: For CSV formatted data:
CSV_URL={path_to_data}
| {path_to_data} | Path to CSV formatted data. |
|---|
Example: For CSV formatted data:
"tm.data_provider.info": "CSV_URL=data/salesforce.csv",
Value: For Copy/Paste data:
DIV_ID={div_in_html}
In the core HTML, insert a hidden DIV (see example below), then paste CSV formatted data into the DIV. The data must be in comma separated format.
| {div_in_html} | Name of the DIV ID in the core HTML that contains the data. |
|---|
Example: For Copy/Paste data:
"tm.data_provider.info": "DIV_ID=flaremapData",
In the core HTML, an example DIV (including data) is below:
<div id="flaremapData" style="display:none;">
Sales_Rep,Sales_Manager,Quota_Q4,Quota_Percent
Brett Black,Albert Bachman III,614000,78
Vincent Iorio,Albert Bachman III,535000,66
Henry Bateman,Albert Bachman III,433000,117
Mike Cowgill,Albert Bachman III,641000,97
</div>
tm.data_provider.loader
Description: The “Data Loader” enables the connection to an external data source, and complies with the “Same-Origin Policy” implemented in modern browsers. For a sample Data Loader, see the file: csvConnect.jsp. This parameter can be omitted in many circumstance – please read the special note on “Same-Origin” Policy (located at the end of this section) for details on when this parameter can be omitted.
Value: CSV_LOADER={path_to_loader}
| {path_to_loader} | Path to Data Loader. |
|---|
Example: "tm.data_provider.loader": "CSV_LOADER=https://myserver.com/data_loader/csvConnect.jsp",
Special Note: “Same-Origin” Policy
Summary: The “Same-Origin” Policy is implemented in all modern browsers. The Policy enforces that all data accessed by a web page must come from the same origin. An origin is defined as a combination of URI scheme, hostname, and port number. This is important to keep in mind when accessing data from different servers and when accessing local data. For example, most browsers consider all file:// URLs as having different origins. Complying with the “Same-Origin” Policy is easy. See the table below for some of the options available.**
Quick reference sheet for complying with "Same-Origin" Policy
| Type of data and URL used by "tm.data_provider.info" parameter | Application is running from local desktop | Application is running on a server |
|---|---|---|
| Copy/Paste (DIV_ID=...) | ✓ Complies | ✓ Complies |
| JS, relative URL (JS_URL=...) | ✓ Complies | ✓ Complies |
| JS, http URL (JS_URL=http://...) | ✓ Complies | ✓ Complies |
| CSV, relative URL (CSV_URL=...) | Does not comply with "Same-Origin" Policy | ✓ Complies |
| CSV, http URL (CSV_URL=http://...) | ✓ Complies with use of Data Loader | ✓ Complies with use of Data Loader |
| Data Loader parameter (tm.data_provider.loader) | Application is running from local desktop | Application is running on a server |
| URL Options | URL must start with http | URL can be relative or start with http |
tm.data_provider.refresh.basic.interval
Description: Specifies a time interval (in milliseconds) at which the data set should be re-loaded and merged into the existing set. New rows are added, existing are updated, and missing rows are removed. In order to define how a row is determined to be new, existing, or missing, a list of "unique key" columns must be specified by the "tm.data_provider.unique_key" parameter.
Value: {number_of_milliseconds}
| {number_of_milliseconds} | An integer corresponding to the number of desired milliseconds between each data refresh attempt. |
|---|
Example: "tm.data_provider.refresh.basic.interval": "60",
tm.data_provider.unique_key
Description: Specifies a list of column names that, collectively, uniquely define a row: if a row added after page load shares identical values with an existing row for each of these columns, the new row will replace the existing row. If such a row does not match any existing rows in all of these columns, it will be considered new and added to the existing data set.
Value: {column_name_1},...,{column_name_N}
| {column_name} | The name of a column that exists in the list specified by the CSV_DataTypes.cells parameter. |
|---|
Example: "tm.data_provider.unique_key": "Sales_Rep,Sales_Manager",