@vived/app v5.0.2

VIVED App

This package is intended to hold all the common logic used by VIVED Slide Apps.

Use Case

You will need to instantiate the baseAppUC by calling makeBaseAppUC(). Typically this is done in your Main script when everything is starting up.

Functions

getIsAuthoring():boolean

Gets the flag to see if the app is currently in an authoring state

setIsAuthoring(isAuthoring:boolean):void

Sets the is authoring flag. If there is a change this will notify all observers

getShowBabylonInspector():boolean

Gets the flag to see if the babylon inspector should be show

setShowBabylonInspector(showInspector: boolean):void

Sets if the Babylon Inspector should be shown. If there is a change this will notify all observers.

addObserver(observer: BaseAppStateObserver): void;

Adds an observer to the Use Case. The observer will be notified if anything in the use case changes

removeObserver(observer: BaseAppStateObserver): void;

Removes an observer so it will no longer be notified of changes in the Use Case

getSerializedState(): SerializedStates;

Get the current serialized state of the App. See the Serilization section below

setSerializedState(state: SerializedStates): void;

Sets the state of the app to a Serialized State. See the Serilization section below

registerSerializableSystem(serializedSystem: SerializableSystem):void;

Registers a Serializable System. This is likely a system in your App which has states that need to be saved and applied. See the Serilization section below

setHostHandler(handler: Handler):void;

When an App is mounted it is passed the Host Handler. This is the Handler to which the Use Case will dispatch all requests. This needs to be set when the app Main is constructed. See the App - Host Communication section below

hasHostHandler():boolean;

This checks to see if a host handler has been set. This is useful for avoiding nasty errors

dispatchOnStateChange(stateObject: object):void;

When authoring the Host should be notified whenever something in the serializable state has changed. Calling this will let the host know that the state has changed and pass along the new state.

dispatchOnStateComplete():void

Calling this will let the Host know that the user has completed their required task and the Host can move on to the next state.

dispatchSubmitResults(results:object):void;

If a user has completed a task and there are results to submit the app can pass these results to the Host via this call.

dispatchGetAppAssetsURL():string

Many Apps require Assets such as GLBs or images. These are expected to be stored in the public/assets folder (assuming the app was built with Create React App). However once the App has been published, the path to this folder will be different. The Host should know this path so calling this will ask the host for the path to the assets folder.

setDevicePreview(x: number, y: number): void;

At some point the User may opt to view the Activity in a way the previews a specific hardware device. This decision is handled by the host but the App will be notified. This function is used to set the desired x and y resolution

clearDevicePreview():void;

Calling this will clear any preview device resoltions.

getUseDevicePreview(): boolean;

This will return a true if the Host has set a device resolution to preview. Otherwise it will return false

getDevicePreviewSize(): {x: number, y:number}

This will return the requested preview device x and y resolution. If no device has been set or the previewed device has been cleared, these will both be -1.

Observers

If you want to be notified when something changes in the Use Case you will need to create an observer class the implements BaseAppStateObserver and then registers itself with the use case via addObserver. If you observer is getting destroyed it needs to call removeObserver on the Use Case

Serilization

The Serilization system is designed to handle all the heavy lifting of serializing and desrializing the state of your app.

Serializable System

You app will likey have one or my systems that have data which needs to be stored in the state. For each of these systems you are expected to write a class that implements SerializableSystem and then register this class with the Base App Use Case by calling registerSerializableSystem.

This implementation requires your class to setup four items:

Name

This is the name of your system. Not this name must be unique across all the serialized systems in your App. In other words you cannot register two different Serializable Systems with the same name. Also, this name should not be modified down the road is it is how the Use Case will determine what Class to send stored activity data to. This name will never be seen by a user.

Serilization Version

This is an integer that is stored with the data and written into an activity file. This is intended to allow the system state data to be changed over time while giving developers the opportunity to be backwards compatable. For example, lets say after a few months the system is improved to include another statable variable. The devloper would iterate the serilizationVersion from 1 to 2. From now on, any new saved states will be saved with version number 2. When the System is asked to apply some saved state data it can check to see if this state data was version 1 or 2 and handle it appropriatetly.

getSerializedObject():object

The Serilization Use Case will trigger this function when it needs to store the current state. The Class is expected to form up an object however they see fit and return it as a vanilla object.

applySerializedObject(state: object, version: number):void

This function will be called when the Serilization Use Case want to apply a state to a system. It will pass in a vanilla object as well as the serilization version that was set when this object was formed. The Class is expected to handle the versions and apply the object appropriatetly.

App - Host Communication

The boundary between the Host and the App has been intentionally designed to allow the the host and the apps to be completely independent of each other while allowing communication between the two.

Request

All messages passed between the Host and the App are called requests. All Requests are strongly typed and versioned in the @vived/app-host-boundary package.

Dispatcher

When an App needs to send a request to the Host all it needs to do is trigger a dispatch action in the Use Case. This package will take care of correctly forming the Request and sending it to the Host.

Handler

When the Host sends a request to the App it must be handled, which is the responsibility of the App Handler. You app is expected to provide a list of AppHandlerFunctions when it creates the App Handler during the construction of the App. This allows allows the App to unpack the request and then call one of these functions, allowing your App to handle it however it wants.

Presenter Models

Presenter Models are intented to update a view whenenver a something specific changes in the Use Case. The Presenter Model will either pass the View a specific parameter or a View Model of parameters. Ideally the View will be able to just consume the View Model or the parameter without needing any logic or refactoring.

To use Presenter Model your View (or Hook) will need to instantiate the Presenter Model, passing in the baseAppUC and a callback function. The callback function will be triggered when the Presenter Moder is initiated and then whenever an update is available. It is important to call Dispose on the Presetner Model if your view or hook is being destroyed in order to remove it's observer from the Use Case.

DevicePreviewPM

This PM will update it's view whenever something with the Device Preview changes. It returns a View Model with the following parameters

• isPreviewingDevice: a boolean letting you know if the render canvas should be scaled
• x: is the pixel width to scale to if isPreviewingDevice. This will be -1 if there is no device to preview
• y: is the pixel height to scale to if isPreviewingDevice. This will be -1 if there is no device

IsAuthoringPM

This PM will update the view whenever the Is Authoring flag changes, passing back the current isAuthor value.

ShowBabylonInspectorPM

This PM will update the view whenever the Show Babylon Inspector flag changes, passing back the current value.

Controllers

defaultAppHandlerFunctions

The function creates all the default app handler functions. These include:

• showBabylonInspector: (show: boolean) => void;
• setIsAuthoring: (isAuthoring: boolean) => void;
• disposeApp: () => void;
• stopApp: () => void;
• startApp: (container: HTMLElement) => void;
• setState: (finalState: string, duration?: number) => void;
• setDevicePreview: (x: number, y: number) => void;

Your App will likely need to handle one or more of these functions differently so the intent is that you use this function to create all the default functions and then replace the appropriate functions with your custom function before creating the App Handler

dispatchStateChange()

This function is created with the factory makeDispatchStateChange. It first gets the latest serialized state and then dispatches that state to the Host

makeAppHandler(functions: AppHandlerFunctions): Handler

This function is used to create the App Handler. It takes in the App Handler Functions and returns a generic Handler, which is passed to the Host. The host can then dispatch a request to this Handler. The App Handler is responsible for reading the request and triggering the appropriate App Handler Function

setDevicePreview(x: number, y: number)

This function is created with the makeSetDevicePreview factory. If either x or y are negative this function will clear the selected device in the baseAppUC. Otherwise it will set the x and y value of the selected device in the Use Case.

setIsAuthoring(isAuthoring: boolean)

This function is created with the makeSetIsAuthoring factory and will apply the isAuthoring flag to the use case. It will also dispatch a state change if the is Authorin is set to true. This allows the Host to know the initial state when the user start authoring.

setState(state: string, duration?: number)

This function is created with the makeSetState facory. It is responsible for recieving a desired state from the Host and applying it locally. You will note that the setState function in this package does not use the duration parameter. This function simply sets the state hard, without any transition. You App will probably what to implement it's own setState function that support nice interpolations for your systems.

showBabylonInspector(showInspector:boolean)

This function is created with the makeShowBabylonInspector factory. It will set the show babylon inspector flag in the Use Case.

startApp(container: HTMLElement)

This function is created with the makeStartApp factory. It is reponsible for starting up all the renderings of the App. This could include the App's react components as well as the Babylon Engine.

stopApp()

This function is created with the makeStopApp factory. It is reponsible for stopping up all the renderings of the App. This could include the App's react components as well as the Babylon Engine. It also ensures that the isAuthoring flag is set to false.