API¶

Additionally, the common API of a module is available.

Initialization methods¶

loadMap()¶

Asynchronous method that loads a specific map from a venue.

1

var promise = viewer.loadMap(load_options);

Input:

• load_options (object): Object with the information of the map to be loaded. Its properties are:
  • venue_id (string): venue id.
  • map_id (string) [optional]: map id. Default map is called "main".

Output:

• promise (Promise): loadMap returns a promise that will be resolved if the map is loaded successfully or it will be rejected if there was a problem when loading the map.
  • If the promise is resolved successfully, the first argument will be an object with the property instance, with the reference to the module.
  • If the promise is rejected, the first argument will be an error with a property instance with the module instance that failed to load.

Example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

var load_options = {
    venue_id: "venue_id"
};

viewer.loadMap(load_options).then(onLoad, onError);

function onLoad(obj) {
    console.log("Map loaded!");
    var loaded_viewer_instance = obj.instance;
}

function onError(err) {
    console.error("something went wrong!", err);
    var failed_viewer_instance = err.instance;
}

isInitialized()¶

Returns true if the viewer has been initialized.

Output::

• initialized (boolean): true if it has been initialized, false otherwise.

Example:

1

var initialized = viewer.isInitialized();

isLoaded()¶

Returns true if there is a map currently loaded.

Output:

• loaded (boolean): true if a map is completely loaded, false otherwise.

Example:

1

var loaded = viewer.isLoaded();

reset()¶

unloads the current map (if any). It is necessary to call loadMap again after this.

Example:

1

viewer.reset();

Info methods¶

getVenueId()¶

Returns the id of the current loaded venue.

Output:

• current_venue (string|null): returns the id of the current loaded venue. If there is no venue loaded yet, it will return null.

Example:

1

var current_venue = viewer.getVenueId();

getMapId()¶

Returns the id of the current loaded map.

Output:

• current_map (string|null): returns the id of the current loaded map. If there is no map loaded yet, it will return null.

Example:

1

var current_map = viewer.getMapId();

getMinimapId()¶

Returns the id of the assigned minimap of the current loaded map.

Output:

• minimap_id (string|null): Returns the id of the assigned minimap of the current loaded map. If there is no map loaded yet, or there is no assigned minimap, it will return null.

Example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

// One main instance, other for the minimap
const p1 = DVM.loadModule("map-viewer", { ... });
const p2 = DVM.loadModule("map-viewer", { ... });

Promise.all([p1, p2]).then(([viewer, minimap]) => {
    viewer.loadMap({ ... })
        .then(() => {
            const minimap_id = viewer.getMinimapId();
            if (minimap_id) {
                minimap.loadMap({ venue_id: viewer.getVenueId(), map_id: minimap_id });
            } else {
                minimap.reset();
            }
        })
});

subscribe()¶

Allows the subscription to callbacks. This is the same as passing the callbacks when loading the module.

Input:

• callback_name (string): Any callback of the list.
• callback_func (function): Function that will be called when triggered.

Output:

• subscription (Subscription): Object with unsubscribe function. It does the same as calling unsubscribe method, but making unnecessary to store the original reference to the subscribed function callback.

Example:

1
2
3
4
5

const sub = viewer.subscribe("click", function(obj) {
    console.log("CLICK");
});

sub.unsubscribe();

unsubscribe()¶

Removes a callback previously added with subscribe method or loading the module.

Input:

• callback_name (string): Any callback of the list.
• callback_func (function): reference to the function to be removed.

Example:

1
2
3
4
5

viewer3d.subscribe("click", func);
function func(obj) {
    console.log(obj.action);
    viewer3d.unsubscribe("click", func);
}

getMapDescription()¶

Asynchronous method that resolves in a map description.

Output:

• description (Promise): promise that will be resolved with an object with "title" and "description".

Example:

1
2
3
4
5
6
7
8
9

viewer.getMapDescription()
    .then(function(result) {
        console.log("Title:", result.title);
        console.log("Description:", result.description);
    })
    .catch(function(err) {
        // Something went wrong. Maybe you do not have permissions or the map doesn't exist.
        console.error(err)
    });

getIconsList()¶

Returns an array with the ids of the available icons to use with the styles.

Output:

• icons_list (string[]): list with the icon ids.

Example:

1

var available_icons = viewer.getIconsList();

getTypesList()¶

Returns an array with the ids of node types used in this map.

Output:

• types_list (string[]): list with the types ids.

Example:

1

var types_list = viewer.getTypesList();

getStatesList()¶

Returns an array with the ids of the states available for a particular type of node.

Input:

• type (string): node type from which you want to obtain te states list.

Output:

• states_list (string[]): list with the states ids.

Example:

1

var states_list = viewer.getStatesList("section");

Node getters methods¶

The following methods are made to obtain the map nodes depending on their properties.

getNodeById()¶

Returns a MapViewerNode from a given id. This can be null if there is no node with this id.

Input:

• node_id (string): unique node identifier.

Output:

• node (MapViewerNode | null): a MapViewerNode if the node exists. Otherwise null.

Example:

1

var node = viewer.getNodeById("S_123");

getNodes()¶

Generic method that allows to combine multiple filters to get a list of nodes.

Input:

• filter (Object)[optional]::** Object with the filters. If it's undefined, the method will return all the set of nodes. Its properties can be:
• type (string | string[]) [optional]: type or types (union).
• state (string | string[]) [optional]: state or states (union).
• parent (string | string[]) [optional]: parent or parents (union).
• group (string | string[]) [optional]: group or groups.
• intersection (boolean) [optional]: true for groups intersection, false (or empty) for
• groups union.
• nodes (MapViewerNode | MapViewerNode[])[optional]::** Nodes to be filtered. If it's undefined, all nodes
• will be filtered.

Output:

• nodes (MapViewerNode[]): nodes that meet al filters.

Example:

1
2
3
4
5

const nodes = viewer.getNodes({
    type: ["seat", "section"],
    state: "available",
    group: ["g1", "g2"]
});

getNodesByParent()¶

Returns a MapViewerNode array with the children nodes from the desired parent.

Input:

• parent_node (string | MapViewerNode): MapViewerNode or id of the parent node.

Output:

• children_nodes (MapViewerNode[]): Array containing the node children. The array will be empty if the node does not have any children.

Example:

1

var nodes = viewer.getNodesByParent("S_123");

getNodesByType()¶

Returns an array of MapViewerNode from a given type.

Input:

• type (string): node type.
• parent (MapViewerNode | string) [optional]: If this is not included, you will get all the nodes with type on the map. If the parent is included, you will get all elements with the desired type that are children of parent.

Output:

• output (MapViewerNode[]): MapViewerNode array with the given type. The array will be empty if any node applies the condition.

Example:

1

var nodes = viewer.getNodesByType("section");

getNodesByState()¶

Returns a MapViewerNode array with the given state. The type is also needed in this case.

Input:

• type (string): Desired nodes type.
• state (string): Desired nodes state.
• parent (MapViewerNode | string) [optional]: If this is not included, you will get all the nodes with state on the map. If the parent is included, you will get all nodes with the desired state that are children of parent.

Output:

• node_array (MapViewerNode[]): MapViewerNode array with the given type and state. The array will be empty if any node applies the condition.

Example:

1

var nodes = viewer.getNodesByState("section", "available");

getNodesByTag()¶

Returns a MapViewerNode array with the nodes with the required tag. If null is introduced, it returns the node without tag assignment.

Input:

• type (string): Desired nodes type.
• style_tag (string | null): desired style tag for the obtained nodes. This must be a valid string (not an empty string), or null for non-tag nodes.
• parent (MapViewerNode | string) [optional]: If this is not included, you will get all the nodes with style_tag on the map. If the parent is included, you will get all nodes with the desired style_tag that are children of parent.

Output:

• node_array (MapViewerNode[]): MapViewerNode array with the nodes that have the required style tag.

Example:

1

var nodes = viewer.getNodesByTag("seat", "vip");

getNodesByGroups()¶

Returns a MapViewerNode array. This method accepts multiple groups as input and has two modes:

• If intersection is false: Returns the joint union of the nodes from the required groups.
• If intersection is true: Returns the joint intersection of the nodes from the required groups.

Input:

• type (string): Desired nodes type.
• groups (string | string[]): group or groups from which the nodes are required.
• intersection (boolean) [optional]: false for union, true for intersection. Default is false.
• parent (MapViewerNode | string) [optional]: If this is not included, you will get all the nodes with groups on the map. If the parent is included, you will get all nodes with the desired groups that are children of parent.

Output:

• node_array (MapViewerNode[]): MapViewerNode array with the union or intersection of the nodes belonging to the required groups. The array will be empty if no node meets the conditions.

Example:

1
2
3
4
5
6
7

viewer.addNodesToGroup(["node1", "node2", "node3"], "group1");
viewer.addNodesToGroup(["node2", "node3", "node4"], "group2");

var g1 = viewer.getNodesByGroups("seat", "group1"); // [node1, node2, node3]
var g2 = viewer.getNodesByGroups("seat", "group2"); // [node2, node3, node4]
var union = viewer.getNodesByGroups("seat", ["group1", "group2"]); // [node1, node2, node3, node4]
var intersection = viewer.getNodesByGroups("seat", ["group1", "group2"], true); // [node2, node3]

getGroupsByType()¶

Returns an object with the available types on the map, and what groups have their nodes.

getNeighbors()¶

Returns the nodes quantity count that achieve the following requirements:

• The introduced node has to belong to a row.
• The introduced node has to be available or selected.
• There must be enough contiguous nodes that are available or selected.

If also filter_single_seats flag is set to true, the following conditions need also to be achieved:

• the returned node set cannot leave a node with state available or selected without at least one adjacent node with state available or selected, or a filterRows marked node.

• In case of achieving the above conditions, an array with the same quantity of nodes requested will be given (including the introduced node).

• In case of not achieving the above conditions, the returning array will be empty.

Input:

• node (string | MapViewerNode): base node from which the contiguous nodes are desired.
• quantity (number) [optional]: Quantity of nodes to be obtained. If no quantity is specified, it will return the full group of available seats.
• filter_single_seats (boolean) [optional]: If true, returned groups will apply the stranded single seats filtering. Default es false.

Output:

• node_array (MapViewerNode[]): MapViewerNode array with the nodes that meet the requirements.

Example:

1

var nodes = viewer.getNeighbors("S_123-A-4", 3, true);

getVisibleNodes()¶

Returns an array with the nodes that are visible on the viewer viewport.

Input:

• type (string): Desired nodes type.

Output:

• node_array (MapViewerNode[]): MapViewerNode array with the visible nodes.

Example:

1

var nodes = viewer.getVisibleNodes("section");

getNodesAt()¶

Returns an array with the nodes that are at the specified scene position.

Input:

• scene_point (ScenePoint): Scene position where nodes are going to be searched.
• type (string) [optional]: If specified, it will return only the nodes with the same type.

Output:

• node_array (MapViewerNode[]): MapViewerNode array with the matching nodes.

Example:

1

var nodes = viewer.getNodesAt([100,50], "seat");

getNodesOnArea()¶

Returns an array with the nodes that are at the specified scene area.

Input:

• scene_area (SceneBBox): [x, y, width, height], where [x,y] is the upper left corner.
• type (string) [optional]: If specified, it will return only the nodes with the same type.

Output:

• node_array (MapViewerNode[]): MapViewerNode array with the matching nodes.

Example:

1

var nodes = viewer.getNodesOnArea([100, 50, 100, 100], "seat");

Availability methods¶

The following methods manage the elements availability.

setAvailability()¶

Sets the map availability inside a specific node array with a defined type. The nodes inside this array will change their status to available, while the nodes outside this array will change their status to unavailable.

Input:

• type (string): the action will be applied to nodes of this type.
• nodes (MapViewerNode | MapViewerNodes[] | string | string[]): Element or elements that will be set as available, in case they have the required type and parent.
• parent (MapViewerNode | string) [optional]: If this is not included, the action will be applied to all elements with the desired type. If the parent is included, the action will be only applied to all elements with the desired type and children of this parent.

Output:

• success (boolean): returns true if the action was executed successfully. Otherwise returns false.

Example:

1

var success = viewer.setAvailability("seat", ["S_123-A-11", "S_123-A-12"], "S_123");

setAvailable()¶

Sets available state to the specified elements with a desired type. The difference between this method and setAvailability is that this method does not apply to the non specified elements in the input.

Input:

• type (string): the action will be applied to nodes of this type.
• nodes (MapViewerNode | MapViewerNodes[] | string | string[]): Element or elements that will be set as available, in case they have the required type and parent.
• parent (MapViewerNode | string) [optional]: If this is not included, the action will be applied to all elements with the desired type. If the parent is included, the action will be only applied to all elements with the desired type and children of this parent.

Output:

• success (boolean): returns true if the action was executed successfully. Otherwise returns false.

Example:

1

var success = viewer.setAvailable("seat", ["S_123-A-11", "S_123-A-12"], "S_123");

setUnavailable()¶

Sets unavailable state to the specified elements with a desired type.

Input:

• type (string): the action will be applied to nodes of this type.
• nodes (MapViewerNode | MapViewerNode[] | string | string[]): Element or elements that will be set as available, in case they have the required type and parent.
• parent (MapViewerNode | string) [optional]: If this is not included, the action will be applied to all elements with the desired type. If the parent is included, the action will be only applied to all elements with the desired type and children of this parent.

Output:

• success (boolean): returns true if the action was executed successfully. Otherwise returns false.

Example:

1

var success = viewer.setUnavailable("seat", ["S_123-A-11", "S_123-A-12"], "S_123");

enable()¶

Changes the state of a node from disabled to unavailable. If the node's state is not disabled, this method will do nothing.

This method is used along with disable.

Input:

• type (string): the action will be applied to nodes of this type.
• nodes (MapViewerNode | MapViewerNode[] | string | string[]): Element or elements that will be enabled, in case they have the required type and parent.
• parent (MapViewerNode | string) [optional]: If this is not included, the action will be applied to all elements with the desired type. If the parent is included, the action will be only applied to all elements with the desired type and children of this parent.

Output:

• success (boolean): returns true if the action was executed successfully. Otherwise returns false.

Example:

1

var success = viewer.enable("seat", ["S_123-A-11", "S_123-A-12"], "S_123");

disable()¶

Set the state of any node to disabled. If a node was selected, it will be unselected before being set to disabled. A disabled node cannot change its state unless you use enable method.

Having nodes disabled is useful in some user cases, For example:

• If you want to make sure that some nodes remains not available (disabled), preventing they being set it to available by accident.
• If disabled state has no styles, disabled nodes will be invisible, so you can tell whether a node is not available in some event (disabled and invisible) or it simply has been already taken (unavailable and grey).

This method is used along with enable.

Input:

• type (string): the action will be applied to nodes of this type.
• nodes (MapViewerNode | MapViewerNode[] | string | string[]): Element or elements that will be disabled, in case they have the required type and parent.
• parent (MapViewerNode | string) [optional]: If this is not included, the action will be applied to all elements with the desired type. If the parent is included, the action will be only applied to all elements with the desired type and children of this parent.

Output:

• success (boolean): returns true if the action was executed successfully. Otherwise returns false.

Example:

1

var success = viewer.disable("seat", ["S_123-A-11", "S_123-A-12"], "S_123");

Selection methods¶

The following methods manage the elements selection inside the map.

max_selection¶

Configures the maximum number of elements allowed to be selected. Once this number is reached by the selection, new selections will not be allowed (and no elements will be unselected). There is no limitation by default (Infinity).

Input/Output:

: - type (Integer): maximum number of elements allowed to be selected. It is a number and must be an integer.

Example:

1

viewer.max_selection = 5;

hover()¶

Forces the viewer to mark a specific node or nodes as if the mouse was hovering it. This is useful when you want the viewer to react to external actions (for instance, selection outside the map).

When this method is used, the previous hovered elements will be overrided.

If you call this method without input, or null, or an empty array, you will unhover all hovered elements.

Input:

• nodes (MapViewerNode | MapViewerNode[] | string | string[] | null): node or nodes to be set as hover.

Output:

• success (boolean): returns true if the action was executed successfully. Otherwise returns false.

Example:

1

var success = viewer.hover("S_123");

select()¶

Selects one or mode nodes. max selection also applies to this action. If some of the elements cannot be selected (for instance, if its state is unavailable), it will not be selected.

Input:

• nodes (MapViewerNode | MapViewerNodes[] | string | string[]): Elements to be selected. It can be a single node (id o MapViewerNode) or an array of elements.

Output:

• success (boolean): returns true if the action was executed successfully. Otherwise returns false.

Example:

1

var success = viewer.select(["S_123-A-11", "S_123-A-12"]);

unselect()¶

Unselects one or mode nodes. These nodes will be only unselected if their state is selected. When an element unselected, its state becomes available.

Input:

• nodes (MapViewerNode | MapViewerNodes[] | string | string[]): Elements to be selected. It can be a single node (id o MapViewerNode) or an array of elements.

Output:

• success (boolean): returns true if the action was executed successfully. Otherwise returns false.

Example:

1

var success = viewer.unselect(["S_123-A-11", "S_123-A-12"]);

unselectAll()¶

Unselects all current selected elements (if there is any).

Output:

• success (boolean): returns true if the action was executed successfully. Otherwise returns false.

Example:

1

var success = viewer.unselectAll();

Groups methods¶

See also getNodesByGroups on node getters section.

addNodesToGroup()¶

Allows adding nodes to a certain group.

Input:

• nodes (MapViewerNode | MapViewerNodes[] | string | string[]): Nodes to be added to the group.
• group (string): Name of the group.

Output:

• success (boolean): returns true if success. Otherwise returns false.

Example:

1

viewer.addNodesToGroup(["node1", "node2", "node3"], "group1");

removeNodesFromGroup()¶

Allows removing nodes from a group.

Input:

• nodes (MapViewerNode | MapViewerNodes[] | string | string[]): Nodes to be removed from the group.
• group (string): Name of the group.

Output:

• success (boolean): returns true if success. Otherwise returns false.

Example:

1

viewer.removeNodesFromGroup(["node1", "node2", "node3"], "group1");

Filter methods¶

filterRows()¶

Filters the nodes that belong to a row that satisfy the following condition:

• A series of contiguous nodes with the state available or selected cannot take part of a count sized group.

In addition, if the parameter filter_single_seats=true, nodes that neither satisfy the following condition will be filtered:

• If an available or selected node cannot take part of a joint with contiguous nodes without leaving an available or selected node alone.

The output of this method returns the nodes to be filtered (the action is not directly applied) - they are the nodes that do not satisfy the condition of taking part of a count sized group.

You can change the state to unavailable with setUnavailable, or assign a specific group to this joint to know if they were unavailable previously to the filtering process, and which were available but do not obey the necessary conditions to be selected.

Internally these nodes are treated like filtered so the method getNeighbors works as expected when using filter_single_seats=true.

This also facilitates making a second filtering process if the desired quantity of seats changes. Having these nodes marked in some common group allows us to retrieve them, revert them to the initial state and filter again.

Normally this should be use with getNeighbors.

Input:

• count (number): Desired group size.
• filter_single_seats (boolean): if true, seats that can cause stranded single seats when selecting count seats will be filtered.
• parent (string | MapViewerNode) [optional]: You can apply the filter on the children of some specific node.

Output:

• success (MapViewerNode[]): Array with the nodes to be filtered.

Example:

1
2
3
4
5
6
7

var old_filtered_seats = viewer.getNodesByGroups("seat", "filtered");
viewer.setAvailable("seat", old_filtered_seats);
viewer.removeNodesFromGroup(old_filtered_seats, "filtered");

var filtered_seats = viewer.filterRows(3, true);
viewer.setUnavailable("seat", filtered_seats);
viewer.addNodesToGroup(filtered_seats, "filtered");

checkIsolatedNodes()¶

It will check if any selected node is leaving any available node isolated. The node must be member of a row.

Output:

• isolated (MapViewerNode[]): Array with all isolated nodes.

Example:

1
2
3
4
5
6
7
8
9

viewer.subscribe("select", checkIsolated);
viewer.subscribe("unselect", checkIsolated);

function checkIsolated() {
    var isolated = viewer.checkIsolatedNodes();
    if (isolated.length > 0) {
        console.warn("Nodes isolated:", isolated);
    }
}

Style methods¶

The following methods give utilities about how to paint nodes in the Viewer.

See also getNodesByTag on node getters section.

forceCursor()¶

Force the cursor style when the cursor is over the map. Forcing the cursor style will ignore any style relative to cursor that any state or style tag may have. You can check available native cursors here.

Input:

• cursor (string|null): if the input is a string, cursor will be forced to use it. If the input is null, forced cursor will be disabled.

getStyles()¶

Returns the current styles being used. You can see more about styles here.

Output:

• success (Object): Current styles.

Example:

1

var styles = viewer.getStyles();

setStyles()¶

Overwrites the current styles configuration by a new one. You can see how to build style objects here.

Input:

• styles (StylesObject[]): This array with an style objects for every level.

Output:

• success (boolean): returns true if success. Otherwise, returns false.

Example:

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144

var styles =
    [
        // Level 0. sections are visible, seats are hidden (no styles needed).
        {
            // Level 0 styles for nodes with "section" type
            section: {
                available: {
                    normal: {
                        none: {
                            fillStyle: "#2E2EFE",
                            strokeStyle: "#2E2EFE",
                            lineWidth: 0.3,
                            cursor: "auto"
                        }
                    },
                    hover: {
                        none: {
                            fillStyle: "#819FF7",
                            strokeStyle: "#819FF7",
                            lineWidth: 0.6,
                            cursor: "pointer"
                        }
                    }
                },
                unavailable: {
                    normal: {
                        none: {
                            fillStyle: "grey",
                            strokeStyle: "grey",
                            lineWidth: 0.3,
                            cursor: "auto"
                        }
                    }
                },
                disabled: "unavailable"
            },
            // Level 0 styles for nodes with "seat" type (no styles = not shown)

            seat: null
        },

        // Level 1. sections are "open", seats are visible
        {
            // Level 1 styles for nodes with "section" type
            section: {
                available: {
                    normal: {
                        none: {
                            fillStyle: "#E0E6F8",
                            strokeStyle: "#2E2EFE",
                            lineWidth: 0.3,
                            cursor: "auto"
                        }
                    },
                    hover: {
                        none: {
                            fillStyle: "#E0E6F8",
                            strokeStyle: "#2E2EFE",
                            lineWidth: 0.6,
                            cursor: "auto"
                        }
                    }
                },
                unavailable: {
                    normal: {
                        none: {
                            fillStyle: "#BDBDBD",
                            strokeStyle: "grey",
                            lineWidth: 0.3,
                            cursor: "auto"
                        }
                    }
                },
                disabled: "unavailable"
            },

            // Level 1 styles for nodes with "seat" type
            seat:  {
                available: {
                    normal: {
                        none: {
                            fillStyle: "#2E2EFE",
                            cursor: "auto"
                        },
                        vip: {
                            fillStyle: "#2E2EFE",
                            cursor: "auto",
                            icon: "vipicon"
                        }
                    },
                    hover: {
                        none: {
                            fillStyle: "#2E2EFE",
                            strokeStyle: "#2E2EFE",
                            lineWidth: 0.1,
                            cursor: "pointer"
                        },
                        vip: {
                            fillStyle: "#2E2EFE",
                            strokeStyle: "#2E2EFE",
                            lineWidth: 0.1,
                            cursor: "pointer",
                            icon: "vipicon"
                        }
                    }
                },
                selected: {
                    normal: {
                        none: {
                            fillStyle: "#01DF01",
                            strokeStyle: "#01DF01",
                            lineWidth: 0.1,
                            cursor: "pointer",
                            icon: "selectedicon"
                        },
                        vip: {
                            fillStyle: "#01DF01",
                            strokeStyle: "#01DF01",
                            lineWidth: 0.1,
                            cursor: "pointer",
                            icon: "vipicon"
                        }
                    }
                },
                unavailable: {
                    normal: {
                        none: {
                            fillStyle: "grey",
                            cursor: "auto"
                        },
                        vip: {
                            fillStyle: "grey",
                            cursor: "auto",
                            icon: "vipicon"
                        }
                    }
                },
                disabled: "unavailable"
            }
        }
    ];


viewer.setStyles(styles);

setNodeCustomStyles()¶

Overrides the default styles of a node (from type > state > pseudostate > tag). This can be useful when you want specific styles for one specific node, without the need of having to generate and assign group styles.

Input:

• node (string | MapViewerNode): Target node.
• styles ((MapViewerStylesTag|null)[] | null): Array with the styles for each level. Passing null will reset the custom styles of that node.
• override (boolean) [optional]: If true, it will replace the default styles, instead of merging with them. false by default.

Example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

const styles = [
    {
        fillStyle: "#ff0000",
        strokeStyle: "#ffffff"
    },
    {
        fillStyle: "#a9a9a9",
        strokeStyle: "#ff0000"
    },
];

viewer.setNodeCustomStyles("S_123", styles);

viewer.setNodeCustomStules("S_456", null); // removes node "S_456" custom styles

setNodesTag()¶

Sets the tag of the specified nodes.

Input:

• nodes (string | string[] | MapViewerNode | MapViewerNode[]): Element or elements to whom the tag will be changed.
• style_tag (string | null): New tag to be assigned. Passing null will remove the nodes tag.

Output:

• success (boolean): returns true if success. Otherwise returns false.

Example:

1

viewer.setNodesTag(["node1", "node2"], "vip");

Label methods¶

getLabel()¶

Gets the information of a specific label of a node.

Input:

• node (string | MapViewerNode): MapViewerNode or id of the node.
• index (number) [optional]: Index of the label to be removed. Default is 0 (first label).

Output:

• Label (Object): It has the following properties:
  • show (boolean): true if the label is visible, otherwise false.
  • text (string|null): Text to be shown as label. If is an empty string (""), no label will be drawn. If it is null, the default label will be drawn. By default, it is the node id without S_.
  • size (number|null): Text size. If null it uses 5 by default.
  • font (string|null): font used. It can be used any valid css font family. If null it uses sans-serif by default.
  • position ([number, number]): [x, y] scene position of the label.
  • rotation (number|null): label rotation in degrees. 0 by default.

addLabel()¶

Creates a new label for a node.

Input:

• node (string | MapViewerNode): MapViewerNode or id of the node to which the label will be added.
• label (Object) : Same object as getLabel() output. Properties can be omitted and that property will use the default value.

updateLabel()¶

Updates an existing label from a node.

Input:

• node (string | MapViewerNode): MapViewerNode or id of the node to which the label will be updated.
• label (Object) : Same object as getLabel() output. Properties can be omitted and that property will not be modified.
• index (number) [optional]: Index of the label to be edited. Default is 0 (first label).

removeLabel()¶

Removes an existing label from a node.

Input:

• node (string | MapViewerNode): MapViewerNode or id of the node to which the label will be removed.
• index (number) [optional]: Index of the label to be removed. Default is 0 (first label).

setLabels()¶

Input:

• labels (Object) : Object with node ids as key and an object with the following properties as value:
  • text (string|null) [optional]: Text to be shown as label. If is an empty string (""), no label will be drawn. If is null, the default label will be drawn. By default, it is used the node id without S_.
  • size (number) [optional]: Text size. 5 by default.
  • font (string) [optional]: font used. It can be used any valid css font family, sans-serif by default.

Example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

var labels = {
    "S_123": {
        text: "Sec. 123",
        size: 7,
        font: "Monospace"
    },
    "S_124": {
        text: "Sec. 124"
    }
}

viewer.setLabels(labels);

Navigation methods¶

The following methods manage the navigation through the map and the zoom levels.

scaling_factor¶

This property contains the current scaling factor used in the map. When setting it, if the factor is greater than the maximum zoom or lower than the minimum zoom, the scaling factor will be forced to the nearer limit.

Input/Output:

• scaling_factor (number): it has to be a number greater than 0.

Example:

1
2

var current_scaling_factor = viewer.scaling_factor;
viewer.scaling_factor = 10;

max_scaling_factor¶

This property contains the maximum scaling factor admited by the map.

Input/Output:

• max_scaling_factor (number): it has to be a number greater than 0.

Example:

1
2

var current_max_scaling_factor = viewer.max_scaling_factor;
viewer.max_scaling_factor = 30;

min_scaling_factor¶

This property contains the minimum scaling factor admited by the map. Unlike max_scaling_factor, the minimum scaling factor will not be forced, but the maximum of the input value and the real value will be used.

Input/Output:

• min_scaling_factor (number): it has to be a number greater than 0.

Example:

1
2

var current_min_scaling_factor = viewer.min_scaling_factor;
viewer.min_scaling_factor = 2;

navigation_buttons_speed¶

Allows to customize the speed of the navigation buttons binded with bindInterfaceAction method.

Input/Output:

• speed (number): it has to be a number greater than 0.

Example:

1
2
3

var current_speed = viewer.navigation_buttons_speed;
// Double speed
viewer.navigation_buttons_speed = current_speed * 2;

zoom_buttons_speed¶

Allows to customize the speed of the zoom buttons binded with bindInterfaceAction method.

Input/Output:

• speed (number): it has to be a number greater than 0.

Example:

1
2
3

var current_speed = viewer.zoom_buttons_speed;
// half speed
viewer.zoom_buttons_speed = current_speed * 0.5;

focusOn()¶

Centers the viewport in the specified element (if it exists), elements, a scene position or a bounding box. In addition, a scaling factor can be specified.

If you target multiple nodes, the viewer will compute their bounding box, and focus on it.

Input:

• target (string | MapViewerNode | (MapViewerNode | string)[] | ScenePosition | BBox): Element to be focused on. It can be a node/nodes, id/ids, a bounding box [x,y,w,h], or scene position [x,y],
• scaling_factor (number): Desired zoom to be applied. This would be the same than setting the parameter before using the scaling_factor property. If no zoom is specified, the previous scaling_factor will be maintained when targeting a ScenePosition, while targeting a node it will be adapted so viewport adjusts to the size of the node.

Example:

:

1
2
3

// target: node S_123
// final scaling_factor: 15
viewer.focusOn("S_123", 15);

1
2
3

// target: node S_123
// final scaling_factor: automatically computed so the viewport will adjust to node "S_123"
viewer.focusOn("S_123");

1
2
3
4

// target: scene position [500, 400] (x, y)
// final scaling_factor: 10
// animation time: 1200 miliseconds
viewer.focusOn([500, 400], 10);

goTo()¶

Centers the viewport in the specified element (if it exists), elements, a scene position or a bounding box. In addition, a scaling factor can be specified. The transition is made with an animation.

If you target multiple nodes, the viewer will compute their bounding box, and focus on it.

It works like focusOn, but creates an animation while focusing on the target.

Input:

• target (string | MapViewerNode | (MapViewerNode | string)[] | ScenePosition | BBox): Element to be focused on. It can be a node/nodes, id/ids, a bounding box [x,y,w,h], or scene position [x,y],
• scaling_factor (number) [optional]: Desired zoom to be applied. This would be the same as setting the parameter before using the scaling_factor property. If no zoom is specified, the previous scaling_factor will be maintained when targeting a ScenePosition, while targeting a node it will be adapted so viewport adjusts to the size of the node.
• time (number) [optional]: Time in milliseconds that will take the animation. Default is 1500 milliseconds.

Output:

• promise (Promise): a Promise is returned when the animation finishes.

Example:

:

1
2
3
4
5
6
7

// target: node S_123
// final scaling_factor: 15
// animation time: 1000 miliseconds
viewer.goTo("S_123", 15, 1000)
    .then(function() {
        console.log("Animation ended");
    });

1
2
3
4
5
6
7

// target: node S_123
// final scaling_factor: automatically computed so the viewport will adjust to node "S_123"
// animation time: 1200 miliseconds
viewer.goTo("S_123", undefined, 1200)
    .then(function() {
        console.log("Animation ended");
    });

1
2
3
4
5
6
7

// target: scene position [500, 400] (x, y)
// final scaling_factor: 10
// animation time: 1200 miliseconds
viewer.goTo([500, 400], 10, 1200)
    .then(function() {
        console.log("Animation ended");
    });

scaleBy()¶

Multiplies the current scaling factor by a number.

Input:

• scaling_factor (number): Number to be multiplied by the current scaling factor. It has to be a number greater than 0.

Example:

1
2
3
4

// Current scaling factor == 1;
viewer.scaleBy(2); // Now it is 2
viewer.scaleBy(2); // Now it is 4
viewer.scaleBy(2); // Now it is 8

move()¶

Allows navigating around the map specifying a direction.

Input:

• distance_in_pixels (number): pixels moved by the camera. It has to be a number greater than 0.
• direction (string): Available options are "left", "right", "up" or "down".

Example:

1

viewer.move(10, "left");

bindInterfaceAction()¶

Binds the necessary events to a DOM element to perform certain actions on the map (zoom and navigation). This allows adding custom UI to the integrations without worrying about the events management.

Input:

• html_element (HTMLElement): HTML element where the actions will be bound.
• action (string): Available options are "zoom-in", "zoom-out", "move-left", "move-right", "move-up" and "move-down".

Output:

• success (boolean): returns true if the action was executed successfully. Otherwise returns false.

Example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

var zoom_in_btn    = document.getElementById("example-btn-zoom-in");
var zoom_out_btn   = document.getElementById("example-btn-zoom-out");

var move_left_btn  = document.getElementById("example-btn-move-left");
var move_right_btn = document.getElementById("example-btn-move-right");
var move_up_btn    = document.getElementById("example-btn-move-up");
var move_down_btn  = document.getElementById("example-btn-move-down");

viewer.bindInterfaceAction(zoom_in_btn, "zoom-in");
viewer.bindInterfaceAction(zoom_out_btn, "zoom-out");

viewer.bindInterfaceAction(move_left_btn, "move-left");
viewer.bindInterfaceAction(move_right_btn, "move-right");
viewer.bindInterfaceAction(move_up_btn, "move-up");
viewer.bindInterfaceAction(move_down_btn, "move-down");

Viewport methods¶

getContainer()¶

Returns the current container (if any) where the viewer is attached.

Output:

• div_element (HTMLDivElement | null): Returns the HTMLDivElement where the viewer is attached, null if there is no container.

setContainer()¶

Changes the container where the viewer is.

Input:

• div_element (string | HTMLDivElement | null): if the input is a string, it must be de unique id of an HTMLDivElement. Otherwise, it must be the HTMLDivElement itself. If it's null, it will remove the viewer from the DOM

Example:

1

viewer.setContainer("new-container-id");

1
2

var container = document.getElementById("new-container-id");
viewer.setContainer(container);

open()¶

Appends the viewer to the DOM.

Example:

1

viewer.open();

close()¶

Detaches the viewer from the DOM.

Example:

1

viewer.close();

fromDomToScene()¶

Converts a point with dom coordinates (relatives to the map html element) to its corresponding point with scene coordinates.

Input:

• dom_point (DomPoint): array [x,y] with the html coordinates of the point relative to the map html element.

Output:

• scene_point (ScenePoint): array [x,y] with the scene point corresponding to the provided dom_point.

Example:

1

var scene_position = viewer.fromDomToScene([50,50]);

fromSceneToDom()¶

Converts a point with scene coordinates to its corresponding point with dom coordinates (relatives to the map html element).

Input:

• scene_point (ScenePoint): array [x,y] with the scene coordinates of the point.

Output:

• dom_point (DomPoint): array [x,y] with the dom point coordinates (relatives to the map html element) corresponding to the provided scene_point.

Example:

1

var dom_position = viewer.fromSceneToDom([125.5, 50]);

aspect_ratio¶

Changes or returns the Viewer aspect ratio. It only works if fixed_aspect_ratio is true.

Input/Output:

• aspect_ratio (number): aspect ratio from the Viewer. The value is obtained by dividing height/width. For instance, to use a 16:9 aspect ratio, the division is9/16. This is set to 9/16 by default.

Example:

1

viewer.aspect_ratio = 9/16;

limits¶

Returns a limits object that contains properties useful to control UI elements (for instance for buttons enable/disable). It gives information about the currentscaling_factor and the map limits:

Output:

• limits (Object): It has the following properties:
  • scaling_factor (number): current scaling_factor.
  • zoom_in_limit (boolean): true if maximum zoom has been reached.
  • zoom_out_limit (boolean): true if minimum zoom has been reached.
  • left_limit (boolean): true if left limit has been reached.
  • right_limit (boolean): true if right limit has been reached.
  • upper_limit (boolean): true if up limit has been reached.
  • lower_limit (boolean): true if down limit has been reached.
  • bbox_scene (number[]): Bounding box of the scene.
  • bbox_limits (number[]): Bounding box of the camera limits. Usually is the same that bbox_scene bounding box, but it may change with some flags.
  • bbox_camera (number[]): Bounding of the visible part of the scene.
  • center_scene (number[]): Central point of the scene.
  • max_scaling_factor (number): maximum scaling factor of the map.
  • min_scaling_factor (number): minimum scaling factor of the map. This value might change if the size of the viewport
  • camera_mode (string): it can be two different modes:
    • "fixed": it uses an element pf the map as a scale reference, usually represented by, at scaling factor = 1 -> "1 seat = 1 pixel". That means that at the same scaling factor, the proportions will be maintained between maps, but the bigger the map is, the lesser is the minimum scaling factor required to show the full map, having factors of less than 1. Also, at the same scaling factor, bigger viewport containers will show more map content.
    • "adaptive": Scaling factor = 1 represents the full map, independently of the viewport size or the map size. scaling factors cannot be less than 1. changes.

Example:

1

var limits = viewer.limits;

Miscellaneous methods¶

has3dViews()¶

Asynchronous method that checks if a venue has 3d views material.

Input:

• venue_id (string): venue id.

Output:

• promise (Promise): returns a promise that will be resolved with a boolean, being true if the venue has 3d views, or false if it does not. The promises will be rejected if there is another problem, for example if you do not have permissions to access this venue, regardless of whether the view exists or not.

Example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

viewer.has3dViews("venue_id")
    .then(function(has_views) {
        if (has_views) {
            // The venue has 3d views material
        } else {
            // The venue hasn't 3d views material
        }
    })
    .catch(function(err) {
        // Something went wrong. Maybe you do not have permissions
        console.error(err)
    });

has3dView()¶

Asynchronous method that checks if a specific 3d view exists.

Input:

• options (object): Object with the information of the 3d view to be checked. Its properties are:
  • venue_id (string): venue id.
  • view_id (string): view id. It is usually a seat id or a section id, and the ids, in general, match those found on a map.

Output:

• promise (Promise): returns a promise that will be resolved with a boolean, being true if the 3d view exists, or false if it does not. The promises will be rejected if there is another problem, for example if you do not have permissions to access this venue, regardless of whether the view exists or not.

Example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

var obj = { venue_id: "venue", view_id: "view" };
viewer.has3dView(obj)
    .then(function(exists) {
        if (exists) {
            // The view does exist
            return viewer.getThumbnail(obj)
        } else {
            // The view does not exist.
            doSomething();
        }
    })
    .catch(function(err) {
        // Something went wrong. Maybe you do not have permissions
        console.error(err)
    });

hasMap()¶

Asynchronous method that checks if a specific map exists.

Input:

• options (object): Object with the information of the 3d view to be checked. Its properties are:
  • venue_id (string): venue id.
  • map_id (string): map id.

Output:

• promise (Promise): returns a promise that will be resolved with a boolean, being true if the map exists, or false if it does not. The promises will be rejected if there is another problem, for example if you do not have permissions to access this venue, regardless of whether the view exists or not.

Example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

var obj = { venue_id: "venue", map_id: "map" };
viewer.hasMap(obj)
    .then(function(exists) {
        if (exists) {
            // The map does exist
        } else {
            // The map does not exist.
        }
    })
    .catch(function(err) {
        // Something went wrong. Maybe you do not have permissions
        console.error(err)
    });

getThumbnail()¶

Asynchronous method that returns an image with a preview of the panoramic view from a seat (or a section).

The returned image has a size of 256x256 pixels.

Input:

• options (object): Object with the information of the preview to be downloaded. Its properties are:
  • venue_id (string): venue id.
  • view_id (string): view id. It is usually a seat id or a section id, and the ids, in general, match those found in maps.
• url (boolean) [optional]: true if you want that the promise to be resolved in a url, false will be resolved in an image. false by default.

Output:

• promise (Promise): If the image is downloaded successfully, the Promise resolves with the image. If the flag url is false it is resolved in an url.

Example:

1
2
3
4
5
6
7
8
9

var obj = { venue_id: "venue", view_id: "view" };

viewer3d.getThumbnail(obj)
    .then(function(img) {
        document.body.appendChild(img);
    })
    .catch(function(err) {
        console.error(err);
    });

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

var obj = { venue_id: "venue", view_id: "view" };

viewer3d.getThumbnail(obj, true)
    .then(function(url) {
        var img = new Image();
        img.src = url;
        document.body.appendChild(img);
    })
    .catch(function(err) {
        console.error(err);
    });

getThumbnail()¶

Asynchronous method that returns an image with a preview of the panoramic view from a seat (or a section).

The returned image has a size of 256x256 pixels.

Input

• node (string | MapViewerNode): MapViewerNode or id of the node with the panoramic view.
• venue_id (string) [optional]: if a map is loaded, its venue will be used. If a venue id is specified here, it will override the map venue. If no venue is specified and no map is loaded the promise will be rejected.
• url (boolean) [optional]: true if you want that the promise to be resolved in a url, false will be resolved in an image. false by default.

Output

• promise (Promise): If the image is downloaded successfully, the Promise resolves with the image. If the flag url is false it is resolved in a url.

Example

1
2
3
4
5
6
7

viewer.getThumbnail("S_123-10-15")
    .then(function(img) {
        document.body.appendChild(img);
    })
    .catch(function(err) {
        console.error(err);
    });

1
2
3
4
5
6
7
8
9

viewer3d.getThumbnail("S_123-10-15", undefined, true)
    .then(function(url) {
        var img = new Image();
        img.src = url;
        document.body.appendChild(img);
    })
    .catch(function(err) {
        console.error(err);
    });

Flags¶

The Viewer instance has a property called flags that contains several properties that modify the map behavior. They have been included separately for organization purposes.

fixed_aspect_ratio¶

Specifies the rescaling mode of the viewer.

• If true: The Viewer will take up the 100% of the container width, and the height will be computed multiplying the width by the aspect_ratio. For instance, if aspect_ratio = 0.5, the height will be 500px when the Viewer container has width of 1000px.
• If false: The Viewer will take up the 100% of the container width and height. It is important to ensure that the container has some height or it will be set as 0px. aspect_ratio will be ignored.

Input/Output:

• fixed_aspect_ratio (boolean): true enables the fixed_aspect_ratio mode. false disables it. This is set to true by default.

Example:

1

viewer.flags.fixed_aspect_ratio = true;

variable_zoom_on_resize¶

Specifies the map behavior when there is a rescale.

• If true: The scaling_factor will be adjusted so the view is not modified when the viewport does. This may cause that the limits where the seat layer is shown or hide are reached.
• If false: The scaling_factor will remain the same when there is a resize, so the smaller the viewport of the Viewer is, less map content will be seen, and vice versa.

Input/Output:

• variable_zoom_on_resize (boolean): true enables the variable_zoom_on_resize mode. false disables it. This is set to false by default.

Example:

1

viewer.flags.variable_zoom_on_resize = true;

max_zoom_on_first_limit¶

Specifies the recompute mode for the camera upper limit (minimum scaling_factor when it is far):

• If true: Once the first map limit is reached (for instance up/down limits for wider Viewers) the camera will not go further any more, allowing that that camera can still move to the opposite axis.
• If false: The camera will be adjusted to the last limit, adding additional vertical and horizontal stripes to the map.

Input/Output:

• max_zoom_on_first_limit (boolean): true enables the max_zoom_on_first_limit mode. false disables it. This is set to false by default.

Example:

1

viewer.flags.max_zoom_on_first_limit = true;

automatic_selection¶

Specifies if a click on an entity causes an automatic selection (in case that its state is available) or automatic deselection (in case that its state is selected).

• If true: When there is a click on an entity with available state, it will change its state to selected. When there is a click on an entity with selected state, it will change its state to available. The corresponding callbacks of click, selected or unselected will be triggered. This is the recommended method for simple integrations where you could avoid using click callbacks.
• If false: Anything will be automatically selected/unselected and it will be up to the integration to use the corresponding available callbacks to define the desired logic. This is the recommended method for a more complex integration as you will have full control of the interaction.

Input/Output:

• automatic_selection (boolean): true enables the automatic_selection mode. false disables it. This is set to true by default.

Example:

1

viewer.flags.automatic_selection = true;

automatic_hover¶

Specifies if "hover=true" must be marked automatically when the mouse is over a node. Leaving this to false might be useful when multiple selection is desired using methods like getNeighbors. In this case a manual management should be done using the hover method.

Take into account that hover, enter and leave callbacks will still be triggered, even if automatic_hover is false.

• If true: When the mouse is over an entity, the hover will be marked, and their corresponding styles will be used.
• If false: The nodes will not be marked as hover (the corresponding callbacks will be still triggered). The hover method has to be used manually.

Input/Output:

• automatic_hover (boolean): true enables the automatic_hover mode. false disables it. This is set to true by default.

Example:

1

viewer.flags.automatic_hover = true;

zooming¶

Enables or disables zooming with mouse or touch.

• If true: allows zooming on the map with mouse scroll or pinch.
• If false: disables zooming on the map with scroll of pinch. You still can zoom in and out with interface buttons or other methods. Disabling it will allow scrolling on the page over the map.

Input/Output:

• zooming (boolean): true enables zooming. false disables it. This is set to true by default.

Example:

1

viewer.flags.zooming = true;

panning¶

Enables or disables panning with mouse or touch.

• If true: allows pannning with mouse or touch.
• If false: disables panning on the map when using mouse or touch. You still can move with interface buttons or other methods.

Input/Output:

• panning (boolean): true enables panning. false disables it. This is set to true by default.

Example:

1

viewer.flags.panning = true;

preserve_min_scaling_factor¶

By default, scaling_factor is preserved while contained between min_scaling_factor and max_scaling_factor. If the viewport changes, min_scaling_factor might change, and might force scaling_factor to change if it goes off range. If min_scaling_factor changes again, the map could stay zoomed.

When this flag is true, if scaling_factor is equal to min_scaling_factor, and min_scaling_factor changes, scaling_factor will stick to it.

• If true: scaling_factor will be preserved when it is within range, except when it is equal to min_scaling_factor, where it will stick to it.
• If false: scaling_factor will be preserved when it is within range.

Input/Output:

• preserve_min_scaling_factor (boolean): true enables it. false disables it. This is set to false by default.

Example:

1

viewer.flags.preserve_min_scaling_factor = true;