The connection is established in the background, and a `connect` event is fired when it is successful. If a `padId` is specified, a [`padData`](./events.md#paddata) or [`serverError`](./events.md#servererror) event will indicate when the map has been opened successfully or unsuccessfully. Note that you can already call methods immediately after constructing the client, causing them to be delayed until the connection is established.
If the connection to the server breaks down, a `disconnect` event will be emitted and socket.io will attempt to reconnect. On successful reconnection, a `reconnect` and `connect` event will be fired. During the interruption, you can still call methods, causing them to be delayed until the connection is reestablished.
* **Events:** Causes a `connect` event to be fired when the connection is established. If `padId` is defined, causes events to be fired with the map settings, all views, all types and all lines (without line points) of the map. If the map with `padId` could not be opened, causes a [`serverError`](./events.md#servererror) event.
*`function` (function): The function that should be executed when the event occurs. If the event emits an object, it will be passed to the function as the first parameter.
This method can only be called once, and only if no `padId` was passed to the constructor. If you want to open a different map, you need to create a new instance of the client.
Setting the padId causes the server to send several objects, such as the map settings, all views, and all lines (just metadata, without line points). Each of these objects is sent as an individual [`event`](./events.md).
* **Events:** Causes events to be fired with the map settings, all views, all types and all lines (without line points) of the map. If the map could not be opened, causes a [`serverError`](./events.md#servererror) event.
Updates the bbox. This will cause all markers, line points and route points within the bbox (except the ones that were already in the previous bbox, if there was one) to be received as individual events.
Finds a collaborative map by ID. This can be used to check if a map with a certain ID exists.
*`data`: An object with the following properties:
*`padId`: The read-only, writable or admin ID of the map.
* **Returns:** A promise that is resolved with undefined (if no map with that ID exists) or with an object with an `id` (read-only ID), `name` and `description` property.
* **Events:** None.
* **Availability:** Always.
## `findPads(data)`
Finds collaborative maps by a search term. Only finds maps that have been made public by setting [`searchEngines`](./types.md#paddata) to `true`.
*`data`: An object with the following properties:
*`query` (string): A search term. `*` can be used as a wildcard and `?` as a single-character wildcard.
*`start`, `limit` (number): If specified, can be used for paging.
* **Returns:**: A promise that is resolved to an object with the following properties:
*`results`: An array of objects with an `id`, `name` and `description` property.
*`totalLength`: The total number of results. If paging is used, this number may be higher than the number of `results` returned.
* **Events:** Causes a [`padData`](./events.md#paddata) event and other events for objects that have been created on the map (such as the default Marker and Line types).
*`data` ([PadData](./types.md#paddata)): The data of the map that should be modified. Fields that are not defined will not be modified. To change the default view, set the `defaultViewId` property. The `defaultView` property is ignored.
* **Returns:** A promise that is resolved with an array of (stripped down) [Marker](./types.md#marker) and [Line](./types.md#line) objects. The objects only contain the `id`, `name`, `typeId`, `lat`/`lon` (for markers), `left`/`top`/`right`/`bottom` (for lines) properties, plus an additional `kind` property that is either `"marker"` or `"line"`.
Calculate a route between two or more points, but but do not return the track points of the route but cache them on the server side and send them according to the client bbox. The route is not persisted on a collaborative map, but is temporarily persisted on the server in the scope one particular client connection only. As long as the route is active, the server will send [`routePoints`](./events.md#routepoints) events in response to [`updateBbox()`](#updatebbox-bbox) with the track points of the route simplified according to the bbox. The route will stay active until it is cleared using [`clearRoute()`](#clearroute-data) or the connection is closed.
Multiple routes can be active at the same time. They can be distinguished by their `routeId` property, which is a custom string that you can specify when activating a route. A `routeId` needs to be unique in the scope of this client instance, other clients are not affected by it. For backwards compatibility reasons, `undefined` is an acceptable value for `routeId`, but is considered a unique identifier nonetheless.
Calling `setRoute()` with a `routeId` of a route that is already active will replace that route.
The metadata of a route whose `routeId` is `undefined` is persisted in the [`route`](./properties.md#route) property and its track points in `route.trackPoints`. The metadata of a route whose `routeId` is a string is persisted in the [`routes[routeId]`](./properties.md#routes) property and its track points in `routes[routeId].trackPoints`.
Call [`setRoute()`](#setroute-data) with the parameters of an existing line. Saves time, as the route does not need to be recalculated. If a route with the same `routeId` is already active, it is replaced.
*`data` ([Marker](./types.md#marker)): The data of the marker to create. An `id` will be assigned by the server.
* **Returns:** A promise that is resolved with a [Marker](./types.md#marker)>, with an `id` assigned and possibly its styles modified by the settings of its type.
* **Events:** May trigger a [`marker`](./events.md#marker) event if the created marker is in the current bbox.
*`data` ([Marker](./types.md#marker)). The new marker data. Fields that are not defined will not be unmodified. Only `id` needs to be defined.
* **Returns:** A promise that is resolved with the updated [Marker](./types.md#marker). Might have some styles modified due to the settings of its type.
* **Events:** May trigger a [`marker`](./events.md#marker) event if the updated marker is in the current bbox.
*`data` ([Line](./types.md#line)): The data of the line to create. An `id` will be assigned by the server.
* **Returns:** A promise that is resolved with a [Line](./types.md#line), with an `id` assigned and possibly its styles modified by the settings of its type.
* **Events:** Causes a [`line`](./events.md#line) event and a [`linePoints`](./events.md#linepoints) event (if the line is in the current bbox).
*`data` ([line](./types.md#line)). The new line data. Fields that are not defined will not be unmodified. Only `id` needs to be defined.
* **Returns:** A promise that is resolved with the update [Line](./types.md#line). Might have some styles modified due to the settings of its type.
* **Events:** Causes a [`line`](./events.md#line) event and possibly a [`linePoints`](./events.md#linepoints) event (if the route mode was changed and the line is in the current bbox).
*`data` ([type](./types.md#type)). The new type data. Fields that are not defined will not be unmodified. Only `id` needs to be defined. To rename a field, set the `oldName` property of the field object to the previous name and the `name` property to the new name. To rename a dropdown entry, set the `oldValue` property to the old value and the `value` property to the new value.
* **Returns:** A promise that is resolved with the updated <[Type](./types.md#type)>.
* **Events:** Causes a [`type`](./events.md#type) event. If the update causes the styles of existing markers or lines to change, events for those are triggered as well.
* **Returns:** A promise that is resolved with the deleted [Type](./types.md#type) when the operation has completed. If there are any objects on the map that still use this type, the promise rejects.
* **Events:** Causes a [`deleteType`](./events.md#deletetype) event.
* **Returns:** A promise that is resolved to a [bounding box](./types.md#bbox) (without zoom) that includes the location of the client. If no location can be determined, the promise is resolved with `undefined`.