This section documents API usage specific to this template, so for an introduction we suggest you refer to the generic API documentation instead.

Template data

There are three different formats in which you can supply data to this template. The most convenient for you to use likely depends on the source of your data, as described below.

1. Array of arrays, and a bindings object

You can supply arrays of arrays to opts.data, which might look like:

{
    data: {
        events: [
            [ "EventsColumn1Value1", "EventsColumn2Value1",
            [ "EventsColumn1Value2", "EventsColumn2Value2",
            [ "EventsColumn1Value3", "EventsColumn2Value3",
            ...
        ],
        colors: [
            [ "ColorsColumn1Value1", "ColorsColumn2Value1",
            [ "ColorsColumn1Value2", "ColorsColumn2Value2",
            [ "ColorsColumn1Value3", "ColorsColumn2Value3",
            ...
        ]
    }
}

where each array of arrays represents the rows in a data sheet.

To tell the API how the values from each column should be associated with the keys that the template is expecting, you must also supply an object attached to opts.bindings. (The meanings of the keys in the bindings object are documented below.) The minimal bindings you can supply for this template are as shown in this example:

{
    template: "_221",
    version: "_10",
    bindings: {
        events: {
            lat: 0, // index of a column in your data
            lon: 1, // index of a column in your data
        },
        colors: {
            category: 0, // index of a column in your data
            color: 1, // index of a column in your data
        }
    },
    data: {
        events: [
            [ "EventsColumn1Value1", "EventsColumn2Value1",
            [ "EventsColumn1Value2", "EventsColumn2Value2",
            [ "EventsColumn1Value3", "EventsColumn2Value3",
            ...
        ],
        colors: [
            [ "ColorsColumn1Value1", "ColorsColumn2Value1",
            [ "ColorsColumn1Value2", "ColorsColumn2Value2",
            [ "ColorsColumn1Value3", "ColorsColumn2Value3",
            ...
        ]
    }
}

All possible bindings that you can supply are shown in this example:

{
    template: "_221",
    version: "_10",
    bindings: {
        events: {
            lat: 0, // index of a column in your data
            lon: 1, // index of a column in your data
            start_timestamp: 2, // index of a column in your data
            end_timestamp: 3, // index of a column in your data
            metadata: [4, 5, ...], // index(es) of column(s) in your data
            category: 6, // index of a column in your data
            scale: 7, // index of a column in your data
        },
        colors: {
            category: 0, // index of a column in your data
            color: 1, // index of a column in your data
        }
    },
    data: {
        events: [
            [ "EventsColumn1Value1", "EventsColumn2Value1",
            [ "EventsColumn1Value2", "EventsColumn2Value2",
            [ "EventsColumn1Value3", "EventsColumn2Value3",
            ...
        ],
        colors: [
            [ "ColorsColumn1Value1", "ColorsColumn2Value1",
            [ "ColorsColumn1Value2", "ColorsColumn2Value2",
            [ "ColorsColumn1Value3", "ColorsColumn2Value3",
            ...
        ]
    }
}

2. Array of objects with arbitrary keys, and a bindings object

This format is most likely useful when you have data from an external source, such as CSV data loaded from d3-dsv. You should supply this attached to the opts.data, which might look like:

{
        events: [
            { "EventsHeader1": ..., "EventsHeader2": ..., ... },
            { "EventsHeader1": ..., "EventsHeader2": ..., ... },
            { "EventsHeader1": ..., "EventsHeader2": ..., ... },
            ...
        ],
        colors: [
            { "ColorsHeader1": ..., "ColorsHeader2": ..., ... },
            { "ColorsHeader1": ..., "ColorsHeader2": ..., ... },
            { "ColorsHeader1": ..., "ColorsHeader2": ..., ... },
            ...
        ]
    }

... but with the keys being the column headers from your source data instead. You must also supply an object attached to opts.bindings. The minimal bindings you can supply for this template are as shown in this example:

{
    template: "_221",
    version: "_10",
    bindings: {
        events: {
            lat: "EventsHeader1",
            lon: "EventsHeader2",
        },
        colors: {
            category: "ColorsHeader1",
            color: "ColorsHeader2",
        }
    },
    data: {
        events: [
            { "EventsHeader1": ..., "EventsHeader2": ..., ... },
            { "EventsHeader1": ..., "EventsHeader2": ..., ... },
            { "EventsHeader1": ..., "EventsHeader2": ..., ... },
            ...
        ],
        colors: [
            { "ColorsHeader1": ..., "ColorsHeader2": ..., ... },
            { "ColorsHeader1": ..., "ColorsHeader2": ..., ... },
            { "ColorsHeader1": ..., "ColorsHeader2": ..., ... },
            ...
        ]
    }
}

All possible bindings that you can supply are shown in this example:

{
    template: "_221",
    version: "_10",
    bindings: {
        events: {
            lat: "EventsHeader1",
            lon: "EventsHeader2",
            start_timestamp: "EventsHeader3",
            end_timestamp: "EventsHeader4",
            metadata: ["EventsHeader5", "EventsHeader6", ...],
            category: "EventsHeader7",
            scale: "EventsHeader8",
        },
        colors: {
            category: "ColorsHeader1",
            color: "ColorsHeader2",
        }
    },
    data: {
        events: [
            { "EventsHeader1": ..., "EventsHeader2": ..., ... },
            { "EventsHeader1": ..., "EventsHeader2": ..., ... },
            { "EventsHeader1": ..., "EventsHeader2": ..., ... },
            ...
        ],
        colors: [
            { "ColorsHeader1": ..., "ColorsHeader2": ..., ... },
            { "ColorsHeader1": ..., "ColorsHeader2": ..., ... },
            { "ColorsHeader1": ..., "ColorsHeader2": ..., ... },
            ...
        ]
    }
}

(As before, the keys containing "Header" would be replaced by column names from your data source.)

3. Array of objects with template-defined keys

There is an alternative format you can use, which is likely to be easier to use if your data is not from a spreadsheet source. With this alternative format you supply your data to the template as an array of objects, attached to opts.data, where the keys must be those used by the template, as documented below. In this case there is no need to supply a bindings object, since the key names are already those expected by the template. The required properties in the data object are as follows (scroll down for a description of what each property is):

{
    template: "_221",
    version: "_10",
    data: {
    events: [
        {
            lat: ...,
            lon: ...,
            metadata: [...]
        },
        ...
    ],
    colors: [
        {
            category: ...,
            color: ...
        },
        ...
    ]
},
    ...
}

And the full list of all possible properties is as follows:

{
    template: "_221",
    version: "_10",
    data: {
    events: [
        {
            lat: ...,
            lon: ...,
            start_timestamp: ...,
            end_timestamp: ...,
            metadata: [...],
            category: ...,
            scale: ...
        },
        ...
    ],
    colors: [
        {
            category: ...,
            color: ...
        },
        ...
    ]
},
    ...
}

Meanings of the template data keys:

• events.lat: lat
• events.lon: lon
• events.start_timestamp: Determines when the circles appear. If left blank all the events will appear at once. If selected, creates a time slider and shows dots over time. The date format must be specified in the settings panel.
• events.end_timestamp: Determines when the circles disappear. If not specified the circle remains for the default duration specified in the settings panel.
• events.metadata: One or more columns to show in the popups
• events.category: Used to determine the colours of the circles, as configured in the separate data sheet
• events.scale: Determines the size of the circles.
• colors.category: The category of the event. Should match the categories specified in the main data sheet.
• colors.color: Can be a hex value such as “#FF7E5D” or an HTML colour name such as “red”.

Template settings

Options for opts.state.

Events

events_pulse_enabled boolean

Show events.

events_pulse_simple boolean

events_pulse_fallback_color color

Default colour. Circle colour when no category colour specified

events_pulse_default_scale number

Default size. The size of the circle when the “Scale” column is not selected or contains an invalid number for the given event

events_pulse_min_scale number

Min size. The smallest circle size allowed; usually best left at zero so that the sizes of the circles are proportional to the values in the data

events_pulse_max_scale number

Max size. The size of the largest circle

events_pulse_on_ocean boolean

Show events over ocean.

Event counter and graph

counter_type string

Count events. Enables the events counter and graph. Use “By count” to display the number of events, or “By size” to display the number scaled by the “Scale” column.

counter_other boolean

Include.

counter_other_label string

Label.

counter_enabled boolean

Show counter.

counter_labels boolean

Category labels.

graph_enabled boolean

Show graph.

graph_height number

Graph height (%).

label_cumulative string

“Total” label.

label_sampled string

“Rate” label.

number_prefix string

Prefix.

number_multiplier number

Multiplier.

number_decimals number

Decimals.

number_suffix string

Suffix.

timeline_bg_opacity number

Opacity of shading behind graph.

controls_bg_opacity number

Opacity of shading behind counter.

Time

events_pulse_date_format string

Date/time format in data. The date/time format in your data sheet. If it isn’t in the list, you can enter a custom format using d3-time-format syntax. See npmjs.com/package/d3-time-format for details.

events_pulse_date_format_display string

Date/time format on slider. The date/time format in your data sheet. If it isn’t in the list, you can enter a custom format using d3-time-format syntax. See npmjs.com/package/d3-time-format for details.

timeline_playing boolean

Play on load.

events_pulse_transition_duration number

Pulse duration. Duration in seconds of the pulse animation

timeline_duration number

Timeline duration. How long in seconds it takes to play through the timeline

timeline_speed number

Time multiplier. Speeds up or slows down the time. Affects the animations as well as the timeline. Set to 1 for normal time.

camera_transition_speed number

Pan/zoom duration. How long to spend moving the camera when changing slides in story mode, in seconds.

Popups

events_pulse_tooltips boolean

Enable popups. Display tooltips when the user hovers over an event circle, based on the column assigned for Labels

events_pulse_tooltips_custom boolean

Custom popups content. Allows you to create bespoke popups using HTML

events_pulse_tooltips_content text

Enable popups. The text to appear in the popup. You can use {{column_name}} to add a value from any selected column. You can add extra columns to “Popups” if needed. Advanced users can include HTML to apply layouts, formatting, images, etc.

Map

box_terrain_enabled boolean

Show map.

box_terrain_mode string

Mode.

box_terrain_color color

Colorize map.

box_terrain_height number

Block height.

box_terrain_textured boolean

Use texture on map.

box_terrain_src url

Custom map file.

Fog and background

fog_color color

Colour.

fog_density number

Density.