PrintViewModel | API Reference | ArcGIS Maps SDK for JavaScript 4.31

Provides the logic for the Print widget.

Known Limitations

See print for a detailed list of known limitations.

See also

Example

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

const print = new Print({
  viewModel: 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
String	The name of the class.	Accessor
Collection<CustomTemplate>	A collection of print templates defined on the Portal.	PrintViewModel
String	The effective URL of the REST endpoint of the Export Web Map Task.	PrintViewModel
Object []	Returns an array of objects of all print templates available on the custom print service to see which templates were published with `customTextElements`.	PrintViewModel
Object	This option allows passing extra parameters to the print (export webmap) requests.	extraParameters
Boolean	Indicates whether or not to include defaultTemplates.	PrintViewModel
Portal	It is possible to search a specified portal instance's locator services.	PrintViewModel
String	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 Print widget UI.	PrintViewModel
String	The view model's state.	PrintViewModel
Object []	An object containing an array of `customTextElements` name-value pair objects for each print template in a custom print service.	PrintViewModel
Object	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	The view from which the widget 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"});

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.

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 Stringreadonly

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

effectiveTemplateCustomTextElements Property effectiveTemplateCustomTextElements Object[]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 Print widget 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.

extraParameters Property extraParameters Objectinner 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

portal Property portal Portal 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

printServiceUrl Property printServiceUrl String

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 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 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 Object[] 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 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 which templates were published with customTextElements, use the effectiveTemplateCustomTextElements property.

Example

const printWidget = new Print({
   viewModel: new PrintVM({
      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" }
         ]
      }
   })
});

templatesInfo Property templatesInfo Objectreadonly

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

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

The view from which the widget 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
CustomTemplate	Returns a CustomTemplate with the specified `id`.	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
Promise<Object>	Prints (exports) the current MapView according to selected options.	PrintViewModel
	Removes a group of handles owned by the object.	Accessor

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.

getLayoutTemplateById Method getLayoutTemplateById(id){CustomTemplate}

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	Returns a CustomTemplate, which contains both `layoutTemplateInfo` and `mapSurroundInfoOptions`.

Example

this.viewModel.getLayoutTemplateById(this.templateOptions.id);

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.

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");