TerriaJsonCatalogFunction

TerriaJsonCatalogFunction

new TerriaJsonCatalogFunction(terria)

Source:

A CatalogFunction that issues an HTTP GET to a service with a set of query parameters specified by the TerriaJsonCatalogFunction#inputs property, and expects to receive back TerriaJS catalog/share JSON.

When this CatalogFunction is added to the catalog, TerriaJS automatically creates a user interface for it based on the inputs. When the user clicks "Run Analysis", it issues an HTTP GET with the user-specified inputs supplied as part of the query string. The returned TerriaJS catalog/share JSON can add items to the workbench, configure the catalog, change the camera view, and more.

Example:

{
  "name": "Simple Example",
  "type": "terria-json",
  "url": "https://putsreq.com/PK2GvS6jHfWhlBmkadrG",
  "inputs": [
    {
      "id": "position",
      "type": "point",
      "name": "Position",
      "description": "The position to pass to the service.",
      "formatter": "longitudeCommaLatitude"
    },
    {
      "id": "someOtherParameter",
      "type": "string",
      "name": "Some Other Parameter",
      "description": "This is another parameter that will be passed to the service."
    }
  ]
}

For this CatalogFunction TerriaJS will present a user interface with two elements: a position on the map and a string. When invoked, TerriaJS will GET a URL like: https://putsreq.com/PK2GvS6jHfWhlBmkadrG?position=151.0%2C-33.0&someOtherParameter=some%20text

The service is expected to return JSON using the application/json content type, and have a body with any of the following:

  • A single catalog member

For example:

{
  "type": "csv",
  "data": "POSTCODE,value\n2000,1"
}

The catalog member will be added to the catalog inside a catalog group directly below this CatalogFunction. Catalog items will also be added to the workbench unless isEnabled is explicitly set to false.

If the catalog item does not have a name, as in the above example, its name will be the name of this CatalogFunction followed by the date and time it was invoked in ISO8601 format. If the catalog item does not have a description, it will be given a description explaining that this is the result of executing a service and will include the input parameters sent to the service.

  • An array of catalog members

An array of catalog members as described above.

For example:

[
  {
    "type": "csv",
    "data": "POSTCODE,value\n2000,1"
  },
  {
    "name": "My Result WMS Layer",
    "type": "wms",
    "url": "http://ereeftds.bom.gov.au/ereefs/tds/wms/ereefs/mwq_gridAgg_P1A",
    "layers": "Chl_MIM_mean"
  }
]
  • A catalog file

For example:

{
  "catalog": [
    {
      "name": "National Datasets",
      "type": "group",
      "items": [
        {
          "name": "My Result WMS Layer",
          "type": "wms",
          "url": "http://ereeftds.bom.gov.au/ereefs/tds/wms/ereefs/mwq_gridAgg_P1A",
          "layers": "Chl_MIM_mean",
          "isEnabled": true
        }
      ]
    }
  ],
  "initialCamera": {
    "west": 141.0,
    "south": -26.0,
    "east": 157.0,
    "north": -9.0
  }
}

Please note that in this case, catalog items are not automatically enabled or named. The name property is required. If isEnabled is not set to true, the catalog item will not appear on the workbench.

  • Share data

Similar to the above except that it allows multiple init sources (catalog files) and has a version property for backward compatibility. For example:

{
  "version": "0.0.05",
  "initSources": [
    {
      "catalog": [
        {
          "name": "National Datasets",
          "type": "group",
          "items": [
            {
              "name": "My Result WMS Layer",
              "type": "wms",
              "url": "http://ereeftds.bom.gov.au/ereefs/tds/wms/ereefs/mwq_gridAgg_P1A",
              "layers": "Chl_MIM_mean",
              "isEnabled": true
            }
          ]
        }
      ],
    },
    {
      "initialCamera": {
        "west": 141.0,
        "south": -26.0,
        "east": 157.0,
        "north": -9.0
      }
    }
  ]
}
Parameters:
Name Type Description
terria Terria

The Terria instance.

Extends

Members

_memoizedInfoItemsSourceLookup

Source:
Inherited From:

Lookup table for _sourceInfoItemNames, access through CatalogMember#_infoItemsWithSourceInfoLookup

cacheDuration :String

Source:
Inherited From:

Gets or sets the cache duration to use for proxied URLs for this catalog member. If undefined, proxied URLs are effectively cachable forever. The duration is expressed as a Varnish-like duration string, such as '1d' (one day) or '10000s' (ten thousand seconds).

Type:
  • String

contextItem :CatalogItem

Source:
Inherited From:

A catalog item that will be enabled while preparing to invoke this catalog function, in order to provide context for the function.

Type:

customProperties :Object

Source:
Inherited From:

Gets or sets the dictionary of custom item properties. This property is observable.

Type:
  • Object

description :String

Source:
Inherited From:

Gets or sets the description of the item. This property is observable.

Type:
  • String

forceProxy :Boolean

Source:
Inherited From:

Gets or sets whether or not this member should be forced to use a proxy. This property is not observable.

Type:
  • Boolean

hasDescription :Boolean

Source:
Inherited From:

Tests whether a description is available, either in the 'description' property or as a member of the 'info' array.

Type:
  • Boolean

hideSource :boolean

Source:
Inherited From:

Indicates that the source of this data should be hidden from the UI (obviously this isn't super-secure as you can just look at the network requests).

Type:
  • boolean

id :String

Source:
Inherited From:

An optional unique id for this member, that is stable across renames and moves. Use uniqueId to get the canonical unique id for this CatalogMember, which is present even if there is no id.

Type:
  • String

info :Array.<Object>

Source:
Inherited From:
Default Value:
  • []

Gets or sets the array of section titles and contents for display in the layer info panel. In future this may replace 'description' above - this list should not contain sections named 'description' or 'Description' if the 'description' property is also set as both will be displayed. The object is of the form {name:string, content:string}. Content will be rendered as Markdown with HTML. This property is observable.

Type:
  • Array.<Object>

infoSectionOrder :Array.<String>

Source:
Inherited From:

Gets or sets the array of section titles definining the display order of info sections. If this property is not defined, DataPreviewSections's DEFAULT_SECTION_ORDER is used. This property is observable.

Type:
  • Array.<String>

initialMessage :Object

Source:
Inherited From:

A message object that is presented to the user when an item or group is initially clicked The object is of the form {title:string, content:string, key: string, confirmation: boolean, confirmText: string, width: number, height: number}. This property is observable.

Type:
  • Object

inputs :Array.<FunctionParameter>

Source:

Gets or sets the input parameters to the service.

Type:

isGroup :Boolean

Source:
Inherited From:

Gets a value that tells the UI whether this is a group. Groups, when clicked, expand to show their constituent items.

Type:
  • Boolean

isHidden :Boolean

Source:
Inherited From:
Default Value:
  • false

Gets or sets a value indicating whether this item is hidden from the catalog. This property is observable.

Type:
  • Boolean

isLoading :Boolean

Source:
Inherited From:

Gets or sets a value indicating whether the group is currently loading. This property is observable.

Type:
  • Boolean

isPromoted :Boolean

Source:
Inherited From:
Default Value:
  • false

Gets or sets a value indicating whether this item is kept above other non-promoted items. This property is observable.

Type:
  • Boolean

isUserSupplied :Boolean

Source:
Inherited From:
Default Value:
  • true

Gets or sets a value indicating whether this member was supplied by the user rather than loaded from one of the Terria#initSources. User-supplied members must be serialized completely when, for example, serializing enabled members for sharing. This property is observable.

Type:
  • Boolean

isWaitingForDisclaimer :boolean

Source:
Inherited From:

Whether this catalog member is waiting for a disclaimer to be accepted before showing itself.

Type:
  • boolean

name :String

Source:
Inherited From:

Gets or sets the name of the item. This property is observable.

Type:
  • String

nameInCatalog :String

Source:
Inherited From:

Gets or sets the name of this catalog member in the catalog. By default this is just name, but can be overridden.

Type:
  • String

parent :CatalogGroup

Source:
Inherited From:

The parent CatalogGroup of this member.

Type:

path :String

Source:
Inherited From:

The complete path of this member's location.

Type:
  • String

propertiesForSharing :Array.<String>

Source:
Inherited From:

Gets the set of names of the properties to be serialized for this object when CatalogMember#serializeToJson is called for a share link.

Type:
  • Array.<String>

serializers :Object

Source:
Inherited From:

Gets the set of functions used to serialize individual properties in CatalogMember#serializeToJson. When a property name on the model matches the name of a property in the serializers object literal, the value will be called as a function and passed a reference to the model, a reference to the destination JSON object literal, and the name of the property.

Type:
  • Object

shareKeys :Array.<String>

Source:
Inherited From:

An array of all possible keys that can be used to match to this catalog member when specified in a share link - used for maintaining backwards compatibility when adding or changing CatalogMember#id.

Type:
  • Array.<String>

shortReport :String

Source:
Inherited From:

A short report to show on the now viewing tab. This property is observable.

Type:
  • String

shortReportSections :Array.<ShortReportSection>

Source:
Inherited From:

The list of collapsible sections of the short report. Each element of the array is an object literal with a name and content property.

Type:
  • Array.<ShortReportSection>

showsInfo :Boolean

Source:
Inherited From:

Gets a value indicating whether this catalog member can show information. If so, an info icon will be shown next to the item in the data catalog.

Type:
  • Boolean

terria :Terria

Source:
Inherited From:

Gets the Terria instance.

Type:

type :String

Source:
Inherited From:

Gets the type of data item represented by this instance.

Type:
  • String

typeName :String

Source:
Inherited From:

Gets a human-readable name for this type of data source, such as 'Web Map Service (WMS)'.

Type:
  • String

uniqueId :String

Source:
Inherited From:

The canonical unique id for this CatalogMember. Will be the id property if one is present, otherwise it will fall back to the uniqueId of this item's parent + this item's name. This means that if no id is set anywhere up the tree, the uniqueId will be a complete path of this member's location.

Type:
  • String

updaters :Object

Source:
Inherited From:

Gets the set of functions used to update individual properties in CatalogMember#updateFromJson. When a property name in the returned object literal matches the name of a property on this instance, the value will be called as a function and passed a reference to this instance, a reference to the source JSON object literal, and the name of the property.

Type:
  • Object

url :String

Source:

Gets or sets the URL of the REST server. This property is observable.

Type:
  • String

Methods

connectsWithRoot()

Source:
Inherited From:

Goes up the hierarchy and determines if this CatalogMember is connected with the root in terria.catalog, or whether it's part of a disconnected sub-tree.

enableWithParents()

Source:
Inherited From:

"Enables" this catalog member in a way that makes sense for its implementation (e.g. isEnabled for items, isOpen for groups, and all its parents and ancestors in the tree.

findInfoSection(sectionName) → {Object}

Source:
Inherited From:

Finds an CatalogMember#info section by name.

Parameters:
Name Type Description
sectionName String

The name of the section to find.
Returns:

The section, or undefined if no section with that name exists.

Type
Object

getParameterValues() → {Object}

Source:
Inherited From:

Gets the current parameters to this function.

Returns:

An object with a property for each parameter. The property name is the id of the parameter and the property value is the value of that parameter.

Type
Object

invoke() → {Promise}

Source:
Overrides:

Invoke the REST function with the provided parameterValues.

Returns:
Type
Promise

load() → {Promise}

Source:
Inherited From:

Loads this function, if it's not already loaded. It is safe to call this method multiple times. The CatalogFunction#isLoading flag will be set while the load is in progress. Derived classes should implement CatalogFunction#_load to perform the actual loading for the function. Derived classes may optionally implement CatalogFunction#_getValuesThatInfluenceLoad to provide an array containing the current value of all properties that influence this function's load process. Each time that CatalogFunction#load is invoked, these values are checked against the list of values returned last time, and CatalogFunction#_load is invoked again if they are different. If CatalogFunction#_getValuesThatInfluenceLoad is undefined or returns an empty array, CatalogFunction#_load will only be invoked once, no matter how many times CatalogFunction#load is invoked.

Returns:

A promise that resolves when the load is complete, or undefined if the function is already loaded.

Type
Promise

serializeToJson(optionsopt) → {Object}

Source:
Inherited From:

Serializes the data item to JSON.

Parameters:
Name Type Attributes Description
options Object <optional>

Object with the following properties:

Properties
Name Type Attributes Description
propertyFilter function <optional>

Filter function that will be executed to determine whether a property should be serialized.
itemFilter function <optional>

Filter function that will be executed for each item in a group to determine whether that item should be serialized.
Returns:

The serialized JSON object-literal.

Type
Object

setParameterValues(parameterValues)

Source:
Inherited From:

Sets the current parameters to this function.

Parameters:
Name Type Description
parameterValues Object

An object describing the parameters to set and their values. Each property name in this object corresponds to the id of a parameter, and the value of that property is the new value for the parameter. If there is no parameter corresponding to a property in this object, that property is silently ignored.

updateFromJson(json, optionsopt) → {Promise}

Source:
Inherited From:

Updates the catalog member from a JSON object-literal description of it. Existing collections with the same name as a collection in the JSON description are updated. If the description contains a collection with a name that does not yet exist, it is created. Because parts of the update may happen asynchronously, this method returns at Promise that will resolve when the update is completely done.

Parameters:
Name Type Attributes Description
json Object

The JSON description. The JSON should be in the form of an object literal, not a string.
options Object <optional>

Object with the following properties:

Properties
Name Type Attributes Description
onlyUpdateExistingItems Boolean <optional>

true to only update existing items and never create new ones, or false is new items may be created by this update.
isUserSupplied Boolean <optional>

If specified, sets the CatalogMember#isUserSupplied property of updated catalog members to the given value. If not specified, the property is left unchanged.
Returns:

A promise that resolves when the update is complete.

Type
Promise