@arcgis/core/WebDocument2D.d.ts

ArcGIS Maps SDK for JavaScript: A complete 2D and 3D mapping and data visualization API

import type EsriMap from "./Map.js";
import type Collection from "./core/Collection.js";
import type PortalItem from "./portal/PortalItem.js";
import type MapFloorInfo from "./support/MapFloorInfo.js";
import type MapView from "./views/MapView.js";
import type Widgets from "./webdoc/Widgets.js";
import type ApplicationProperties from "./webmap/ApplicationProperties.js";
import type Bookmark from "./webmap/Bookmark.js";
import type InitialViewProperties from "./webmap/InitialViewProperties.js";
import type { LoadableMixin, LoadableMixinProperties } from "./core/Loadable.js";
import type { MultiOriginJSONSupportMixin } from "./core/MultiOriginJSONSupport.js";
import type { EsriPromiseMixin } from "./core/Promise.js";
import type { AbortOptions } from "./core/promiseUtils.js";
import type { PortalItemProperties } from "./portal/PortalItem.js";
import type { SaveAsOptions, SaveOptions, ThumbnailSize } from "./webdoc/support/types.js";
import type { ApplicationPropertiesProperties } from "./webmap/ApplicationProperties.js";
import type { BookmarkProperties } from "./webmap/Bookmark.js";
import type { ReadonlyArrayOrCollection } from "./core/Collection.js";
import type { MapFloorInfoProperties } from "./support/MapFloorInfo.js";
import type { InitialViewPropertiesProperties } from "./webmap/InitialViewProperties.js";
import type { WidgetsProperties } from "./webdoc/Widgets.js";
import type { MapProperties as EsriMapProperties } from "./Map.js";

export interface WebDocument2DProperties extends EsriMapProperties, LoadableMixinProperties, Partial<Pick<WebDocument2D, "authoringApp" | "authoringAppVersion" | "thumbnailUrl">> {
  /** The applicationProperties contains the viewing properties of the WebMap. */
  applicationProperties?: ApplicationPropertiesProperties | null;
  /** An array of saved geographic extents that allow end users to quickly navigate to a particular area of interest. */
  bookmarks?: ReadonlyArrayOrCollection<BookmarkProperties>;
  /**
   * When a web map is configured as floor-aware, it has a floorInfo property defined.
   * A floor-aware map is a map that contains indoor GIS data representing floor plan features.
   * The floor info must contain [MapFloorInfo.levelLayer](https://developers.arcgis.com/javascript/latest/references/core/support/MapFloorInfo/#levelLayer)
   *  and [MapFloorInfo.facilityLayer](https://developers.arcgis.com/javascript/latest/references/core/support/MapFloorInfo/#facilityLayer) properties at a minimum.
   * The [MapFloorInfo.siteLayer](https://developers.arcgis.com/javascript/latest/references/core/support/MapFloorInfo/#siteLayer) property is optional.
   */
  floorInfo?: MapFloorInfoProperties | null;
  /**
   * The initial view of the WebMap. This object contains properties
   * such as [InitialViewProperties.viewpoint](https://developers.arcgis.com/javascript/latest/references/core/webmap/InitialViewProperties/#viewpoint),
   * [InitialViewProperties.spatialReference](https://developers.arcgis.com/javascript/latest/references/core/webmap/InitialViewProperties/#spatialReference),
   * that will be applied to the view when the WebMap loads.
   */
  initialViewProperties?: InitialViewPropertiesProperties;
  /** The portal item from which the WebMap is loaded. */
  portalItem?: PortalItemProperties | null;
  /** The widgets object contains widgets that are exposed to the user. */
  widgets?: WidgetsProperties | null;
}

export interface UpdateFromOptions {
  /**
   * When `true`, the view's [MapView.background](https://developers.arcgis.com/javascript/latest/references/core/views/MapView/#background) will not be updated for the webmap.
   * The default is `false` meaning the background will be updated for the webmap if there is a background.
   */
  backgroundExcluded?: boolean;
  /**
   * When `true`, the view's [MapView.scale](https://developers.arcgis.com/javascript/latest/references/core/views/MapView/#scale) will be updated for the webmap.
   * Defaults to `false` meaning view's scale will not be updated for the webmap. It is ignored when `viewpointExcluded` is `true`.
   */
  scalePreserved?: boolean;
  /** When `true`, the thumbnail will not be updated for the webmap. Defaults to `false` meaning the thumbnail will be updated for the webmap. */
  thumbnailExcluded?: boolean;
  /**
   * The size of the thumbnail. Defaults to
   *   600x400 (ratio 1.5:1). Note that the thumbnail size may currently not be
   *   larger than the size of the view.
   */
  thumbnailSize?: ThumbnailSize;
  /**
   * When `true`, the initial [InitialViewProperties.viewpoint](https://developers.arcgis.com/javascript/latest/references/core/webmap/InitialViewProperties/#viewpoint)
   * of the view will not be updated for the webmap. Defaults to `false`, meaning the viewpoint will be updated for the webmap. Must set `scalePreserved` to `true` if
   * the view's scale should be updated for the webmap.
   */
  viewpointExcluded?: boolean;
  /**
   * When `true`, the webmap's [WebMap.widgets](https://developers.arcgis.com/javascript/latest/references/core/WebMap/#widgets) property will not be updated.
   *     When `false`, the definition of the first [TimeSlider](https://developers.arcgis.com/javascript/latest/references/core/widgets/TimeSlider/) assigned to the
   *     [View](https://developers.arcgis.com/javascript/latest/references/core/views/View/) will be used to update the [WebMap.widgets](https://developers.arcgis.com/javascript/latest/references/core/WebMap/#widgets)
   *     property.
   *     The default value is `false`.
   */
  widgetsExcluded?: boolean;
}

/**
 * WebDocument2D is the base class for all 2D web documents.
 * To construct 2D documents see [WebMap](https://developers.arcgis.com/javascript/latest/references/core/WebMap/) and [WebLinkChart](https://developers.arcgis.com/javascript/latest/references/core/WebLinkChart/).
 *
 * @since 4.31
 * @see [WebMap](https://developers.arcgis.com/javascript/latest/references/core/WebMap/)
 * @see [WebLinkChart](https://developers.arcgis.com/javascript/latest/references/core/WebLinkChart/)
 */
export default abstract class WebDocument2D extends WebDocument2DSuperclass {
  /** The applicationProperties contains the viewing properties of the WebMap. */
  get applicationProperties(): ApplicationProperties | null | undefined;
  set applicationProperties(value: ApplicationPropertiesProperties | null | undefined);
  /** The name of the application that authored the WebMap. */
  accessor authoringApp: string | null | undefined;
  /** The version of the application that authored the WebMap. */
  accessor authoringAppVersion: string | null | undefined;
  /** An array of saved geographic extents that allow end users to quickly navigate to a particular area of interest. */
  get bookmarks(): Collection<Bookmark>;
  set bookmarks(value: ReadonlyArrayOrCollection<BookmarkProperties>);
  /**
   * When a web map is configured as floor-aware, it has a floorInfo property defined.
   * A floor-aware map is a map that contains indoor GIS data representing floor plan features.
   * The floor info must contain [MapFloorInfo.levelLayer](https://developers.arcgis.com/javascript/latest/references/core/support/MapFloorInfo/#levelLayer)
   *  and [MapFloorInfo.facilityLayer](https://developers.arcgis.com/javascript/latest/references/core/support/MapFloorInfo/#facilityLayer) properties at a minimum.
   * The [MapFloorInfo.siteLayer](https://developers.arcgis.com/javascript/latest/references/core/support/MapFloorInfo/#siteLayer) property is optional.
   */
  get floorInfo(): MapFloorInfo | null | undefined;
  set floorInfo(value: MapFloorInfoProperties | null | undefined);
  /**
   * The initial view of the WebMap. This object contains properties
   * such as [InitialViewProperties.viewpoint](https://developers.arcgis.com/javascript/latest/references/core/webmap/InitialViewProperties/#viewpoint),
   * [InitialViewProperties.spatialReference](https://developers.arcgis.com/javascript/latest/references/core/webmap/InitialViewProperties/#spatialReference),
   * that will be applied to the view when the WebMap loads.
   */
  get initialViewProperties(): InitialViewProperties;
  set initialViewProperties(value: InitialViewPropertiesProperties);
  /**
   * Indicates whether the instance has loaded. When `true`,
   * the properties of the object can be accessed. A WebMap is considered loaded
   * when its [layers](https://developers.arcgis.com/javascript/latest/references/core/WebDocument2D/#layers) and [basemap](https://developers.arcgis.com/javascript/latest/references/core/WebDocument2D/#basemap) are created, but not
   * yet loaded.
   *
   * @default false
   */
  get loaded(): boolean;
  /** The portal item from which the WebMap is loaded. */
  get portalItem(): PortalItem | null | undefined;
  set portalItem(value: PortalItemProperties | null | undefined);
  /**
   * The URL to the thumbnail used for the webmap. The `thumbnailUrl` will default to
   * the thumbnail URL from the portal item associated to the webmap. The thumbnail
   * of the webmap may be updated by changing the thumbnail URL and saving the
   * webmap. Use [updateFrom()](https://developers.arcgis.com/javascript/latest/references/core/WebDocument2D/#updateFrom) to update the thumbnail automatically from a specified
   * view.
   *
   * @example
   * webmap.updateFrom(view)
   *   .then(function() {
   *     return webmap.save();
   *   })
   *   // thumbnail will be updated based on current extent of webmap
   *   .then(function(portalItem) {
   *     console.log("Saved to portal", portalItem.id);
   *   })
   *   .catch(function(error) {
   *     console.error("Error saving to portal", error);
   *   });
   */
  accessor thumbnailUrl: string | null | undefined;
  /** The widgets object contains widgets that are exposed to the user. */
  get widgets(): Widgets | null | undefined;
  set widgets(value: WidgetsProperties | null | undefined);
  /**
   * Destroys the webmap, and any associated resources, including its [layers](https://developers.arcgis.com/javascript/latest/references/core/WebDocument2D/#layers), [basemap](https://developers.arcgis.com/javascript/latest/references/core/WebDocument2D/#basemap),
   * [ground](https://developers.arcgis.com/javascript/latest/references/core/WebDocument2D/#ground), [tables](https://developers.arcgis.com/javascript/latest/references/core/WebDocument2D/#tables), and [portalItem](https://developers.arcgis.com/javascript/latest/references/core/WebDocument2D/#portalItem).
   * These can no longer be used once the map has been destroyed. To prevent these objects from being destroyed,
   * remove them from the webmap before calling `destroy()`.
   *
   * ```
   * // prevent the layers from being destroyed by removing them from the webmap
   * const layers = webmap.layers.removeAll();
   *
   * // prevent the tables from being destroyed by removing them from the webmap
   * const tables = webmap.tables.removeAll();
   *
   * // unset basemap from the webmap so that it is not destroyed
   * const basemap = webmap.basemap;
   * webmap.basemap = null;
   *
   * // unset portalItem from the webmap so that it is not destroyed
   * const portalItem = webmap.portalItem;
   * webmap.portalItem = null;
   *
   * // prevent the utility networks from being destroyed by removing them from the webmap
   * const networks = webmap.utilityNetworks.removeAll();
   *
   * // destroy the webmap and any remaining associated resources
   * webmap.destroy();
   * ```
   *
   * @see [Map.destroy()](https://developers.arcgis.com/javascript/latest/references/core/Map/#destroy)
   * @see [WebScene.destroy()](https://developers.arcgis.com/javascript/latest/references/core/WebScene/#destroy)
   * @see [Basemap.destroy()](https://developers.arcgis.com/javascript/latest/references/core/Basemap/#destroy)
   * @see [Ground.destroy()](https://developers.arcgis.com/javascript/latest/references/core/Ground/#destroy)
   * @see [Layer.destroy()](https://developers.arcgis.com/javascript/latest/references/core/layers/Layer/#destroy)
   * @see [PortalItem.destroy()](https://developers.arcgis.com/javascript/latest/references/core/portal/PortalItem/#destroy)
   * @since 4.17
   * @see [WebMap.destroy()](https://developers.arcgis.com/javascript/latest/references/core/WebMap/#destroy)
   * @see [WebScene.destroy()](https://developers.arcgis.com/javascript/latest/references/core/WebScene/#destroy)
   * @see [Basemap.destroy()](https://developers.arcgis.com/javascript/latest/references/core/Basemap/#destroy)
   * @see [Ground.destroy()](https://developers.arcgis.com/javascript/latest/references/core/Ground/#destroy)
   * @see [Layer.destroy()](https://developers.arcgis.com/javascript/latest/references/core/layers/Layer/#destroy)
   * @see [PortalItem.destroy()](https://developers.arcgis.com/javascript/latest/references/core/portal/PortalItem/#destroy)
   */
  destroy(): void;
  /**
   * Triggers the loading of the WebMap instance.
   *
   * A WebMap is considered [loaded](https://developers.arcgis.com/javascript/latest/references/core/WebDocument2D/#loaded) when its [operational layers](https://developers.arcgis.com/javascript/latest/references/core/WebDocument2D/#layers)
   * and [basemap](https://developers.arcgis.com/javascript/latest/references/core/WebDocument2D/#basemap) are fully created.
   * When created with a [portalItem](https://developers.arcgis.com/javascript/latest/references/core/WebDocument2D/#portalItem), `load()` will first
   * fetch its data to create the content, otherwise it resolves immediately.
   *
   * The [MapView](https://developers.arcgis.com/javascript/latest/references/core/views/MapView/) automatically calls the `load()` method
   * when a WebMap instance is added to its [MapView.map](https://developers.arcgis.com/javascript/latest/references/core/views/MapView/#map) property
   * so it can display in the view and load each individual layer.
   * If the WebMap is used outside of a view, for example to preload it, you must call `load()`
   * explicitly to interact with its resources.
   *
   * @param options - Additional options.
   * @returns Resolves when the WebMap is [loaded](https://developers.arcgis.com/javascript/latest/references/core/WebDocument2D/#loaded).
   * @see [portalItem](https://developers.arcgis.com/javascript/latest/references/core/WebDocument2D/#portalItem)
   * @example
   * const WebMap = await $arcgis.import("@arcgis/core/WebMap.js");
   *
   * const map = new WebMap({
   *   portalItem: {
   *     id: "e691172598f04ea8881cd2a4adaa45ba"
   *   }
   * });
   *
   * map.load()
   *   .then(function() {
   *     // load the basemap to get its layers created
   *     return map.basemap.load();
   *   })
   *   .then(function() {
   *     // grab all the layers and load them
   *     const allLayers = map.allLayers;
   *     const promises = allLayers.map(function(layer) {
   *       return layer.load();
   *     });
   *     return Promise.all(promises.toArray());
   *   })
   *   .then(function(layers) {
   *     // each layer load promise resolves with the layer
   *     console.log("all " + layers.length + " layers loaded");
   *   })
   *   .catch(function(error) {
   *     console.error(error);
   *   });
   */
  load(options?: AbortOptions | null | undefined): Promise<this>;
  /**
   * Loads all the externally loadable resources associated with the webmap.
   * For the webmap this will load the ground, basemap and layers.
   *
   * @returns Resolves when all the loadable resources have been loaded.
   *   Rejects if at least one of the loadable resources failed to load.
   * @see [load()](https://developers.arcgis.com/javascript/latest/references/core/WebDocument2D/#load)
   * @example
   * // Load all resources but ignore if one or more of them failed to load
   * webmap.loadAll()
   *   .catch(function(error) {
   *     // Ignore any failed resources
   *   })
   *   .then(function() {
   *     console.log("All loaded");
   *   });
   */
  loadAll(): Promise<this>;
  /**
   * Saves the [WebMap](https://developers.arcgis.com/javascript/latest/references/core/WebMap/) or [WebLinkChart](https://developers.arcgis.com/javascript/latest/references/core/WebLinkChart/) to its associated portal item. The portal item
   * must already exist and be valid. This is a convenience method that will
   * use [PortalItem.update()](https://developers.arcgis.com/javascript/latest/references/core/portal/PortalItem/#update) to store the `WebMap` / `WebLinkChart`
   * in the item.
   *
   * Use [updateFrom()](https://developers.arcgis.com/javascript/latest/references/core/WebDocument2D/#updateFrom) to store the current view properties in the
   * webmap before saving it.
   *
   * Note that this saves the `WebMap` / `WebLinkChart` to its existing item. Depending on how
   * it is shared, users that do not own the `WebMap` / `WebLinkChart` may be able to modify it. To save
   * an existing `WebMap` / `WebLinkChart` as a new item owned by the user signed into the portal
   * instance, use [saveAs()](https://developers.arcgis.com/javascript/latest/references/core/WebDocument2D/#saveAs).
   *
   * The `WebMap` / `WebLinkChart` will be automatically loaded if it is not already before
   * saving.
   *
   * Wait until each [save()](https://developers.arcgis.com/javascript/latest/references/core/WebDocument2D/#save) operation has resolved before starting a new [save()](https://developers.arcgis.com/javascript/latest/references/core/WebDocument2D/#save)
   * operation to avoid a potential `abort-error`.
   *
   * > [!WARNING]
   * >
   * > **Known Limitations**
   * >
   * > Feature collections and multi-layer feature collections cannot currently be saved.
   *
   * @param options - Additional options.
   * @returns A promise that resolves with the [PortalItem](https://developers.arcgis.com/javascript/latest/references/core/portal/PortalItem/)
   *   instance when the item has successfully been saved, or rejected otherwise.
   * @see [updateFrom()](https://developers.arcgis.com/javascript/latest/references/core/WebDocument2D/#updateFrom)
   * @example
   * webmap.updateFrom(view)
   *   .then(function() {
   *     return webmap.save();
   *   })
   *   .then(function(portalItem) {
   *     console.log("Saved to portal", portalItem.id);
   *   })
   *   .catch(function(error) {
   *     console.error("Error saving to portal", error);
   *   });
   */
  save(options?: SaveOptions): Promise<PortalItem>;
  /**
   * Saves the [WebMap](https://developers.arcgis.com/javascript/latest/references/core/WebMap/) or [WebLinkChart](https://developers.arcgis.com/javascript/latest/references/core/WebLinkChart/) to a new [portal item](https://developers.arcgis.com/javascript/latest/references/core/portal/PortalItem/). If saving has completed
   * successfully, then the saved portal item will be set in the [portalItem](https://developers.arcgis.com/javascript/latest/references/core/WebDocument2D/#portalItem)
   * property of the `WebMap` / `WebLinkChart`. This is a convenience method that will create a new
   * [PortalItem](https://developers.arcgis.com/javascript/latest/references/core/portal/PortalItem/) and use
   * [PortalUser.addItem()](https://developers.arcgis.com/javascript/latest/references/core/portal/PortalUser/#addItem) to store
   * the `WebMap` / `WebLinkChart` in a [Portal](https://developers.arcgis.com/javascript/latest/references/core/portal/Portal/).
   *
   * Use [updateFrom()](https://developers.arcgis.com/javascript/latest/references/core/WebDocument2D/#updateFrom) to store the current view properties in the
   * `WebMap` / `WebLinkChart` before saving it.
   *
   * Note that this always saves the `WebMap` / `WebLinkChart` as a new portal item owned by the user
   * signed into the portal instance that executes the `saveAs()` method. If you want to modify
   * an existing item without changing its ownership, use [save()](https://developers.arcgis.com/javascript/latest/references/core/WebDocument2D/#save).
   *
   * The `WebMap` / `WebLinkChart` will be automatically loaded if it is not already before
   * saving.
   *
   * Wait until each [saveAs()](https://developers.arcgis.com/javascript/latest/references/core/WebDocument2D/#saveAs) operation has resolved before starting a new [saveAs()](https://developers.arcgis.com/javascript/latest/references/core/WebDocument2D/#saveAs)
   * operation to avoid a potential `abort-error`.
   *
   * > [!WARNING]
   * >
   * > **Known Limitations**
   * >
   * > Feature collections and multi-layer feature collections cannot currently be saved.
   *
   * @param portalItem - The new portal item to which
   * the `WebMap` / `WebLinkChart` will be saved.
   *
   * Portal item properties such as the title or description
   * need to be explicitly set on the item and will not be automatically copied from
   * the current associated `WebMap` / `WebLinkChart` portal item (if any).
   * @param options - Additional save options.
   * @returns A promise that resolves with the [PortalItem](https://developers.arcgis.com/javascript/latest/references/core/portal/PortalItem/)
   *   instance when the item has successfully been saved, or rejected otherwise.
   * @see [updateFrom()](https://developers.arcgis.com/javascript/latest/references/core/WebDocument2D/#updateFrom)
   * @example
   * const webmap = new WebMap();
   * // Use updateFrom to store the current view properties
   * // in the webmap before saving it
   * webmap.updateFrom(view);
   * webmap.saveAs({
   *   // autocasts as new PortalItem()
   *   title: "New WebMap"
   * });
   */
  saveAs(portalItem: PortalItemProperties, options?: SaveAsOptions): Promise<PortalItem>;
  /**
   * Update properties of the WebMap related to the view. This should usually
   * be called just before saving a webmap. The following properties are updated
   * from the view:
   * 1. [InitialViewProperties.spatialReference](https://developers.arcgis.com/javascript/latest/references/core/webmap/InitialViewProperties/#spatialReference)
   *
   * Depending on the provided options, the following properties are also updated:
   *
   * 2. The [Viewpoint.rotation](https://developers.arcgis.com/javascript/latest/references/core/Viewpoint/#rotation), [Viewpoint.scale](https://developers.arcgis.com/javascript/latest/references/core/Viewpoint/#scale), and
   * [Viewpoint.targetGeometry](https://developers.arcgis.com/javascript/latest/references/core/Viewpoint/#targetGeometry) properties of [InitialViewProperties.viewpoint](https://developers.arcgis.com/javascript/latest/references/core/webmap/InitialViewProperties/#viewpoint)
   * 3. The `thumbnail` of the [PortalItem](https://developers.arcgis.com/javascript/latest/references/core/portal/PortalItem/)
   *
   * @param view - The view to update from.
   * @param options - Update options.
   * @returns Resolves when the update has completed.
   * @see [save()](https://developers.arcgis.com/javascript/latest/references/core/WebDocument2D/#save)
   * @see [saveAs()](https://developers.arcgis.com/javascript/latest/references/core/WebDocument2D/#saveAs)
   */
  updateFrom(view: MapView, options?: UpdateFromOptions): Promise<void>;
}
declare const WebDocument2DSuperclass: typeof EsriMap & typeof EsriPromiseMixin & typeof LoadableMixin & typeof MultiOriginJSONSupportMixin