Add examples for doc. (#7034)

* Add examples for doc.

* Added more examples.

* Update doc

* Update doc

* Fixed an incorrect import.

* Updated doc.

* Added a new example.

* Added an example for arcgis-portal-item type.

CHANGES.md

@@ -15,6 +15,7 @@
 - Prevent user adding empty web url
 - Fix bug where search results shown in `My Data` tab
 - Fix bug in function createDiscreteTimesFromIsoSegments where it might create duplicate timestamps.
+- Add examples.
 - [The next improvement]
 
 #### 8.4.1 - 2023-12-08

lib/Models/Catalog/Esri/ArcGisCatalogGroup.ts

@@ -11,7 +11,7 @@ import CatalogMemberMixin from "../../../ModelMixins/CatalogMemberMixin";
 import GroupMixin from "../../../ModelMixins/GroupMixin";
 import UrlMixin from "../../../ModelMixins/UrlMixin";
 import ModelReference from "../../../Traits/ModelReference";
-import ArcGisCatalogGroupTraits from "../../../Traits/TraitsClasses/ArcGisMapServerCatalogGroupTraits";
+import ArcGisCatalogGroupTraits from "../../../Traits/TraitsClasses/ArcGisCatalogGroupTraits";
 import CommonStrata from "../../Definition/CommonStrata";
 import CreateModel from "../../Definition/CreateModel";
 import LoadableStratum from "../../Definition/LoadableStratum";

lib/Traits/TraitsClasses/ApiTableCatalogItemTraits.ts

@@ -2,6 +2,7 @@ import objectArrayTrait from "../Decorators/objectArrayTrait";
 import primitiveArrayTrait from "../Decorators/primitiveArrayTrait";
 import primitiveTrait from "../Decorators/primitiveTrait";
 import ModelTraits from "../ModelTraits";
+import { traitClass } from "../Trait";
 import mixTraits from "../mixTraits";
 import ApiRequestTraits, { QueryParamTraits } from "./ApiRequestTraits";
 import AutoRefreshingTraits from "./AutoRefreshingTraits";
@@ -47,6 +48,56 @@ export class ApiTableColumnTraits extends ModelTraits {
   responseDataPath?: string;
 }
 
+@traitClass({
+  description: `Creates an <b>api-table</b> type dataset in the catalog, typically used for live sensor data.`,
+  example: {
+    type: "api-table",
+    name: "City of Melbourne Pedestrian Counter",
+    description:
+      "The City of Melbourne Pedestrian Counting System data has been obtained from the City of Melbourne Open data platform: www.data.melbourne.vic.gov.au to demonstrate the directional movement of pedestrians across the city.\n\nThe counters generate a per minute reading on each of the pedestrian traffic sensors which are then displayed as near-live data.\n\nTo find out more about the City of Melbourne's Pedestrian Counting System or to seek access to their data, please click:\n\nhttp://www.pedestrian.melbourne.vic.gov.au/?_ga=2.244642053.1432520662.1632694466-1456630549.1631675392#date=27-09-2021&time=1",
+    defaultStyle: {
+      time: {
+        spreadFinishTime: true,
+        timeColumn: "sensing_datetime"
+      }
+    },
+    initialTimeSource: "stop",
+    columns: [
+      {
+        name: "total_of_directions"
+      },
+      {
+        name: "direction_2"
+      },
+      {
+        name: "direction_1"
+      },
+      {
+        name: "sensing_datetime"
+      },
+      {
+        name: "latitude"
+      },
+      {
+        name: "longitude"
+      }
+    ],
+    idKey: "location_id",
+    refreshInterval: 60,
+    removeDuplicateRows: true,
+    apis: [
+      {
+        url: "https://melbournetestbed.opendatasoft.com/api/explore/v2.1/catalog/datasets/pedestrian-counting-system-past-hour-counts-per-minute/records?select=location_id%2Csensing_datetime%2Cdirection_1%2Cdirection_2%2Ctotal_of_directions&order_by=sensing_datetime%20DESC&limit=100",
+        responseDataPath: "results",
+        kind: "PER_ROW"
+      },
+      {
+        url: "https://melbournetestbed.opendatasoft.com/api/explore/v2.1/catalog/datasets/pedestrian-counting-system-sensor-locations/exports/json?lang=en&timezone=Australia%2FSydney",
+        kind: "PER_ID"
+      }
+    ]
+  }
+})
 export default class ApiTableCatalogItemTraits extends mixTraits(
   TableTraits,
   CatalogMemberTraits,

lib/Traits/TraitsClasses/ArcGisCatalogGroupTraits.ts

@@ -1,9 +1,19 @@
+import { traitClass } from "../Trait";
 import mixTraits from "../mixTraits";
 import CatalogMemberTraits from "./CatalogMemberTraits";
 import GroupTraits from "./GroupTraits";
 import LegendOwnerTraits from "./LegendOwnerTraits";
 import UrlTraits from "./UrlTraits";
 
+@traitClass({
+  description: `Creates a group that has individual ESRI services ("MapServer" or "FeatureServer") in the given URL as members (subgroups) in the catalog.`,
+  example: {
+    type: "esri-group",
+    name: "Sydney",
+    url: "https://services1.arcgis.com/cNVyNtjGVZybOQWZ/arcgis/rest/services",
+    id: "some id"
+  }
+})
 export default class ArcGisCatalogGroupTraits extends mixTraits(
   GroupTraits,
   UrlTraits,

lib/Traits/TraitsClasses/ArcGisFeatureServerCatalogGroupTraits.ts

@@ -1,9 +1,22 @@
+import { traitClass } from "../Trait";
 import mixTraits from "../mixTraits";
 import CatalogMemberTraits from "./CatalogMemberTraits";
 import GroupTraits from "./GroupTraits";
 import LegendOwnerTraits from "./LegendOwnerTraits";
 import UrlTraits from "./UrlTraits";
 
+@traitClass({
+  description: `Creates a group that has individual ESRI WFS layers in the given URL as members.
+
+  <strong>Note:</strong> <i>To exclude unwanted layers, specify their <b>names</b> in property <code>excludeMembers</code>.</i>`,
+  example: {
+    url: "https://services7.arcgis.com/fVJQ0uhT9L4zp35f/arcgis/rest/services/ActivityArea_gdb/FeatureServer",
+    type: "esri-featureServer-group",
+    excludeMembers: ["BCC SHWEP"],
+    name: "Activity Area",
+    id: "some id"
+  }
+})
 export default class ArcGisFeatureServerCatalogGroupTraits extends mixTraits(
   GroupTraits,
   UrlTraits,

lib/Traits/TraitsClasses/ArcGisFeatureServerCatalogItemTraits.ts

@@ -1,11 +1,23 @@
 import primitiveTrait from "../Decorators/primitiveTrait";
+import { traitClass } from "../Trait";
 import mixTraits from "../mixTraits";
 import CatalogMemberTraits from "./CatalogMemberTraits";
 import { GeoJsonTraits } from "./GeoJsonTraits";
 import LegendOwnerTraits from "./LegendOwnerTraits";
 import MappableTraits from "./MappableTraits";
 import UrlTraits from "./UrlTraits";
 
+@traitClass({
+  description: `Creates a single item in the catalog from one ESRI WFS layer.
+
+  <strong>Note:</strong> <i>Must specify <b>layer ID</b>, e.g. <code>/0</code>, in the URL path.</i>`,
+  example: {
+    url: "https://services5.arcgis.com/OvOcYIrJnM97ABBA/arcgis/rest/services/Australian_Public_Hospitals_WFL1/FeatureServer/0",
+    type: "esri-featureServer",
+    name: "Australian Public Hospitals",
+    id: "some id"
+  }
+})
 export default class ArcGisFeatureServerCatalogItemTraits extends mixTraits(
   UrlTraits,
   MappableTraits,

lib/Traits/TraitsClasses/ArcGisMapServerCatalogGroupTraits.ts

@@ -1,11 +1,21 @@
 import { JsonObject } from "../../Core/Json";
 import anyTrait from "../Decorators/anyTrait";
+import { traitClass } from "../Trait";
 import mixTraits from "../mixTraits";
 import CatalogMemberTraits from "./CatalogMemberTraits";
 import GroupTraits from "./GroupTraits";
 import LegendOwnerTraits from "./LegendOwnerTraits";
 import UrlTraits from "./UrlTraits";
 
+@traitClass({
+  description: `Creates a group that has individual ESRI WMS layers in the given URL as members in the catalog.`,
+  example: {
+    type: "esri-mapServer-group",
+    name: "Catchment Scale Land Use",
+    id: "354db2f2",
+    url: "https://www.asris.csiro.au/arcgis/rest/services/abares/clum_50m_2018/MapServer"
+  }
+})
 export default class ArcGisMapServerCatalogGroupTraits extends mixTraits(
   GroupTraits,
   UrlTraits,

lib/Traits/TraitsClasses/ArcGisMapServerCatalogItemTraits.ts

@@ -1,6 +1,7 @@
 import { JsonObject } from "../../Core/Json";
 import anyTrait from "../Decorators/anyTrait";
 import primitiveTrait from "../Decorators/primitiveTrait";
+import { traitClass } from "../Trait";
 import mixTraits from "../mixTraits";
 import CatalogMemberTraits from "./CatalogMemberTraits";
 import DiscretelyTimeVaryingTraits from "./DiscretelyTimeVaryingTraits";
@@ -10,6 +11,16 @@ import LegendOwnerTraits from "./LegendOwnerTraits";
 import { MinMaxLevelTraits } from "./MinMaxLevelTraits";
 import UrlTraits from "./UrlTraits";
 
+@traitClass({
+  description: `Creates a single item in the catalog from one or many ESRI WMS layers.
+
+  <strong>Note:</strong> <i>The following example does not specify <b>layers</b> property therefore will present all layers in the given URL as single catalog item. To present specific layers only, add them in <b>layers</b> property, e.g. <code>"layers": "AUS_GA_2500k_MiscLines,AUS_GA_2500k_Faults"</code>.</i>`,
+  example: {
+    url: "https://services.ga.gov.au/gis/rest/services/GA_Surface_Geology/MapServer",
+    type: "esri-mapServer",
+    name: "Surface Geology"
+  }
+})
 export default class ArcGisMapServerCatalogItemTraits extends mixTraits(
   ImageryProviderTraits,
   LayerOrderingTraits,

lib/Traits/TraitsClasses/ArcGisPortalCatalogGroupTraits.ts

@@ -1,13 +1,34 @@
 import { JsonObject } from "../../Core/Json";
 import anyTrait from "../Decorators/anyTrait";
 import primitiveTrait from "../Decorators/primitiveTrait";
+import { traitClass } from "../Trait";
 import mixTraits from "../mixTraits";
 import ArcGisPortalSharedTraits from "./ArcGisPortalSharedTraits";
 import CatalogMemberTraits from "./CatalogMemberTraits";
 import GroupTraits from "./GroupTraits";
 import LegendOwnerTraits from "./LegendOwnerTraits";
 import UrlTraits from "./UrlTraits";
 
+@traitClass({
+  description: `Creates a group with members from ArcGIS server portal.
+
+  <strong>Note:</strong> 
+  <br>The following example will</br>
+  <li>Request datasets of specific types only.</li>
+  <li>Organise members in subgroups according to their categories.</li>
+  <li>Sort members according to their titles.</li>`,
+  example: {
+    url: "https://portal.spatial.nsw.gov.au/portal",
+    type: "arcgis-portal-group",
+    groupBy: "portalCategories",
+    name: "NSW Spatial Portal Categories",
+    searchParams: {
+      q: '(type:"Map Service" OR type:"WMS" OR type:"KML")',
+      sortField: "title"
+    },
+    id: "some id"
+  }
+})
 export default class ArcGisPortalCatalogGroupTraits extends mixTraits(
   GroupTraits,
   UrlTraits,

lib/Traits/TraitsClasses/ArcGisPortalItemTraits.ts

@@ -4,7 +4,21 @@ import MappableTraits from "./MappableTraits";
 import mixTraits from "../mixTraits";
 import primitiveTrait from "../Decorators/primitiveTrait";
 import UrlTraits from "./UrlTraits";
+import { traitClass } from "../Trait";
 
+@traitClass({
+  description: `Creates an item or group that referehces an item in ArcGIS portal.
+  <strong>Note:</strong> 
+  <li>The <code>itemId</code> in the example is the referenced item's ID in the portal.</li>
+  <li>Not all referenced items can be added to the map. E.g., some types need conversions.</li>`,
+  example: {
+    type: "arcgis-portal-item",
+    itemId: "084c61c6dd404517bc2db69079ddec38",
+    name: "NSW Administrative Theme",
+    url: "https://portal.spatial.nsw.gov.au/portal",
+    id: "some id"
+  }
+})
 export default class ArcGisPortalItemTraits extends mixTraits(
   UrlTraits,
   MappableTraits,