PrintViewModel

AMD: require(["esri/widgets/Print/PrintViewModel"], (PrintVM) => { /* code goes here */ });
ESM: import PrintVM from "@arcgis/core/widgets/Print/PrintViewModel";
Class: esri/widgets/Print/PrintViewModel
Inheritance: PrintViewModel Accessor
Since: ArcGIS API for JavaScript 4.2

Provides the logic for the Print widget.

Known Limitations

See print for a detailed list of known limitations.

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

let print = new Print({
  viewModel: new PrintVM({
    view: view
  })
});

Constructors

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 Working with Properties topic.
Show inherited properties Hide inherited properties
Name 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.

more details
PrintViewModel
String|String[]

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

more details
PrintViewModel
String

The name of the class.

more details
Accessor
Collection<CustomTemplate>

A collection of print templates defined on the Portal.

more details
PrintViewModel
String

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

more details
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.

more details
PrintViewModel
Object

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

more details
extraParameters
Boolean

Indicates whether or not to include defaultTemplates.

more details
PrintViewModel
Portal

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

more details
PrintViewModel
String

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

more details
PrintViewModel
String

The view model's state.

more details
PrintViewModel
Object[]

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

more details
PrintViewModel
Object

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

more details
PrintViewModel
Number

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

more details
PrintViewModel
MapView

The view from which the widget will operate.

more details
PrintViewModel

Property Details

allowedFormats String|String[]
Since: ArcGIS API for JavaScript 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 String|String[]
Since: ArcGIS API for JavaScript 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"});
declaredClass Stringreadonly inherited
Since: ArcGIS API for JavaScript 4.7

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

defaultTemplates Collection<CustomTemplate>readonly
Since: ArcGIS API for JavaScript 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 Stringreadonly

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

effectiveTemplateCustomTextElements Object[]readonly
Since: ArcGIS API for JavaScript 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 Objectinner
Since: ArcGIS API for JavaScript 4.20

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

includeDefaultTemplates Boolean
Since: ArcGIS API for JavaScript 4.18

Indicates whether or not to include defaultTemplates.

Default Value:true
portal Portal
Since: ArcGIS API for JavaScript 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
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.

state Stringreadonly

The view model's state.

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

Default Value:disabled
templateCustomTextElements Object[]
Since: ArcGIS API for JavaScript 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 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 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 Number

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

Default Value:1000
view MapView

The view from which the widget 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.

more details
Accessor
Boolean

Returns true if a named group of handles exist.

more details
Accessor
Promise

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

more details
PrintViewModel
Promise<object>

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

more details
PrintViewModel

Removes a group of handles owned by the object.

more details
Accessor

Method Details

addHandles(handleOrHandles, groupKey)inherited
Since: ArcGIS API for JavaScript 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 }
);

// Handle gets removed when the object is destroyed.
this.addHandles(handle);
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.

hasHandles(groupKey){Boolean}inherited
Since: ArcGIS API for JavaScript 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(){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(printTemplate){Promise<object>}

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

Parameter
printTemplate 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(groupKey)inherited
Since: ArcGIS API for JavaScript 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");

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