# Geocortex API Concepts

TODO: Right now this is just a topic outline. It will be turned into proper
documentation in the future.

## Entities

-   Have a unique ID
-   Are always observable (using Esri `Accessor` style API).
-   Use observable collections (Esri's `Collection` for lists, plus observable
    versions of ES6 `Map` and `Set`)
-   Have constructors that take a single JSON object, which sets the object's
    properties
-   Have an `assignProperties()` method for updating from JSON (same syntax as
    constructor)
-   Constructor/`assignProperties()` support autocasting in many cases
-   Have `toJSON()` methods for serializing (same schema as JSON used in
    constructor, except that references to other entities are converted into
    item:// URIs)

## Extension Objects

-   Always related to an Esri API object, which can be specified in several ways
    (show examples):
    1. Pass instance of an Esri object to extension constructor
    1. Pass JSON for Esri object to extension constructor (NB: uses web map
       JSON, not JS API JSON!)
    1. Use a `$ref` property in the JSON, which references an existing object in
       the parent; other JSON properties are then applied to the referenced
       object once resolved
    1. Some extensions allow \$portalItem to reference item in Portal
-   Generally won't duplicate properties of Esri objects
-   Always mirrors Esri object hierarchy (e.g. adding a layer to a `Map` means the
    associated map extension will have a new layer extension, and vice-versa)
-   Hierarchies like `LayerExtension` and `SublayerExtension` have customizable
    factories that allow you to create custom extensions for 3rd party layer and
    sublayer objects

## Initialization

-   Many API objects have an async `initialize()` method
-   Must be called before invoking methods (OK to set properties beforehand)
-   Safe to call multiple times (only runs once)
-   Loads extended Esri object if applicable
-   Initializes child extension objects
-   Respects failure mode on child items (will raise event rather than throwing if
    child item can't initialize and has non-error failure mode)

## Settings

-   Automatically inherited from parent where possible (show example of changing
    number format on `MapExtension`, which causes presentable value for a
    `Feature` attribute to immediately change)
-   Inherited settings can be locally overridden
-   Only locally overridden settings are serialized

## Cancellation

-   Many async operations in the API accept an optional cancel token
-   A cancel token can be obtained from an instance of `Cancellable`
-   Calling `Cancellable.cancel()` cancels any operation associated with its token
-   Cancellation is signaled by rejecting the promise with an instance of
    `Cancellation`

## Logging

-   API logs using the `utilities/log` module
-   By default it outputs to the console, but applications can supply their own
    `Logger` factory to customize logging, e.g. by supplying an adapter for a 3rd
    party logging framework

## Projects

(this section should go in `Geocortex Apps.md`)

-   `Project` is a helper class for creating and loading projects
-   Projects and Apps are the same -- the only difference is how much is typically
    saved and who creates them
-   When saving, add entities to a `Project` and call `toJSON`
-   `Project` will detect item:// references in the JSON and automatically include
    referenced items
-   When loading, `Project` is just like `AppContainer` except that it can be
    linked to another container (this will apply changes to existing items if they
    are found in the linked container)

## API Organization

### data

-   Centers on `Feature`, which can represent either spatial or non-spatial data
-   Defines `FeatureSource`, which represents something that has or can produce
    features
    -   Has a schema that describes the shape and metadata associated with
        features originating from that source (e.g. fields, geometry type, etc.)
    -   Can have relationships to other sources
    -   Has methods for saving features (if supported by the source)
    -   Has various feature-related settings that are inherited by features
    -   Applications can define their own feature sources and relationships to
        integrate 3rd party data
-   Has conversion utilities to convert to/from other formats like CSV, Excel,
    Shapefile, etc.
-   Other key types: `FeatureSet`, `TableExtension`

### mapping

-   Contains extension objects for maps, scenes, basemaps, layers, and sublayers

### tasks

-   Services that allow operations to be performed on one or more feature sources
    simultaneously, e.g. search and identify
    -   Each service type supports "providers" that work with specific types of
        sources
    -   Applications can supply their own providers for 3rd party feature sources

### themes

-   A theme defines a particular visual configuration for a map, e.g. visible
    layers, current basemap, layer list settings
-   Applying a theme to a map or scene reconfigures the map/scene to match the
    theme (only for matching layers and basemaps)
-   The same theme can be applied to multiple maps

### menus

-   A shared configuration model for menus and toolbars

### utilities

-   Various useful utilities dealing with logging, collections, promises,
    formatting, etc
-   Date and number format utilities provide consistent i18n across different
    browsers
