This guide provides examples of common Accessor usage patterns. Accessor aims to make developing custom API classes easy by providing a mechanism to get, set, and watch properties.
The code snippets below include @arcgis/core ES modules (ESM) for use in local builds, and AMD examples in vanilla JavaScript.
Many classes in the API extend the Accessor class. These classes can expose watchable properties that may have unique characteristics, such as being read-only or computed.
Create a simple subclass
When building applications with JavaScript use the createSubclass() method which automatically calls super(). When building with TypeScript, use the @subclass() decorator along with the extends keyword.
Also when using TypeScript decorators such as @subclass(), it is required to set the useDefineForClassFields flag to false for backwards compatibility. More information is available in the TSConfig Reference.
The declaredClass property is specified as a string in the constructor, and helps the API differentiate between the existing class that you are extending and the custom one you are building. In the API, declaredClass is readonly. This property provides the same functionality in both JavaScript and TypeScript. However, as shown in the example below, the implementations are different.
When developing with AMD using the ArcGIS CDN, see the Build with AMD modules guide topic to learn more about loading custom modules.
Mixins with Accessor
The ArcGIS Maps SDK for JavaScript uses mixins to build its classes. A mixin is a function that assists in the creation of the super class when building a subclass. Read this excellent article that goes deep dive on mixins with TypeScript.
First we define our EventedMixin to add an event system to a class.
Defining an Accessor mixin - ESM TSDefining an Accessor mixin - ESM TSDefining an Accessor mixin - AMD JS
Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
import Accessor from"@arcgis/core/core/Accessor.js";
import { subclass } from"@arcgis/core/core/accessorSupport/decorators.js";
// A type to represent a constructor functiontype Constructor<T = object> = new (...args: any[]) => T;
// A type to represent a mixin function// See for more details https://www.bryntum.com/blog/the-mixin-pattern-in-typescript-all-you-need-to-know/type Mixin<T extends (...input: any[]) => any> = InstanceType<ReturnType<T>>;
// TBase extends Constructor<Accessor> indicating that `EventedMixin`// expects the base class to extend `Accessor`, for example to be able to use the `watch` method.exportconst EventedMixin = <TBase extends Constructor<Accessor>>(Base: TBase) => {
@subclass("custom.EventedMixin")
return class Evented extends Base {
// A first function defined by the mixin
emit(type: string, event?: any): boolean {
// ...
}
// Another function defined by the mixin
on(type: string, listener: (event: any) => void): IHandle {
// ...
}
}
}
// define the type of the mixin. This is useful to type properties that extends this mixin
// eg: `myProperty: EventedMixin;`
export type EventedMixinType = Mixin<typeof EventedMixin>;
In this example we create a super class that extends Accessor and adds capabilities from EventedMixin. The Collection class then extends the final subclass.
Using an Accessor mixin - ESM TSUsing an Accessor mixin - ESM TSUsing an AMD Accessor mixin - AMD JS
Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
import Accessor from"@arcgis/core/core/Accessor.js";
import { subclass } from"@arcgis/core/core/accessorSupport/decorators";
// import the newly created custom mixinimport { EventedMixin } from"custom/EventedMixin.ts";
@subclass("custom.Collection")
exportclassCollectionextendsEventedMixin(Accessor) {
// Collection extends a super class composed of Accessor and EventedMixin.}
Properties
Define a simple property
Use the following syntax for creating simple, watchable, properties that do not require any additional behavior. You can define both default values and types for primitive property values. If working with TypeScript, default property values can be set in the constructor.
There may be times when you may need to verify, validate, or transform values set on a property. You may also need to do additional (synchronous) work when a property is being set. The this.set() method is inherited from Accessor. The following snippets show this.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
import Accessor from"@arcgis/core/core/Accessor.js";
import { subclass, property } from"@arcgis/core/core/accessorSupport/decorators.js";
@subclass("custom.Collection")
classCollectionextendsAccessor{
private _items: any[] = [];
// Example: Define a custom property getter.// Accessor caches the values returned by the getters.// At this point `length` will never change.// See the "Notify a property change" section@property()
getlength(): number {
returnthis._items.length;
}
setlength(value: number) {
// Example: perform validationif (value <= 0) {
thrownewError(`value of length not valid: ${value}`);
}
// internally you can access the cached value of `length` using `_get`.const oldValue = this.get<number>("length");
if (oldValue !== value) {
// a setter has to update the value from the cachethis.set("length", value);
// Example: perform additional work when the length changesthis._items.length = value;
}
}
}
Define a read-only property
The following syntax shows how to set a read-only property. The this.set() method is inherited from Accessor.
Sometimes properties cannot notify when changed. Accessor has an internal method to notify of any changes, and it marks the property as dirty. The next time the property is accessed its value is re-evaluated.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
import Accessor from"@arcgis/core/core/Accessor.js";
import { subclass, property } from"@arcgis/core/core/accessorSupport/decorators.js";
@subclass("custom.Collection")
classCollectionextendsAccessor{
private _items: any[] = [];
@property({
readOnly: true })
getlength(): number {
returnthis._items.length;
}
add(item: any): void {
this._items.push(item);
// We know the value of `length` is changed.// Notify so that at next access, the getter will be invokedthis.notifyChange("length");
}
}
Autocast
Define the property type
It is possible to define a type for a class property.
Define the property type - ESM TSDefine the property type - ESM TSDefine the property type - AMD JS
Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
import Graphic from"@arcgis/core/Graphic.js";
import Accessor from"@arcgis/core/core/Accessor.js";
import Collection from"@arcgis/core/core/Collection.js";
import { subclass, property } from"@arcgis/core/core/accessorSupport/decorators.js";
@subclass()
classGraphicsLayerextendsAccessor{
@property({
// Define the type of the collection of Graphics// When the property is set with an array,// the collection constructor will automatically be calledtype: Collection.ofType(Graphic)
})
graphics: Collection<Graphic>;
}
Define a method to cast a property
Sometimes you need to validate a property's value type when it is being set. A good example of this is having well-known, preset, names for specific values, such as map.basemap = "streets-vector".
The type metadata automatically creates an appropriate cast for Accessor and primitive types if it is not already set.
Define a casting method - ESM TSDefine a casting method - ESM TSDefine a casting method - AMD JS
Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
import Accessor from"@arcgis/core/core/Accessor.js";
import { subclass, property, cast } from"@arcgis/core/core/accessorSupport/decorators.js";
@subclass()
classColorextendsAccessor{
@property()
r: number = 0;
@property()
g: number = 0;
@property()
b: number = 0;
@property()
a: number = 1;
@cast("r")
@cast("g")
@cast("b")
protected castComponent(value: number): number {
// cast method to clamp the value that// will be set on r, g or b between 0 and 255returnMath.max(0, Math.min(255, value));
}
@cast("a")
protected castAlpha(value: number): number {
// cast method to clamp the value that// will be set on a between 0 and 1returnMath.max(0, Math.min(1, value));
}
}
Additional information
Please refer to these additional links for further information: