org.visallo.dashboard.item

Add items that can be placed on dashboards

Allow custom content to be rendered in a card on dashboards. They can be included in defaults dashboards using the org.visallo.dashboard.layout extension, or added manually by users using the "Add Item" button when editing dashboards.

The bundled items are defined in registerDefaultItems.js for examples.

Either componentPath or report is required.

Report

Instead of specifying a component to render, specify a report template that requests data from the server and passes the results to a org.visallo.dashboard.reportRenderer that can handle that data. The most common report uses search with aggregations configured.

An item can be a report if either:

  • The extension defines the report
  • a component registered with componentPath saves a report inside the items configuration, e.g. item.configuration.report = { ... }

Example

Report of Entity Type Counts

registry.registerExtension('org.visallo.dashboard.item', {
    title: 'Entity Type Counts',
    description: 'Show total counts for entity types',
    identifier: 'org-example-concept-counts',
    report: {
        defaultRenderer: 'org-visallo-pie',
        endpoint: '/vertex/search',
        endpointParameters: {
            q: '*',
            size: 0,
            filter: '[]',
            aggregations: [
                {
                    type: 'term',
                    name: 'field',
                    field: 'http://visallo.org#conceptType'
                }
            ].map(JSON.stringify)
        }
    }
});

Registration

registry.registerExtension("org.visallo.dashboard.item", config)

Source:
Tutorials:
See:
Configuration Properties:
Name Type Attributes Description
identifier string

Unique identifier for this type of dashboard item. Only used internally, not exposed to user.

title string

The title shown in "Add Item" list

description string

Shown under the title in "Add Item" list

report object <optional>

Use Visallo reportRenderers to render a search aggregation

Properties
Name Type Attributes Description
defaultRenderer string <optional>

The identifier of a report renderer to use as default when adding this item.

endpoint string

The endpoint path to access the data. See Router for all available endpoints.

endpointParameters object <optional>

Parameters to pass to endpoint. Parameters when using search: org.visallo.dashboard.item~reportParametersForSearch

mapping object <optional>

Custom configuration for mapping results

Properties
Name Type Attributes Description
transformerModulePath string <optional>

RequireJS path to function that can transform the endpoint results to something a reportRenderer can handle. Only necessary if aggregations or search aren't used.

clickHandlerModulePath string <optional>

RequireJS path to a function that handles click events. Called with arguments: target, object.

componentPath string <optional>

The path to the Component to render when the user selects this item from the list.

configurationPath string <optional>

The path to the ConfigComponent. Provides custom interface displayed in the configuration popover, when the user clicks the gear icon in the items toolbar.

grid object <optional>

Default sizing of item in grid

Properties
Name Type Attributes Description
width number <optional>

Default width of item in grid units when added 1-12

height number <optional>

Default height of item in grid units when added >0

options object <optional>
Properties
Name Type Attributes Default Description
flushContent boolean <optional>
false

By default all cards get some default content padding, settings this to true will remove the padding.

preventDefaultConfig boolean <optional>
false

Set to true to disable the system adding a title configuration form.

Validation Function

Extensions registered must pass this validation check to be used.

function extensionValidator(e) {
    return _.isString(e.identifier) && (_.isString(e.componentPath) || _.isObject(e.report)) && e.title && e.description;
}

Type Definitions

aggregation

Source:

term Group by value of field and return counts.

geohash Group by value of field with geohash precision (required) and return counts.

histogram Group range (specified by interval (required)) of values and their counts.

statistics Statistics for property: min, max, count, average, sum.

Properties:
Name Type Description
type string

Type of aggregation: term, geohash, histogram

name string

Name the aggregation that's returned with results. Useful when more than one aggregation is used.

field string

Property name iri to aggregate.

Component

Source:

FlightJS or React component that renders the card content.

For Flight, trigger an event with the name of the function instead of invoking directly.

Properties:
Name Type Attributes Description
extension object
item object
reportConfiguration object <optional>
report object <optional>
showError function

Render a generic error instead of this component

finishedLoading function

Notify that content is ready (removes loading spinner)

configureItem function

Open the configuration popover for this card

configurationChanged configurationChanged

Change the configuration

Listens:
Examples

React Notify Finished

componentDidMount() {
    this.props.finishedLoading();
}

React Change Configuration

handleClick() {
    const { item, extension } = this.props;
    const updated = getUpdatedConfiguration();
    this.props.configurationChanged({
        item: { ...item, configuration: updated },
        extension
    });
}

FlightJS Notify Finished

this.after('initialize', function() {
    this.trigger('finishedLoading');
})

FlightJS Change Configuration

this.after('initialize', function() {
   this.on('click', function() {
       // ... update item.configuration
       this.trigger('configurationChanged', {
           item: item,
           extension: extension
       });
   })
})

ConfigComponent

Source:

FlightJS or React component that renders card configuration content.

For Flight, trigger an event with the name of the function instead of invoking directly.

Properties:
Name Type Attributes Description
extension object
item object
report object <optional>
configurationChanged configurationChanged

Change the configuration

configurationChanged(data)

Source:
Parameters:
Name Type Description
data object
Properties
Name Type Attributes Description
item object
extension object
options object <optional>
Properties
Name Type Attributes Description
changed string <optional>

What key changed (if item.title only the card title is updated)

filter

Source:
Properties:
Name Type Attributes Description
propertyName string

Iri of property name to filter.

predicate string

Type of filter operation has, hasNot, equal, contains, range, <, >

values Array.<object> <optional>

The values for the property length of 2 when range filter, usually 1

reportParametersForSearch

Source:

These work for search endpoints

  • vertex/search: Only return vertices.
  • edge/search: Only return edges.
  • element/search: Search both vertices and edges.
Properties:
Name Type Attributes Description
q string

Search query, or asterisk.

size number <optional>

Number of results to limit to, use 0 if using aggregations.

offset number <optional>

Index of results to start.

filter string

JSON array of org.visallo.dashboard.item~filter objects to AND.

aggregations Array.<string> <optional>

List of org.visallo.dashboard.item~aggregation to apply, each item is json string. The aggregations should be converted from objects to strings. See example.

Example
{
    q: '*',
    size: 0,
    filter: '[]',
    aggregations: [
        {
            type: 'term',
            name: 'field',
            field: 'http://visallo.org#conceptType'
        }
    ].map(JSON.stringify) // Convert each item to strings
}

Events

reflow

Source:

Dashboard requests card to reflow because its container size has changed.

Consider using _.throttle or _.debounce to limit the cost of many reflow events from user resizing.

Listeners of This Event:

refreshData

Source:

The dashboard includes a refresh button in the top left. When activited, needs to notify cards to update content if necessary.

Listeners of This Event: