PrintViewModel

ESM: import PrintVM from "@arcgis/core/widgets/Print/PrintViewModel.js";
CDN: const PrintVM = await $arcgis.import("@arcgis/core/widgets/Print/PrintViewModel.js");
Class: @arcgis/core/widgets/Print/PrintViewModel
Inheritance: PrintViewModelAccessor
Since: ArcGIS Maps SDK for JavaScript 4.2

Provides the logic for the Print widget and component.

Known Limitations

See print for a detailed list of known limitations.

See also
Example
const view = new MapView({
  container: "viewDiv",
  map: map
});

const printViewModel = new PrintViewModel({
    view: view
});

Constructors

PrintViewModel

Constructor
new PrintViewModel(properties)
Parameter
properties Object
optional

See the properties for a list of all the properties that may be passed into the constructor.

Property Overview

Any properties can be set, retrieved or listened to. See the Watch for changes topic.
Show inherited properties Hide inherited properties
Name Type Summary Class

Specify the print output file format(s) that the user can select based on the options available from the print service.

PrintViewModel

Specify the print output layout(s) that the user can select based on the options available from the print service.

PrintViewModel

A collection of print templates defined on the Portal.

PrintViewModel

The name of the class.

Accessor

The template which defines the default print template.

PrintViewModel

A collection of print templates defined on the Portal.

PrintViewModel

The effective URL of the REST endpoint of the Export Web Map Task.

PrintViewModel

Returns an array of objects of all print templates available on the custom print service to see which templates were published with customTextElements.

PrintViewModel

The error that occurred during printing.

PrintViewModel

The collection of links exported from Print.

PrintViewModel

This option allows passing extra parameters to the print (export webmap) requests.

extraParameters

Indicates whether or not to include defaultTemplates.

PrintViewModel

The spatial reference used to render the printed map on the server.

PrintViewModel

It is possible to search a specified portal instance's locator services.

PrintViewModel

An array of portalItem Ids that are used to identify the print templates using layoutItem Id.

PrintViewModel

A collection of print templates defined on the Portal.

PrintViewModel

The URL of the REST endpoint of the Export Web Map Task.

PrintViewModel

Print timeout value in milliseconds.

PrintViewModel

The initial state of the print area toggle in the UI.

PrintViewModel

The view model's state.

PrintViewModel

An object containing an array of customTextElements name-value pair objects for each print template in a custom print service.

PrintViewModel

Defines the layout template options to generate the print page.

PrintViewModel

The service metadata that contains the format and layout information for the printout.

PrintViewModel

The time interval in milliseconds between each job status request sent to an asynchronous GP task.

PrintViewModel

The view from which Print will operate.

PrintViewModel

Property Details

allowedFormats

Property
allowedFormats String |String[]
Since: ArcGIS Maps SDK for JavaScript 4.15 PrintViewModel since 4.2, allowedFormats added at 4.15.

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 Value:"all"
See also
Example
const print = new Print({
  view: view,
  printServiceUrl: url
});

print.viewModel.allowedFormats = ["jpg", "png8", "png32"];

view.ui.add(print, {position: "top-right"});

allowedLayouts

Property
allowedLayouts String |String[]
Since: ArcGIS Maps SDK for JavaScript 4.15 PrintViewModel since 4.2, allowedLayouts added at 4.15.

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 Value:"all"
See also
Example
const print = new Print({
  view: view,
  printServiceUrl: url
});

print.viewModel.allowedLayouts = ["a3-landscape", "a3-portrait"];

view.ui.add(print, {position: "top-right"});

browseTemplates

Property
browseTemplates Collection<CustomTemplate>readonly
Since: ArcGIS Maps SDK for JavaScript 4.33 PrintViewModel since 4.2, browseTemplates added at 4.33.

A collection of print templates defined on the Portal.

Print templates are used to apply pre-defined values to existing print options.

declaredClass

Inherited
Property
declaredClass Stringreadonly
Inherited from Accessor
Since: ArcGIS Maps SDK for JavaScript 4.7 Accessor since 4.0, declaredClass added at 4.7.

The name of the class. The declared class name is formatted as esri.folder.className.

defaultTemplate

Property
defaultTemplate CustomTemplate |null |undefinedreadonly
Since: ArcGIS Maps SDK for JavaScript 4.33 PrintViewModel since 4.2, defaultTemplate added at 4.33.

The template which defines the default print template.

defaultTemplates

Property
defaultTemplates Collection<CustomTemplate>readonly
Since: ArcGIS Maps SDK for JavaScript 4.18 PrintViewModel since 4.2, defaultTemplates added at 4.18.

A collection of print templates defined on the Portal.

Print templates are used to apply pre-defined values to existing print options.

effectivePrintServiceUrl

Property
effectivePrintServiceUrl String |null |undefinedreadonly

The effective URL of the REST endpoint of the Export Web Map Task.

effectiveTemplateCustomTextElements

Property
effectiveTemplateCustomTextElements HashMap<HashMap<string>[]>readonly
Since: ArcGIS Maps SDK for JavaScript 4.22 PrintViewModel since 4.2, effectiveTemplateCustomTextElements added at 4.22.

Returns an array of objects of all print templates available on the custom print service to see which templates were published with customTextElements. These values can be overwritten in the UI, or programmatically using the templateCustomTextElements property.

The PrintViewModel calls the Get Layout Templates Info task on the GPServer to discover available templates. If the Get Layout Templates Info task is named differently on the custom print service, then no values will be returned, and it will not be possible to support customTextElements. In this scenario, we recommend republishing the print service to use the standard Get Layout Templates Info name.

error

Property
error Error |null |undefinedreadonly
Since: ArcGIS Maps SDK for JavaScript 4.33 PrintViewModel since 4.2, error added at 4.33.

The error that occurred during printing.

Property
exportedLinks Collection<FileLink>autocast
Since: ArcGIS Maps SDK for JavaScript 4.33 PrintViewModel since 4.2, exportedLinks added at 4.33.

The collection of links exported from Print.

extraParameters

Property
extraParameters Object |null |undefinedinner
Since: ArcGIS Maps SDK for JavaScript 4.20 extraParameters since 4.2, extraParameters added at 4.20.

This option allows passing extra parameters to the print (export webmap) requests.

includeDefaultTemplates

Property
includeDefaultTemplates Boolean
Since: ArcGIS Maps SDK for JavaScript 4.18 PrintViewModel since 4.2, includeDefaultTemplates added at 4.18.

Indicates whether or not to include defaultTemplates.

Default Value:true

outSpatialReference

Property
outSpatialReference SpatialReference |null |undefinedautocast
Since: ArcGIS Maps SDK for JavaScript 4.33 PrintViewModel since 4.2, outSpatialReference added at 4.33.

The spatial reference used to render the printed map on the server.

portal

Property
portal Portalautocast
Since: ArcGIS Maps SDK for JavaScript 4.18 PrintViewModel since 4.2, portal added at 4.18.

It is possible to search a specified portal instance's locator services. Use this property to set this ArcGIS Portal instance to search. This is especially helpful when working with a custom print template.

If this property is set, it is not necessary to set the printServiceUrl property.

See also

portalTemplateIds

Property
portalTemplateIds String[]readonly
Since: ArcGIS Maps SDK for JavaScript 4.33 PrintViewModel since 4.2, portalTemplateIds added at 4.33.

An array of portalItem Ids that are used to identify the print templates using layoutItem Id.

printServiceTemplates

Property
printServiceTemplates Collection<CustomTemplate>readonly
Since: ArcGIS Maps SDK for JavaScript 4.33 PrintViewModel since 4.2, printServiceTemplates added at 4.33.

A collection of print templates defined on the Portal.

Print templates are used to apply pre-defined values to existing print options.

printServiceUrl

Property
printServiceUrl String |null |undefined

The URL of the REST endpoint of the Export Web Map Task. If the portal property is set, it is not necessary to set this property.

printTimeout

Property
printTimeout Number
Since: ArcGIS Maps SDK for JavaScript 4.28 PrintViewModel since 4.2, printTimeout added at 4.28.

Print timeout value in milliseconds.

Default Value:120000

showPrintAreaEnabled

Property
showPrintAreaEnabled Boolean
Since: ArcGIS Maps SDK for JavaScript 4.30 PrintViewModel since 4.2, showPrintAreaEnabled added at 4.30.

The initial state of the print area toggle in the 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 Value:false
See also

state

Property
state Stringreadonly

The view model's state.

Possible Values:"disabled" |"initializing" |"ready" |"error"

Default Value:"disabled"

templateCustomTextElements

Property
templateCustomTextElements HashMap<HashMap<string>[]> |null |undefined
Since: ArcGIS Maps SDK for JavaScript 4.22 PrintViewModel since 4.2, templateCustomTextElements added at 4.22.

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 PrintViewModel 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 under Advanced options. These values can be overwritten in the UI, or programmatically using this property. To list all print templates available on the print service to see which templates were published with customTextElements, use the effectiveTemplateCustomTextElements property.

Example
const printViewModel = new PrintViewModel({
   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
      "Portrait_TextElements": [
          // the possible values are defined in the print service
          { "headquarters": "Tampa, Florida" },
          { "division": "NFC South" },
          { "founded": "1976" }
      ]
   }
 });

templateOptions

Property
templateOptions TemplateOptionsautocast
Since: ArcGIS Maps SDK for JavaScript 4.33 PrintViewModel since 4.2, templateOptions added at 4.33.

Defines the layout template options to generate the print page.

templatesInfo

Property
templatesInfo Object |null |undefinedreadonly
Since: ArcGIS Maps SDK for JavaScript 4.33 PrintViewModel since 4.2, templatesInfo added at 4.33.

The service metadata that contains the format and layout information for the printout.

Properties
format Object
optional

Metadata about the available output formats.

Specification
choiceList String[]
optional

A list of supported output formats.

defaultValue String
optional

The default output format selected by the print service.

layout Object
optional

Metadata about the available page layouts.

Specification
choiceList String[]
optional

A list of supported layouts.

defaultValue String
optional

The default layout selected by the print service.

Example
const print = new Print({
  view: view,
  printServiceUrl: url
});

view.ui.add(print, {position: "top-right"});

console.log("PrintViewModel templatesInfo Formats: ", print.viewModel.templatesInfo.format.choiceList);
console.log("PrintViewModel templatesInfo Layouts: ", print.viewModel.templatesInfo.layout.choiceList);

updateDelay

Property
updateDelay Number

The time interval in milliseconds between each job status request sent to an asynchronous GP task.

Default Value:1000

view

Property
view MapView |null |undefined

The view from which Print will operate.

Method Overview

Show inherited methods Hide inherited methods
Name Return Type Summary Class

Adds one or more handles which are to be tied to the lifecycle of the object.

Accessor
Promise<void>

Adds a template to a portal.

PrintViewModel
Promise<void>

Applies the specified print template to the templateOptions property.

PrintViewModel

Creates a new FileLink object for the given file name.

PrintViewModel

Emits an event on the instance.

PrintViewModel

Exports the current print template to a file.

PrintViewModel

Returns a CustomTemplate with the specified id.

PrintViewModel

Indicates whether there is an event listener on the instance that matches the provided event name.

PrintViewModel

Returns true if a named group of handles exist.

Accessor
Promise

This method should be called to load the view model's printing resources.

PrintViewModel

Registers an event handler on the instance.

PrintViewModel
Promise<Object>

Prints (exports) the current MapView according to selected options.

PrintViewModel

Removes a group of handles owned by the object.

Accessor
void

Removes Template from browseTemplates.

PrintViewModel

Helper method to create print templates from a template options object.

PrintViewModel

Method Details

addHandles

Inherited
Method
addHandles(handleOrHandles, groupKey)
Inherited from Accessor
Since: ArcGIS Maps SDK for JavaScript 4.25 Accessor since 4.0, addHandles added at 4.25.

Adds one or more handles which are to be tied to the lifecycle of the object. The handles will be removed when the object is destroyed.

// Manually manage handles
const handle = reactiveUtils.when(
  () => !view.updating,
  () => {
    wkidSelect.disabled = false;
  },
  { once: true }
);

this.addHandles(handle);

// Destroy the object
this.destroy();
Parameters
handleOrHandles WatchHandle|WatchHandle[]

Handles marked for removal once the object is destroyed.

groupKey *
optional

Key identifying the group to which the handles should be added. All the handles in the group can later be removed with Accessor.removeHandles(). If no key is provided the handles are added to a default group.

addPortalTemplate

Method
addPortalTemplate(portalItem){Promise<void>}

Adds a template to a portal.

Parameter

The PortalItem used to create a print template. This template will be added to the browseTemplates collection.

Returns
Type Description
Promise<void> Resolves when the template is added.

applyTemplate

Method
applyTemplate(template){Promise<void>}

Applies the specified print template to the templateOptions property. This method updates the layout, custom text elements, and other template-specific options based on the provided template. If the template is "map-only", it sets the layout to "map-only" and skips additional processing.

If the provided template is invalid or not supported, the method falls back to the default template (if available) or resets the templateOptions to their initial state.

Parameter

The CustomTemplate will be applied.

Possible Values:"map-only"

Returns
Type Description
Promise<void> Resolves when the template is applied.
Method
createExportedFileLink(fileName){FileLink}

Creates a new FileLink object for the given file name. This method generates a unique file name with the appropriate extension based on the selected print template format and updates the internal file name map to track the number of exports with the same name.

Parameter
fileName String

The base name of the file to be exported (without extension).

Returns
Type Description
FileLink A FileLink object containing the file name, extension, and export count.

emit

Method
emit(type, event){Boolean}
Since: ArcGIS Maps SDK for JavaScript 4.5 PrintViewModel since 4.2, emit added at 4.5.

Emits an event on the instance. This method should only be used when creating subclasses of this class.

Parameters
type String

The name of the event.

event Object
optional

The event payload.

Returns
Type Description
Boolean true if a listener was notified

export

Method
export(fileName){PrintExport}

Exports the current print template to a file.

This method generates a file link and initiates the export process using the current print template options. The returned object contains a FileLink instance and a promise that resolves when the export is complete.

Parameter
fileName String

The name of the file to export (without extension).

Returns
Type Description
PrintExport An object containing: - link: A FileLink object representing the exported file. - promise: A promise that resolves to the FileLink when the export is complete.

getLayoutTemplateById

Method
getLayoutTemplateById(id){CustomTemplate |null |undefined}

Returns a CustomTemplate with the specified id. The associated properties are useful for print considerations.

Parameter
id String

The id of the CustomTemplate.

Returns
Type Description
CustomTemplate | null | undefined Returns a CustomTemplate, which contains both layoutTemplateInfo and mapSurroundInfoOptions.
Example
this.viewModel.getLayoutTemplateById(this.templateOptions.id);

hasEventListener

Method
hasEventListener(type){Boolean}

Indicates whether there is an event listener on the instance that matches the provided event name.

Parameter
type String

The name of the event.

Returns
Type Description
Boolean Returns true if the class supports the input event.

hasHandles

Inherited
Method
hasHandles(groupKey){Boolean}
Inherited from Accessor
Since: ArcGIS Maps SDK for JavaScript 4.25 Accessor since 4.0, hasHandles added at 4.25.

Returns true if a named group of handles exist.

Parameter
groupKey *
optional

A group key.

Returns
Type Description
Boolean Returns true if a named group of handles exist.
Example
// Remove a named group of handles if they exist.
if (obj.hasHandles("watch-view-updates")) {
  obj.removeHandles("watch-view-updates");
}

load

Method
load(){Promise}

This method should be called to load the view model's printing resources.

Returns
Type Description
Promise When resolved, the view model has loaded the print service metadata necessary for printing.

on

Method
on(type, listener){Object}

Registers an event handler on the instance. Call this method to hook an event with a listener.

Parameters

An event or an array of events to listen for.

listener Function

The function to call when the event fires.

Returns
Type Description
Object Returns an event handler with a remove() method that should be called to stop listening for the event(s).
Property Type Description
remove Function When called, removes the listener from the event.
Example
view.on("click", function(event){
  // event is the event handle returned after the event fires.
  console.log(event.mapPoint);
});

print

Method
print(template){Promise<Object>}

Prints (exports) the current MapView according to selected options.

Parameter
template PrintTemplate

The PrintTemplate is used to specify the layout template options which is then used by the PrintTask to generate the print page.

Returns
Type Description
Promise<Object> Resolves to an object with the following properties:
Property Type Description
url String URL to the exported printout.

removeHandles

Inherited
Method
removeHandles(groupKey)
Inherited from Accessor
Since: ArcGIS Maps SDK for JavaScript 4.25 Accessor since 4.0, removeHandles added at 4.25.

Removes a group of handles owned by the object.

Parameter
groupKey *
optional

A group key or an array or collection of group keys to remove.

Example
obj.removeHandles(); // removes handles from default group

obj.removeHandles("handle-group");
obj.removeHandles("other-handle-group");

removePortalTemplate

Method
removePortalTemplate(template){void}

Removes Template from browseTemplates.

Parameter

The CustomTemplate will be removed.

Returns
Type Description
void Resolves when the template is removed.

toPrintTemplate

Method
toPrintTemplate(templateOptions){PrintTemplate}

Helper method to create print templates from a template options object.

Parameter
templateOptions TemplateOptions
Returns
Type Description
PrintTemplate

Type Definitions

PrintExport

Type Definition
PrintExport Object

The printed export.

Properties
link FileLink

The link for the exported file.

promise Promise<FileLink>

The promise for the exported file.

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.