PrintViewModel | API Reference | ArcGIS Maps SDK for JavaScript 4.33

Provides the logic for the Print widget and component.

Known Limitations

See print for a detailed list of known limitations.

See also

Print widget - Deprecated since 4.33. Use the Print component instead.
Print component
print
Programming patterns: Widget viewModel pattern

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

Type	Summary	Class
String\|String []	Specify the print output file format(s) that the user can select based on the options available from the print service.	PrintViewModel
String\|String []	Specify the print output layout(s) that the user can select based on the options available from the print service.	PrintViewModel
Collection<CustomTemplate>	A collection of print templates defined on the Portal.	PrintViewModel
String	The name of the class.	Accessor
CustomTemplate\|null\|undefined	The template which defines the default print template.	PrintViewModel
Collection<CustomTemplate>	A collection of print templates defined on the Portal.	PrintViewModel
String\|null\|undefined	The effective URL of the REST endpoint of the Export Web Map Task.	PrintViewModel
HashMap<HashMap<string>[]>	Returns an array of objects of all print templates available on the custom print service to see which templates were published with `customTextElements`.	PrintViewModel
Error\|null\|undefined	The error that occurred during printing.	PrintViewModel
Collection<FileLink>	The collection of links exported from Print.	PrintViewModel
Object\|null\|undefined	This option allows passing extra parameters to the print (export webmap) requests.	extraParameters
Boolean	Indicates whether or not to include defaultTemplates.	PrintViewModel
SpatialReference\|null\|undefined	The spatial reference used to render the printed map on the server.	PrintViewModel
Portal	It is possible to search a specified portal instance's locator services.	PrintViewModel
String []	An array of portalItem Ids that are used to identify the print templates using layoutItem Id.	PrintViewModel
Collection<CustomTemplate>	A collection of print templates defined on the Portal.	PrintViewModel
String\|null\|undefined	The URL of the REST endpoint of the Export Web Map Task.	PrintViewModel
Number	Print timeout value in milliseconds.	PrintViewModel
Boolean	The initial state of the print area toggle in the UI.	PrintViewModel
String	The view model's state.	PrintViewModel
HashMap<HashMap<string>[]>\|null\|undefined	An object containing an array of `customTextElements` name-value pair objects for each print template in a custom print service.	PrintViewModel
TemplateOptions	Defines the layout template options to generate the print page.	PrintViewModel
Object\|null\|undefined	The service metadata that contains the format and layout information for the printout.	PrintViewModel
Number	The time interval in milliseconds between each job status request sent to an asynchronous GP task.	PrintViewModel
MapView\|null\|undefined	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

TemplateOptions.format

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

TemplateOptions.layout

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.

exportedLinks 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

CustomTemplate

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

Print component

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

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
FileLink	Creates a new FileLink object for the given file name.	PrintViewModel
Boolean	Emits an event on the instance.	PrintViewModel
PrintExport	Exports the current print template to a file.	PrintViewModel
CustomTemplate\|null\|undefined	Returns a CustomTemplate with the specified `id`.	PrintViewModel
Boolean	Indicates whether there is an event listener on the instance that matches the provided event name.	PrintViewModel
Boolean	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
Object	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
PrintTemplate	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

portalItem PortalItem|null|undefined

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

template CustomTemplate|String|null|undefined

The CustomTemplate will be applied.

Possible Values:"map-only"

Returns

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

createExportedFileLink 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

type String|String []

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

template CustomTemplate|null|undefined

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.