import PrintVM from "@arcgis/core/widgets/Print/PrintViewModel.js";
const PrintVM = await $arcgis.import("@arcgis/core/widgets/Print/PrintViewModel.js");
@arcgis/core/widgets/Print/PrintViewModel
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.
const view = new MapView({
container: "viewDiv",
map: map
});
const printViewModel = new PrintViewModel({
view: view
});
Constructors
-
Parameterproperties Objectoptional
See the properties for a list of all the properties that may be passed into the constructor.
Property Overview
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 | 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 | 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
-
Since: ArcGIS Maps SDK for JavaScript 4.15PrintViewModel 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
Exampleconst print = new Print({ view: view, printServiceUrl: url }); print.viewModel.allowedFormats = ["jpg", "png8", "png32"]; view.ui.add(print, {position: "top-right"});
-
Since: ArcGIS Maps SDK for JavaScript 4.15PrintViewModel 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
Exampleconst print = new Print({ view: view, printServiceUrl: url }); print.viewModel.allowedLayouts = ["a3-landscape", "a3-portrait"]; view.ui.add(print, {position: "top-right"});
-
browseTemplates
browseTemplates Collection<CustomTemplate>readonly
Since: ArcGIS Maps SDK for JavaScript 4.33PrintViewModel 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.
-
defaultTemplate
defaultTemplate CustomTemplate |null |undefinedreadonly
Since: ArcGIS Maps SDK for JavaScript 4.33PrintViewModel since 4.2, defaultTemplate added at 4.33. -
The template which defines the default print template.
-
defaultTemplates
defaultTemplates Collection<CustomTemplate>readonly
Since: ArcGIS Maps SDK for JavaScript 4.18PrintViewModel 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.
-
The effective URL of the REST endpoint of the Export Web Map Task.
-
effectiveTemplateCustomTextElements
effectiveTemplateCustomTextElements HashMap<HashMap<string>[]>readonly
Since: ArcGIS Maps SDK for JavaScript 4.22PrintViewModel 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 theGet 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 supportcustomTextElements
. In this scenario, we recommend republishing the print service to use the standardGet Layout Templates Info
name.
-
Since: ArcGIS Maps SDK for JavaScript 4.33PrintViewModel since 4.2, error added at 4.33. -
The error that occurred during printing.
-
exportedLinks
exportedLinks Collection<FileLink>autocast
Since: ArcGIS Maps SDK for JavaScript 4.33PrintViewModel since 4.2, exportedLinks added at 4.33. -
The collection of links exported from Print.
-
Since: ArcGIS Maps SDK for JavaScript 4.20extraParameters since 4.2, extraParameters added at 4.20. -
This option allows passing extra parameters to the print (export webmap) requests.
-
includeDefaultTemplates
includeDefaultTemplates Boolean
Since: ArcGIS Maps SDK for JavaScript 4.18PrintViewModel since 4.2, includeDefaultTemplates added at 4.18. -
Indicates whether or not to include defaultTemplates.
- Default Value:true
-
outSpatialReference
outSpatialReference SpatialReference |null |undefinedautocast
Since: ArcGIS Maps SDK for JavaScript 4.33PrintViewModel since 4.2, outSpatialReference added at 4.33. -
The spatial reference used to render the printed map on the server.
-
Since: ArcGIS Maps SDK for JavaScript 4.18PrintViewModel 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
-
Since: ArcGIS Maps SDK for JavaScript 4.33PrintViewModel 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
printServiceTemplates Collection<CustomTemplate>readonly
Since: ArcGIS Maps SDK for JavaScript 4.33PrintViewModel 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.
-
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
printTimeout Number
Since: ArcGIS Maps SDK for JavaScript 4.28PrintViewModel since 4.2, printTimeout added at 4.28. -
Print timeout value in milliseconds.
- Default Value:120000
-
showPrintAreaEnabled
showPrintAreaEnabled Boolean
Since: ArcGIS Maps SDK for JavaScript 4.30PrintViewModel 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 tofalse
, the print area toggle is disabled by default.- Default Value:false
- See also
-
state
state Stringreadonly
-
The view model's state.
Possible Values:"disabled" |"initializing" |"ready" |"error"
- Default Value:"disabled"
-
templateCustomTextElements
templateCustomTextElements HashMap<HashMap<string>[]> |null |undefined
Since: ArcGIS Maps SDK for JavaScript 4.22PrintViewModel 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 possiblecustomTextElements
values for each template. The name of the task must matchGet Layout Templates Info
, templates must be published withcustomTextElements
, and values must be strings. Values found there will be populated underAdvanced 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 withcustomTextElements
, use the effectiveTemplateCustomTextElements property.Exampleconst 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
templateOptions TemplateOptionsautocast
Since: ArcGIS Maps SDK for JavaScript 4.33PrintViewModel since 4.2, templateOptions added at 4.33. -
Defines the layout template options to generate the print page.
-
Since: ArcGIS Maps SDK for JavaScript 4.33PrintViewModel since 4.2, templatesInfo added at 4.33. -
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
updateDelay Number
-
The time interval in milliseconds between each job status request sent to an asynchronous GP task.
- Default Value:1000
Method Overview
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 | 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 | 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 | PrintViewModel | |
Helper method to create print templates from a template options object. | PrintViewModel |
Method Details
-
Inherited from Accessor
Since: ArcGIS Maps SDK for JavaScript 4.25Accessor 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();
ParametershandleOrHandles WatchHandle|WatchHandle[]Handles marked for removal once the object is destroyed.
groupKey *optionalKey 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.
-
Adds a template to a portal.
ParameterportalItem PortalItem|null|undefinedThe PortalItem used to create a print template. This template will be added to the
browseTemplates
collection.ReturnsType Description Promise<void> Resolves when the template is added.
-
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.Parametertemplate CustomTemplate|String|null|undefinedThe CustomTemplate will be applied.
Possible Values:"map-only"
ReturnsType Description Promise<void> Resolves when the template is applied.
-
createExportedFileLink
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.
ParameterfileName StringThe base name of the file to be exported (without extension).
ReturnsType Description FileLink A FileLink
object containing the file name, extension, and export count.
-
export
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.ParameterfileName StringThe name of the file to export (without extension).
ReturnsType Description PrintExport An object containing: - link
: A FileLink object representing the exported file. -promise
: A promise that resolves to theFileLink
when the export is complete.
-
getLayoutTemplateById
getLayoutTemplateById(id){CustomTemplate |null |undefined}
-
Returns a CustomTemplate with the specified
id
. The associated properties are useful for print considerations.Parameterid StringThe
id
of the CustomTemplate.ReturnsType Description CustomTemplate | null | undefined Returns a CustomTemplate, which contains both layoutTemplateInfo
andmapSurroundInfoOptions
.Examplethis.viewModel.getLayoutTemplateById(this.templateOptions.id);
-
hasHandles
InheritedMethodhasHandles(groupKey){Boolean}
Inherited from AccessorSince: ArcGIS Maps SDK for JavaScript 4.25Accessor since 4.0, hasHandles added at 4.25. -
Returns true if a named group of handles exist.
ParametergroupKey *optionalA group key.
ReturnsType 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"); }
-
This method should be called to load the view model's printing resources.
ReturnsType Description Promise When resolved, the view model has loaded the print service metadata necessary for printing.
-
on
on(type, listener){Object}
-
Registers an event handler on the instance. Call this method to hook an event with a listener.
ParametersReturnsType 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. Exampleview.on("click", function(event){ // event is the event handle returned after the event fires. console.log(event.mapPoint); });
-
print
print(template){Promise<Object>}
-
Prints (exports) the current MapView according to selected options.
Parametertemplate PrintTemplateThe PrintTemplate is used to specify the layout template options which is then used by the PrintTask to generate the print page.
ReturnsType Description Promise<Object> Resolves to an object with the following properties: Property Type Description url String URL to the exported printout.
-
Inherited from Accessor
Since: ArcGIS Maps SDK for JavaScript 4.25Accessor since 4.0, removeHandles added at 4.25. -
Removes a group of handles owned by the object.
ParametergroupKey *optionalA group key or an array or collection of group keys to remove.
Exampleobj.removeHandles(); // removes handles from default group obj.removeHandles("handle-group"); obj.removeHandles("other-handle-group");
-
Removes Template from
browseTemplates
.Parametertemplate CustomTemplate|null|undefinedThe CustomTemplate will be removed.
ReturnsType Description void Resolves when the template is removed.
-
toPrintTemplate
toPrintTemplate(templateOptions){PrintTemplate}
-
Helper method to create print templates from a template options object.
ParametertemplateOptions TemplateOptionsReturnsType Description PrintTemplate