Implementing Accessor

This guide provides examples of common Accessor usage patterns. Accessor aims to make developing custom API classes easy by providing a mechanism to get, and set properties.

The code snippets below include @arcgis/core ES modules (ESM) for use in local builds, and CDN examples in vanilla JavaScript. @arcgis/core includes TypeScript typings in the install. Typings are not available for use with the CDN.

Extend Accessor

Many classes in the core API extend the Accessor class. These classes can expose 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.

Simple ESM subclass - TS

Simple CDN subclass - JS

Use dark colors for code blocksCopy
import Accessor from "@arcgis/core/core/Accessor.js";
import { subclass } from "@arcgis/core/core/accessorSupport/decorators.js";

// declaredClass is "custom.Color"
@subclass("custom.Color")
class Color extends Accessor {
  // ...
}

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 TS

Defining an Accessor mixin - CDN JS

Use dark colors for code blocksCopy
import Accessor from "@arcgis/core/core/Accessor.js";
import { subclass } from "@arcgis/core/core/accessorSupport/decorators.js";

// A type to represent a constructor function
type 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`.
export const 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 TS

Using an Accessor mixin - CDN JS

Use dark colors for code blocksCopy
import Accessor from "@arcgis/core/core/Accessor.js";
import { subclass } from "@arcgis/core/core/accessorSupport/decorators";

// import the newly created custom mixin
import { EventedMixin } from "custom/EventedMixin.ts";

@subclass("custom.Collection")
export class Collection extends EventedMixin(Accessor) {
  // Collection extends a super class composed of Accessor and EventedMixin.
}

Properties

Define a simple property

Use the following syntax for creating simple 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.

Simple property - ESM TS

Simple property - CDN JS

Use dark colors for code blocksCopy
import Accessor from "@arcgis/core/core/Accessor.js";
import { subclass, property } from "@arcgis/core/core/accessorSupport/decorators.js";

@subclass("custom.Color")
class Color extends Accessor {
  @property()
  r: number = 255;

  @property()
  g: number = 255;

  @property()
  b: number = 255;

  @property()
  a: number = 1;
}

Define custom getter and setter

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.

Setter property - ESM TS

Setter property - CDN JS

Use dark colors for code blocksCopy
import Accessor from "@arcgis/core/core/Accessor.js";
import { subclass, property } from "@arcgis/core/core/accessorSupport/decorators.js";

@subclass("custom.Collection")
class Collection extends Accessor {
  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()
  get length(): number {
    return this._items.length;
  }

  set length(value: number) {
    // Example: perform  validation
    if (value <= 0) {
      throw new Error(`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 cache
      this._set("length", value);

      // Example: perform additional work when the length changes
      this._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.

Read-only - ESM TS

Read-only - CDN JS

Use dark colors for code blocksCopy
import Accessor from "@arcgis/core/core/Accessor.js";
import { subclass, property } from "@arcgis/core/core/accessorSupport/decorators.js";

@subclass("custom.Person")
class Person extends Accessor {
  // Example: read-only property may not be externally set
  @property({ readOnly: true })
  firstName: string;

  @property({ readOnly: true })
  lastName: string;

  updateName(firstName: string, lastName: string): void {
    // We may still update the read-only property internally, which will change
    // the property and notify changes to watchers
    this._set({
      firstName,
      lastName
    });
  }
}

Define a proxy property

These snippets show how to create a two-way binding on an inner property.

Proxy property - ESM TS

Proxy property - CDN JS

Use dark colors for code blocksCopy
import Accessor from "@arcgis/core/core/Accessor.js";
import Collection from "@arcgis/core/core/Collection.js";
import { subclass, property, aliasOf } from "@arcgis/core/core/accessorSupport/decorators.js";

@subclass("custom.GroupLayer")
class GroupLayer extends Accessor {
  @property()
  sublayers: Collection = new Collection();

  // Define a property that reflects one in another object.
  @property({ aliasOf: "sublayers.length" })
  length: number;

  // Alternatively you can use the `@aliasOf` decorator
  //  @aliasOf
  //  length: number

  // You can also proxy a method from another object.
  @aliasOf("sublayers.add")
  add: (item: any) => void;
}

Computed properties

Define a computed property

You may need to use this when a property value depends on numerous other properties. These properties are always read-only.

Computed property - ESM TS

Computed property - CDN JS

Use dark colors for code blocksCopy
import Accessor from "@arcgis/core/core/Accessor.js";
import { subclass, property } from "@arcgis/core/core/accessorSupport/decorators.js";

@subclass()
class Person extends Accessor {
  @property()
  firstName: string;

  @property()
  lastName: string;

  @property({
    readOnly: true
  })
  get fullName(): string {
    return `${this.firstName} ${this.lastName}`;
  }
}

Define a writable computed property

Writable computed property - ESM TS

Writable computed property - CDN JS

Use dark colors for code blocksCopy
import Accessor from "@arcgis/core/core/Accessor.js";
import { subclass, property } from "@arcgis/core/core/accessorSupport/decorators.js";

@subclass()
class Person extends Accessor {
  @property()
  firstName: string;

  @property()
  lastName: string;

  @property()
  get fullName(): string {
    return `${this.firstName} ${this.lastName}`;
  }

  set fullName(value: string) {
    if (value === "") {
      this._set("firstName", null);
      this._set("lastName", null);

      return;
    }

    const [firstName, lastName] = value.split(" ");
    this._set("firstName", firstName);
    this._set("lastName", lastName);
  }
}

Notify a property change

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.

Writable computed property - ESM TS

Writable computed property - CDN JS

Use dark colors for code blocksCopy
import Accessor from "@arcgis/core/core/Accessor.js";
import { subclass, property } from "@arcgis/core/core/accessorSupport/decorators.js";

@subclass("custom.Collection")
class Collection extends Accessor {
  private _items: any[] = [];

  @property({
    readOnly: true
  })
  get length(): number {
    return this._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 invoked
    this.notifyChange("length");
  }
}

Autocast

Define the property type

It is possible to define a type for a class property.

Define the property type - ESM TS

Define the property type - CDN JS

Use dark colors for code blocksCopy
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()
class GraphicsLayer extends Accessor {
  @property({
    // Define the type of the collection of Graphics
    // When the property is set with an array,
    // the collection constructor will automatically be called
    type: 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 TS

Define a casting method - CDN JS

Use dark colors for code blocksCopy
import Accessor from "@arcgis/core/core/Accessor.js";
import { subclass, property, cast } from "@arcgis/core/core/accessorSupport/decorators.js";

@subclass()
class Color extends Accessor {
  @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 255
    return Math.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 1
    return Math.max(0, Math.min(1, value));
  }
}

Additional information

Please refer to these additional links for further information:

Core API Reference - Accessor class