This repository has been archived by the owner on Jan 10, 2020. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 8
Visualization Superclass API
Thomas Schellenberg edited this page Mar 14, 2016
·
2 revisions
Version 1.2
Created by the Next Century Neon Development Team
- Introduction
- Superclass Properties
- Superclass Abstract Functions
- Superclass Utility Functions
- Single Layer Superclass Abstract Functions
- Single Layer Superclass Utility Functions
- Multiple Layer Superclass Properties
- Multiple Layer Superclass Abstract Functions
- Multiple Layer Superclass Utility Functions
The Visualization Superclass is an angular controller and directive that defines behavior, functions, and properties that are used by all of the visualizations in the Neon Dashboard*. The superclass is created by the Visualization Widget; in turn, it creates the controller for a specific Superclass Implementation, a controller for a specific Visualization, and multiple directives for that visualization. The superclass implementation defines specific behavior and overrides superclass functions needed for a specific subset of the visualizations. The visualization defines the its own behavior using the properties, abstract functions and utility functions defined in the superclass and superclass implementation.
The hierarchy is as follows:
<visualization-widget>
<visualization-superclass>
<div ng-controller="superclassImplementationController">
<div ng-controller="visualizationController">
// Template and visualization directives
* Except the Filter Builder due to its unique design and layout.
Two superclass implementations are currently available: the Single Layer implementation and the Multiple Layer implementation. The single layer implementation is used by visualizations that only display data from a single table in a single database at a time. The multiple layer implementation is used by visualizations that can display data from multiple tables and multiple databases at the same time.
The following Single Layer Visualizations are currently available:
- Aggregation Table
- Bar Chart
- Data Table
- Gantt Chart
- Network Graph
- News Feed
- Ops Clock
- Scatter Plot
- Sunburst Chart
- Text Cloud
- Timeline
The following Multiple Layer Visualizations are currently available:
- Line Chart
- Map
Each visualization has at least three angular directives: a Visualization Display, Visualization Headers, and Visualization Options. Each multiple layer visualization has a fourth angular directive: Visualization Layer Options. Each of these directives has its own template but none of them have an angular controller; instead, they are all controlled by the single visualization controller created by the superclass.
New visualizations should be created using the visualization superclasss. Properties and functions that are needed in the angular template should be defined on $scope.active and $scope.functions respectively. Superclass abstract functions (as listed in the API below) should be overwritten through $scope.functions as needed.
The following properties are defined on $scope.active. They are referenced by functions in the superclass. They should be set by visualizations as needed.
/**
* Whether this visualization allows translations of its text.
* @property allowsTranslations
* @type Boolean
* @default false
*/
/**
* Whether the display of this visualization overlaps its headers.
* @property displayOverlapsHeaders
* @type Boolean
* @default false
*/
The following functions are defined on $scope.functions as stubs. They are called by functions in the superclass. They should be overridden by visualizations as needed.
/**
* Adds properties to the given collection of bindings and returns the updated collection for this visualization.
* @method addToBindings
* @param {Object} bindings
* @return {Object}
*/
$scope.functions.addToBindings = function(bindings) {
return bindings;
};
/**
* Adds properties to the given Neon query and returns the updated query for the given layers.
* @method addToQuery
* @param {neon.query.Query} query
* @param {Array} layers
* @return {neon.query.Query}
*/
$scope.functions.addToQuery = function(query) {
return query;
};
/**
* Returns whether the data fields in the given layers are valid in order to execute a query.
* @method areDataFieldsValid
* @param {Array} layers
* @return {Boolean}
*/
$scope.functions.areDataFieldsValid = function(layers) {
return true;
};
/**
* Returns the description text for the global filter data object to show in the filter tray (usually containing the database, table, fields and filter value).
* @method createFilterTrayText
* @param {String} databaseName
* @param {String} tableName
* @param {Array} fieldNames
* @return {String}
*/
$scope.functions.createFilterTrayText = function() {
return "";
};
/**
* Creates and returns the text for the options menu button.
* Called by the options-menu directive.
* @method createMenuText
* @return {String}
*/
$scope.functions.createMenuText = function() {
return "";
};
/**
* Creates and returns the Neon where clause for a Neon filter on the given database, table, and fields using the filters set in this visualization.
* Called by the Filter Service.
* @method createNeonFilterClause
* @param {Object} databaseAndTableName Contains {String} database and {String} table
* @param {String} fieldName or {Array} fieldNames The name (or list of names) of the filter fields
* @return {neon.query.WhereClause}
*/
$scope.functions.createNeonFilterClause = function(databaseAndTableName, fieldName) {
return neon.query.where(fieldName, "!=", null);
};
/**
* Creates and returns the Neon where clause for queries for the given layers (or returns undefined).
* @method createNeonQueryWhereClause
* @param {Array} layers
* @return {neon.query.WhereClause}
*/
$scope.functions.createNeonQueryWhereClause = function() {
return undefined;
};
/**
* Executes the given query using the given connection.
* @method executeQuery
* @param {Object} connection
* @param {neon.query.Query} query
*/
$scope.functions.executeQuery = function(connection, query) {
return connection.executeQuery(query);
};
/**
* Returns the list of field objects on which filters for given layer are set.
* @method getFilterFields
* @param {Object} layer
* @return {Array}
*/
$scope.functions.getFilterFields = function() {
return [];
};
/**
* Returns whether a filter is set in this visualization.
* @method isFilterSet
* @return {Boolean}
*/
$scope.functions.isFilterSet = function() {
return false;
};
/**
* Returns whether to hide the headers in the filter header container for this visualization. The default implementation hides the headers if a filter is not set.
* @method hideHeaders
* @return {Boolean}
*/
$scope.functions.hideHeaders = function() {
return !$scope.functions.isFilterSet();
};
/**
* Returns whether the filter displayed by this visualization needs to be updated based on the given list of Neon filters set in the dashboard.
* @method needToUpdateFilter
* @param {Array} of {neon.query.Filter} neonFilters
* @return {Boolean}
*/
$scope.functions.needToUpdateFilter = function() {
return false;
};
/**
* Handles any additional behavior for changing an option in this visualization.
* @method onChangeOption
*/
$scope.functions.onChangeOption = function() {
// Do nothing by default.
};
/**
* Handles any additional behavior for deleting the given layer from this visualization.
* @method onDeleteLayer
* @param {Object} layer
*/
$scope.functions.onDeleteLayer = function(layer) {
// Do nothing by default.
};
/**
* Handles any additional behavior for destroying this visualization.
* @method onDestroy
*/
$scope.functions.onDestroy = function() {
// Do nothing by default.
};
/**
* Handles any additional behavior for responding to a query error.
* @method onError
* @param {Object} response The query response
* @param {Object} errorCodes An object containing the error codes important to the Neon Dashboard
*/
$scope.functions.onError = function() {
// Do nothing by default.
};
/**
* Handles any additional behavior for initializing this visualization.
* @method onInit
*/
$scope.functions.onInit = function() {
// Do nothing by default.
};
/**
* Handles any additional behavior for resizing this visualization.
* @method onResize
* @param {Number} elementHeight The height of the visualization element
* @param {Number} elementWidth The width of the visualization element
* @param {Number} titleHeight The height of the text container for the title
* @param {Number} containersHeight The height of all text containers in the visualization
*/
$scope.functions.onResize = function() {
// Do nothing by default.
};
/**
* Handles any behavior for changing the theme of elements in this visualization to the given theme.
* @method onThemeChanged
* @param {Object} theme
* @return {Boolean} Whether them theme of any elements in this visualization needed to be changed
*/
$scope.functions.onThemeChanged = function() {
return false;
};
/**
* Handles any additional behavior for updating the fields for the given layer.
* @method onUpdateFields
* @param {Object} layer
*/
$scope.functions.onUpdateFields = function() {
// Do nothing by default.
};
/**
* Removes the filter displayed by this visualization.
* @method removeFilterValues
*/
$scope.functions.removeFilterValues = function() {
// Do nothing by default.
};
/**
* Removes all translations from this visualization.
* @method removeTranslations
*/
$scope.functions.removeTranslations = function() {
// Do nothing by default.
};
/**
* Returns whether this visualization should query for new data and update its display after changing its filter.
* @method shouldQueryAfterFilter
* @return {Boolean}
*/
$scope.functions.shouldQueryAfterFilter = function() {
return false;
};
/**
* Returns whether to show the text for the options menu button.
* Called by the options-menu directive.
* @method showMenuText
* @return {Boolean}
*/
$scope.functions.showMenuText = function() {
return false;
};
/**
* Updates the data and display in this visualization using the given data for the given layers. Removes all data from the display instead if the arguments are undefined.
* @method updateData
* @param {Array} data
* @param {Array} layers
*/
$scope.functions.updateData = function() {
// Do nothing by default.
};
/**
* Updates the filter displayed by this visualization on the fields with the given names using the where clause in the given Neon filter.
* @method updateFilterValues
* @param {neon.query.Filter} neonFilter
* @param {Array} fieldNames
*/
$scope.functions.updateFilterValues = function() {
// Do nothing by default.
};
/**
* Updates all translations in this visualization.
* @method updateTranslations
*/
$scope.functions.updateTranslations = function() {
// Do nothing by default.
};
The following functions are defined on $scope.functions. They can be called by functions in the visualization. They should not be overridden!
/**
* Adds a resize listener defined by the superclass to the given jQuery element in this visualization.
* @method addResizeListener
* @param {String} element
*/
/**
* Returns whether any of the external application services are active.
* @method areExternalServicesActive
* @return {Boolean}
*/
$scope.functions.areExternalServicesActive = function() {
return external.active;
};
/**
* Creates and returns the links for the given external service type, link data, link key, and link source.
* @method createLinksForData
* @param {String} type The type of external application
* @param {Object} data The data on which to create the links
* @param {String} key The unique key to save the new links in the links popup service
* @param {String} [source=$scope.visualizationId] (Optional) The unique source to save the new links in links popup service
* @return {Boolean} Whether any links were created
*/
/**
* Returns the options for the active dataset.
* @method getDatasetOptions
* @return {Object}
*/
/**
* Returns the jQuery element in this visualization matching the given string, or the element for this visualization itself if no string is given.
* @method getElement
* @param {String} element
* @return {Object}
*/
/**
* Returns the config for the linky library.
* @method getLinkyConfig
* @return {Object}
*/
/**
* Returns the links popup service object.
* @method getLinksPopupService
* @return {Object}
*/
/**
* Returns whether the given Neon filter object is a single clause filter.
* @method getNumberOfFilterClauses
* @param {neon.query.Filter} filter
* @return {Boolean}
*/
/**
* Returns whether the given field object is valid.
* @method isFieldValid
* @param {Object} fieldObject
* @return {Boolean}
*/
/**
* Logs a change of the given option to the given value using an element of the given type, runs a new query and updates the data in this visualization.
* @method logChangeAndUpdate
* @param {String} option The name of the changed visualization option for the log message
* @param {String} value The new value of the changed visualization option for the log message
* @param {String} [type=combobox] (Optional) The type of HTML element that was used to trigger the change
*/
/**
* Publishes an event with the given type and data using the messenger for this visualization.
* @method publish
* @param {String} type
* @param {Object} data
*/
/**
* Builds and executes a query and updates the data for this visualization using the given options.
* @method queryAndUpdate
* @param {Object} [options] The collection of function arguments.
* @param {String} [options.databaseName] (Optional) The name of a databse. If not given, queries and updates all layers.
* @param {String} [options.tableName] (Optional) The name of a table. If not given, queries and updates all layers.
* @param {Function} [options.addToQuery=$scope.functions.addToQuery] (Optional) The function to help build the Neon query. If not given, it uses $scope.functions.addToQuery.
* @param {Function} [options.executeQuery=$scope.functions.executeQuery] (Optional) The function to execute the Neon query. If not given, it uses $scope.functions.executeQuery.
* @param {Function} [options.updateData=$scope.functions.updateData] (Optional) The function to update the data in this visualization. If not given, it uses $scope.functions.updateData.
*/
/**
* Removes the links for the given field object and value, or all links for this visualization if no field or value are given.
* @method removeLinks
* @param {Object} [field] (Optional)
* @param {String} [value] (Optional)
*/
/**
* Removes the Neon filter from the dashboard on all filterable layers in this visualization.
* @method removeNeonFilter
* @param {Boolean} [queryAfterFilter=false] (Optional)
*/
/**
* Translates the given data for this visualization using the global to/from languages and the given success/failure callbacks.
* @method runTranslation
* @param {Array} data
* @param {Function} [translationSuccessCallback] (Optional)
* @param {Function} [translationFailureCallback] (Optional)
*/
/**
* Subscribes the messenger for this visualization to events with the given type using the given listener.
* @method subscribe
* @param {String} type
* @param {Function} listener
*/
/**
* Adds or replaces the Neon filter in the dashboard on all filterable layers based on the filter values set in this visualization.
* @method updateNeonFilter
* @param {Boolean} [queryAfterFilter=false] (Optional)
*/
The following functions are defined on $scope.functions for visualizations using the single layer superclass implementation. They are called by functions in the superclass. They should be overridden by visualizations as needed.
/**
* Creates and returns an object containing the data needed to export this visualization.
* @method createExportDataObject
* @param {String} exportId
* @param {neon.query.Query} query
* @return {Object}
*/
$scope.functions.createExportDataObject = function() {
return {};
};
The following functions are defined on $scope.functions for visualizations using the single layer superclass implementation. They can be called by functions in the visualization. They should not be overridden!
/**
* Creates and returns the links for the given field object and item object.
* @method createLinks
* @param {Object} field The field object on which to create the links containing {String} columnName
* @param {String} value The value on which to create the links
* @return {Boolean} Whether any links were created
*/
/**
* Creates and returns the link buttons for the given field object and data array.
* @method createLinkButtons
* @param {Object} field The field object on which to create the link containing {String} columnName
* @param {Array} array A list of objects each containing a property matching the field name
* @return {Array} The list of link buttons as HTML strings
*/
/**
* Finds and returns the field object in the global list of fields that matches the binding or mapping with the given key.
* Returns a blank field object if no such field exists.
* @method findFieldObject
* @param {String} bindingKey The name of a visualization binding that may contain a field name
* @param {String} mappingKey The name of a Neon mapping that may contain a field name
* @return {Object}
*/
/**
* Returns the color maps for the field with the given name.
* @method getColorMaps
* @param {String} fieldName
* @return {Object}
*/
/**
* Returns the filter key for the given Neon filter clause.
* @method getFilterKey
* @param {Object} filterClause
* @return {String}
*/
/**
* Returns the mapping for the given key or any empty string if no mapping exists.
* @method getMapping
* @param {String} key
* @return {String}
*/
/**
* Returns the list of unsorted fields (in the order they are defined in the dashboard configuration).
* @method getUnsortedFields
* @return {Array}
*/
The following properties are defined on $scope.active for visualizations using the multiple layer superclass implementation. They are referenced by functions in the superclass. They should be set by visualizations as needed.
/**
* Whether this visualization should query for data in all data layers with the same database and table with a single query instead of querying for data in each data layer with an individual query.
* @property queryByTable
* @type Boolean
* @default false
*/
The following functions are defined on $scope.functions for visualizations using the multiple layer superclass implementation. They are called by functions in the superclass. They should be overridden by visualizations as needed.
/**
* Adds properties to the given collection of layer bindings using the given layer and returns the updated collection for this visualization.
* @method addToLayerBindings
* @param {Object} bindings
* @param {Object} layer
* @return {Object}
*/
$scope.functions.addToLayerBindings = function(bindings, layer) {
bindings.name = layer.name;
return bindings;
};
/**
* Adds properties to the given layer object specific to this visualization and returns the updated layer.
* @method addToNewLayer
* @param {Object} layer
* @return {Object}
*/
$scope.functions.addToNewLayer = function(layer) {
return layer;
};
/**
* Creates and returns an object containing the data needed to export this visualization.
* @method createExportDataObject
* @param {String} exportId
* @param {Array} queryData A list of objects containing {String} database, {String} table, and {neon.query.Query} query
* @return {Object}
*/
$scope.functions.createExportDataObject = function() {
return {};
};
/**
* Handles any additional behavior for reordering the layers in this visualization.
* @method onReorderLayers
*/
$scope.functions.onReorderLayers = function() {
// Do nothing by default.
};
/**
* Handles any additional behavior for toggling the show setting for the given layer.
* @method onToggleShowLayer
* @param {Object} layer
*/
$scope.functions.onToggleShowLayer = function(layer) {
// Do nothing by default.
};
/**
* Updates the display in this visualization for the given layer after its options have been changed.
* @method updateLayerDisplay
* @param {Object} layer
*/
$scope.functions.updateLayerDisplay = function(layer) {
// Do nothing by default.
};
The following functions are defined on $scope.functions for visualizations using the multiple layer superclass implementation. They can be called by functions in the visualization. They should not be overridden!
/**
* Creates a new data layer for this visualization using the dataset defaults and set in new & edit mode.
* @method createLayer
*/
/**
* Creates and returns the links for the given field object and item object in the database and table with the given names.
* @method createLinks
* @param {String} databaseName
* @param {String} tableName
* @param {Object} field The field object on which to create the links containing {String} columnName
* @param {String} value The value on which to create the links
* @return {Boolean} Whether any links were created
*/
/**
* Creates and returns the link buttons for the given field object and data array in the database and table with the given names.
* @method $scope.functions.createLinkButtons
* @param {String} databaseName
* @param {String} tableName
* @param {Object} field The field object on which to create the link containing {String} columnName
* @param {Array} array A list of objects each containing a property matching the field name
* @return {Array} The list of link buttons as HTML strings
*/
/**
* Deletes the given layer, removing its filter and updating this visualization.
* @method deleteLayer
* @param {Object} layer
* @param {Number} indexReversed The index of the layer in the list of layers (reversed).
*/
/**
* Finds and returns the field object in the fields in the given layer that matches the given field name or mapping with the given key.
* Returns a blank field object if no such field exists.
* @param {String} fieldName A field name to find in the list of fields in the given layer
* @param {String} mappingKey The name of a Neon mapping that may contain a field name
* @param {Object} layer
* @return {Object}
*/
/**
* Returns the color maps for the database and table in the given layer and the field with the given names.
* @method getColorMaps
* @param {Object} layer
* @param {String} tableName
* @param {String} fieldName
* @return {Object}
*/
/**
* Returns the filter key for the database and table in the given layer and the given Neon filter clause.
* @method getFilterKey
* @param {Object} layer
* @param {Object} filterClause
* @return {String}
*/
/**
* Returns the mapping for the database, table, and key with the given names or any empty string if no mapping exists.
* @method getMapping
* @param {String} databaseName
* @param {String} tableName
* @param {String} key
* @return {String}
*/
/**
* Returns the list of unsorted fields for the database and table in the given layer (in the order they are defined in the dashboard config).
* @method getUnsortedFields
* @param {Object} layer
* @return {Array}
*/
/**
* Moves the given layer to the given new index and reorders the other layers as needed.
* @method reorderLayer
* @param {Object} layer
* @param {Number} newIndexReversed The new index of the layer in the list of layers (reversed).
*/
/**
* Toggles editing on the given layer.
* @method toggleEditLayer
* @param {Object} layer
*/
/**
* Toggles filtering on the given layer.
* @method toggleFilterLayer
* @param {Object} layer
*/
/**
* Toggles showing the given layer.
* @method toggleShowLayer
* @param {Object} layer
*/
/**
* Gets the list of fields from the dataset service and sets the active fields for the given layer.
* @method updateFields
* @param {Object} layer
* @private
*/
/**
* Updates the properties for the given layer, removes it from new & edit mode, updates its filter, queries for new data and updates this visualization.
* @method updateLayer
* @param {Object} layer
*/
/**
* Gets the list of tables from the dataset service and sets the active table and fields for the given layer.
* @method updateTables
* @param {Object} layer
*/
/**
* Validates the name of the given layer, setting its error property if the name is not unique.
* @method validateLayerName
* @param {Object} layer
* @param {Number} indexReversed The index of the layer in the list of layers (reversed).
*/