@arcgis/core/widgets/Print.d.ts

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

import type Collection from "../core/Collection.js";
import type Portal from "../portal/Portal.js";
import type MapView from "../views/MapView.js";
import type Widget from "./Widget.js";
import type FileLink from "./Print/FileLink.js";
import type PrintViewModel from "./Print/PrintViewModel.js";
import type TemplateOptions from "./Print/TemplateOptions.js";
import type { Icon } from "@esri/calcite-components/components/calcite-icon";
import type { WidgetProperties } from "./Widget.js";
import type { PrintViewModelEvents, PrintViewModelProperties } from "./Print/PrintViewModel.js";
import type { Formats, Layouts } from "./Print/types.js";
import type { HeadingLevel } from "./support/types.js";
import type { FileLinkProperties } from "./Print/FileLink.js";
import type { ReadonlyArrayOrCollection } from "../core/Collection.js";
import type { PortalProperties } from "../portal/Portal.js";
import type { TemplateOptionsProperties } from "./Print/TemplateOptions.js";

export interface PrintProperties extends WidgetProperties, Partial<Pick<Print, "allowedFormats" | "allowedLayouts" | "extraParameters" | "headingLevel" | "includeDefaultTemplates" | "includeOrganizationTemplates" | "printServiceUrl" | "showPrintAreaEnabled" | "templateCustomTextElements" | "view">> {
  /**
   * The collection of links exported from the Print widget.
   *
   * @since 4.17
   * @example
   * const [Print, esriConfig] = await $arcgis.import([
   *   "@arcgis/core/widgets/Print.js",
   *   "@arcgis/core/config.js"
   * ]);
   *
   * // ...
   *
   * view.when(function () {
   *   print = new Print({
   *     view: view,
   *     // specify your own print service
   *     printServiceUrl:
   *       "https://utility.arcgisonline.com/arcgis/rest/services/Utilities/PrintingTools/GPServer/Export%20Web%20Map%20Task"
   *   });
   *
   *   // Add widget to the top right corner of the view
   *   view.ui.add(print, "top-right");
   *
   *   // use a requestInterceptor to monitor the print widget
   *   // for print completion
   *   esriConfig.request.interceptors.push({
   *     // set the `urls` property to the URL of the print service so that this
   *     // interceptor only applies to requests made to the print service URL
   *     urls: print.printServiceUrl,
   *     // use the AfterInterceptorCallback to interrogate the exportedLinks property
   *     after: (response) => {
   *       console.log("exportedLinks: ", print.exportedLinks.items[0]);
   *     }
   *   });
   * });
   */
  exportedLinks?: ReadonlyArrayOrCollection<FileLinkProperties>;
  /**
   * Icon which represents the widget. It is typically used when the widget is controlled by another
   * one (e.g. in the Expand widget).
   *
   * @default "print"
   * @since 4.27
   * @see [Calcite Icon Search](https://developers.arcgis.com/calcite-design-system/icons/)
   * @see [Calcite Icon Search](https://developers.arcgis.com/calcite-design-system/icons/)
   */
  icon?: Icon["icon"] | null;
  /**
   * The widget's default label.
   *
   * @since 4.7
   */
  label?: string | null;
  /**
   * It is possible to search a specified portal instance's [locator services](https://enterprise.arcgis.com/en/portal/latest/administer/windows/configure-portal-to-geocode-addresses.htm).
   * Use this property to set this [ArcGIS Portal](https://enterprise.arcgis.com/en/portal/) instance to search.
   * This is especially helpful when working with a [custom print template](https://developers.arcgis.com/javascript/latest/references/core/widgets/Print/CustomTemplate/).
   *
   * If this property is set, it is not necessary to set the [printServiceUrl](https://developers.arcgis.com/javascript/latest/references/core/widgets/Print/#printServiceUrl) property.
   *
   * @since 4.18
   * @see [CustomTemplate](https://developers.arcgis.com/javascript/latest/references/core/widgets/Print/CustomTemplate/)
   * @example
   * const printWidget = new Print({
   *    view: view,
   *    portal: { url: "https://example.arcgis.com/sharing/" },
   *    container: "printDiv"
   * });
   */
  portal?: PortalProperties;
  /**
   * Defines the layout template options used by the [Print](https://developers.arcgis.com/javascript/latest/references/core/widgets/Print/) widget to generate the print page.
   *
   * @since 4.6
   * @example
   * templateOptions: {
   *   title: "My Print",
   *   author: "Sam",
   *   copyright: "My Company",
   *   legendEnabled: false
   * }
   */
  templateOptions?: TemplateOptionsProperties;
  /**
   * The view model for this widget. This is a class that contains all the logic
   * (properties and methods) that controls this widget's behavior. See the
   * [PrintViewModel](https://developers.arcgis.com/javascript/latest/references/core/widgets/Print/PrintViewModel/) class to access
   * all properties and methods on the widget.
   */
  viewModel?: PrintViewModelProperties;
}

export interface PrintEvents extends PrintViewModelEvents {}

/**
 * The Print widget connects your application with a [printing service](https://enterprise.arcgis.com/en/portal/latest/administer/windows/configure-the-portal-to-print-maps.htm) to allow the map to be printed.
 * It takes advantage of server-side, high-quality, full cartographic print functionality using the ExportWebMap service of ArcGIS,
 * which can be configured with custom layout templates. One is provided that shows the map only, while another provides a layout with legend, etc.
 * The Print widget works with the [print](https://developers.arcgis.com/javascript/latest/references/core/rest/print/) which generates a printer-ready version of the map.
 *
 * The Print widget has two required properties: [view](https://developers.arcgis.com/javascript/latest/references/core/widgets/Print/#view) (reference to the MapView)
 * and [printServiceUrl](https://developers.arcgis.com/javascript/latest/references/core/widgets/Print/#printServiceUrl) (URL of the REST endpoint of the Export Web Map Task).
 * The widget can preserve map scale or map extent in the printout. By default, the map extent is
 * preserved. Use [TemplateOptions.scaleEnabled](https://developers.arcgis.com/javascript/latest/references/core/widgets/Print/TemplateOptions/#scaleEnabled) to preserve scale
 * instead.
 *
 * The Print widget prints a localized date for all [layouts](https://developers.arcgis.com/javascript/latest/references/core/rest/support/PrintTemplate/#layout)
 * except `map-only`. If using a custom print service, then `customTextElements` are supported for each print
 * template. Values found there will be populated in the Print widget under `Advanced options`. These values can
 * be overwritten in the Print widget UI, or programmatically using the
 * [templateCustomTextElements](https://developers.arcgis.com/javascript/latest/references/core/widgets/Print/#templateCustomTextElements) property.
 *
 * For more information about printing with the `MAP_ONLY` layout, please see
 * [PrintTemplate.exportOptions](https://developers.arcgis.com/javascript/latest/references/core/rest/support/PrintTemplate/#exportOptions).
 *
 * > [!WARNING]
 * >
 * > **Known Limitations**
 * >
 * > See [print](https://developers.arcgis.com/javascript/latest/references/core/rest/print/) for a detailed list of known limitations.
 *
 * @deprecated since version 4.33. Use the [Print component](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-print/) instead. For information on widget deprecation, read about [Esri's move to web components](https://developers.arcgis.com/javascript/latest/components-transition-plan/).
 * @since 4.2
 * @see [Print component demo](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-print/#demo/)
 * @see [PrintViewModel](https://developers.arcgis.com/javascript/latest/references/core/widgets/Print/PrintViewModel/)
 * @see [Printing in web applications](https://enterprise.arcgis.com/en/server/latest/publish-services/windows/printing-in-web-applications.htm)
 * @see [Configure the portal to print maps](https://enterprise.arcgis.com/en/portal/latest/administer/windows/configure-the-portal-to-print-maps.htm)
 * @see [Export Web Map Task (Geoprocessing service) [REST doc]](https://developers.arcgis.com/rest/services-reference/export-web-map-task.htm)
 * @example
 * const print = new Print({
 *   view: view,
 *   // specify your own print service
 *   printServiceUrl:
 *      "https://utility.arcgisonline.com/arcgis/rest/services/Utilities/PrintingTools/GPServer/Export%20Web%20Map%20Task"
 * });
 *
 * // Adds widget below other elements in the top left corner of the view
 * view.ui.add(print, "top-left");
 */
export default class Print extends Widget<PrintProperties> {
  /**
   * @deprecated
   * Do not directly reference this property.
   * Use EventNames and EventTypes helpers from \@arcgis/core/Evented
   */
  "@eventTypes": PrintEvents;
  /**
   * @example
   * // typical usage
   * const print = new Print({
   *   view: view,
   *   printServiceUrl: "https://www.example.com/arcgis/rest/services/Utilities/PrintingTools/GPServer/Export%20Web%20Map%20Task"
   * });
   */
  constructor(properties?: PrintProperties);
  /**
   * Specify the print output file format(s) that the user can select based on the options available from the print service.
   * This property can take a string value or an array of string values.
   *
   * When this value is "all" (default value), all the print service formats are available to be used.
   * When an array of string values is used, only those values that match the options available from the print service will be used.
   * If none of the input string values match those available from the print service, `allowedFormats` will fallback to default behavior.
   *
   * @default "all"
   * @since 4.15
   * @see [TemplateOptions.format](https://developers.arcgis.com/javascript/latest/references/core/widgets/Print/TemplateOptions/#format)
   * @example
   * const print = new Print({
   *   view: view,
   *   printServiceUrl:
   *          "https://utility.arcgisonline.com/arcgis/rest/services/Utilities/PrintingTools/GPServer/Export%20Web%20Map%20Task",
   *   allowedFormats: ["jpg", "png8", "png32"]
   * });
   */
  accessor allowedFormats: Formats;
  /**
   * Specify the print output layout(s) that the user can select based on the options available from the print service.
   * This property can take a string value or an array of string values.
   *
   * When this value is "all" (default value), all the print service layouts are available to be used.
   * When an array of string values is used, only those values that match the options available from the print service will be used.
   * If none of the input string values match those available from the print service, `allowedLayouts` will fallback to default behavior.
   *
   * @default "all"
   * @since 4.15
   * @see [TemplateOptions.layout](https://developers.arcgis.com/javascript/latest/references/core/widgets/Print/TemplateOptions/#format)
   * @example
   * const print = new Print({
   *   view: view,
   *   printServiceUrl:
   *          "https://utility.arcgisonline.com/arcgis/rest/services/Utilities/PrintingTools/GPServer/Export%20Web%20Map%20Task",
   *   allowedLayouts: ["a3-landscape", "a3-portrait"]
   * });
   */
  accessor allowedLayouts: Layouts;
  /**
   * The collection of links exported from the Print widget.
   *
   * @since 4.17
   * @example
   * const [Print, esriConfig] = await $arcgis.import([
   *   "@arcgis/core/widgets/Print.js",
   *   "@arcgis/core/config.js"
   * ]);
   *
   * // ...
   *
   * view.when(function () {
   *   print = new Print({
   *     view: view,
   *     // specify your own print service
   *     printServiceUrl:
   *       "https://utility.arcgisonline.com/arcgis/rest/services/Utilities/PrintingTools/GPServer/Export%20Web%20Map%20Task"
   *   });
   *
   *   // Add widget to the top right corner of the view
   *   view.ui.add(print, "top-right");
   *
   *   // use a requestInterceptor to monitor the print widget
   *   // for print completion
   *   esriConfig.request.interceptors.push({
   *     // set the `urls` property to the URL of the print service so that this
   *     // interceptor only applies to requests made to the print service URL
   *     urls: print.printServiceUrl,
   *     // use the AfterInterceptorCallback to interrogate the exportedLinks property
   *     after: (response) => {
   *       console.log("exportedLinks: ", print.exportedLinks.items[0]);
   *     }
   *   });
   * });
   */
  get exportedLinks(): Collection<FileLink>;
  set exportedLinks(value: ReadonlyArrayOrCollection<FileLinkProperties>);
  /**
   * This option allows passing extra parameters (in addition to [templateOptions](https://developers.arcgis.com/javascript/latest/references/core/widgets/Print/#templateOptions)) to the print (export webmap) requests.
   *
   * @since 4.20
   */
  accessor extraParameters: Record<string, any> | null | undefined;
  /**
   * Indicates the heading level to use for the "Exported files" text where users can
   * access the exported map printout. By default, this text is rendered
   * as a level 3 heading (e.g. `<h3>Exported files</h3>`). Depending on the widget's placement
   * in your app, you may need to adjust this heading for proper semantics. This is
   * important for meeting accessibility standards.
   *
   * @default 3
   * @since 4.20
   * @see [Heading Elements](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements)
   * @example
   * // "Exported files" will render as an <h4>
   * print.headingLevel = 4;
   */
  accessor headingLevel: HeadingLevel;
  /**
   * Icon which represents the widget. It is typically used when the widget is controlled by another
   * one (e.g. in the Expand widget).
   *
   * @default "print"
   * @since 4.27
   * @see [Calcite Icon Search](https://developers.arcgis.com/calcite-design-system/icons/)
   * @see [Calcite Icon Search](https://developers.arcgis.com/calcite-design-system/icons/)
   */
  get icon(): Icon["icon"];
  set icon(value: Icon["icon"] | null | undefined);
  /**
   * Indicates whether or not to include [PrintViewModel.defaultTemplates](https://developers.arcgis.com/javascript/latest/references/core/widgets/Print/PrintViewModel/#defaultTemplates).
   *
   * @default true
   * @since 4.18
   * @example
   * const printWidget = new Print({
   *   view: view,
   *   includeDefaultTemplates: false,
   *   portal: { url: "https://.example.arcgis.com/sharing/" },
   *   container: "printDiv"
   * });
   */
  accessor includeDefaultTemplates: boolean;
  /**
   * Indicates whether or not to include templates from an organization's portal.
   *
   * @default true
   * @since 4.32
   * @example
   * const printWidget = new Print({
   *   view: view,
   *   includeOrganizationTemplates: false,
   *   portal: { url: "https://.example.arcgis.com/sharing/" },
   *   container: "printDiv"
   * });
   */
  accessor includeOrganizationTemplates: boolean;
  /**
   * The widget's default label.
   *
   * @since 4.7
   */
  get label(): string;
  set label(value: string | null | undefined);
  /**
   * It is possible to search a specified portal instance's [locator services](https://enterprise.arcgis.com/en/portal/latest/administer/windows/configure-portal-to-geocode-addresses.htm).
   * Use this property to set this [ArcGIS Portal](https://enterprise.arcgis.com/en/portal/) instance to search.
   * This is especially helpful when working with a [custom print template](https://developers.arcgis.com/javascript/latest/references/core/widgets/Print/CustomTemplate/).
   *
   * If this property is set, it is not necessary to set the [printServiceUrl](https://developers.arcgis.com/javascript/latest/references/core/widgets/Print/#printServiceUrl) property.
   *
   * @since 4.18
   * @see [CustomTemplate](https://developers.arcgis.com/javascript/latest/references/core/widgets/Print/CustomTemplate/)
   * @example
   * const printWidget = new Print({
   *    view: view,
   *    portal: { url: "https://example.arcgis.com/sharing/" },
   *    container: "printDiv"
   * });
   */
  get portal(): Portal;
  set portal(value: PortalProperties);
  /**
   * The URL of the REST endpoint of the Export Web Map Task.
   * If the [portal](https://developers.arcgis.com/javascript/latest/references/core/widgets/Print/#portal) property is set, it is not necessary to set this property.
   */
  accessor printServiceUrl: string | null | undefined;
  /**
   * The initial state of the print area toggle in the Print widget UI.
   * When set to `true`, the print area toggle is enabled by default.
   * When set to `false`, the print area toggle is disabled by default.
   *
   * @default false
   * @since 4.30
   */
  accessor showPrintAreaEnabled: boolean;
  /**
   * An object containing an array of `customTextElements` name-value pair objects
   * for each print template in a custom print service. Use this property to update
   * the text for custom text elements on the page layout.
   *
   * The Print widget calls the `Get Layout Templates Info` task on the GPServer
   * to discover possible `customTextElements` values for each template. The name of
   * the task must match `Get Layout Templates Info`, templates must be published
   * with `customTextElements`, and values must be strings. Values found there will be
   * populated in the Print widget under `Advanced options`. These values can be
   * overwritten in the Print widget UI, or programmatically using this property.
   * To list all print templates available on the print service to see
   * see which templates were published with `customTextElements`, use the
   * [PrintViewModel.effectiveTemplateCustomTextElements](https://developers.arcgis.com/javascript/latest/references/core/widgets/Print/PrintViewModel/#effectiveTemplateCustomTextElements)
   * property.
   *
   * @since 4.22
   * @example
   * const printWidget = new Print({
   *    view: view,
   *    // specify your custom print service
   *    printServiceUrl: "",
   *    // `customTextElements` are defined per print template
   *    // this example has one template with `customTextElements`
   *    templateCustomTextElements: {
   *       // if there were more applicable templates, then we would
   *       // create another object with the template name containing
   *       // an array of more name-value pairs
   *       "Landscape_TextElements": [
   *          // the possible values are defined in the print service
   *          { "headquarters": "Foxborough, Massachusetts" },
   *          { "division": "AFC East" },
   *          { "founded": "1959" }
   *       ]
   *    }
   * });
   */
  accessor templateCustomTextElements: PrintViewModel["templateCustomTextElements"];
  /**
   * Defines the layout template options used by the [Print](https://developers.arcgis.com/javascript/latest/references/core/widgets/Print/) widget to generate the print page.
   *
   * @since 4.6
   * @example
   * templateOptions: {
   *   title: "My Print",
   *   author: "Sam",
   *   copyright: "My Company",
   *   legendEnabled: false
   * }
   */
  get templateOptions(): TemplateOptions;
  set templateOptions(value: TemplateOptionsProperties);
  /**
   * A reference to the [MapView](https://developers.arcgis.com/javascript/latest/references/core/views/MapView/). Set this to link
   * the widget to a specific view.
   */
  accessor view: MapView | null | undefined;
  /**
   * The view model for this widget. This is a class that contains all the logic
   * (properties and methods) that controls this widget's behavior. See the
   * [PrintViewModel](https://developers.arcgis.com/javascript/latest/references/core/widgets/Print/PrintViewModel/) class to access
   * all properties and methods on the widget.
   */
  get viewModel(): PrintViewModel;
  set viewModel(value: PrintViewModelProperties);
}