@arcgis/core/WebLinkChart.d.ts

ArcGIS Maps SDK for JavaScript: A complete 2D and 3D mapping and data visualization API

import type WebDocument2D from "./WebDocument2D.js";
import type Extent from "./geometry/Extent.js";
import type Point from "./geometry/Point.js";
import type LinkChartLayer from "./layers/LinkChartLayer.js";
import type KnowledgeGraphSublayer from "./layers/knowledgeGraph/KnowledgeGraphSublayer.js";
import type LayoutSettings from "./linkChart/LayoutSettings.js";
import type LinkChartProperties from "./linkChart/LinkChartProperties.js";
import type GraphQueryStreaming from "./rest/knowledgeGraph/GraphQueryStreaming.js";
import type KnowledgeGraph from "./rest/knowledgeGraph/KnowledgeGraph.js";
import type { WebDocument2DProperties } from "./WebDocument2D.js";
import type { AbortOptions } from "./core/promiseUtils.js";
import type { InitializationLinkChartConfig } from "./layers/LinkChartLayer.js";
import type { LayoutMode, IdTypePair } from "./layers/knowledgeGraph/types.js";
import type { RequestOptions } from "./request/types.js";
import type { LinkChartPropertiesProperties } from "./linkChart/LinkChartProperties.js";

export interface WebLinkChartProperties extends WebDocument2DProperties {
  /** [Properties](https://developers.arcgis.com/javascript/latest/references/core/linkChart/LinkChartProperties/) specific to the link chart. */
  linkChartProperties?: LinkChartPropertiesProperties;
}

/**
 * The WebLinkChart class contains properties and methods for storing, managing, and overlaying layers in a link chart.
 * Layers can be added and removed from the link chart, but are rendered via a
 * [LinkChartView](https://developers.arcgis.com/javascript/latest/references/core/views/LinkChartView/). Thus a WebLinkChart instance is a container
 * that holds the [LinkChartLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/LinkChartLayer/), while the [LinkChartView](https://developers.arcgis.com/javascript/latest/references/core/views/LinkChartView/) is the means of displaying it.
 *
 * A WebLinkChart also loads a [WebLinkChart](https://enterprise.arcgis.com/en/knowledge/latest/knowledge-studio/what-is-a-link-chart-.htm) from an [ArcGIS Enterprise portal](https://enterprise.arcgis.com/en/portal/latest/administer/windows/what-is-portal-for-arcgis-.htm)
 * into a [LinkChartView](https://developers.arcgis.com/javascript/latest/references/core/views/LinkChartView/). To load a WebLinkChart from an ArcGIS Enterprise portal into a LinkChartView, you must reference the ID of the WebLinkChart in the [portalItem](https://developers.arcgis.com/javascript/latest/references/core/WebLinkChart/#portalItem) property of this class.
 *
 * ```js
 * // Load the WebLinkChart and LinkChartView modules
 * const [LinkChart, LinkChartView, LinkChartLayer] = await $arcgis.import([
 *   "@arcgis/core/WebLinkChart".js,
 *   "@arcgis/core/views/LinkChartView.js",
 *   "@arcgis/core/layers/LinkChartLayer.js"
 * ]);
 * // Create a WebLinkChart instance
 * const myLinkChart = new WebLinkChart({
 *   portalItem: { // autocasts as new PortalItem()
 *     id: "e691172598f04ea8881cd2a4adaa45ba"
 *   }
 * });
 * // Create a LinkChartView instance and reference the WebLinkChart instance
 * const view = new LinkChartView({
 *   map: myLinkChart,
 *   container: 'viewDiv'
 * });
 * ```
 *
 * A LinkChartLayer can also be created from a knowledgeGraphService and added to a WebLinkChart. The entire graph can be added to the link chart
 * or a subset of the records in the graph can be included in the layer by specifying the [LinkChartLayer.initializationInclusionModeDefinition](https://developers.arcgis.com/javascript/latest/references/core/layers/LinkChartLayer/#initializationInclusionModeDefinition).
 *
 * ```js
 * //create a link chart layer from a knowledge graph service with an inclusion definition
 * // constructing an inclusion list:
 * // The exact record ids of each of the records of a specific named type (entity type or relationship type)
 * // to include in the layer. In this case the layer will contain one record
 * const layerInclusionMemberDefinition = new Map();
 * layerInclusionMemberDefinition.set("{1A4W8G4-W52G-W89G-1W5G-J1R4S8H52H4S}",{id:"{1A4W8G4-W52G-W89G-1W5G-J1R4S8H52H4S}"})
 *
 *  //The layerInclusionDefinition specifies whether to use all of the data in a named type or only the records
 * // specified in the 'members' list. In this case we only want the records specified.
 * const layerInclusionDefinition = {
 *   useAllData: false, //only include instances in the member list
 *   members: layerInclusionMemberDefinition
 * };
 *
 * // The namedTypeDefinition is a map of the typeName of each type to be included.
 * // In this case we are only including the "Observation" entity type.
 * // The layerInclusionDefinition specifies exactly which "Observation" entities to include in the layer.
 * const namedTypeDefinition = new Map();
 * namedTypeDefinition.set("Observation", layerInclusionDefinition);
 *
 * // Specify if a sublayer should be generated for all named types.
 * // If true, a sublayer will be created for all named types regardless of
 * // whether they have a list of instances to include or not.
 * // If there are no instances the sublayer will be empty. In this case we have set 'generateAllSubLayers' to false so the
 * // layer will only contain sublayers for the named types (entity types or relationship types) that are specified
 * // in the namedTypeDefinitions.
 * // Also defines the collection of named types to include in the layer.
 * const inclusionListDefinition = {
 *   generateAllSublayers: false, //only create sublayers for the named types in the namedTypeDefinition
 *   namedTypeDefinitions: namedTypeDefinition
 * }
 *
 * //create the link chart layer with the inclusion definintion
 * const myLinkChartLayer = new LinkChartLayer({
 *     title: "link chart layer",
 *     url: "https://sampleserver7.arcgisonline.com/arcgis/rest/services/Hosted/SmallBumbleBees/KnowledgeGraphServer",
 *     initializationInclusionModeDefinition: inclusionListDefinition
 *   });
 * //add the layer to a new link chart
 *   myLinkChartLayer.load().then(()=>{
 *     const myLinkChart = new WebLinkChart({
 *       layers: [myLinkChartLayer]
 *     });
 *     // Create a LinkChartView instance and reference the WebLinkChart instance
 *     const view = new LinkChartView({
 *       map: myLinkChart,
 *       container: 'viewDiv'
 *     });
 *  })
 * ```
 *
 * @since 4.31
 * @see [LinkChartView](https://developers.arcgis.com/javascript/latest/references/core/views/LinkChartView/)
 * @see [LinkChartLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/LinkChartLayer/)
 */
export default class WebLinkChart extends WebDocument2D {
  /**
   * Creates a WebLinkChart from a Cypher query against a knowledge graph service.
   *
   * @param kg - The knowledge graph service to query.
   * @param queryArguments - The cypher query and parameters to execute against the knowledge graph service.
   * @param initializationLinkChartConfig - Configuration options for initializing the link chart layer.
   * @param requestOptions - Additional options for the request.
   * @returns A promise that resolves to the created WebLinkChart.
   */
  static fromCypherQuery(kg: KnowledgeGraph, queryArguments: GraphQueryStreaming, initializationLinkChartConfig?: InitializationLinkChartConfig, requestOptions?: RequestOptions): Promise<WebLinkChart>;
  /**
   * Creates a WebLinkChart from an array of id-type pairs against a knowledge graph service.
   *
   * @param kg - The knowledge graph service to query.
   * @param idTypePairs - An array of objects with an id and named type for each record to include in the link chart.
   * @param initializationLinkChartConfig - Configuration options for initializing the link chart layer.
   * @param requestOptions - Additional options for the request.
   * @returns A promise that resolves to the created WebLinkChart.
   */
  static fromIdTypePairs(kg: KnowledgeGraph, idTypePairs: IdTypePair[], initializationLinkChartConfig?: InitializationLinkChartConfig, requestOptions?: RequestOptions): WebLinkChart;
  /**
   * @example
   * // Typical usage
   * const map = new Map({
   *   basemap: "topo-vector"
   * });
   */
  constructor(properties?: WebLinkChartProperties);
  /** The active [link chart layer](https://developers.arcgis.com/javascript/latest/references/core/layers/LinkChartLayer/). */
  get activeLinkChartLayer(): LinkChartLayer | null | undefined;
  /**
   * The extent of the current layout.
   *
   * @since 4.32
   */
  get diagramNodesExtent(): Extent | null | undefined;
  /**
   * The number of entities in the link chart.
   *
   * @since 4.32
   */
  get entityCount(): number;
  /**
   * The knowledge graph service containing the data displayed in the link chart.
   *
   * @since 4.32
   */
  get knowledgeGraph(): KnowledgeGraph;
  /** [Properties](https://developers.arcgis.com/javascript/latest/references/core/linkChart/LinkChartProperties/) specific to the link chart. */
  get linkChartProperties(): LinkChartProperties;
  set linkChartProperties(value: LinkChartPropertiesProperties);
  /** The map type. Will always be "webLinkChart". */
  get mapType(): "webLinkChart";
  /**
   * The number of relationship in the link chart.
   *
   * @since 4.32
   */
  get relationshipCount(): number;
  /**
   * Adds records to the [link chart layer](https://developers.arcgis.com/javascript/latest/references/core/layers/LinkChartLayer/), given an array of paired ids and named types for each record to add.
   *
   * @param records - An array of objects with an id and named type to be added to the link chart.
   * @param options - Additional options that can be set when adding records.
   * @returns Resolves when the records have been added to the link chart.
   * @since 4.32
   * @example
   * const newRecords = [{ id: "{A0F6BF5F-6CA8-49CB-B47E-165CEC47CA4E}", typeName: "Observation" }]
   * webLinkChart.addRecords(newRecords)
   */
  addRecords(records: IdTypePair[], options?: WebLinkChartAddRecordsOptions): Promise<void>;
  /**
   * Change the layout applied to the link chart. Link chart layouts fall into different categories depending on how they organize
   * entities and relationships in the link chart.
   *
   * See [layout types](https://developers.arcgis.com/javascript/latest/references/core/linkChart/LinkChartProperties/#layoutType) for a description of the different layout algorithms.
   *
   * @param layoutMode - The layout applied to the link chart.
   * @param options - Additional options for refining how the layout is calculated and applied to the link chart.
   * @returns Resolves when the layout has been applied.
   * @since 4.32
   */
  applyLayout(layoutMode?: LayoutMode, options?: WebLinkChartApplyLayoutOptions): Promise<void>;
  /**
   * Indicates whether the nonspatial data on the link chart is visible. Link charts can contain both spatial and nonspatial records. Spatial records are entities with geometry and relationships that
   * connect two spatial entities (both the relationship origin and destination entities have geometry). Nonspatial records are entities without
   * geometry (even if they are a member of a spatially enabled entity type) and relationships that have at least one endpoint with no geometry.
   *
   * @param mode - A map with a key of the named Type and the list of Identifiers to be added. Default: "visible"
   * @since 4.32
   */
  changeNonspatialDataDisplay(mode: "hidden" | "visible"): void;
  /**
   * Connect between entities adds any existing direct relationships between the selected entities.
   *
   * @param entityIds - List of entity ids on the link chart to find direct relationships between.
   * @param options - Additional options for the connect request.
   * @returns An array of objects representing the relationships added to connect the entities
   * @since 4.32
   */
  connectBetweenEntities(entityIds: string[], options?: AbortOptions): Promise<IdTypePair[]>;
  /**
   * Connect from entities adds any existing direct relationships between the specified entities and any other entities in the link chart.
   *
   * @param entityIds - List of entity ids on the link chart to find direct relationships to any other entities on the link chart.
   * @param options - Additional options for the connect request.
   * @returns An array of objects representing the relationships added to connect the entities
   * @since 4.32
   */
  connectFromEntities(entityIds: string[], options?: AbortOptions): Promise<IdTypePair[]>;
  /**
   * @param typeName - The name of the named type to create a sublayer for
   * @returns Resolves when the sublayer is created and added to the layer.
   */
  createSublayerForNamedType(typeName: string): Promise<KnowledgeGraphSublayer>;
  /**
   * Given a list of entity IDs to expand from, will attempt to retrieve all one-hop connected entities and the connecting relationships.
   * If relationship named types are given, the expand will only look for entities connected by the specified relationship types.
   * Note: the starting nodes must already exist in the [link chart layer](https://developers.arcgis.com/javascript/latest/references/core/layers/LinkChartLayer/).
   *
   * @param nodeIds - Array of entity IDs to expand from.
   * @param options - Additional options for the expand request.
   * @returns Resolves to an object with a records property containing ids and named types for each connected relationship/entity
   * @since 4.32
   */
  expand(nodeIds: string[], options?: WebLinkChartExpandOptions): Promise<IdTypePair[]>;
  /**
   * Retrieve the record IDs for all instances of a specified named type in the link chart.
   *
   * @param typeName - The named type to get the member ids for
   * @returns Returns a list of all of the records of the named type present in the link chart.
   * @since 4.32
   */
  getMemberIdsByType(typeName: string): string[];
  /**
   * Refreshes the data in the link chart. If an entity or relationship in the link chart no longer exists in the graph it will be removed.
   * Updates any properties on the records in the link chart. Optionally specify a subset of ids to only update the
   * data for a specific set of records.
   *
   * @param ids - List of specific entities and relationships to update.
   * @returns Resolves when the data in the link chart has been updated.
   * @since 4.32
   */
  refreshLinkChartData(ids?: string[]): Promise<void>;
  /**
   * Removes records from the [link chart layer](https://developers.arcgis.com/javascript/latest/references/core/layers/LinkChartLayer/). Does not delete them from the knowledge graph.
   *
   * @param records - An array of objects with an id and named type to be removed from the link chart.
   * @since 4.32
   */
  removeRecords(records: IdTypePair[]): Promise<IdTypePair[]>;
}

/** Additional options for refining how the layout is calculated and applied to the link chart. */
export interface WebLinkChartApplyLayoutOptions {
  /** Additional settings for organic layouts (particularly geographic layout) and chronological layouts. If not specified, then the current layout settings will be used. */
  layoutSettings?: LayoutSettings;
  /**
   * A map of entity IDs to their locked locations. Specify the location of specific entities. When the layout is recalculated these entities are placed at the specified location.
   *
   * @deprecated since version 5.0. Use `lockedEntityLocations` instead.
   */
  lockedNodeLocations?: Map<string, Point>;
  /** A map of entity IDs to their locked locations. Specify the location of specific entities. When the layout is recalculated these entities are placed at the specified location. */
  lockedEntityLocations?: Map<string, Point>;
  /** A set of entity IDs to be used as root entities in the layout. Only applicable in tree, radial and hierachical layouts. */
  rootEntityIds?: Set<string>;
}

/** Additional options that can be set when adding records to a link chart. */
export interface WebLinkChartAddRecordsOptions extends AbortOptions {
  /** If set to true, adding a relationship will also add it's origin and destination entities. */
  cascadeAddRelationshipEndNodes?: boolean;
}

/** Additional options for specifying which entities and relationships to traverse in the expand operation. */
export interface WebLinkChartExpandOptions extends AbortOptions {
  /** Array of relationship named types to filter which entities and relationships are added in the expand. */
  relationshipTypeNames?: string[];
}