import Bookmarks from "@arcgis/core/widgets/Bookmarks.js";const Bookmarks = await $arcgis.import("@arcgis/core/widgets/Bookmarks.js");- Since
- ArcGIS Maps SDK for JavaScript 4.8
The Bookmarks widget allows end users to quickly navigate to a particular area of interest. It displays a list of bookmarks, which are typically defined inside the WebMap.bookmarks.
Each bookmark may contain the following properties: name, thumbnail, viewpoint (defines rotation, scale, and target geometry), and timeExtent.
If the timeExtent is defined on a bookmark, it will be displayed in the bookmark widget as shown in the following image.
When a bookmark with a timeExtent is selected, the MapView.timeExtent of the View will be set to the timeExtent of the selected bookmark.
To disable time capability in the Bookmarks widget, set capabilities.time in the BookmarksViewModel to false.
Constructors
Constructor
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| properties | | |
Properties
| Property | Type | Class |
|---|---|---|
| | ||
container inherited | HTMLElement | null | undefined | |
declaredClass readonly inherited | ||
| | ||
| | ||
destroyed readonly inherited | ||
| | ||
| | ||
| | ||
| | ||
| | ||
| | ||
Icon["icon"] | | |
id inherited | ||
| | ||
uid readonly inherited | ||
| | ||
| | ||
visible inherited | ||
| |
bookmarks
- Type
- Collection<Bookmark>
A collection of Bookmarks. These are typically defined inside of a WebMap.bookmarks, but can also be defined manually, as shown in the code snippet below.
Example
const bookmarks = new Bookmarks({ view: view, bookmarks: [ // array of bookmarks defined manually new Bookmark({ name: "Angeles National Forest", viewpoint: { targetGeometry: { type: "extent", spatialReference: { wkid: 102100 }, xmin: -13139131.948889678, ymin: 4047767.23531948, xmax: -13092887.54677721, ymax: 4090610.189673263 } } }), new Bookmark({ name: "Crystal Lake", viewpoint: { targetGeometry: { type: "extent", spatialReference: { wkid: 102100 }, xmin: -13125852.551697943, ymin: 4066904.1101411926, xmax: -13114291.451169826, ymax: 4077614.8487296384 }, rotation: 90 } }) ]}); container
- Type
- HTMLElement | null | undefined
The ID or node representing the DOM element containing the widget. This property can only be set once. The following examples are all valid use case when working with widgets.
Examples
// Create the HTML div element programmatically at runtime and set to the widget's containerconst basemapGallery = new BasemapGallery({ view: view, container: document.createElement("div")});
// Add the widget to the top-right corner of the viewview.ui.add(basemapGallery, { position: "top-right"});// Specify an already-defined HTML div element in the widget's container
const basemapGallery = new BasemapGallery({ view: view, container: basemapGalleryDiv});
// Add the widget to the top-right corner of the viewview.ui.add(basemapGallery, { position: "top-right"});
// HTML markup<body> <div id="viewDiv"></div> <div id="basemapGalleryDiv"></div></body>// Specify the widget while adding to the view's UIconst basemapGallery = new BasemapGallery({ view: view});
// Add the widget to the top-right corner of the viewview.ui.add(basemapGallery, { position: "top-right"}); defaultCreateOptions
- Type
- BookmarkOptions
- Since
- ArcGIS Maps SDK for JavaScript 4.18
Specifies how new bookmarks will be created if visibleElements.addBookmarkButton is set to true.
Can be used to enable or disable taking screenshots or capturing the bookmark's viewpoint based on the current
view when a bookmark is created. See BookmarkOptions
for the full list of options.
Example
const bookmarks = new Bookmarks({ view: view, visibleElements: { addBookmarkButton: true, editBookmarkButton: true }, draggable: true, // whenever a new bookmark is created, a 100x100 px // screenshot of the view will be taken and the rotation, scale, and extent // of the view will not be set as the viewpoint of the new bookmark defaultCreateOptions: { takeScreenshot: true, captureViewpoint: false, captureTimeExtent: false, // the time extent of the view will not be saved in the bookmark screenshotSettings: { width: 100, height: 100 } }}); defaultEditOptions
- Type
- BookmarkOptions
- Since
- ArcGIS Maps SDK for JavaScript 4.18
Specifies how bookmarks will be edited, if visibleElements.editBookmarkButton is set to true.
Can be used to enable or disable taking screenshots or capturing the bookmark's viewpoint based on the current
view when a bookmark is edited. See BookmarkOptions
for the full list of options.
disabled
- Type
- boolean
- Since
- ArcGIS Maps SDK for JavaScript 4.15
When true, the widget is visually withdrawn and cannot be interacted with.
- Default value
- false
dragEnabled
- Type
- boolean
- Since
- ArcGIS Maps SDK for JavaScript 4.29
Indicates if a Bookmark is able to be dragged in order to update its position in the list.
- Default value
- false
filterPlaceholder
- Type
- string
- Since
- ArcGIS Maps SDK for JavaScript 4.29
Defines the text used as a placeholder when visibleElements.filter is set to true.
- Default value
- ""
filterText
- Type
- string
- Since
- ArcGIS Maps SDK for JavaScript 4.29
Defines the text used to filter the bookmarks when visibleElements.filter is set to true.
- Default value
- ""
goToOverride
- Type
- GoToOverride | null | undefined
This function provides the ability to override either the MapView goTo() or SceneView goTo() methods.
- See also
Example
// The following snippet uses Search but can be applied to any// widgets that support the goToOverride property.search.goToOverride = function(view, goToParams) { goToParams.options = { duration: updatedDuration }; return view.goTo(goToParams.target, goToParams.options);}; headingLevel
- Type
- HeadingLevel
- Since
- ArcGIS Maps SDK for JavaScript 4.20
Indicates the heading level to use for the message "No bookmarks" when no bookmarks
are available in this widget. By default, this message is rendered
as a level 2 heading (e.g. <h2>No bookmarks</h2>). Depending on the widget's placement
in your app, you may need to adjust this heading for proper semantics. This is
important for meeting accessibility standards.
- See also
- Default value
- 2
Example
// "No bookmarks" will render as an <h3>bookmarks.headingLevel = 3; icon
- Type
- Icon["icon"]
- Since
- ArcGIS Maps SDK for JavaScript 4.27
Icon which represents the widget. It is typically used when the widget is controlled by another one (e.g. in the Expand widget).
- Default value
- "bookmark"
uid
- Type
- string
- Since
- ArcGIS Maps SDK for JavaScript 4.33
An automatically generated unique identifier assigned to the instance. The unique id is generated each time the application is loaded.
view
- Type
- MapViewOrSceneView | null | undefined
The view from which the widget will operate.
Note: Bookmarks are supported in a SceneView only if they come from a WebMap or are provided manually. Presentation provides a similar experience for WebScenes.
viewModel
- Type
- BookmarksViewModel
The view model for this widget. This is a class that contains all the logic (properties and methods) that controls this widget's behavior. See the BookmarksViewModel class to access all properties and methods on the widget.
visible
- Type
- boolean
Indicates whether the widget is visible.
If false, the widget will no longer be rendered in the web document. This may affect the layout of other elements or widgets in the document. For example, if this widget is
the first of three widgets associated to the upper right hand corner of the DefaultUI, then the other widgets will reposition when this widget is made invisible.
For more information, refer to the css display value of "none".
- Default value
- true
Example
// Hides the widget in the viewwidget.visible = false; visibleElements
- Since
- ArcGIS Maps SDK for JavaScript 4.13
The visible elements that are displayed within the widget. This property provides the ability to turn individual elements of the widget's display on/off.
Example
bookmarks.visibleElements = { thumbnail: false};Methods
| Method | Signature | Class |
|---|---|---|
classes inherited | classes(...classNames: ((string | null | undefined) | ((string[] | Record<string, boolean>) | null | undefined) | false | null | undefined)[]): string | |
destroy inherited | destroy(): void | |
emit inherited | emit<Type extends EventNames<this>>(type: Type, event?: this["@eventTypes"][Type]): boolean | |
goTo(bookmark: Bookmark): Promise<void> | | |
hasEventListener inherited | hasEventListener<Type extends EventNames<this>>(type: Type): boolean | |
isFulfilled inherited | isFulfilled(): boolean | |
isRejected inherited | isRejected(): boolean | |
isResolved inherited | isResolved(): boolean | |
on inherited | on<Type extends EventNames<this>>(type: Type, listener: EventedCallback<this["@eventTypes"][Type]>): ResourceHandle | |
postInitialize inherited | postInitialize(): void | |
render inherited | render(): any | null | |
renderNow inherited | renderNow(): void | |
scheduleRender inherited | scheduleRender(): void | |
when inherited | when<TResult1 = this, TResult2 = never>(onFulfilled?: OnFulfilledCallback<this, TResult1> | null | undefined, onRejected?: OnRejectedCallback<TResult2> | null | undefined): Promise<TResult1 | TResult2> |
classes
- Signature
-
classes (...classNames: ((string | null | undefined) | ((string[] | Record<string, boolean>) | null | undefined) | false | null | undefined)[]): string
A utility method used for building the value for a widget's class property.
This aids in simplifying css class setup.
Parameters
- Returns
- string
The computed class name.
Example
// .tsx syntax showing how to set css classes while rendering the widget
render() { const dynamicClasses = { [css.flip]: this.flip, [css.primary]: this.primary };
return ( <div class={classes(css.root, css.mixin, dynamicClasses)} /> );} emit
- Signature
-
emit <Type extends EventNames<this>>(type: Type, event?: this["@eventTypes"][Type]): boolean
- Type parameters
- <Type extends EventNames<this>>
Emits an event on the instance. This method should only be used when creating subclasses of this class.
hasEventListener
- Signature
-
hasEventListener <Type extends EventNames<this>>(type: Type): boolean
- Type parameters
- <Type extends EventNames<this>>
Indicates whether there is an event listener on the instance that matches the provided event name.
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| type | Type | The name of the event. | |
- Returns
- boolean
Returns true if the class supports the input event.
isFulfilled
- Signature
-
isFulfilled (): boolean
isFulfilled() may be used to verify if creating an instance of the class is fulfilled (either resolved or rejected).
If it is fulfilled, true will be returned.
- Returns
- boolean
Indicates whether creating an instance of the class has been fulfilled (either resolved or rejected).
isRejected
- Signature
-
isRejected (): boolean
isRejected() may be used to verify if creating an instance of the class is rejected.
If it is rejected, true will be returned.
- Returns
- boolean
Indicates whether creating an instance of the class has been rejected.
isResolved
- Signature
-
isResolved (): boolean
isResolved() may be used to verify if creating an instance of the class is resolved.
If it is resolved, true will be returned.
- Returns
- boolean
Indicates whether creating an instance of the class has been resolved.
on
- Signature
-
on <Type extends EventNames<this>>(type: Type, listener: EventedCallback<this["@eventTypes"][Type]>): ResourceHandle
- Type parameters
- <Type extends EventNames<this>>
Registers an event handler on the instance. Call this method to hook an event with a listener.
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| type | Type | An event or an array of events to listen for. | |
| listener | EventedCallback<this["@eventTypes"][Type]> | The function to call when the event fires. | |
- Returns
- ResourceHandle
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);}); when
- Signature
-
when <TResult1 = this, TResult2 = never>(onFulfilled?: OnFulfilledCallback<this, TResult1> | null | undefined, onRejected?: OnRejectedCallback<TResult2> | null | undefined): Promise<TResult1 | TResult2>
when() may be leveraged once an instance of the class is created. This method takes two input parameters: an onFulfilled function and an onRejected function.
The onFulfilled executes when the instance of the class loads. The
onRejected executes if the instance of the class fails to load.
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| onFulfilled | OnFulfilledCallback<this, TResult1> | null | undefined | The function to call when the promise resolves. | |
| onRejected | The function to execute when the promise fails. | |
- Returns
- Promise<TResult1 | TResult2>
Returns a new promise for the result of
onFulfilledthat may be used to chain additional functions.
Example
// Although this example uses MapView, any class instance that is a promise may use when() in the same waylet view = new MapView();view.when(function(){ // This function will execute once the promise is resolved}, function(error){ // This function will execute if the promise is rejected due to an error});Events
| Name | Type |
|---|---|
bookmark-edit inherited | |
bookmark-select inherited |
bookmark-edit
bookmark-edit: CustomEvent<BookmarksViewModelBookmarkEditEvent> - Since
- ArcGIS Maps SDK for JavaScript 4.17
Fires when a Bookmark is edited.
Example
// once an edit has been made, enable the "Save Webmap" button// to allow the user to save their changesbookmarksWidget.on("bookmark-edit", function(event){ saveBtn.disabled = false;} bookmark-select
bookmark-select: CustomEvent<BookmarksViewModelBookmarkSelectEvent> - Since
- ArcGIS Maps SDK for JavaScript 4.17
Fires when a Bookmark is selected.
Example
const bookmarksWidget = new Bookmarks({ view: view});
const bookmarksExpand = new Expand({ view: view, content: bookmarksWidget});view.ui.add(bookmarksExpand, "top-right");
// collapses the associated Expand instance// when the user selects a bookmarkbookmarksWidget.on("bookmark-select", function(event){ bookmarksExpand.expanded = false;});