The Aktive Instance

The Aktive object represents a query or a visualization. We can have control of them all the time through the getAllVisualizations() method from the cf object as explained here. From this object we can control all the aspects of a visualization or query by setting or modifying options, parameters and more.

As soon as we use cf.create() or cf.provider() a new Aktive instance will be registered.

Aktive state

Each Aktive object has control on its own state. The state is nothing else than the configuration regarding to options, group bys, filters, metrics, fields...etc, that the object has at a given moment.

Knowing the state of an Aktive instance allows to decide if some specific filters should be applied or not, or if a given option can be changed, among others.

At any moment we can obtain two states: the current and the next. The current state represents the configuration used the last time the Aktive object was executed, so technically is what the visualization "is showing" at the moment. The next state on the other hand is any modification done to the object but it has not been applied yet (has not been executed). Let's say for example we've added a new color but it has not taken effect.

Next and current states will be the same if no new options or configurations have being applied or if the object has not being executed for the first time.

Getting the current and next states

Most of the time we'll be working with single-query visualizations. To obtain the states from them we use the .get() function as the easiest way:

const currentState = aktive.get() 
const currentFilters = aktive.get('config').filters;
const currentColor = aktive.get('color');

const nextState = aktive.get(false, 'next');
const nextFilters = aktive.get('config', 'next').filters;
const nextColor = aktive.get('color', 'next');

When using multi-query visuals, we can still use .get() along with .use()

const currentFirstQuery = aktive.use('first').get();
const nextFirstQuery =  aktive.use('first').get(false, 'next');

API Methods

This object has lots of methods available and you've probably seen most of them in the Quick Start or in the demos.

Most of these methods can be chained since they return the same Aktive instance. Let's take a look at them.

provider(name)

Sets a provider to the Aktive instance. The provider name must exists. Can be chained.

create(name)

Set a name or id to the query so it can be identified at any time and be re-used. Check the multiple queries section for more information. Can be chained.

get(option)

Returns an option or configuration matching the string paratemer passed. If no parameter is specified it returns the full current object configuration. Returns an JSON object so it can not be chained.

let conf = chart.get('config');
let color = chart.get('color');
let fullConf = chart.get();

This method is also used as a shortcut to obtain internal objects such as the visualization or the query configuration. It is fundamental for the Aktive state management described in the Aktive state section.

set(option, config, updateOnly = false)

Sets a configuration to the aktive object. It's usually used at declaration time, but some options can be set after the aktive instance is executed. Check here for more information on how to set options. This method can be chained.

After the aktive instance was executed, let's say a Bar visualization queried and rendered the data, and this method is called over the Bar instance as shown here:

bar.set('orientation', 'horizontal')

This will NOT trigger another query, instead it will re-render the Bar in order to apply the changes. In case that we only want to update the internal configuration without re-rendering, we pass true for the third parameter updateOnly which is false by default.

getCurrentAQL()

Returns the current query configuration. This is useful when we need to obtain the current query from the query configs array.

// Visual is created
const viz = cf.create('my-query')
                .provider('provider')
                .execute();

// Obtain the default query
const defaultQuery = viz.getCurrentAQL();

getAQLConfig(id/pos)

Returns the query configuration based on the id or position. This is particulary useful when multi-query visualizations are used and we need to obtain one of them.

// Visual is created
const multi = cf.create('first')
                .provider('provider')
                ...
                .create('second')
                ...
                .execute()

// Obtain the query based on the id
const first = multi.getAQLConfig('first');
const second = multi.getAQLConfig('second');

// Obtain the query based on position
const first = multi.getAQLConfig(0);
const second = multi.getAQLConfig(1);

If no parameter is specified, it will return all queries.

source(name)

Sets a source matching the name passed as parameter. The source must exist in the data provider. Can be chained.

graph(name)

Indicates what type of visualization to use. Check here for a full list of supported visualizations. This method is not required if we only need the data and not a visualization to be rendered. Can be chained.

element(id)

Specifies the HTML element to be used as the container for the visualization. This method is also used as the main identifier of the Aktive object so it is required. If we only need the query (no visual to be rendered) we must specify any string or identifier. We can later get this instance by using cf.getVisualization(id). Can be chained.

groupby(groups)

Sets the fields or groups to aggregate by. It may receive several Attribute objects or an array of them. Can be chained.

colgroupby(groups)

Sets the fields or groups to aggregate by. This function works together with the groupby() function to obtain results where top-n groups are rendered as rows and top-n column groups are rendered as columns in pivot tables or heat map visualizations. This function may receive several Attribute objects or an array of them. Can be chained. Note: Only one Attribute is currently supported.

timeField(field)

Used only by the Time Slider and the Time Range Filter. Sets the time field to be used by the visualization. Receives an Attribute object. Can be chained.

metrics(metrics)

Sets the metrics to be used. It may receive several Metric objects or an array of them. Can be chained.

fields(metrics)

Sets the fields to be used to create a raw query. Usually used with the Raw Data Table. It may receive several Field objects or an array of them. Can also receive several strings representing the names of the fields. If no fields are specified, all fields will be returned. Can be chained.

filters(filters)

Sets server filters to the visualization. It replaces existing filters. It may receive several Filter objects or an array of them. Can be chained.

filter(filter)

Adds one server filter to the visualization. Receives one Filter object. Can be chained.

staticFilters(filters)

Sets persistent server filters to the visualization. These filters are meant to be set only at declaration time and they are inmutable, so they can not be removed or modified. It may receive several Filter objects or an array of them. Can be chained.

clientFilters(filters)

Sets client filters to the visualization. It may receive several Filter objects or an array of them. For the visualization to take effect it has to be executed again. Can be chained.

updateWithClientFilters()

This method is mostly used internaly by the Toolkit, however it can be useful in some situations. For example let's say we have a bar chart and we want to highlight the bar being hovered by changing the color of the other bars to gray (the same look as if we apply a clientFilters:true rule from the Interaction Manager). In this case we could do something like this:

chart.on('mousemove', event => {
    chart.updateWithClientFilter({
        path: 'field_name',
        operation: 'IN',
        value: [event.data.group[0]]
    })
})

chart.on('mouseleave', () => { chart.updateWithClientFilter()})

removefilters(filters)

Removes the filters passed as paramenter. It receives several strings representing the field name of the filter to be removed. It removes filters and client filters. It does not remove static filters. Can be chained.

textfilter(str)

Applies the text search filter passed as a parameter. It accepts expressions in the format of query strings. This is applicable to data engines based on Apache Lucene such as Elasticsearch. For example, if you'd like to show documents where the "queue" field is not populated, you would accomplish it as below:

let provider = cf.provider("Elasticsearch");
let source = provider.source('agent-activity');
let myData = source.fields();
// Define chart options
myData.textfilter("-queue:[* TO *]");
// Pass the query string to the visual
let myChart = myData.graph("Raw Data Table")
            .set("showRowNumber", true)
            .set("autoSizeColumns", true)
            .element('chart')
            .execute();

staticTextFilter(str)

Applies a persistent text search filter to the visualization. This filter is meant to be set only at declaration time and it is inmutable, so it can not be removed or modified. Can be chained.

onlyWithFilters(...filters)

It specifies one or more filters as a requirement to render the visualization. See the Visualization level description of the Filter Restrictions section in the Interaction Manager document for more details.

onlyWithFiltersMsg(msg)

It specifies a message to render when the filter requirements specified by the .onlyWithFilters(...filters) function are not met. Its default value is "This visualization requires some filters to be rendered.". See the Visualization level description of the Filter Restrictions section in the Interaction Manager document for more details.

limit(value)

Specifies the limit of a query or visualization. It receives a number as a paramenter. Can be chained.

data(data)

Injects data to the visualization. This is only used when working with Custom Data. Can be chained.

execute()

This is the method that performs the query and renders the visualization (if any). Until this method is not called for an Aktive instance nothing will happen and the object will be inactive. Returns a Javascript promise that, when resolved, will contain the data (if any) queried.

This function is used with no parameters in most cases. The parameters below are used only special scenarios.

Parameters:

query - true by default and it means that data will be re-queried before rendering the visualization. false means that it will just re-rendered the visualization without re-quering data. Note that calling the set() function to set visualization options after the aktive instance was executed will automatically update the visualization without re-triggering another query so you don't need to call execute(false) explicitly. See the set() function documentation for more details.

buildOptions - false by default. Only applicable when query is false. Set it to true when you change a Metric or Attribute configuration and want to re-render the visualization without re-quering. An example is when you are building a chart editor and want to update the visualization to hide its metric function (e.g. sum, avg) from the tooltips and axis by calling the cf.Metric().hideFunction(). In this case, because you changed a measure object, the execute() function would automatically re-query data. You can call execute(false, true) to re-build the query options to take into account the Metric configuration change and re-render the visualziation without re-quering.

on(event, callback)

Creates a listener for the event name passed as parameter using the callback function. Please refer to the events section for more information about them. Can be chained.

once(event, callback)

Same as .on() but the event will be catched only once and then the listener will be deleted.

off(event, callback)

Removes an event listeners. To be succesfully removed the callback has to be exactly the same function (same variable, which means same memory address) when it was created.

resize()

Resizes the visualization (if any). Usually used under a resize event like for example windows.resize

$(window).on('resize', function () {
    aktive.resize();
});

remove()

Deletes the Aktive object. It will be also unregistered from the cf object. Cannot be chained.

duplicate()

Duplicates the Aktive object. The new object has the same configuration but a new element id must be assigned. Returns the copy.

getFields(type, subtype)

Returns the fields from the source used in the visualization or query matching the type: attributes or metrics and the subtype: 'ATTRIBUTE', 'TIME', 'NUMBER', 'MONEY', 'INTEGER', 'PERCENT'. If not type or subtype are specified all fields will be returned.

let timeFields = aktive.getFields('attribute', 'TIME');
let percentFields = aktive.getFields('metrics', 'PERCENT');
let metrics = aktive.getFields('metrics');
let allFields = aktive.getFields();

getProvider()

Returns the provider object used in the visualization. Depends on the data provider used.

use(queryID, silenceOthers = false)

This function is useful when using the multiple queries feature of an Aktive instance. It sets the query identified with the queryID string as the current query. The silenceOthers boolean parameter allows to skip the execution of other queries in the Aktive instance for the next execution.

useOnly(queryID)

This function is useful when using the multiple queries feature of an Aktive instance. It sets the query identified with the queryID string as the current query and it silences any other query configuration so that you only execute the current query. After the execution, all queries will be un-silenced again. This section shows how to use the useOnly() function. This function is equivalent to aktive.use(queryID, true);