Adding documentation for example pages, cleanup

Author: harshita-adsk

.gitignore

@@ -12,4 +12,4 @@ dist/
 node_modules/
 .DS_Store
 .env
-package-lock.json
+package-lock.json

README.md

@@ -41,7 +41,7 @@ If you'd like to add your own customization on top of our baseline, then you can
 
 ## Further Reading
 
-API Reference - https://forge.autodesk.com/en/docs/dataviz/v1/reference/UI/
+API Reference - https://forge.autodesk.com/en/docs/dataviz/v1/reference/Core/
 
 ## License
 

client/config/SensorStyles.js

@@ -6,6 +6,9 @@ import co2Svg from "../../assets/images/co2_property.svg";
 
 export const SpriteSize = 24;
 
+/**
+ * @type {SensorStyleDefinitions}
+ */
 export const SensorStyleDefinitions = {
     default: {
         url: circleSvg,

client/pages/AnimatedSprites.jsx

@@ -108,6 +108,12 @@ const sensorPositions = {
 /**
  * @component
  * @param {Object} props
+ * @param {Object} props.appData Data passed to the AnimatedSprites.
+ * @param {("AutodeskStaging"|"AutodeskProduction")} props.appData.env Forge API environment
+ * @param {string} props.appData.docUrn Document URN of model
+ * 
+ * @memberof Autodesk.DataVisualization.Examples
+ * @alias Autodesk.DataVisualization.Examples.AnimatedSprites
  */
 function AnimatedSprites(props) {
     const { env, docUrn } = props.appData;
@@ -119,18 +125,8 @@ function AnimatedSprites(props) {
     /**
      * Generates simulation data used for this sample app
      *
-     * @returns {Object} The resulting simulation data in the following form:
-     *
-     *  const obj = [
-     *      {
-     *          id: "Cafeteria",
-     *          position: { x: -143.3017, y: 87.1875, z: -16.9196 },
-     *          type: "thermometer",
-     *          sensorTypes: ["temperature"],
-     *      },
-     *      ...
-     *  ];
-     *
+     * @returns {Array.<SimulationData>} The resulting array of simulation data objects.
+     * @alias Autodesk.DataVisualization.Examples.AnimatedSprites#generateSimulationData
      *
      */
     function generateSimulationData() {
@@ -151,8 +147,9 @@ function AnimatedSprites(props) {
      * Generates viewables to be added to the view. These viewables are sprite-based objects
      * in the 3D viewer canvas, each representing a physical sensor in the real world.
      *
-     * @param {Object} dataItems The simulation data generated in 'generateSimulationData'.
-     * @returns {ViewableData} The resulting viewable data that carries all viewables.
+     * @param {Array.<SimulationData>} dataItems The simulation data generated in 'generateSimulationData'.
+     * @returns {Autodesk.DataVisualization.Core.ViewableData} The resulting viewable data that carries all viewables.
+     * @alias Autodesk.DataVisualization.Examples.AnimatedSprites#generateViewableData
      */
     async function generateViewableData(dataItems) {
         // Create a visual style shared by all the thermometers since they're the same type.
@@ -165,7 +162,7 @@ function AnimatedSprites(props) {
             fan00
         );
 
-        
+
         fans.forEach((fan) => ductFanStyle.preloadSprite(fan));
 
         const motionStyle = new dataVizExtn.ViewableStyle(
@@ -211,6 +208,12 @@ function AnimatedSprites(props) {
         return viewableData;
     }
 
+    /**
+     * Determines a random set of viewable ids that will be animated.
+     * 
+     * @param {Autodesk.DataVisualization.Core.SpriteViewable[]} viewables 
+     * @returns {number[]}
+     */
     function getViewableIdsToAnimate(viewables) {
         let indices = viewables.map((v) => v.dbId);
         indices = indices.sort(() => Math.random() - 0.5); // Shuffle the list.
@@ -221,8 +224,9 @@ function AnimatedSprites(props) {
      * Handles `Autodesk.Viewing.GEOMETRY_LOADED_EVENT` event that is sent
      * when a model has been completely loaded in the viewer.
      *
-     * @param {Viewer3D} viewer The viewer in which the model is loaded.
+     * @param {Autodesk.Viewing.GuiViewer3D} viewer The viewer in which the model is loaded.
      * @param {Object} data Event data that contains the loaded model.
+     * @alias Autodesk.DataVisualization.Examples.AnimatedSprites#onModelLoaded
      */
     async function onModelLoaded(viewer, data) {
 

client/pages/App.jsx

@@ -13,6 +13,19 @@ import StructureInfo from "./StructureInfo.jsx";
 import Navisworks from "./Navisworks.jsx";
 import CustomPage from "./CustomPage.jsx";
 
+/**
+ * 
+ * @param {Object} props 
+ * @param {Object} props.appData Data passed to the application.
+ * @param {("AutodeskStaging"|"AutodeskProduction")} props.appData.env Forge API environment
+ * @param {string} props.appData.docUrn Document URN of model
+ * @param {string} props.appData.adapterType Corresponds to Data Adapter used to query data. i.e - synthetic, azure etc.
+ * @param {"derivativeV2"|"derivativeV2_EU"|"modelDerivativeV2"|"fluent"|"D3S"|"D3S_EU"} [props.appData.api] Please refer to LMV documentation for more information.
+ * @param {string} [props.appData.dataStart] Start date for provided CSV data in ISO string format.
+ * @param {string} [props.appData.dataEnd] End date for provided CSV data in ISO string format.
+ * @param {Object} props.appContext Contains base urls used to query assets, LMV, data etc.
+ * @param {string} [props.appContext.dataUrl] The base url used to configure a specific {@link Autodesk.DataVisualization.Data.DataAdapter}
+ */
 function App(props) {
     return (
         <div className="outer-container">

client/pages/Dot.jsx

@@ -1,7 +1,14 @@
+/**
+ * This sample illustrates how to add Sprite Viewables.
+ */
+
 import React from "react";
 import { Viewer } from "forge-dataviz-iot-react-components";
 import ApplicationContext from "../../shared/config/ApplicationContext.js";
 
+/**
+ * @type {SensorStyleDefinitions}
+ */
 const SensorStyleDefinitions = {
     co2: {
         url: `${ApplicationContext.assetUrlPrefix}/images/co2.svg`,
@@ -41,11 +48,21 @@ const devices = [
 /**
  * An example illustrating how to add viewables to the scene.
  * @component
+ * @memberof Autodesk.DataVisualization.Examples
  * @param {Object} props
+ * @param {Object} props.appData Data passed to the Dot Page.
+ * @param {("AutodeskStaging"|"AutodeskProduction")} props.appData.env Forge API environment
+ * @param {string} props.appData.docUrn Document URN of model
  */
 function Dot(props) {
-    const { env, token, docUrn } = props.appData;
+    const { env, docUrn } = props.appData;
 
+    /**
+     * Handles `Autodesk.Viewing.GEOMETRY_LOADED_EVENT` event that is sent
+     * when a model has been completely loaded in the viewer.
+     *
+     * @param {Autodesk.Viewing.GuiViewer3D} viewer The viewer in which the model is loaded.
+     */
     async function onModelLoaded(viewer) {
         const dataVizExt = await viewer.loadExtension("Autodesk.DataVisualization", { useInternal: true });
         const DATAVIZEXTN = Autodesk.DataVisualization.Core;
@@ -73,10 +90,18 @@ function Dot(props) {
         await viewableData.finish();
         dataVizExt.addViewables(viewableData);
 
+        /**
+         * Called when a user clicks on a Sprite Viewable
+         * @param {Event} event 
+         */
         function onItemClick(event) {
-            
+
         }
 
+        /**
+         *  Called when a user hovers over a Sprite Viewable 
+         * @param {Event} event 
+         */
         function onItemHovering(event) {
             console.log("Show tooltip here", event.dbId);
         }

client/pages/EngineSimulation.jsx

@@ -1,3 +1,7 @@
+/**
+ * This sample illustrates how to add a heatmap to groups of dbIds.
+ */
+
 import React, { useEffect, useRef, useState } from "react";
 import { BaseApp } from "forge-dataviz-iot-react-components";
 import DataHelper from "./DataHelper";
@@ -109,10 +113,23 @@ const RAW_DATA = [
     },
 ];
 
-class EventBus {}
+class EventBus { }
 
 THREE.EventDispatcher.prototype.apply(EventBus.prototype);
 
+/**
+ * 
+ * @param {Object} props 
+ * @param {Object} props.appData Data passed to the EngineSimulation.
+ * @param {("AutodeskStaging"|"AutodeskProduction")} props.appData.env Forge API environment
+ * @param {string} props.appData.docUrn Document URN of model
+ * @param {string} props.appData.adapterType Corresponds to Data Adapter used to query data. i.e - synthetic, azure etc.
+ * @param {"derivativeV2"|"derivativeV2_EU"|"modelDerivativeV2"|"fluent"|"D3S"|"D3S_EU"} [props.appData.api] Please refer to LMV documentation for more information.
+ * @param {Object} props.appContext Contains base urls used to query assets, LMV, data etc.
+ * @param {string} [props.appContext.dataUrl] The base url used to configure a specific {@link Autodesk.DataVisualization.Data.DataAdapter}
+ * 
+ * @memberof Autodesk.DataVisualization.Examples
+ */
 function EngineSimulation(props) {
     const eventBusRef = useRef(new EventBus());
     const [data, setData] = useState(null);
@@ -139,10 +156,6 @@ function EngineSimulation(props) {
                 devicePanelData,
             };
             setData(dataRef.current);
-
-            return function cleanUp() {
-                eventBusRef.current._listeners = {};
-            };
         });
     }, []);
 

client/pages/Heatmap.jsx

@@ -1,15 +1,18 @@
 /**
- * This is a sample code to show how to render basic heatmap on the screen
+ * This is a sample code to show how to render a basic heatmap on the screen
  *
- * Heatmap is the terminology we used to show the corresponding sensor values in the room
- * and this is a step foreward by combine both Dot and ModelStructureInfo to created a combined
+ * Heatmap is the terminology we use to show the corresponding sensor values in the room
+ * and this is a step foreward by combining both Dot and ModelStructureInfo to create a combined
  * user experience
  */
 
 import React from "react";
 import { Viewer } from "forge-dataviz-iot-react-components";
 import ApplicationContext from "../../shared/config/ApplicationContext.js";
 
+/**
+ * @type {SensorStyleDefinitions}
+ */
 const SensorStyleDefinitions = {
     co2: {
         url: `${ApplicationContext.assetUrlPrefix}/images/co2.svg`,
@@ -51,10 +54,23 @@ const devices = [
 /**
  * @component Sample heatmap code
  * @param {Object} props
+ * @param {Object} props 
+ * @param {Object} props.appData Data passed to the application.
+ * @param {("AutodeskStaging"|"AutodeskProduction")} props.appData.env Forge API environment
+ * @param {string} props.appData.docUrn Document URN of model
+ * 
+ * @memberof Autodesk.DataVisualization.Examples
  */
 function Heatmap(props) {
-    const { env, token, docUrn } = props.appData;
-
+    const { env, docUrn } = props.appData;
+
+    /**
+     * Handles `Autodesk.Viewing.GEOMETRY_LOADED_EVENT` event that is sent
+     * when a model has been completely loaded in the viewer.
+     *
+     * @param {Autodesk.Viewing.GuiViewer3D} viewer The viewer in which the model is loaded.
+     * @param {Object} data Event data that contains the loaded model.
+     */
     async function onModelLoaded(viewer, data) {
         const dataVizExt = await viewer.loadExtension("Autodesk.DataVisualization", { useInternal: true });
         const DATAVIZEXTN = Autodesk.DataVisualization.Core;
@@ -106,7 +122,8 @@ function Heatmap(props) {
         dataVizExt.registerSurfaceShadingColors("temperature", [0xff0000, 0x0000ff]);
 
         /**
-         * Interface for application to decide what is the current value for the heatmap
+         * Interface for application to decide what the current value for the heatmap is.
+         * 
          * @param {string} device device id
          * @param {string} sensorType sensor type
          */

client/pages/Navisworks.jsx

@@ -1,3 +1,7 @@
+/**
+ * This sample illustrates adding Sprite viewables and rendering a heatmap on a NWD file.
+ */
+
 import React, { useEffect, useRef, useState } from "react";
 import { BaseApp } from "forge-dataviz-iot-react-components";
 import DataHelper from "./DataHelper";
@@ -10,7 +14,7 @@ import fan03 from "../../assets/images/fan-03.svg";
 import fan04 from "../../assets/images/fan-04.svg";
 import fan05 from "../../assets/images/fan-04.svg";
 
-import { SpriteSize, SensorStyleDefinitions, PropIdGradientMap, PropertyIconMap } from "../config/SensorStyles.js";
+import { SpriteSize, SensorStyleDefinitions, PropIdGradientMap } from "../config/SensorStyles.js";
 
 const fans = [fan00, fan01, fan02, fan03, fan04, fan05];
 
@@ -53,6 +57,19 @@ const surfaceShadingConfig = {
     gradientSetting: PropIdGradientMap
 };
 
+/**
+ * @memberof Autodesk.DataVisualization.Examples
+ * 
+ * @param {Object} props 
+ * @param {Object} props.appData Data passed to the Navisworks.
+ * @param {("AutodeskStaging"|"AutodeskProduction")} [props.appData.env] Forge API environment
+ * @param {string} props.appData.docUrn Document URN of model
+ * @param {string} props.appData.adapterType Corresponds to Data Adapter used to query data. i.e - synthetic, azure etc.
+ * @param {"derivativeV2"|"derivativeV2_EU"|"modelDerivativeV2"|"fluent"|"D3S"|"D3S_EU"} [props.appData.api] Please refer to LMV documentation for more information.
+ * @param {Object} props.appContext Contains base urls used to query assets, LMV, data etc.
+ * @param {string} [props.appContext.dataUrl] The base url used to configure a specific {@link Autodesk.DataVisualization.Data.DataAdapter}
+ * 
+ */
 function Navisworks(props) {
     const eventBusRef = useRef(new EventBus());
     const [data, setData] = useState(null);
@@ -79,14 +96,10 @@ function Navisworks(props) {
                 devicePanelData,
             };
             setData(dataRef.current);
-
-            return function cleanUp() {
-                eventBusRef.current._listeners = {};
-            };
         });
     }, []);
 
-    eventBusRef.current.addEventListener("VIEWER_DATA_READY", (event) => {
+    eventBusRef.current.addEventListener(EventTypes.VIEWABLES_LOADED, (event) => {
         let { dataVizExtn } = event.data;
 
         let i = 0;

client/pages/ReferenceApp.jsx

@@ -17,6 +17,21 @@ class EventBus { }
 
 THREE.EventDispatcher.prototype.apply(EventBus.prototype);
 
+/**
+ * 
+ * @param {Object} props 
+ * @param {Object} props.appData Data passed to the BaseApp.
+ * @param {("AutodeskStaging"|"AutodeskProduction")} props.appData.env Forge API environment
+ * @param {string} props.appData.docUrn Document URN of model
+ * @param {string} props.appData.adapterType Corresponds to Data Adapter used to query data. i.e - synthetic, azure etc.
+ * @param {"derivativeV2"|"derivativeV2_EU"|"modelDerivativeV2"|"fluent"|"D3S"|"D3S_EU"} [props.appData.api] Please refer to LMV documentation for more information.
+ * @param {string} [props.appData.dataStart] Start date for provided CSV data in ISO string format.
+ * @param {string} [props.appData.dataEnd] End date for provided CSV data in ISO string format.
+ * @param {Object} props.appContext Contains base urls used to query assets, LMV, data etc.
+ * @param {string} [props.appContext.dataUrl] The base url used to configure a specific {@link Autodesk.DataVisualization.Data.DataAdapter}
+ * 
+ * @memberof Autodesk.DataVisualization.Examples
+ */
 function ReferenceApp(props) {
 
     const eventBusRef = useRef(new EventBus());
@@ -60,6 +75,11 @@ function ReferenceApp(props) {
                 // event.hasStopped = true;
             })
 
+            /**
+             * Called when a user has selected a level in the {@link Autodesk.DataVisualization.UI.LevelsTree} or expanded/closed a 
+             * grouping in {@link Autodesk.DataVisualization.UI.DeviceTree}
+             * @param {Event} event 
+             */
             function handleNodeChange(event) {
                 if (levelsExt) {
                     let { selectedNodeId } = appStateRef.current;
@@ -124,10 +144,6 @@ function ReferenceApp(props) {
                 devicePanelData
             };
             setData(dataRef.current);
-
-            return function cleanUp() {
-                eventBusRef.current._listeners = {}
-            }
         });
     }, []);
 
@@ -146,4 +162,4 @@ function ReferenceApp(props) {
     );
 }
 
-module.exports = ReferenceApp;
+module.exports = ReferenceApp;