https://community.esri.com/people/EPolle_TensingInternational/blog/2020/06/14/tutorial-arcgis-api-for-javascript-4x-table-of-contents
watchUtils: only add Compass Widget when needed
In general maps are oriented north. This is a widely used convention in cartography. And the same is true for most web maps. With the ArcGIS API for JavaScript 4.x however it is possible to rotate the map on the screen.
The user can rotate the map (or rather the view) in two ways:
right-click + drag with the mouse- tapping the
A and D keys
You, as a developer, can also use programmatic navigation by adjusting MapView.rotation
To allow the user to reset the compass orientation to 0 (i.e. with north at the top of the view) you have to add a Compass widget to the view. This widget indicates where north is in relation to the current view rotation. Clicking the widget rotates the view back to face north (heading = 0).
So, in a sense, you could say that you only need this Compass widget when the map is not oriented north. Or, the other way round: most of the time the Compass widget is not needed, because the map is "correctly" oriented.
In the sample below we only add the Compass when the user rotates the map (be it by accident or on purpose). And the moment the compass orientation has been reset to 0 we remove it again.
To check the orientation of the view we use watchUtils like this:
watchUtils<SPAN class="punctuation token">.</SPAN><SPAN class="token function">whenTrue</SPAN><SPAN class="punctuation token">(</SPAN>view<SPAN class="punctuation token">,</SPAN> <SPAN class="string token">"stationary"</SPAN><SPAN class="punctuation token">,</SPAN> <SPAN class="keyword token">function</SPAN><SPAN class="punctuation token">(</SPAN><SPAN class="punctuation token">)</SPAN> <SPAN class="punctuation token">{</SPAN>
<SPAN class="keyword token">if</SPAN> <SPAN class="punctuation token">(</SPAN>view<SPAN class="punctuation token">.</SPAN>rotation <SPAN class="operator token">==</SPAN> <SPAN class="number token">0</SPAN><SPAN class="punctuation token">)</SPAN><SPAN class="punctuation token">{</SPAN>
view<SPAN class="punctuation token">.</SPAN>ui<SPAN class="punctuation token">.</SPAN><SPAN class="token function">remove</SPAN><SPAN class="punctuation token">(</SPAN>compassWidget<SPAN class="punctuation token">)</SPAN><SPAN class="punctuation token">;</SPAN>
<SPAN class="punctuation token">}</SPAN> <SPAN class="keyword token">else</SPAN> <SPAN class="punctuation token">{</SPAN>
view<SPAN class="punctuation token">.</SPAN>ui<SPAN class="punctuation token">.</SPAN><SPAN class="token function">add</SPAN><SPAN class="punctuation token">(</SPAN>compassWidget<SPAN class="punctuation token">,</SPAN> <SPAN class="string token">"top-left"</SPAN><SPAN class="punctuation token">)</SPAN><SPAN class="punctuation token">;</SPAN>
<SPAN class="punctuation token">}</SPAN>
<SPAN class="punctuation token">}</SPAN><SPAN class="punctuation token">)</SPAN><SPAN class="line-numbers-rows"><SPAN></SPAN><SPAN></SPAN><SPAN></SPAN><SPAN></SPAN><SPAN></SPAN><SPAN></SPAN><SPAN></SPAN></SPAN>Below you will find the full code of this sample, and you can view it live:
ArcGIS JavaScript Tutorial - Add Compass Widget only when needed
<SPAN class="token tag"><SPAN class="token tag"><SPAN class="punctuation token"><</SPAN>html</SPAN><SPAN class="punctuation token">></SPAN></SPAN>
<SPAN class="token tag"><SPAN class="token tag"><SPAN class="punctuation token"><</SPAN>head</SPAN><SPAN class="punctuation token">></SPAN></SPAN>
<SPAN class="token tag"><SPAN class="token tag"><SPAN class="punctuation token"><</SPAN>meta</SPAN> <SPAN class="attr-name token">charset</SPAN><SPAN class="attr-value token"><SPAN class="punctuation token">=</SPAN><SPAN class="punctuation token">"</SPAN>utf-8<SPAN class="punctuation token">"</SPAN></SPAN> <SPAN class="punctuation token">/></SPAN></SPAN>
<SPAN class="token tag"><SPAN class="token tag"><SPAN class="punctuation token"><</SPAN>meta</SPAN> <SPAN class="attr-name token">name</SPAN><SPAN class="attr-value token"><SPAN class="punctuation token">=</SPAN><SPAN class="punctuation token">"</SPAN>viewport<SPAN class="punctuation token">"</SPAN></SPAN> <SPAN class="attr-name token">content</SPAN><SPAN class="attr-value token"><SPAN class="punctuation token">=</SPAN><SPAN class="punctuation token">"</SPAN>initial-scale<SPAN class="punctuation token">=</SPAN>1,maximum-scale<SPAN class="punctuation token">=</SPAN>1,user-scalable<SPAN class="punctuation token">=</SPAN>no<SPAN class="punctuation token">"</SPAN></SPAN><SPAN class="punctuation token">/></SPAN></SPAN>
<SPAN class="token tag"><SPAN class="token tag"><SPAN class="punctuation token"><</SPAN>title</SPAN><SPAN class="punctuation token">></SPAN></SPAN>ArcGIS JavaScript Tutorial - Add Compass Widget only when needed<SPAN class="token tag"><SPAN class="token tag"><SPAN class="punctuation token"></</SPAN>title</SPAN><SPAN class="punctuation token">></SPAN></SPAN>
<SPAN class="token tag"><SPAN class="token tag"><SPAN class="punctuation token"><</SPAN>link</SPAN> <SPAN class="attr-name token">rel</SPAN><SPAN class="attr-value token"><SPAN class="punctuation token">=</SPAN><SPAN class="punctuation token">"</SPAN>stylesheet<SPAN class="punctuation token">"</SPAN></SPAN> <SPAN class="attr-name token">href</SPAN><SPAN class="attr-value token"><SPAN class="punctuation token">=</SPAN><SPAN class="punctuation token">"</SPAN>https://js.arcgis.com/4.15/esri/themes/light/main.css<SPAN class="punctuation token">"</SPAN></SPAN><SPAN class="punctuation token">/></SPAN></SPAN>
<SPAN class="language-javascript script token"><SPAN class="token tag"><SPAN class="token tag"><SPAN class="punctuation token"><</SPAN>script</SPAN> <SPAN class="attr-name token">src</SPAN><SPAN class="attr-value token"><SPAN class="punctuation token">=</SPAN><SPAN class="punctuation token">"</SPAN>https://js.arcgis.com/4.15/<SPAN class="punctuation token">"</SPAN></SPAN><SPAN class="punctuation token">></SPAN></SPAN><SPAN class="token tag"><SPAN class="token tag"><SPAN class="punctuation token"></</SPAN>script</SPAN><SPAN class="punctuation token">></SPAN></SPAN></SPAN>
<SPAN class="language-css style token"><SPAN class="token tag"><SPAN class="token tag"><SPAN class="punctuation token"><</SPAN>style</SPAN><SPAN class="punctuation token">></SPAN></SPAN>
<SPAN class="selector token">html, body, #viewDiv</SPAN> <SPAN class="punctuation token">{</SPAN>
<SPAN class="property token">padding</SPAN><SPAN class="punctuation token">:</SPAN> 0<SPAN class="punctuation token">;</SPAN>
<SPAN class="property token">margin</SPAN><SPAN class="punctuation token">:</SPAN> 0<SPAN class="punctuation token">;</SPAN>
<SPAN class="property token">height</SPAN><SPAN class="punctuation token">:</SPAN> 100%<SPAN class="punctuation token">;</SPAN>
<SPAN class="property token">width</SPAN><SPAN class="punctuation token">:</SPAN> 100%<SPAN class="punctuation token">;</SPAN>
<SPAN class="punctuation token">}</SPAN>
<SPAN class="token tag"><SPAN class="token tag"><SPAN class="punctuation token"></</SPAN>style</SPAN><SPAN class="punctuation token">></SPAN></SPAN></SPAN>
<SPAN class="language-javascript script token"><SPAN class="token tag"><SPAN class="token tag"><SPAN class="punctuation token"><</SPAN>script</SPAN><SPAN class="punctuation token">></SPAN></SPAN>
<SPAN class="token function">require</SPAN><SPAN class="punctuation token">(</SPAN><SPAN class="punctuation token">[</SPAN>
<SPAN class="string token">"esri/Map"</SPAN><SPAN class="punctuation token">,</SPAN>
<SPAN class="string token">"esri/views/MapView"</SPAN><SPAN class="punctuation token">,</SPAN>
<SPAN class="string token">"esri/widgets/Compass"</SPAN><SPAN class="punctuation token">,</SPAN>
<SPAN class="string token">"esri/core/watchUtils"</SPAN>
<SPAN class="punctuation token">]</SPAN><SPAN class="punctuation token">,</SPAN> <SPAN class="keyword token">function</SPAN><SPAN class="punctuation token">(</SPAN>Map<SPAN class="punctuation token">,</SPAN> MapView<SPAN class="punctuation token">,</SPAN> Compass<SPAN class="punctuation token">,</SPAN> watchUtils<SPAN class="punctuation token">)</SPAN> <SPAN class="punctuation token">{</SPAN>
<SPAN class="keyword token">var</SPAN> map <SPAN class="operator token">=</SPAN> <SPAN class="keyword token">new</SPAN> <SPAN class="token class-name">Map</SPAN><SPAN class="punctuation token">(</SPAN><SPAN class="punctuation token">{</SPAN>
basemap<SPAN class="punctuation token">:</SPAN> <SPAN class="string token">"national-geographic"</SPAN>
<SPAN class="punctuation token">}</SPAN><SPAN class="punctuation token">)</SPAN><SPAN class="punctuation token">;</SPAN>
<SPAN class="keyword token">var</SPAN> view <SPAN class="operator token">=</SPAN> <SPAN class="keyword token">new</SPAN> <SPAN class="token class-name">MapView</SPAN><SPAN class="punctuation token">(</SPAN><SPAN class="punctuation token">{</SPAN>
container<SPAN class="punctuation token">:</SPAN> <SPAN class="string token">"viewDiv"</SPAN><SPAN class="punctuation token">,</SPAN>
scale<SPAN class="punctuation token">:</SPAN> <SPAN class="number token">500000</SPAN><SPAN class="punctuation token">,</SPAN>
center<SPAN class="punctuation token">:</SPAN> <SPAN class="punctuation token">[</SPAN><SPAN class="number token">26.26</SPAN><SPAN class="punctuation token">,</SPAN> <SPAN class="number token">39.17</SPAN><SPAN class="punctuation token">]</SPAN><SPAN class="punctuation token">,</SPAN>
rotation<SPAN class="punctuation token">:</SPAN> <SPAN class="number token">45</SPAN><SPAN class="punctuation token">,</SPAN>
map<SPAN class="punctuation token">:</SPAN> map
<SPAN class="punctuation token">}</SPAN><SPAN class="punctuation token">)</SPAN><SPAN class="punctuation token">;</SPAN>
<SPAN class="keyword token">var</SPAN> compassWidget <SPAN class="operator token">=</SPAN> <SPAN class="keyword token">new</SPAN> <SPAN class="token class-name">Compass</SPAN><SPAN class="punctuation token">(</SPAN><SPAN class="punctuation token">{</SPAN>
view<SPAN class="punctuation token">:</SPAN> view
<SPAN class="punctuation token">}</SPAN><SPAN class="punctuation token">)</SPAN><SPAN class="punctuation token">;</SPAN>
<SPAN class="comment token">// Watch view's stationary property for becoming true to check the rotation</SPAN>
<SPAN class="comment token">// If the rotation equals 0 (i.e. map is oriented North) remove the compass widget,</SPAN>
<SPAN class="comment token">// otherwise add this widget</SPAN>
watchUtils<SPAN class="punctuation token">.</SPAN><SPAN class="token function">whenTrue</SPAN><SPAN class="punctuation token">(</SPAN>view<SPAN class="punctuation token">,</SPAN> <SPAN class="string token">"stationary"</SPAN><SPAN class="punctuation token">,</SPAN> <SPAN class="keyword token">function</SPAN><SPAN class="punctuation token">(</SPAN><SPAN class="punctuation token">)</SPAN> <SPAN class="punctuation token">{</SPAN>
<SPAN class="keyword token">if</SPAN> <SPAN class="punctuation token">(</SPAN>view<SPAN class="punctuation token">.</SPAN>rotation <SPAN class="operator token">==</SPAN> <SPAN class="number token">0</SPAN><SPAN class="punctuation token">)</SPAN><SPAN class="punctuation token">{</SPAN>
view<SPAN class="punctuation token">.</SPAN>ui<SPAN class="punctuation token">.</SPAN><SPAN class="token function">remove</SPAN><SPAN class="punctuation token">(</SPAN>compassWidget<SPAN class="punctuation token">)</SPAN><SPAN class="punctuation token">;</SPAN>
<SPAN class="punctuation token">}</SPAN> <SPAN class="keyword token">else</SPAN> <SPAN class="punctuation token">{</SPAN>
view<SPAN class="punctuation token">.</SPAN>ui<SPAN class="punctuation token">.</SPAN><SPAN class="token function">add</SPAN><SPAN class="punctuation token">(</SPAN>compassWidget<SPAN class="punctuation token">,</SPAN> <SPAN class="string token">"top-left"</SPAN><SPAN class="punctuation token">)</SPAN><SPAN class="punctuation token">;</SPAN>
<SPAN class="punctuation token">}</SPAN>
<SPAN class="punctuation token">}</SPAN><SPAN class="punctuation token">)</SPAN>
<SPAN class="punctuation token">}</SPAN><SPAN class="punctuation token">)</SPAN><SPAN class="punctuation token">;</SPAN>
<SPAN class="token tag"><SPAN class="token tag"><SPAN class="punctuation token"></</SPAN>script</SPAN><SPAN class="punctuation token">></SPAN></SPAN></SPAN>
<SPAN class="token tag"><SPAN class="token tag"><SPAN class="punctuation token"></</SPAN>head</SPAN><SPAN class="punctuation token">></SPAN></SPAN>
<SPAN class="token tag"><SPAN class="token tag"><SPAN class="punctuation token"><</SPAN>body</SPAN><SPAN class="punctuation token">></SPAN></SPAN>
<SPAN class="token tag"><SPAN class="token tag"><SPAN class="punctuation token"><</SPAN>div</SPAN> <SPAN class="attr-name token">id</SPAN><SPAN class="attr-value token"><SPAN class="punctuation token">=</SPAN><SPAN class="punctuation token">"</SPAN>viewDiv<SPAN class="punctuation token">"</SPAN></SPAN><SPAN class="punctuation token">></SPAN></SPAN><SPAN class="token tag"><SPAN class="token tag"><SPAN class="punctuation token"></</SPAN>div</SPAN><SPAN class="punctuation token">></SPAN></SPAN>
<SPAN class="token tag"><SPAN class="token tag"><SPAN class="punctuation token"></</SPAN>body</SPAN><SPAN class="punctuation token">></SPAN></SPAN>
<SPAN class="token tag"><SPAN class="token tag"><SPAN class="punctuation token"></</SPAN>html</SPAN><SPAN class="punctuation token">></SPAN></SPAN><SPAN class="line-numbers-rows"><SPAN></SPAN><SPAN></SPAN><SPAN></SPAN><SPAN></SPAN><SPAN></SPAN><SPAN></SPAN><SPAN></SPAN><SPAN></SPAN><SPAN></SPAN><SPAN></SPAN><SPAN></SPAN><SPAN></SPAN><SPAN></SPAN><SPAN></SPAN><SPAN></SPAN><SPAN></SPAN><SPAN></SPAN><SPAN></SPAN><SPAN></SPAN><SPAN></SPAN><SPAN></SPAN><SPAN></SPAN><SPAN></SPAN><SPAN></SPAN><SPAN></SPAN><SPAN></SPAN><SPAN></SPAN><SPAN></SPAN><SPAN></SPAN><SPAN></SPAN><SPAN></SPAN><SPAN></SPAN><SPAN></SPAN><SPAN></SPAN><SPAN></SPAN><SPAN></SPAN><SPAN></SPAN><SPAN></SPAN><SPAN></SPAN><SPAN></SPAN><SPAN></SPAN><SPAN></SPAN><SPAN></SPAN><SPAN></SPAN><SPAN></SPAN><SPAN></SPAN><SPAN></SPAN><SPAN></SPAN><SPAN></SPAN><SPAN></SPAN><SPAN></SPAN><SPAN></SPAN><SPAN></SPAN><SPAN></SPAN><SPAN></SPAN></SPAN>
