Implementation of URL parameter linking to history

Author: bgoldowsky

README.md

@@ -162,6 +162,7 @@ There are a number of URL parameters that can aid in testing:
 |`noPersistentUI`|none                     |Do not initialize persistent ui store.|
 |`researcher`    |`true`                   |When set to true the user authenticates as a researcher|
 |`studentDocument`|string                  |If set to the ID of a document, this will be displayed as the left-side content.|
+|`studentDocumentHistoryId`|string         |Open the history slider and move to the specified revision in the `studentDocument`.|
 
 The `unit` parameter can be in 3 forms:
 

docs/firestore-schema.md

@@ -75,6 +75,12 @@ Fields:
 
 ### Contents of `documents/{docId}`
 
+Holds metadata, history, and comments related to a user Document.
+(The actual current Document content is not stored here, it is in Firebase.)
+Note that there can be multiple Firestore records for a single Document,
+with different networks. These are needed to hold comments that can only
+be read by members of the network of their authors.
+
 Fields:
 
 - key: (string, the id of the document in firebase)

src/components/document/canvas.tsx

@@ -47,6 +47,7 @@ interface IState {
   documentScrollY: number;
   historyDocumentCopy?: DocumentModelType;
   showPlaybackControls: boolean;
+  requestedHistoryId: string | undefined;
 }
 
 @inject("stores")
@@ -80,11 +81,27 @@ export class CanvasComponent extends BaseComponent<IProps, IState> {
       documentScrollX: 0,
       documentScrollY: 0,
       showPlaybackControls: false,
+      requestedHistoryId: undefined,
     };
 
     this.canvasMethods = { cacheObjectBoundingBox: this.cacheObjectBoundingBox };
   }
 
+  componentDidMount(): void {
+    // If there is a request to show this document at a point in its history, show the history slider.
+    if (this.props.showPlayback && this.props.document?.key) {
+      const request = this.stores.sortedDocuments.getDocumentHistoryViewRequest(this.props.document?.key);
+      if (request) {
+        this.setState((prevState, props) => {
+          return {
+            ...this.updateHistoryDocument(prevState, true),
+            requestedHistoryId: request
+          };
+        });
+      }
+    }
+  }
+
   private fallbackRender = ({ error, resetErrorBoundary }: FallbackProps) => {
     return (
       <DocumentError
@@ -205,6 +222,7 @@ export class CanvasComponent extends BaseComponent<IProps, IState> {
               document={documentToShow}
               showPlaybackControls={showPlaybackControls}
               onTogglePlaybackControls={this.handleTogglePlaybackControlComponent}
+              requestedHistoryId={this.state.requestedHistoryId}
             />
           )}
         </>

src/components/playback/playback.tsx

@@ -1,9 +1,9 @@
-import React from "react";
+import React, { useEffect } from "react";
 import { Instance } from "mobx-state-tree";
 import { observer } from "mobx-react";
 import classNames from "classnames";
 import { usePersistentUIStore } from "../../hooks/use-stores";
-import { HistoryStatus, TreeManager } from "../../models/history//tree-manager";
+import { HistoryStatus, TreeManager } from "../../models/history/tree-manager";
 import { DocumentModelType } from "../../models/document/document";
 import { PlaybackControlComponent } from "./playback-control";
 import PlaybackIcon from "../../clue/assets/icons/playback/playback-icon.svg";
@@ -14,13 +14,20 @@ interface IProps {
   document: DocumentModelType | undefined;
   showPlaybackControls: boolean | undefined;
   onTogglePlaybackControls: (() => void) | undefined;
+  requestedHistoryId: string | undefined;
 }
 
 export const PlaybackComponent: React.FC<IProps> = observer((props: IProps) => {
   const { document, showPlaybackControls, onTogglePlaybackControls  } = props;
   const { activeNavTab } = usePersistentUIStore();
   const treeManager = document?.treeManagerAPI as Instance<typeof TreeManager>;
 
+  useEffect(() => {
+    if (props.requestedHistoryId) {
+      treeManager.moveToHistoryEntryAfterLoad(props.requestedHistoryId);
+    }
+  }, [props.requestedHistoryId, treeManager]);
+
   const renderPlaybackToolbarButton = () => {
     const playbackToolbarButtonComponentStyle =
       classNames("playback-toolbar-button-component", {"disabled" : false},

src/initialize-app.tsx

@@ -70,7 +70,8 @@ export const initializeApp = (authoring: boolean): IStores => {
 
   const appConfig = AppConfigModel.create(appConfigSnapshot);
   const stores = createStores(
-    { appMode, appVersion, appConfig, user, showDemoCreator, demoName, documentToDisplay: urlParams.studentDocument });
+    { appMode, appVersion, appConfig, user, showDemoCreator, demoName,
+      documentToDisplay: urlParams.studentDocument, documentHistoryId: urlParams.studentDocumentHistoryId });
 
   // Expose the stores if the debug flag is set or we are running in Cypress
   const aWindow = window as any;

src/models/history/tree-manager.ts

@@ -1,6 +1,7 @@
 import {
   types, Instance, flow, IJsonPatch, detach, destroy, getSnapshot, toGenerator, addDisposer
 } from "mobx-state-tree";
+import { when } from "mobx";
 import firebase from "firebase/app";
 import { nanoid } from "nanoid";
 import { TreeAPI } from "./tree-api";
@@ -93,6 +94,10 @@ export const TreeManager = types
     return self.document.history.find(entry => entry.id === historyEntryId);
   },
 
+  findHistoryEntryIndex(historyEntryId: string) {
+    return self.document.history.findIndex(entry => entry.id === historyEntryId);
+  },
+
   findActiveHistoryEntry(historyEntryId: string) {
     return self.activeHistoryEntries.find(entry => entry.id === historyEntryId);
   },
@@ -586,6 +591,17 @@ export const TreeManager = types
     self.numHistoryEventsApplied = newHistoryPosition;
   })
 }))
+.actions((self) => ({
+  async moveToHistoryEntryAfterLoad(historyId: string) {
+    await when(() => self.historyStatus === HistoryStatus.HISTORY_LOADED);
+    const entry = self.findHistoryEntryIndex(historyId);
+    if (entry >= 0) {
+      self.goToHistoryEntry(entry);
+    } else {
+      console.warn("Did not find history entry with id: ", historyId);
+    }
+  }
+}))
 .views(self => ({
   getHistoryEntry: (historyIndex: number) => {
     return self.document.history.at(historyIndex);

src/models/stores/sorted-documents.ts

@@ -1,4 +1,4 @@
-import { autorun, makeAutoObservable, runInAction } from "mobx";
+import { makeAutoObservable, runInAction, when } from "mobx";
 import { types, Instance, SnapshotIn, applySnapshot, typecheck, unprotect } from "mobx-state-tree";
 import { union } from "lodash";
 import firebase from "firebase";
@@ -80,6 +80,8 @@ export class SortedDocuments {
   metadataDocsFiltered = MetadataDocMapModel.create();
   metadataDocsWithoutUnit = MetadataDocMapModel.create();
   docsReceived = false;
+  // Maps from document ID to the history entry ID that the user requested to view.
+  documentHistoryViewRequests: Record<string,string> = {};
 
   constructor(stores: ISortedDocumentsStores) {
     makeAutoObservable(this);
@@ -117,6 +119,20 @@ export class SortedDocuments {
     return this.stores.user;
   }
 
+  setDocumentHistoryViewRequest(docKey: string, historyId: string) {
+    this.documentHistoryViewRequests[docKey] = historyId;
+    console.log("setDocumentHistoryViewRequest", docKey, historyId);
+  }
+  getDocumentHistoryViewRequest(docKey: string) {
+    // We only want to move to this history entry once,
+    // so we delete the request after it has been fulfilled.
+    const historyId = this.documentHistoryViewRequests[docKey];
+    if (historyId) {
+      delete this.documentHistoryViewRequests[docKey];
+    }
+    return historyId;
+  }
+
   sortBy(sortType: PrimarySortType): DocumentGroup[] {
     switch (sortType) {
       case "Group":
@@ -356,15 +372,8 @@ export class SortedDocuments {
 
   async fetchFullDocument(docKey: string) {
     if (!this.docsReceived) {
-      // Wait until the initial documents have been received before trying to open a document.
-      await new Promise<void>(resolve => {
-        const disposer = autorun(() => {
-          if (this.docsReceived) {
-            disposer();
-            resolve();
-          }
-        });
-      });
+      // Wait until the initial batch of documents has been received from Firestore.
+      await when(() => this.docsReceived);
     }
     const metadataDoc = this.firestoreMetadataDocs.find(doc => doc.key === docKey);
     if (!metadataDoc) {

src/models/stores/stores.ts

@@ -43,6 +43,7 @@ export interface IStores extends IBaseStores {
   userContextProvider: UserContextProvider;
   tabsToDisplay: NavTabModelType[];
   documentToDisplay?: string;
+  documentHistoryId?: string;
   isShowingTeacherContent: boolean;
   studentWorkTabSelectedGroupId: string | undefined;
   setAppMode: (appMode: AppMode) => void;
@@ -169,6 +170,10 @@ class Stores implements IStores{
     if (docToDisplay) {
       // Make sure there is a Sort Work tab to display the document in.
       this.appConfig.setRequireSortWorkTab(true);
+      // Set request for viewing at the given history ID, if provided
+      if (params.documentHistoryId) {
+        this.sortedDocuments.setDocumentHistoryViewRequest(docToDisplay, params.documentHistoryId);
+      }
       // Wait until the document is loaded, then open it.
       const docPromise = this.sortedDocuments.fetchFullDocument(docToDisplay);
       docPromise.then((doc) => {

src/utilities/url-params.ts

@@ -46,8 +46,9 @@ export interface QueryParams {
   reportType?: string;
   // set to string "true" to authenticate as a researcher
   researcher?: string;
-  // display a certain student document
+  // display a certain student document, optionally at a point in its history
   studentDocument?: string;
+  studentDocumentHistoryId?: string
 
   //
   // demo features