@carto/airship-bridge/dist/vl/VLBridge.d.ts

Airship bridge to other libs (CARTO VL, CARTO.js)

import { AnimationControlsOptions, AnimationOptions, CategoricalHistogramOptions, CategoryOptions, NumericalHistogramOptions, VLBridgeOptions } from '../types';
import { AnimationControls } from './animation-controls/AnimationControls';
import { CategoryFilter } from './category/CategoryFilter';
import { CategoricalHistogramFilter } from './histogram/CategoricalHistogramFilter';
import { NumericalHistogramFilter } from './histogram/NumericalHistogramFilter';
import { GlobalRangeFilter } from './range/GlobalRangeFilter';
import { TimeSeries } from './time-series/TimeSeries';
/**
 * This class is the main interface to bind a VL layer to one or more Airship widgets.
 *
 * The normal usage is create an instance and use its public methods to generate filters for
 * different widgets.
 *
 * After you have specified all the required filters, simply call the method `build` and all will be
 * handled for you. Internally, a new layer will be created with an invisible Viz, as a source for all
 * the widget's data.
 *
 * Some caveats:
 * - You can create as many filters for a column you want, but only one per widget.
 * - If you enable non-read-only capabilities, it is recommended that the Viz filter property not to
 * be changed, as it will be changed internally by each filter.
 *
 * @export
 * @class VLBridge
 */
export default class VLBridge {
    private _carto;
    private _map;
    private _layer;
    private _source;
    private _vizFilters;
    private _readOnlyLayer;
    private _id;
    private _animation;
    /**
     * Creates an instance of VLBridge.
     * @param {VLBridgeOptions} { carto, map, layer, source }
     *  - carto: CARTO VL namespace
     *  - map: CARTO VL map instance (Mapbox GL)
     *  - layer: CARTO VL layer
     *  - source: CARTO VL source
     * @memberof VLBridge
     */
    constructor({ carto, map, layer, source }: VLBridgeOptions);
    /**
     * Create a numerical histogram filter. See {@link NumericalHistogramOptions} for more details
     *
     * @param {(any | string)} widget Your widget or a
     * selector to locate it
     * @param {string} column The column you want to pull data from
     * @param {NumericalHistogramOptions} [options={}] Options for the bridge
     * @returns {NumericalHistogramFilter}
     * @memberof VLBridge
     */
    numericalHistogram(widget: any | string, column: string | {
        propertyName: string;
    }, options?: NumericalHistogramOptions): NumericalHistogramFilter;
    /**
     * Create a categorical histogram filter. See {@link CategoricalHistogramOptions} for more details
     *
     * @param {(any | string)} widget Your widget or a selector to locate it
     * @param {string} column The column to pull data from
     * @param {CategoricalHistogramOptions} [options={}] Options for this particular filter
     * @returns {CategoricalHistogramFilter}
     * @memberof VLBridge
     */
    categoricalHistogram(widget: any | string, column: string | {
        propertyName: string;
    }, options?: CategoricalHistogramOptions): CategoricalHistogramFilter;
    /**
     * Creates a numerical or categorical histogram, depending on the arguments.
     *
     * If neither buckets or bucketRanges are provided, a categorical one will be created. A numerical one otherwise
     *
     * @param {(any | string)} widget Your widget or a selector
     * @param {string} column The column to pull data from
     * @param {NumericalHistogramOptions} options Options for the Histogram
     * @returns {NumericalHistogramFilter | CategoricalHistogramFilter}
     * @memberof VLBridge
     */
    histogram(widget: any | string, column: string | {
        propertyName: string;
    }, options?: NumericalHistogramOptions): NumericalHistogramFilter | CategoricalHistogramFilter;
    /**
     * Creates a category widget filter.
     *
     * You can provide an HTML element (like a button) on the options, so the filtering takes place
     * after the user clicks on it. This option is ignored if readOnly
     *
     * @param {any | string} widget An airship category widget, or a selector
     * @param {string} column Column to pull data from
     * @param {CategoryOptions} [options={}]
     * @returns
     * @memberof VLBridge
     */
    category(widget: any | string, column: string | {
        propertyName: string;
    }, options?: CategoryOptions): CategoryFilter;
    /**
     * Creates a time series widget filter.
     *
     * Internally this creates a {@link NumericalHistogramFilter} and instances a {@link TimeSeries}.
     *
     * One will take care of the histogram part and the other of the animation parts.
     *
     * There can only be one animation per layer (per VLBridge instance)
     *
     * @param {(any | string)} widget The Time series widget, or a selector
     * @param {string} column The string to pull data from it
     * @param {AnimationOptions} [options={}]
     * @memberof VLBridge
     */
    timeSeries(widget: any | string, column: string, options?: AnimationOptions): TimeSeries;
    /**
     * Creates an animation controls widget
     *
     * By default, the animation is set to the 'filter' property,
     * but it is possible to animate any style property using the 'propertyName' option.
     *
     * There can only be one animation per layer (per VLBridge instance)
     *
     * @param {(any | string)} widget The Animation Controls widget, or a selector
     * @param {string} column The name of the column in the dataset used in the animation
     * @param {AnimationControlsOptions} [options={}]
     * @param {number} [options.duration] Animation duration in seconds. It is 10 by default
     * @param {[number, number]} [options.fade] Animation fade in and out.
     * @param {string} [options.variableName] Name of the viz variable that has the animation assigned
     * @param {string} [options.propertyName] Name of the style property to apply the animation, 'filter' by default.
     * @memberof VLBridge
     */
    animationControls(widget: any | string, column: string, options?: AnimationControlsOptions): AnimationControls;
    /**
     * Creates a global range slider filter.
     *
     * @param {(any | string)} widget A range slider widget or a selector
     * @param {string} column The column to pull data from
     * @returns {GlobalRangeFilter}
     * @memberof VLBridge
     */
    globalRange(widget: any | string, column: string): GlobalRangeFilter;
    /**
     * Call this method after creating all the different filters you require.
     *
     * It will internally do the following:
     *  - Add new variables to your Viz, with the columns of all the non-read-only filters
     *  - Create a new layer as the filters' data source
     * @returns
     * @memberof VLBridge
     */
    build(): void;
    private _addFilter;
    /**
     * This will append extra variables with all the columns of non-read-only filters.
     *
     * This is required so that whenever the filter is changed, the original viz layer
     * can be filtered by it.
     *
     * @private
     * @memberof VLBridge
     */
    private _appendVariables;
    /**
     * This will create a new Layer using the same source as the original, add it to the map, and
     * pass it to all the filters so they can hook up to read the data
     *
     * It has style properties to make it invisible, plus all the expressions created by each filter.
     *
     * @private
     * @memberof VLBridge
     */
    private _buildDataLayer;
    private _getVariables;
    private _updateDataLayerVariables;
    /**
     * Gather all the VL filters from each filter, combine them and filter both the data layer and
     * the original layer with it.
     *
     * If there is an animation involved, it uses @animation and all the filters.
     *
     * @private
     * @memberof VLBridge
     */
    private _rebuildFilters;
    private _combineFilters;
}