Alerting the user of stale map areas​

The first Workflow we'll look at checks for custom areas which have already been downloaded, calculates if the date it was last updated is past a certain threshold, and alerts the user if the area is stale. The Workflow can be downloaded here and imported into Designer.

I'll walk you through the key functionality.

1. First, this Workflow runs the offline.get-custom-areas command, and checks if there are any results (if not, there's nothing more to do).

   This command, and subsequently this whole Workflow, works without an Internet connection, because it's only looking at local data on the device.

2. Next, we're going to loop over each custom map area, and build a message to display if they're stale.

3. Inside the For Each loop, we first check the status of the map area to see if it is downloaded.

   The status is indicated as a flags enum, where 2 represents the Downloaded state and 4 represents Active. Hence the bitwise & operations in this If activity checks for the presence of the Downloaded or Active state flags.

4. If the area is downloaded, we'll compare the last update date on the map area with the current date and time to see if it's stale. Workflow's Format Date activity makes it easy to do the math with the unix timestamp, and to display the date in a friendly way, so we'll use that activity.

5. Here's where we do that math: in this example, checking if the update was more than one week ago from today.

   If you have a different update schedule, e.g. "my users should update their map areas every Monday", you could adjust the logic here.

6. Rather than displaying a separate notification for each stale area, we're going to aggregate all the stale area warnings so we can just display a single notification after we've finished checking each area.

7. Here's where we run the ui.display-notification operation, displaying the alert to the user (if we did indeed add any lines to the message in Step 6).

   In this example, we display it at the 'warning' level. You could add some logic that displays an 'info' level notification if their map areas are only a few days stale and a 'warning' level for older ones, or display a more obvious alert rather than just a notification, etc.

Here's the result:

Automatically downloading areas​

The second Workflow we'll look at deals with preplanned areas. It will check if there are any which have not yet been downloaded. If there are, it notifies the user, automatically begins the download process, and opens the Map Areas panel so the user can monitor the download progress. It can be downloaded for import here.

1. This Workflow starts off similarly to the first one, but uses offline.get-areas instead of offline.get-custom-areas. This returns both custom and preplanned areas.

2. We want to filter through all the map areas to find only the ones that are preplanned (which we can do by checking if the Removable property is false) and which are in the Available to Download state (a value of 0 in the enum described earlier).

   You could change the logic here to look for a map areas with a specific title, if you only wanted some subset of your map areas to be automatically downloaded, for example.

3. If we have no Internet connection, the Workflow would have still gotten to this point if it found local map areas (custom, or already-downloaded preplanned areas). However, we won't be able to perform a download without a connection. Inside this Container activity we'll check that we are connected, and that network requests are not disabled in the app settings. If the conditions are not met, we'll exit the Workflow early.

4. Now we know we can start the downloads; let's alert the user.

5. Here we'll loop over each preplanned area, and call offline.download-area via the Run Command activity.

   Using Run Command rather than Run Operation here ensures that the Workflow will move on to the next activity as soon as it triggers the command, as opposed to waiting for the operation (i.e. the whole download process) to complete. This enables us to get multiple downloads all running in parallel.

   If you wanted to modify this Workflow to also update areas which are already downloaded, you could adjust the filter in Step 2 to include these map areas (see the check from Step 3 in the first Workflow) and call the offline.update-area command in this loop as well.

6. Finally, we'll call ui.activate to automatically open the Offline Areas panel. Now the user can watch their downloads proceed, and if they want to manually start downloading a custom map area at the same time or something, they can do so.

note

Note that the argument to ui.activate in this sample Workflow, "item://offline/map-areas", is using the default item id ("map-areas") for the Offline Areas panel from the Mobile Default app template from Designer. If your component's id is different, you'll have to change this argument. You can check the id by clicking the cog icon at the top of the component's configuration panel in Designer.

And here's the result in action:

Running the Workflows on start-up​

Both of the above Workflows are designed to run from the same point: from the 'Map Initialized' event. This is because the first step, checking for map areas, needs to access the map. The configuration for this can be found in Designer, under the Map Component's Events configuration section.

Once you've added your Workflow there, it will run every time the user launches or refreshes the app. Since neither of these Workflows displays a Workflow Form, set the Target property to 'None'. This prevents a panel from unnecessarily appearing in the taskbar to host your Workflow.

Feel free to copy these Workflows and modify them as necessary for your own use cases!

ArcGIS Maps SDK for JavaScript .watch Deprecation​

Prior to the ArcGIS Maps SDK for JavaScript (ArcGIS JS SDK) version 4.32 release, almost every class in the ArcGIS JS SDK had a .watch method. This method was inherited from the base class Accessor that most classes in the ArcGIS JS SDK ultimately inherit from. With the release of 4.32, the .watch method on Accessor was deprecated in favour of using their reactiveUtils utility functions instead as these were the utilities that replaced the watchUtils the ArcGIS JS SDK had at initial release.

When VertiGIS Studio Web (Web) was first developed, we followed the watch pattern that had been established by the ArcGIS JS SDK. Doing this allowed for a more seamless experience when developing Web SDK applications; you could follow the same pattern and the watch utilities were compatible.

When watchUtils was deprecated and reactiveUtils support was added, we had to make a decision of how we would support this change going forward. Because only watchUtils support was being removed, and the .watch method on Accessor was remaining, it was decided to leave the .watch method on our classes as well but also add support for using our classes with reactiveUtils. By doing this we were able to support reactiveUtils without any breaking changes to our APIs. You can read about the watchUtils to reactiveUtils change in the ArcGIS JS SDK here: Why you should be using reactiveUtils instead of watchUtils.

Now, with the deprecation of the .watch method on Accessor, the last vestige of the watchUtils is finally being removed from the ArcGIS JS SDK. But as much of our code still uses the .watch method pattern, we finally had to confront a breaking change.

How the Removal of One Method Snowballed into an Overhaul​

Why not just remove the one deprecated pattern and leave the reactiveUtils support? Good question. That was definitely an option. But the support for reactiveUtils and how it was implemented had some major side effects that we’ve been trying to deal with ever since.

reactiveUtils Inside VertiGIS Studio Web​

To understand why the deprecation of .watch cascaded into an overhaul of our property watch system, you have to understand how we’re currently supporting the use of our classes with the ArcGIS JS SDK’s reactiveUtils and how reactiveUtils work.

All of the ArcGIS JS SDK’s classes (or at least most) are compatible with reactiveUtils; you can use them with reactiveUtils without thinking about it and it will just work. However, if you try to use your own class with reactiveUtils it isn’t going to do anything.

For properties to be "watchable" with reactiveUtils, your property needs to be able to "announce" itself to the ArcGIS JS SDK reactiveUtils system whenever it is accessed, not just when it changes. To do this you would normally need to add a decorator the ArcGIS JS SDK provides to your property (See Property). This decorator adds the necessary code to the property to make the property "watchable". Having to add this decorator to every property in Web would have been a daunting task, but that wasn’t the only problem we faced.

At the time, to use those decorators you needed to set your tsconfig with useDefineForClassFields to false. Setting this to false is only meant for pre-TC39 projects as part of migration and this compiler option now defaults to true since ES2022 when not specified. We did not like the idea of using an old compiler option to use reactiveUtils with our classes.

So if we didn't want to find every single property in our classes to decorate and we didn't want to use the old compiler option, we needed another solution. Enter, the JS Proxy... and some dicey JS.

If we could wrap our classes in a JS Proxy we would be able to use its traps for ‘get’ and ‘set’ which would give us the ability to "announce" access and changes of a property to the underlying system supporting reactiveUtils. We already had a core base class called Observable that was handling the old watchUtils style watches and all classes in Web ultimately inherited from this base class, so the proxy was added to the constructor of this class.

Now, the classes and interfaces necessary to be able to tell reactiveUtils about properties are not exposed publicly from the ArcGIS JS SDK, but being JS everything is technically accessible. We did some reverse engineering to discover how to tell reactiveUtils when a property was accessed or changed and implemented that in the proxy traps. This effectively allowed every property on all of our classes to participate in the reactiveUtils watch system.

The Downsides of Using JS Proxy with Classes in Web​

For the most part, the JS Proxy implementation has been very effective. So effective, in fact, that it seems to be doing magic, and that magic has created some very hard to find bugs over the years.

Because the JS Proxy traps all properties on the object, this means that all data properties, accessor properties, and methods must run through the ‘get’ and ‘set’ traps. Additionally, every time an accessor property was accessed (getter), every single underlying property and method that was on one of our classes that was invoked in the property getter would announce itself to the reactiveUtils watch system. This cascade of property tracking made it easy to create a new property without needing to worry about the watch system and what it needs to know about to watch that property for changes. However, this amount of magic is costly, and performance takes a significant hit for this convenience. Memory usage also suffers with the amount of extra things being tracked that don’t necessarily need to be. On top of this, because this was implemented in the base class that everything in Web inherits from, it made everything in Web watchable, even when it didn’t need to be, creating even more overhead.

There are other development level inconveniences. The amount of "magic" happening for watches meant that when the "magic" didn’t work, developers would spend an inordinate amount of time trying to figure out why, instead of understanding the limitations of the watch system and when they needed to perform some extra calls to ensure that watches would work properly. It would even result in some interesting workarounds to what should have been a simple fix. Using the proxy also made it so that JS’s private property #prop couldn’t be used as these properties are not available on JS Proxies, limiting use of a built-in modern JS feature in our codebase. The main inconvenience though, is during debugging. JS Proxies add an extra layer to objects to sift through when trying to debug your code, and if every single class is a proxy, that’s a lot of extra layers to go through to get to the information you’re looking for, subsequently burning development time.

With these issues in mind, particularly the performance hit, we’ve been wanting to remove the use of the JS Proxy from our classes for some time, but we’ve never had a good path forward that would allow us to continue providing property change watch support with reactiveUtils.

The Pros and Cons of reactiveUtils​

Over the years we have seen many uses of reactiveUtils, both in our codebase and across various Web SDK applications built internally and externally, and we have learned a lot about how to use it well, where it shines, and where we wish we had something slightly different.

Let’s talk about the pros. The interface is simple and somewhat familiar to JS developers. Callbacks are commonplace in JS and by utilizing them for the watch value callback the watch function from reactiveUtils is easy to use. Autocomplete and renaming properties/methods work well in IDEs and there’s flexibility, allowing you to do more than just return a property value: you can return calculations from multiple properties and all of that would be tracked and trigger the callback when those properties change. If using TypeScript, as we recommend and use in our codebase, the return value from the watch value callback is typed properly when passed to the callback, making development that much easier and less error prone.

But there are some downsides we’ve found, and some are harder to spot than others. The first issue that caught us quite a few times is that the property you are watching, the entire object chain, may not actually be watchable and there’s nothing in the IDE, types from TypeScript, or even at runtime that will tell you that the watch you setup isn’t going to do anything.

The callback in this code will never execute:

const myObj = { testProp = "test1" };
watch(
    () => myObj.testProp,
    // This callback will never fire because the
    // object being watched isn't watchable.
    (value) => console.log(value)
);
myObj.testProp = "test2";

While this is a contrived example, it is easy to see where someone can accidentally fall into this trap when you’re working with many nested properties on a mix of objects from different sources. There have been a number of times where a watch would be added that looks like it is needed and everything seems to be working as intended but the watch itself never actually does anything because it is watching something that is unwatchable and the intended behavior is actually occurring due to another piece of code. While having a watch that does nothing may not seem so bad on the surface, it does clutter up code and change people’s expectations of how something is supposed to be working. There is also another drawback we discovered.

Creating a new watch does impact performance. When you spend a minute to think about it, of course it does! You’re executing a function that is going to do something, it must do work which takes some amount of time. But it isn’t always something that is considered; executing code to setup something that will ultimately never perform the action it is supposed to is, of course, going to impact performance. With watch from reactiveUtils not being able to tell us if the thing we’re watching is actually watchable, we could be adding a small performance hit to something and if that small performance hit happens 100,000 times, well... you get the idea.

Another thing we've noticed was a recurring misuse of watch from reactiveUtils. watch will return a handle that is supposed to be called to cleanup the watch when it is no longer needed. While this pattern of cleaning up a handler (or listener) is extremely prevalent in development, we’ve found that this is easily missed with reactiveUtils use, and have been known to miss it ourselves from time to time, causing memory leaks.

There is one more consideration that is easily missed when constructing watches using reactiveUtils, and to understand this, you need to know how JavaScript closures and lexical scoping work.

Let’s take the following code as an example:

function myLeakyFunc(
    someLargeObject: object,
    someObservableObject: object
) {
    // The lexical scope created at this level
    // includes both `someLargeObject` and `someObservableObject`.

    // This lexical scope is captured by all 3 anonymous
    // functions' closures and will live for as long as the
    // anonymous functions are referenced.

    const myFunc = () => {
        console.log(someLargeObject);
    };

    const handle = watch(
        () => someObservableObject.prop,
        (newPropValue) => console.log(newPropValue)
    );

    return [myFunc, handle];
}

On the surface this seems innocent enough. We have a large object that needs to be used in an anonymous function and a watch that needs to watch a property on a completely separate observable object, and the anonymous function is returned for use by the caller as well as the watch handle for cleanup when no longer needed. But sadly this has the potential to create a whole host of memory leaks depending on the browser engine and garbage collector being used.

When JavaScript creates closures for functions, those closures are created using the lexical environment for where that function is created. When functions exist at the same lexical environment level, they share the same lexical scope. In this case, both myFunc, the watch value callback, and the watch callback all share the same lexical scope. This means that any objects that are needed for one of these anonymous functions are included in the closure for the other functions, even though they don’t use the value. This means that, even if the returned myFunc goes out of scope by the running program and is cleaned up by the GC, the watch is still holding onto the large object because the large object was included in the lexical scope that the watch callbacks’ closures captured. This also happens the other way around, where myFunc will hold the observable object alive even when we cleanup the watch by calling remove on the returned handle when we were done with it.

While this last example is a basic one, it is easy to imagine how quickly these closure leaks can become a problem in modern JavaScript development.

So, Back to the Removal of .watch​

With the removal of .watch from the ArcGIS JS SDK classes it makes sense for us to remove our implementation of .watch as well, given that our .watch is tied into the ArcGIS JS SDK implementation. This would be a breaking change in the Web SDK which we do try to approach with much caution. While the removal of .watch from the ArcGIS JS SDK is going to be a breaking change for Web SDK developers, and there isn’t anything we can do about that, we always look carefully at any breaking changes we’re going to make to our APIs to ensure that they are truly in the best interests of progressing the ease of future development.

Removing .watch would leave us relying on reactiveUtils for observable functionality, and as you’ve seen reading through this, perhaps that isn’t the best approach for Web, with the use of the JS Proxy and various performance and memory issues. After much discussion, since we were going to have to make a breaking change to the Web SDK anyway with the removal of .watch, we decided to look into what it might look like if we revisited property observability with a fresh approach.

Shaping the New Watch System​

The Wish List​

We compiled a wish list of everything we would want in a property observability implementation, knowing that we likely would need to compromise in some places.

1. Does not use a JS Proxy.
2. A watch system that would remain stable with the same interface if the ArcGIS JS SDK ever changes their watch system again.
3. Will error at compile time with TypeScript if given objects or properties that cannot be watched.
4. Will error or warn at runtime if trying to watch objects or properties that cannot be watched.
5. Will not leak memory, even when misused.
6. Will not do anything functional when nothing is watching a property that is watchable. i.e.: no tracking announcements, no change notifications to nowhere, etc.
7. Will provide auto-completions with TypeScript for properties that are watchable.
8. Will provide correct types with TypeScript for values passed to any callbacks.
9. Remove the need for a root base class that everything must inherit from so that we can be selective about classes that can be observable, not everything needs to be watched.
10. Does not use private/internal code from a third-party library or the ArcGIS JS SDK.
11. Does not require any form of specifying the exact properties that will be observable when creating a new class or updating an existing one.
12. Observability must be opted into by the class implementor.
13. Can accept objects from the ArcGIS JS SDK that are watchable.

And as a must have: Allows us to provide a smooth transition for Web SDK apps with full backwards compatibility for, at minimum, a couple of full release cycles.

This seemed like a pretty daunting wish list. But we had a few ideas, and JavaScript is inherently extremely flexible.

reactiveUtils Support – Or Lack Thereof​

There was one thing that stood out to us with our wish list though; we would not be able to support using our classes with the ArcGIS JS SDK’s reactiveUtils with any new system we came up with that lacked a JS Proxy. reactiveUtils inherently requires the running of property access tracking code when you have no idea if something is watching a property or not, which conflicts with wish list item #6 (no extra code execution). And even if we could come up with something, we’d still end up breaking wish list item #1 (no JS Proxy) and #10 (no third-party private code use). Wish list item #5 (no memory leaks) would also continue to be an issue, and there would be the threat of wish list item #2 (stable interface) not being met.

Because of these reasons, we decided to proceed with a proof-of-concept (POC) that would not include support for using our classes with reactiveUtils functions. We would work in support after if the POC was viable for backwards compatibility, but if the implementation made it past POC the expectation to be set was that support for reactiveUtils would be removed.

Typing the New Watch Function​

A number of our wish list items are related to TypeScript and typing watch functionality so we can surface mistakes at compile time and in an IDE well before code tries to run.

The reactiveUtils pattern does get part way there, but as we’ve explored, it won’t tell you if you’re watching something that shouldn’t be watched because there is no way to interrogate the objects being used in the watch value callback. To compound the type issues with the reactiveUtils watch pattern, we were also thinking about how to deal with accidental/misuse caused memory leaks. We knew we were going to have to have some form of callback for the watch property value change, but if we could control how the property value is accessed before executing that callback and wrap the main object reference in a WeakRef, we’d be able to manage the watch’s object references in a more efficient and less prone to leaks way.

With these things in mind, we decided that our best option was to create a utility function, separate from any classes and require the object to be watched to be passed to it, which will allow us to control how the watch system holds a reference to that watched object.

The original .watch functions used a string to specify paths to properties, but it was just a string, causing mistypes and refactors to break watches without anything surfacing the issue in a timely manner. Those .watch functions were written quite awhile ago, when TypeScript wasn’t very good at recursive typing, and template string types didn’t exist.

So, along with the object to be watched we decided a string property path would be our best option. With modern TypeScript, we can now build out a complex, template string recursive type that can build out the available watch options for nested watch property paths. There is a bit of a performance hit in IDEs when this recursive type encounters large deeply nested objects, so after dialing in the type performance we had to limit the depth of recursion to three for full type checking. But we expect that with the new native TypeScript compiler that’s in the works, this performance issue will get much better and we will likely be able to expand the depth of the type checking further.

Aside from the minor IDE performance issue, there is another IDE related drawback to the string property path: you won’t be able to use rename functionality and have that update the string references, nor will a reference lookup find watches for the properties being watched. But we decided these IDE drawbacks can be lived with, given the memory management advantage of this pattern.

After dialing in the types and starting to spread around the new watch, we did encounter one other quirk. When attempting to pass this as the object being watched, TypeScript wasn’t happy. Turns out, when you’re using constrained generic types for typing arguments and you pass this to one of those arguments TypeScript won’t infer the type of this. They have their reasons, but it is a bit inconvenient in our use case. We debated on how to handle this, and tried a number of different ways to workaround it, but in the end we couldn’t find anything better than just casting this when passed. But, we also realized that in a lot of cases we see where this is being passed as the watch object, a watch really shouldn’t be used. Using the watch system to know when a property changes that you have control of is pretty heavy handed; a better approach would be to do whatever action you want in a setter instead.

No Base Class? Let’s try Decorators … (spoiler, we didn’t use decorators)​

Wish list #9 would have us remove the Observable base class from all of our classes so that we can be more targeted about what is actually observable and what is not. To do this we would need some way to add functionality to a class without inheritance. This sounds like exactly what decorators are designed to do. The first iteration of the new observable implementation was built as a class decorator. This would fulfill wish list item #9 and #11 (no base class and not specifying exact properties that are observable, respectively).

However, we ran into some immediate problems around TypeScript typing. Mainly, TypeScript doesn’t augment the types of a class (or anything) that uses a decorator that, from the JavaScript perspective, does augment the class with new functionality. This created a typing problem: to satisfy wish list item #12 (opt in observability) we would need an extra interface that implementors would also have to add to their observable classes to ensure that the class is observable. It looked something like this:

interface IObservable {
    __isObservable: true;
}

Now, having to spread that around everywhere whenever you used the decorator was going to be very annoying. So, we decided that perhaps, at this moment in time, decorators were not the answer to our problem.

Enter the Mixin Pattern​

Decorators are really just a another way of using the mixin pattern, so we switched gears and gave that a try instead, and it ended up working out really well. With the mixin pattern we were able to wrap any class with our observable implementation, even base classes that a class is inheriting from. It also allowed us to type the returned class so TypeScript would understand that this class is observable so we could surface the type errors we were hoping to without needing to expose an extra interface.

This still requires using the mixin as a base class in most use cases, but because it is a mixin, you can use it to wrap a base class you are already inheriting from, effectively allowing multiple inheritance. While it doesn’t get rid of the base class requirement if the mixin is used this way, it does get rid of the problem that we were trying to solve when we wished for the watch system to not use a base class.

As with everything, there is one drawback to this pattern. If you have constructed a class hierarchy that requires a generic type be passed from a child class to a parent class, TypeScript will not be happy with that.

After reviewing this issue, it was decided this was an acceptable drawback. In most cases, there are other ways to workaround this using base types or type overrides in the child class and this situation does not occur commonly in our Web SDK patterns.

How do you Watch a Property for Changes Without a JS Proxy?​

A JS Proxy has its uses, and observability is one of them, but we’ve found that in Web it just doesn’t scale well. Then the question became, how do you watch a property for changes while satisfying wish list item #11 and not requiring developers to specify every single property they want to be able to watch?

Looking at this problem at the very basic level, we want to be able to call a function (the watch callback) whenever a property is set to a new value. If doing this for just one class, you’d likely consider adding a call to property setters. This thought is what lead us to our implementation.

JavaScript objects allow you to redefine property descriptors so long as the descriptor is configurable. Since all of the objects we work with have configurable descriptors we realized that we could redefine the properties on demand to augment their setter (or if they don’t have one add a setter) to include code to handle calling watch callbacks when the property value changes. A quick POC of this proved its viability. This admittedly may seem a little hacky, but if done thoughtfully and carefully we would be able to create a watch system that only ever does work if something creates a watch instead of having to assume there might be a watch.

Classes from the ArcGIS JS SDK are a bit different. We felt that since it already has a watch system (reactiveUtils) and all the underlying code of that system would be run anyway, we might as well defer to it when we encounter an ArcGIS JS SDK object that is watchable. By controlling how reactiveUtils is used with ArcGIS JS SDK objects under the hood of the new watch system, we can control when a watch needs to be created and manage the accessed objects with WeakRefs for better memory management.

Backwards Compatibility and the Consequences​

At this point we had a pretty good looking POC, everything in our codebase was swapped over and all was well with our automated tests and initial basic testing. But there would be no way we could release this as is as it would break almost every single Web SDK built app out there. We had to come up with a plan for a non-breaking transition.

Deprecating the old .watch functions on our classes instead of removing them outright and swapping the underlying code to the new watch system was fairly straightforward. We just had to change some places where we were throwing exceptions in our new code to log warnings instead and add some extra null checks. We deprecated some other utility functions as well in favour of the new observable system functions.

The real challenge was going to be reactiveUtils support. We ran through a number of different ways to try to add it into the new system without using a JS Proxy, but nothing was going to work 100% of the time. We had to add the proxy back… This meant that some of our innovations for better memory management and improved performance would not be able to make the first release of the new observable system, but backwards compatibility was non-negotiable.

If You’ve Been Keeping Score​

If we look through our wish list items, it looks like we managed to tick everything off the list! Well, almost… the improved memory management and performance will have to wait until we can remove the support added for backwards compatibility and reactiveUtils. We’ll also need to wait for the native TypeScript compiler to dial in the type checking even further. We also didn’t fully get rid of a base class, but we did solve the problem that wish list item was for with the mixin pattern allowing for multiple inheritance. But overall, we managed to accomplish what we set out to do.

The New Watch System​

We’ve completely overhauled how watching objects for property changes works in the VertiGIS Studio Web SDK (Web SDK). This new functionality is going to be more performant and use less memory than the previous versions (once the old code and support for backwards compatibility is removed) and will create a stable interface for us to continuously improve and add to the property watch system.

This new system will reduce the number of common errors we see when using the currently available property watch systems. We did have to deprecate a number of things from the old systems that will be removed, so make sure to review the list and update your Web SDK apps soon. While we are giving a transition period of a couple full release cycles, it is better to jump on this change sooner rather than later.

New Module: observableUtils​

We’ve added a new module that contains all of the new observable functionality called observableUtils.

You can import observableUtils functions from @vertigis/arcgis-extensions.

import { watch } from "@vertigis/arcgis-extensions/support/observableUtils";

Observable Mixin​

To add observability to a class there are a few different ways to use the new mixin to accomplish this, but we’ve found the cleanest approach, and the one that gets you the best type checking by TypeScript, is to extend the mixin, or wrap a base class being extended with the mixin.

class MyClassNoBaseClass extends observable() {}

class MyClassWithBaseClass extends observable(BaseClass) {}

This will make your class observable so it can be used with the other observableUtils functions.

watch​

This is the main watch function, it is also what backs useWatch and most if its variants. This function supports watching any classes from the Web SDK that are observable, any classes from the ArcGIS JS SDK that inherit from Accessor which indicates that they are observable, and any custom classes that you create that use the observable mixin.

watch watches a property for changes. This can be a property on the given object or a property on a nested object if the nested object is also observable. It will call the given callback whenever the property value for the given path changes. The callback, however, will not be invoked if the value is set to the same value or the value ultimately has not changed. This includes if a parent property in a nested property path changes but the resulting value is the same as the previous value.

class MyObservable extends observable() {
    private _backingFieldForGetter = "backingFieldForGetter";
    dataProperty: string = "dataProperty";

    get getter() {
      return this._backingFieldForGetter;
    }
}

const myObservable = new MyObservable();
watch(myObservable, "getter", callback);
watch(myObservable, "dataProperty", callback);

class MyClass extends observable() {
   private _backingFieldForAccessor = new MyObservable();

   get getterSetter {
     return this._backingFieldForAccessor;
   }
   set getterSetter(value: MyObservable) {
     this._backingFieldForAccessor = value;
   }
}

const myClass = new MyClass();
watch(myClass, "getterSetter", callback);
watch(myClass, "getterSetter.getter", callback);
watch(myClass, "getterSetter.dataProperty", callback);

watch returns an IHandle that should be removed once the watch is no longer needed.

const handle = watch(myClass, "getterSetter", callback);
// Call remove on the handle when you no longer need the watch.
handle.remove();

The watch function accepts some options to modify its behavior.

watch(myClass, "myProp", callback, {
    sync: true,
    initial: true,
    once: true,
});

In regards to the sync option, it is recommended to avoid using this when possible and instead allow your callback to be invoked async. Reacting to property changes asynchronously gives more room for the JS event loop to continue with other async work including user interactions, creating a better user experience.

notifyChange​

notifyChange allows you to tell the watch system that a property may have changed. When notifyChange is called for a property, the watch system will check if the property value has indeed changed, if it has it will trigger the watches for that property as appropriate, else it will do nothing.

For the most part, the watch system handles basic property updates itself without needing notifyChange to be called manually. There are some cases though where the watch system cannot determine on its own if the value of a property has changed. It is important to be aware of these cases and handle them properly.

The most common case is when an accessor property’s backing property is updated directly instead of using a setter. It is common to see this with getter only properties. In this scenario, the watch system has no way to know that the backing property was updated, and that the accessor’s value has changed.

class MyClass extends observable() {
    private _myBackingProperty: number = 0;

    get myProp() {
        return this._myBackingProperty;
    }

    doSomething() {
        this._myBackingProperty++;
        // We need to announce a change for the prop `myProp`
        // because we have updated its backing property.
        notifyChange(this, "myProp");
    }
}

Other cases where notifyChange needs to be called are similar and usually involve a getter that derives its value from other properties either on the current object, on referenced objects, or from static or global properties.

onWatch​

Sometimes, you need to know when a property is being watched. This is what onWatch is for, it calls a callback whenever the specified property on an object starts being watched.

The function came about from a common pattern we saw in our codebase where we would create a watch to call notifyChange on a local property. By wrapping this pattern in this function we’re now able to avoid the overhead of watching a property to call notifyChange for another property when no one is actually watching the property we are notifying for.

class MyClass extends observable() {
    _foo = "foo";
    _bar = "bar";
    get foo() {
        return `${this._foo} ${this._bar}`;
    }
    get bar() {
        return this._bar;
    }
    set bar(value: string) {
        this._bar = value;
    }
}

const myClass = new MyClass();

const handle = onWatch(myClass, "foo", () =>
    watch(myClass, "bar", () => notifyChange(myClass, "foo"), {
        // We use sync: true here so the notify is synchronous.
        // This ensures that any watches on the property being
        // changed can respond sync or async as they are configured.
        sync: true,
    })
);

// Call remove on the returned handle when the onWatch is no longer needed.
handle.remove();

onWatch expects the callback it is given to return an IHandle, the handle returned by the callback will be called when the property onWatch is monitoring is no longer being watched by anything.

watchEach​

When you need to watch for changes on objects in a Collection, you can use watchEach. watchEach allows you to watch a Collection or specify a path to a property on an object that contains a Collection and watch for changes to a property that exists on the items in the Collection.

class MyObservable extends observable() {
    property: string = "testProperty";
}

class MyClass extends observable() {
    collection: Collection<MyObservable> = new Collection();
}

const myClass = new MyClass();
const handle1 = watchEach(
    myClass,
    "collection.[].property",
    (newValue, oldValue) => {}
);

const myCollection = new Collection<MyObservable>();
const handle2 = watchEach(
    myCollection,
    "[].property",
    (newValue, oldValue) => {}
);

// Call remove on the returned handle when the watchEach is no longer needed.
handle1.remove();
handle2.remove();

The []. syntax was created to help the watch system determine where the Collection starts so it can iterate over the Collection to watch the items in it as appropriate.

watchEvent​

There are times when you want to subscribe to an event on the value of a property, but that property’s value can change. watchEvent is a convenience function that makes handling this case a bit easier than managing the watch and event subscriptions yourself.

// The watch callback is optional. It is called when the value of the watched property changes.
const handle = watchEvent(
    myObj,
    "myProp",
    ["change", eventCallback],
    watchCallback
);

// Call remove on the returned handle when the `watchEvent` is no longer needed.
handle.remove();

once​

This is a convenience function to make it easier to await for a property change if you only need to wait for one change. You can pass an AbortSignal to the options to cancel waiting, in which case the returned promise will be aborted.

await once(obj, "myProp", { signal });

when​

when allows you to react to a property becoming truthy. (Truthy and falsy are common terms in JavaScript, if unfamiliar see Truthy and Falsy). when will invoke the given callback whenever the property’s value becomes truthy.

class MyClass extends observable() {
    myProp: string | undefined = undefined;
}

const obj = new MyClass();

const handle = when(obj, "myProp", callback);

// Setting the property value to a falsy value will not invoke the callback.
obj.myProp = "";

// Setting the property value to a truthy value will invoke the callback.
obj.myProp = "test value";

// Call remove on the returned handle when the `when` is no longer needed.
handle.remove();

If the value of the property being watched is already truthy, the callback will be invoked immediately.

The when function accepts some options to modify its behavior.

when(myClass, "myProp", callback, {
    sync: true,
    invert: true,
    once: true,
});

In regards to the sync option, it is recommended to avoid using this when possible and instead allow your callback to be invoked async. Reacting to property changes asynchronously gives more room for the JS event loop to continue with other async work including user interactions, creating a better user experience.

whenOnce​

This is a convenience function to make it easier to await for a property to become truthy if you only need to wait for one change. You can pass an AbortSignal to the options to cancel waiting, in which case the returned promise will be aborted.

await whenOnce(obj, "myProp", { signal });

createIHandle​

Creating a number of watches in one place is fairly common, which results in having a number of returned handles to deal with. To help simplify some situations we’ve added this utility function createIHandle that takes an Iterable<IHandle> and returns a single IHandle. This is useful when combined with onWatch but also other scenarios.

onWatch(this, "myProp", () => {
  const handles: IHandle[] = [];
  handles.push(
    watch(otherObj, "otherProp", () => notifyChange(this, "myProp"));
    watch(anotherObj, "anotherProp", () => notifyChange(this, "myProp"));
  );
  return createIHandle(handles);
});

The returned handle from createIHandle holds a reference to the iterable and will remove the handles currently held in the iterable when called, allowing you to update the iterable with new handles or remove old ones but still use the same returned handle to remove whatever is left in the iterable.

What did we Deprecate?​

All classes that were inheriting from Observable (@vertigis/arcgis-extensions/support/Observable.ts) no longer inherit from Observable. Most have been updated to use the new mixin, however SerializableBase has not been updated to use the mixin as it did not make sense for this class to be observable on its own. Every class, including SerializableBase, that no longer inherits from Observable has had deprecated methods added to temporarily provide the previous methods from Observable. Support for reactiveUtils for all classes that were previously inheriting from Observable will still work as well during the transition period.

If you’re unsure if you have any references to anything that will be removed, you can check the browser console; all deprecated functions, classes, and modules that are still in use are logged there as warnings.

reactiveUtils Support​

At the time of writing this, reactiveUtils will still work with VertiGIS Studio Web (Web) classes. We’ve ensured backwards compatibility for the moment. However, moving forward, we do plan to remove support for reactiveUtils from Web entirely, so using reactiveUtils inside of Web or the Web SDK is now considered deprecated. Instead, Web SDK developers should use observableUtils only, even with ArcGIS JS SDK classes. This will insulate everyone from changes to the ArcGIS JS SDK watch system in the future and will eventually allow us to clean up a lot of memory leaks. It should also improve performance of Web and Web SDK apps once backwards compatibility is removed.

Certain useWatch and useWatch Variant Overloads​

As a consequence of the new watch pattern and the deprecation of using reactiveUtils inside Web, the useWatch overloads that use the watch value callback pattern similar to reactiveUtils watch have been deprecated. We’ve also deprecated passing an array of property paths to useWatch and some specific useWatch variants, however we have maintained the array pattern for useWatchAndRerender.

We’ve also deprecated the useWatch callback that has the propertyName and target. In future, useWatch will only pass the newValue and oldValue arguments to the callback.

/** Deprecated */
useWatch(() => myObj.myProp, callback);
/** Use instead */
useWatch(myObj, "myProp", callback);

/** Deprecated */
useWatch(myObj, ["myProp1", "myProp2"], callback);
/** Use instead */
useWatch(myObj, "myProp1", callback);
useWatch(myObj, "myProp2", callback);

/** Deprecated */
useWatchAndRerender(() => myObj.myProp);
/** Use instead */
useWatchAndRerender(myObj, "myProp");

/** Deprecated */
useWatchInit(() => myObj.myProp, callback);
/** Use instead */
useWatchInit(myObj, "myProp", callback);

/** Deprecated */
useWatchInit(myObj, ["myProp1", "myProp2"], callback);
/** Use instead */
useWatchInit(myObj, "myProp1", callback);
useWatchInit(myObj, "myProp2", callback);

/** Deprecated */
useWatchEach(() => myObj.myProp, callback);
/** Use instead */
useWatchEach(myObj, "myProp", callback);

/** Deprecated */
useWatchEach(myObj, ["myProp1", "myProp2"], callback);
/** Use instead */
useWatchEach(myObj, "myProp1", callback);
useWatchEach(myObj, "myProp2", callback);

/** Deprecated */
useWatchEachAndRerender(() => myObj.myProp);
/** Use instead */
useWatchEachAndRerender(myObj, "myProp");

Common Anti-Patterns to Avoid​

We’ve seen various different anti-patterns over the years with the previous watch system that will likely continue with the new one. We’re calling them out here to try to make people aware of these anti-patterns and their consequences of being used.

Also, with the addition of new watch functionality, there are also some new anti-patterns we expect to see come up from time to time that should also be avoided.

Watching a Property on this​

Please pay close attention to watches that use this as the watch object. This is an anti-pattern and should be avoided.

watch(this as MyClass, "myProp", callback);

While it is simple to create a watch and sometimes more complicated to get the right behavior with other options, it is still less performant to use the watch system for watching a property on this than other options, like using an accessor property instead and calling your callback equivalent in the setter, even with our new watch system.

watch Callback Invokes notifyChange​

Using a watch with notifyChange for a property on the current object when not wrapped in onWatch is now an anti-pattern.

// This is an anti-pattern.  Wrap this in onWatch instead.
watch(this.obj, "objProp", () => notifyChange(this, "myProp"));

The above is always watching and notifying about those properties, even if no one cares. While this is a common pattern, and needed in most cases where it is used, we’ve introduced a new function called onWatch to assist with this situation and make it more performant by only initiating the watch once it is actually needed making this pattern a new anti-pattern. See onWatch for an example of the new pattern to use.

Calling notifyChange in a Setter for the Property Being Set​

There is no need to call notifyChange inside a setter for the property the setter is for. Doing so creates a bit of extra work that is not necessary.

class MyClass extends observable() {
    get myProp() {
        return this._backingProp;
    }
    set myProp(value: number) {
        this._backingProp = value;
        // There is no need to call this notifyChange for this property.
        // The watch system is able to detect this change on its own.
        notifyChange(this, "myProp");

        // We do need to call notifyChange for myOtherProp though.
        notifyChange(this, "myOtherProp");
    }

    get myOtherProp() {
        return this._backingProp + 1;
    }
}

Using onCollectionPropertyChange But Ignoring the Passed Event Object​

If you're using onCollectionPropertyChange (@vertigis/arcgis-extensions/utilities/watch.ts) to detect changes but the actual change event value was being ignored, please use watchEvent (@vertigis/arcgis-extensions/support/observableUtils.ts) instead as it will have better performance when the underlying watched property changes.

function collectionPropertyChange() {
    console.log(
        "do something that doesn’t require the change event value"
    );
}

/** Do not do this **/
onCollectionPropertyChange(
    myObj,
    "myCollectionProp",
    collectionPropertyChange
);

/** Instead, do this **/
watchEvent(
    myObj,
    "myCollectionProp",
    ["change", collectionPropertyChange],
    collectionPropertyChange
);

watchEvent has two callbacks, one for the event and one for when the property being watched changes. By using the same callback for both, the callback will be invoked when the property value itself changes as well as the when the event is fired, creating the equivalent behavior of onCollectionPropertyChange, but without the difference being calculated between the two different Collections when the property value changes.

Overview​

In this sample, we use AI image recognition to populate attributes in a new feature. The high level flow looks like this:

1. Capture an image from your device
2. Pass the image and a custom prompt into the AI service
3. Parse the AI response into feature attributes
4. Create a feature from these attributes, with the image as an attachment
5. Have the user review the generated feature and modify any fields if desired

There are several advantages to this kind of flow. For one thing, it allows you to fill in fields with data you may not know, like the scientific name of a particular tree, without having to look it up elsewhere. Another is that it speeds up the data entry process—typing on a Mobile device in particular can be cumbersome, so starting with the fields filled out just ready for you to review is a nice benefit.

Implementing the custom project​

We have a Quickstart project already available on GitHub to help expedite the process of creating a custom Studio Mobile app. The code for this AI demo builds on the Quickstart as a base. You can find the full project on GitHub.

The AI Service​

Our sample here uses a model from Azure OpenAI. Note that this model was not specifically trained to identify trees, though the results are still quite good. However, bear in mind that for your own real-life use cases you may want to use your own model rather than a generic one like this, in order to get better accuracy; particularly if your domain requires more niche expertise. That is outside the scope of this sample.

The AI service is set up in OpenAIAssistant.cs.

internal class OpenAIAssistant
{
    /** INSERT YOUR OWN DEPLOYMENT NAME / ENDPOINT / KEY HERE **/
    private const string deploymentName = "";
    private const string endpoint = "";
    private const string key = "";

    private AzureOpenAIClient _openAIClient;

    public OpenAIAssistant()
    {
        _openAIClient = new AzureOpenAIClient(new Uri(endpoint), new AzureKeyCredential(key));
    }

    public async Task<ChatCompletion> QueryImageAsync(byte[] imageData, List<string> queries, string systemPrompt)
    {
        // Limit image to 2MB for quick response and less tokens used
        if (imageData.Length > 2097152)
        {
            throw new ArgumentException("Image exceeded 2MB, try downsizing the image");
        }

        if (imageData.Length == 0)
        {
            throw new ArgumentException("Image is invalid");
        }

        var chatClient = _openAIClient.GetChatClient(deploymentName);
        var chatContent = ChatMessageContentPart.CreateImagePart(imageBytes: BinaryData.FromBytes(imageData), "image/png");
        var systemChatMessage = new SystemChatMessage(systemPrompt);
        var imageChatMessage = new UserChatMessage(chatContent);

        var chatMessages = new List<ChatMessage>
        {
            systemChatMessage,
            imageChatMessage,
        };

        foreach (var query in queries)
        {
            var userChatMessage = new UserChatMessage(query);
            chatMessages.Add(userChatMessage);
        }

        var chatCompletionOptions = new ChatCompletionOptions() { ResponseFormat = ChatResponseFormat.CreateJsonObjectFormat()};
        ChatCompletion chatCompletion = await chatClient.CompleteChatAsync(chatMessages, chatCompletionOptions);
        return chatCompletion;
    }
}

Note that there are variables for a deployment name, endpoint URL and a key at the top of the file (lines 10-12). You will need to have your own values there in order to actually make the AI queries. From line 34 to 49, we configure the chat client with a message and image which will be passed in by the caller - in QuickCaptureService.cs - described in the next section. The system prompt passed in on line 36 provides the model with context for any the queries we will be making. The ResponseFormat option being set to json on line 51 will make parsing the response easier.

You can learn more about how to interact with OpenAI models in the Azure documentation.

The Mobile integration​

Integrating the AI service with Mobile and creating the feature happens in QuickCaptureService.cs.

First, we create the service and set up a custom command. This command can then be invoked from the I Want To... menu or from a button within the Mobile app, for example.

[assembly: Service(typeof(QuickCaptureService))]
namespace App1
{
    public class QuickCaptureService : ServiceBase
    {
        private AllOperations _ops;
        private IDialogController _dialog;
        private MapRepository _mapRepo;
        private OpenAIAssistant _openAIAssistant;

        public QuickCaptureService(CommonAppDependencies deps)
        {
            // Save some objects we'll want later
            _ops = deps.Operations;
            _dialog = deps.DialogController;
            _mapRepo = deps.MapRepo;
            _openAIAssistant = new OpenAIAssistant();

            // Register our custom command. This is called by name later from the "I Want To..." menu.
            deps.OperationRegistry.VoidOperation("custom.quick-capture").RegisterExecute(DoQuickCaptureAsync, this);
        }

        private async Task DoQuickCaptureAsync()
        {
            ...
        }
    }
}

Then we can fill in the contents of DoQuickCaptureAsync; the command implementation.

private async Task DoQuickCaptureAsync()
{
    // Get the map (the first/only available map), and the layer we want to add to
    var map = _mapRepo.AllMaps.EnumerateExisting().First().MapExtension;
    var layerExt = map.LayerExtensions.FindByLayerId("1968288a255-layer-2"); // 1968288a255-layer-2 = the trees layer
    var table = layerExt.GetFeatureTable();

    // Get current location (will place feature there)
    var position = await _ops.GeolocationOperations.GetPosition.ExecuteAsync();
    position = HandleZAndMValues(table, position);

    EnhancedFileData fileData = await GetPhotoFromUser();

    await _ops.UIOperations.DisplayBusyState.ExecuteAsync();

    var systemPrompt = "You are a helpful assistant knowledgeable about trees";

    var queries = new List<string>
    {
        """
        Fill out the following information about a specific tree, from the given image.
        {
            CommonName:
            ScientificName:
            Family:
            ConservationStatus:
            Health:
        }
        'Health' should be an evaluation of the health of the individual tree pictured.
        Respond only with JSON.
        """,
    };

    var response = await _openAIAssistant.QueryImageAsync(fileData.Data, queries, systemPrompt);
    Dictionary<string, object?> attributes = GetAttributesFromResponse(response.Content[0].Text);

    // Create the new feature
    var vertiGISFeature = await GetNewFeature(layerExt, table, position, attributes);

    // Add the photo as an attachment on the feature
    var attachmentArgs = new AddAttachmentArgs(fileData, [vertiGISFeature], map);
    await _ops.EditOperations.AddAttachment.ExecuteAsync(attachmentArgs);

    await _ops.ResultsOperations.DisplayDetails.ExecuteAsync(vertiGISFeature);

    // Launch the feature editing form so user can tweak values if necessary
    await _ops.EditOperations.DisplayUpdateFeature.ExecuteAsync(vertiGISFeature);
}

Line 52 has the layer ID for our sample trees layer. You'd want to replace it with your own layer. Although you could have a more complicated use case where the layer is populated dynamically, this process tends to work best with a specific known layer, so that you can tell the AI model exactly the attribute names you're looking for and what the values should look like. The prompt, starting on line 68, illustrates this: the keys listed there correspond exactly to the tree layer's attribute names. This makes it easy to convert the json response from the AI service directly into a feature without having to do any extra parsing.

We found that the AI Model did a fine job of inferring what kind of value we were looking for for most of the attributes just based on the name. However, for the "Health" attribute, the model was giving us responses that referred to the health of the species of tree in general, rather than doing a specific assessment for the individual specimen in the photo. For example, it would give us "this is a hardy species but is susceptible to root rot", rather than "this tree shows signs of a caterpillar infestation". Hence we included a note in the prompt clarifying the intention of that field (line 76). If you have a similar setup, where your attribute names may not be intuitive, or perhaps the values have to be constrained to a certain data type like enum values, you can elaborate on that here.

To get the image, we'll use the Mobile's TakePhoto operation. In this sample we also have the option of launching a file picker, to make testing easier.

Starting on line 81 is where we we call the AI service, get the attributes from the AI response, and create a feature. Note that we convert the feature into a VertiGIS Feature type: this enables us to work with it more easily in other Mobile SDK functions, such as adding the attachment (line 89) and activating feature editing (line 94).

Our documentation page Edit the Layout and App Config explains the final piece of the puzzle, which is setting up your SDK app to point to your webmap, with the trees layer in this sample, and defining the layout (including adding a place to launch our custom AI command).

1 - Creating the Search Override Workflow​

To start off the work, we'll need to head to VertiGIS Studio Workflow and create a new blank Workflow. Call it Search Override. This Workflow will be used to override the search functionality in Mobile.

To create the Workflow, you may either download and import this skeleton file in Workflow Designer, or create and configure it yourself in the following way:

1. Add a Get Workflow Inputs activity with ID getWorkflowInputs1
2. Add a Set Property activity, which we'll leave empty for now.
3. Add a Run Command activity; configure the parameters as follows:
   • Command Name: ="tasks.search,results.display"
   • Command Parameter: =$getWorkflowInputs1.inputs.context

We will be using this Workflow to override the default search behaviour in Mobile so that we change the search area prior to performing the search.

2 - Finding the Area to Override Search​

There are two ways of obtaining the extent numbers needed to override the search area: Using a layer's FullExtent property to obtain the extent, or using a geometry picker to create a custom search area.

I will walk you through how to use both of these methods to enable the most amount of customization and to fit your use case.

2.1 - Using a layer's FullExtent property to obtain the extent​

Using a layer to obtain the extent numbers is the more foolproof way since it doesn't involve hard-coding any specific numbers to Workflow.

On the Search Override Workflow, add a Get Layer activity to obtain a layer that will act as the basis of the search area. Add this activity to the start of the Workflow. Assuming the Get Layer activity's ID is layer1, we will be using =$layer1.layer.Unwrap().FullExtent as input to the Set Property activity; the next section will point out how to fill the activity properly. layer.unwrap() is an undocumented function which unwraps a layer from what we use internally in VertiGIS Studio products into ESRI's layer objects.

2.2 - Using custom bounds to obtain the extent​

Creating a custom search area requires a bit more work to obtain the required search extent numbers. To start off, you may either download and import this skeleton file in Workflow Designer, or you can create it yourself.

If you wish to create the Workflow yourself: Create a new blank Workflow, call it something along the lines of Get Geometry from Geometry Picker. We will be using this Workflow to obtain the extent values from a geometry picker which will be used to define our search area. Follow these steps to configure the Workflow:

1. Add a Display Form activity, with ID form1, and add a geometry picker in there. Make sure that the geometry type is set to Polygon
2. Add a Convert To JSON next and use =$form1.state.geometryPicker1.value.geometry[0] as the inputs to the Object parameter
3. Use another Display Form activity to display these results in a way that is easily copyable. Add a Text Area form element and a load event on the form's title that replaces the text area's value with the output from the Convert To JSON activity

The output should look something like the following but unformatted; you may format it for readability. Ensure sure the first point matches the last point and that these two are the only identical points.

{
    "rings": [
        [
            [-13261447.128629405, 4248956.0934711397],
            [-13255720.535082744, 3797373.288077388],
            [-12575073.987822598, 3791646.6945307283],
            [-12581618.666161638, 4253046.5174330398],
            [-13261447.128629405, 4248956.0934711397]
        ]
    ],
    "spatialReference": { "wkid": 102100, "latestWkid": 3857 }
}

After obtaining the JSON of the search area, add a Get Geometry From JSON activity to the Search Override Workflow, and use the JSON as input to the Json parameter for the Get Geometry From JSON activity you just added. Assuming the mentioned Get Geometry From JSON activity's ID is geometry1, we will be using =$geometry1.geometry.Polygon as input to the Set Property activity. The next section will point out how to fill the activity properly.

3 - Finishing the Workflow​

After finding the search area's geometry, the process is the same no matter which method of obtaining the search area you chose. After you've performed the required setup as described in section 2.1 or section 2.2, head to the Search Override Workflow. There, we will populate the Set Property activity we've added in section 1. This activity is where we will replace the search area with the one we customized. Set up the activity as follows:

• Object: Use =$getWorkflowInputs1.inputs.context
• Property Name: Use ="SearchArea"
• Property Value:
  • =$layer1.layer.Unwrap().FullExtent if you've followed section 2.1.
  • =$geometry1.geometry.Polygon if you've followed section 2.2.

={
  "type": "esriSFS",
  "style": "esriSFSSolid",
  "color": [34,237,24,150],
    "outline": {
    "type": "esriSLS",
    "style": "esriSLSSolid",
    "color": [110,110,110,150],
    "width": 1
  }
}

4 - Updating the Mobile app JSON and overriding the Search functionality​

To use this Workflow we've created in Mobile, launch the SuDo editor in Designer using Ctrl+Shift+E and scroll to the bottom. There, add a new entry to reference the Search Override Workflow we created earlier. You may use the following template and replace portalItem with your Workflow's ArcGIS portal link:

{
    "id": "search-override-workflow",
    "title": "Search Override Workflow",
    "target": "auto",
    "portalItem": "<Replace me>",
    "commandArgumentInput": "context",
    "$type": "workflow"
}

When done correctly, the app JSON should look like the following:

Lastly, look up the search object in Designer, which you can find by searching (Ctrl+F) for "$type": "search". Change it from

{
    "id": "search-config-1",
    "$type": "search"
},

To

{
    "id": "search-config-1",
    "onSearch": "workflow.run-XXXX-XXX-XX-XXXXX-XXXXXX",
    "$type": "search"
},

Where you replace the XXX... with the value of the id field you typed in the previous step. So it looks like the following:

After that is done, click on the Apply, I know what I'm doing button and wait for Designer to load, then save the app. Launch the app in Go and attempt to search for a feature that doesn't exist in the visible extent. If you've done everything correctly, the search should go through with the configured extent.

You can find the PR for this conversion in our samples repo here: https://github.com/vertigis/studio-dev-center/pull/79

There are some helpful guides out there already. For example, Microsoft has written Upgrade a Xamarin.Forms app to a .NET MAUI app with the .NET Upgrade Assistant and Manually upgrade a Xamarin.Forms app to a single project .NET MAUI app, which I do recommend checking out. However, I will detail some specific errors I encountered along the way, which may provide some extra help.

The method I'll be going through will result in one shared project, and separate projects for each platform - the structure you're probably familiar with from your Xamarin Forms app. It is possible afterwards to merge these projects together to take advantage of MAUI's convenient single-project structure. To do so, I recommend creating a brand new single-project MAUI app and moving your files over, the way Microsoft describes in their "Manually upgrade [...]" article I linked above. This blog post will not talk about the process of converting custom Renderers to use the new MAUI Handler pattern, but if you do have custom Renderers that is something you'll have to handle as well during your upgrade process.

Step 1 - Run the .NET Upgrade Assistant​

We'll be using the .NET Upgrade Assistant to help us through the first step. It won't get you to 100%, but it's a good starting point. You can find installation instructions here.

Once you've installed it, run the tool on each project in your Xamarin Forms solution, to upgrade it to a newer .NET version - in this case, .NET 8 (which will also necessarily migrate your project from Xamarin Forms to MAUI).

Step 2 - Upgrade packages​

The Upgrade Assistant will have done some package updates automatically, but not all of them. If you're referencing any Esri ArcGIS Runtime packages, you'll need to upgrade those from 100.x to the 200.x version (as of writing this post, Mobile is using 200.5). In some cases you'll need a different package rather than just changing the version number; for example, Esri.ArcGISRuntime.Xamarin.Forms is replaced by Esri.ArcGISRuntime.MAUI.

<PackageReference Include="VertiGIS.Mobile" Version="5.34.0" ExcludeAssets="buildTransitive;build" PrivateAssets="all" />

public static MAUIApp CreateMAUIApp()
{
    var builder = MAUIApp.CreateBuilder();

    builder
    .UseSharedMAUIApp()
    .UseStudioMobile();

    return builder.Build();
}

Step 3 - Remove any lingering outdated references​

Do a search through your codebase for any remaining references to Xamarin.Forms. There are probably some instances that the Upgrade Assistant didn't handle. For example:

// TODO Xamarin.Forms.Device.RuntimePlatform is no longer supported. Use Microsoft.MAUI.Devices.DeviceInfo.Platform instead. For more details see https://learn.microsoft.com/en-us/dotnet/maui/migration/forms-projects#device-changes
if (Xamarin.Forms.Device.RuntimePlatform != Xamarin.Forms.Device.UWP)
{
    AppManager.Instance.OnActivated();
}

will become:

if (DeviceInfo.Platform != DevicePlatform.WinUI)
{
    AppManager.Instance.OnActivated();
}

(Note the change from UWP to WinUI).

A few types in Mobile, like the EnhancedActivityIndicator and EnhancedSwitch which were previously used in our Samples, have been removed as no longer necessary. Instead you should use MAUI's standard controls, in this case ActivityIndicator or Switch.

Step 4 - Fix other build errors​

To fix this problem in your solution:

Open your .sln file in a text editor and delete everything in the GlobalSection(ProjectConfigurationPlatforms) = postSolution section. When you re-open the sln file in Visual Studio, it will repopulate that section correctly.

On Windows, the build error Type 'App' already defines a member called 'InitializeComponent' with the same parameter types is solved by adding the following lines to the csproj:

<!-- We do not want WinUI XAML files to be processed as .NET MAUI XAML -->
<EnableDefaultXamlItems>false</EnableDefaultXamlItems>
<EnableDefaultMAUIItems>false</EnableDefaultMAUIItems>

If you find that Visual Studio simply isn't giving you the option to deploy to Windows, you may be missing your launchsettings.json file. Ensure you add such a file under the Properties folder of your Windows project.

Those are some specific errors I ran into while converting the Samples project. Continue working through your own project fixing any additional problems you might have, until you are able to build succesfully.

Step 5 - Migrate code from *.original files​

You may have noticed that in Step 1 the Upgrade Assistant created copies of several platform-specific startup files, suffixed with .original. E.g. AppDelegate.cs.original

For each of the platforms, compare the .original file to the new version and copy over any logic required. For example, your SDK project would likely have extended VertiGISMobileActivity and VertiGISAppDelegate for Android and iOS, respectively. The upgrade tool won't have preserved that, so you'll need to do that now.

Step 6 - Fix runtime errors​

At this point you should be able to build and run your app, but will likely encounter some runtime errors.

On Android for example, you'll likely have to fix [AndroidRuntime] java.lang.RuntimeException: Unable to get provider android.support.v4.content.FileProvider: java.lang.ClassNotFoundException: Didn't find class "android.support.v4.content.FileProvider" on path: [...] by making a change in your AndroidManifest.xml.

Change

<provider android:name="android.support.v4.content.FileProvider" android:authorities="${applicationId}.fileprovider" android:exported="false" android:grantUriPermissions="true">

to

<provider android:name="androidx.core.content.FileProvider" android:authorities="${applicationId}.fileprovider" android:exported="false" android:grantUriPermissions="true">

And if your Android MainActivity had a custom name, make sure the name is still being set in MainActivity.cs.

On Windows, if you were merging in Mobile's VertiGISResources.xaml file in a merged dictionary, like <ResourceDictionary Source="VertiGIS.Mobile.UWP/Resources/VertiGISResources.xaml"/>, you'll now need to update the path: <ResourceDictionary Source="VertiGIS.Mobile/Platforms/Windows/VertiGISResources.xaml"/>. VertiGIS.Mobile.Toolkit.UWP/Resources/ToolkitResources.xaml no longer exists as a separate file.

Step 7 - Update outdated controls​

Once you've got all the build and runtime errors sorted out, I strongly recommend updating certain MAUI controls to their new and improved counterparts. This article, "Layout behavior changes from Xamarin.Forms", has some useful information about this.

In particular, all Frame controls should be replaced with Border.

StackLayout should be replaced by VerticalStackLayout or HorizontalStackLayout, or by Grid, depending on your use case. For the layout options, *AndExpand is no longer supported in MAUI, so any instances of StartAndExpand or CenterAndExpand for example should now be replaced by just Start or Center. The article I mentioned above explains how to replace a StackLayout to preserve the previous expanding behaviour.

With the new SDK, Esri dropped support for Xamarin Forms in favor of .NET MAUI. Therefore, upgrading to the 200.x SDK also necessitated updating our version of .NET and migrating VertiGIS Mobile from a Xamarin Forms-based solution to a MAUI-based solution.

For a large project like Mobile, which includes dozens of custom controls for each of our supported platforms (iOS, Android and Windows), this turned out to be a complicated and time-consuming endeavor. We had to contend not only with deprecations and breaking changes in the Esri SDK, MAUI, and other third-party libraries, but also with unexpected issues in MAUI, as it was in its early days itself when we started our upgrade and went through a few growing pains.

We are glad to finally be able to present the result of our hard work to the public. See our Community post here for more information on how to access the beta and to provide feedback.

Getting Started​

You will need a few tools to build a custom band:

• Download and install Node.js
• Download and install Visual Studio Code

Once you are set up with those you can create a folder with everything you need to build a custom band. With the terminal of your choice, create instance of inline sdk with

npx @vertigis/inline-sdk create <my-project>

Open the folder with the name you supplied in VS Code. You should see a number of files already there.

Exploring the SDK​

There are a few key parts of the SDK that you can use to build your own custom band.

Registry Service​

Custom bands are registered in Inline using a custom VertiGIS Web service. This service is found in src/services/CustomBandRegistry/CustomBandRegistry.ts. This file loads any available custom bands and registers them with Inline when it is added to an app. It can register any number of custom bands at the same time.

Types​

In the src/definitions/inline.d.ts file you can find all of the Inline types that you can use to create your custom band. There are comments provided in this file to describe the uses of these types.

Sample Band​

The Inline SDK comes preinstalled with a sample band that you can use for reference. In your SDK navigate to src/bands/SampleBand. In here you will find 4 files.

• Band.css contains the styles that are applied to the chart.
• Band.tsx contains the React code that is run in Inline.
• designer.ts describes the settings that are available when configuring a custom band in the Inline Designer.
• index.ts combines it all together to be properly registered.

Creating a new band​

The band we will be creating today will be able to display a video and seek to any point in the video based on the location of the crosshair on the map and on other inline charts.

To create a new band run

npx @vertigis/inline-sdk generate VideoBand

Add settings for the Inline Designer​

The designer.ts file provides the Inline designer with a settings schema to display configurable settings for a custom band. These settings can be any combination of:

• input
• checkbox
• radio
• dropdown

The Sample Band has some examples of how to use these settings. The src/bands/VideoBand/designer.ts file will have a small function ready to go.

import { InlineDesignerConfig } from "inline";

export const getDesignerConfig = (): InlineDesignerConfig => {
    const config: InlineDesignerConfig = [
        {
            title: "Video Band Settings",
            fields: [],
        },
    ];

    return config;
};

The InlineDesignerConfig is a list of settings sections. Each section has a name and list of fields that can be configured by users in the Inline designer.

Next, add an input field for the video URL.

import { InlineDesignerConfig, InputDesignerConfig } from "inline";

export const getDesignerConfig = () => {
    const config: InlineDesignerConfig = [
        {
            title: "Video Band Settings",
            fields: [],
        },
    ];

    const urlField: InputDesignerConfig = {
        id: "url",
        type: "input",
        default: "",
        label: "Video URL",
        helpText:
            "The URL of the video. This must be a valid URL to a video file.",
    };

    config[0].fields.push(urlField);

    return config;
};

This pattern can be repeated to create any other settings that are necessary for the band.

Creating a Video Player React Hook​

Without a video player, this band will not do much. Let's create one using a custom React Hook.

Create a new file the the VideoBand folder called useVideoPlayer.ts. In this file we will include all the tools we need to create an interactive video player in a custom band.

Set up the hook as a function that takes a single parameter, videoElement. This is a reference to a video HTML element.

const useVideoPlayer = (
    videoElement: React.MutableRefObject<HTMLVideoElement>
) => {};

export default useVideoPlayer;

Add some state to track to current status of the player.

import { useState } from "react";

const useVideoPlayer = (
    videoElement: React.MutableRefObject<HTMLVideoElement>
) => {
    const [playerState, setPlayerState] = useState({
        isPlaying: false,
        progress: 0,
        speed: 1,
        isMuted: false,
    });
};

Add a function to toggle the current play/pause state of the video.

const useVideoPlayer = (videoElement: React.MutableRefObject<HTMLVideoElement>) => {
    ...
    const togglePlay = () => {
        setPlayerState({
            ...playerState,
            isPlaying: !playerState.isPlaying
        });
    }
}

Add a function that updates the progress bar of the video as it is playing. The progress is any value between 0 and 100 and is not directly related to the length of the video.

const useVideoPlayer = (videoElement: React.MutableRefObject<HTMLVideoElement>) => {
    ...
    const handleOnTimeUpdate = () => {
        const progress = (videoElement.current.currentTime / videoElement.current.duration) * 100;
        setPlayerState({
            ...playerState,
            progress
        });
    };
}

Add a function to seek to any point in the video, taking a number that is the percentage of the video length that the video should start playing at.

const useVideoPlayer = (videoElement: React.MutableRefObject<HTMLVideoElement>) => {
    ...
    const seekTo = (value: number) => {
        if (value >= 0 && value <= 100) {
            videoElement.current.currentTime = (videoElement.current.duration / 100) * value;
            setPlayerState({
                ...playerState,
                progress: value
            });
        }
    };
}

Add functions to change the playback speed of the video and turn the sound on/off.

const useVideoPlayer = (videoElement: React.MutableRefObject<HTMLVideoElement>) => {
    ...
    const handleVideoSpeed = (event) => {
        const speed = +event.target.value;
        videoElement.current.playbackRate = speed;
        setPlayerState({
            ...playerState,
            speed
        });
    }

    const toggleMute = () => {
        setPlayerState({
            ...isMuted: !playerState.isMuted
        });
    }
}

Add useEffect hooks that will update the muted state of the video player, the playback speed, and the current play/pause state of the video player when their respective states have been changed.

import { useState, useEffect } from "react";

const useVideoPlayer = (videoElement: React.MutableRefObject<HTMLVideoElement>) => {
    ...
    useEffect(() => {
        videoElement.current.muted = playerState.isMuted;
    }, [playerState.isMuted, videoElement]);

    useEffect(() => {
        videoElement.current.playbackRate = playerState.speed;
    }, [playerState.speed, videoElement]);

    useEffect(() => {
        playerState.isPlaying ?
        void videoElement.current.play() :
        void videoElement.current.pause();
    }, [playerState.isPlaying, videoElement]);
}

Finally, provide all of these functions to the consumer of the hook by returning an object containing everything needed to create an interactive video player.

import { useState, useEffect } from "react";

const useVideoPlayer = (videoElement: React.MutableRefObject<HTMLVideoElement>) => {
    ...
    return {
        playerState,
        togglePlay,
        handleOnTimeUpdate,
        handleVideoSpeed,
        toggleMute,
        seekTo
    }
}

With everything put together, your useVideoPlayer hook should look like this:

import { useState, useEffect } from "react";

const useVideoPlayer = (
    videoElement: React.MutableRefObject<HTMLVideoElement>
) => {
    const [playerState, setPlayerState] = useState({
        isPlaying: false,
        progress: 0,
        speed: 1,
        isMuted: false,
    });

    const togglePlay = () => {
        setPlayerState({
            ...playerState,
            isPlaying: !playerState.isPlaying,
        });
    };

    const handleOnTimeUpdate = () => {
        const progress =
            (videoElement.current.currentTime /
                videoElement.current.duration) *
            100;
        setPlayerState({
            ...playerState,
            progress,
        });
    };

    const seekTo = (value: number) => {
        if (value >= 0 && value <= 100) {
            videoElement.current.currentTime =
                (videoElement.current.duration / 100) * value;
            setPlayerState({
                ...playerState,
                progress: value,
            });
        }
    };

    const handleVideoSpeed = (event) => {
        const speed = +event.target.value;
        videoElement.current.playbackRate = speed;
        setPlayerState({
            ...playerState,
            speed,
        });
    };

    const toggleMute = () => {
        setPlayerState({
            ...playerState,
            isMuted: !playerState.isMuted,
        });
    };

    useEffect(() => {
        videoElement.current.muted = playerState.isMuted;
    }, [playerState.isMuted, videoElement]);

    useEffect(() => {
        videoElement.current.playbackRate = playerState.speed;
    }, [playerState.speed, videoElement]);

    useEffect(() => {
        playerState.isPlaying
            ? void videoElement.current.play()
            : void videoElement.current.pause();
    }, [playerState.isPlaying, videoElement]);

    return {
        playerState,
        togglePlay,
        handleOnTimeUpdate,
        handleVideoSpeed,
        toggleMute,
        seekTo,
    };
};

export default useVideoPlayer;

Creating the component​

Now, add the hook to your custom band. Open src/bands/VideoBand/Band.tsx. Here you will find a simple react component. This component is the entrypoint for the band. In the Band component, add a player ref and add your useVideoPlayer hook. Add the props function parameter to the component.

import React, { useRef } from "react";
import { BandProps } from "inline";
import "./Band.css";
import useVideoPlayer from "./useVideoPlayer";

export const Band: React.FC<BandProps> = (props) => {
    const player = useRef<HTMLVideoElement>();
    const {
        playerState,
        togglePlay,
        handleOnTimeUpdate,
        handleVideoSpeed,
        toggleMute,
        seekTo,
    } = useVideoPlayer(player);

    return <div className="video-band">Video Band</div>;
};

Add a video player and controls in a wrapper in the return statement of the component. The video player will take the URL to your video, player ref and the handleOnTimeUpdate function as props to the video player. The URL will be accessed using the band.customBandSettings prop passed in to the custom band.

return (
    <div className="video-band">
        <div className="video-wrapper">
            <video
                ref={player}
                onTimeUpdate={handleOnTimeUpdate}
                src={props.band.customBandSettings.url ?? ""}
            />
            <div className="controls"></div>
        </div>
    </div>
);

The first control we will add is the start/stop button. This will show an icon depending on whether the video is playing or paused. To use that icon we need to install an npm package, react-icons. Run

npm install react-icons

in the terminal to install all the icons you will need for this project.

import { BiPlay, BiPause} from "react-icons/bi";
...
return (
    <div className="video-band">
        <div className="video-wrapper">
            ...
            <div className="controls">
                <div className="actions">
                    <button onClick={togglePlay}>
                        {!playerState.isPlaying ? (
                            <BiPlay color="white" />
                        ) : (
                            <BiPause color="white" />
                        )}
                    </button>
                </div>
            </div>
        </div>
    </div>
);

Add a progress bar that allows the user to seek through the length of the video and shows the current timestamp of the video. We also need to add a function to handle the input's onChange prop.

const handleVideoProgress = (event: React.ChangeEvent<HTMLInputElement>) => {
    const value = isNaN(+event.target.value) ? 0 : +event.target.value;
    seekTo(value);
}

return (
    <div className="video-band">
        <div className="video-wrapper">
            ...
            <div className="controls">
                {...}
                <input
                    type="range"
                    min="0"
                    max="100"
                    value={playerState.progress}
                    onChange={handleVideoProgress}
                />
            </div>
        </div>
    </div>
);