A concise interface is provided to help control other dizmos, especially controlling them using the Navigator. The interface consists of several tree nodes in dizmos and a library to provide a helper layer for developers to use. The library is optional, although strongly encouraged. If something on the underlying tree nodes changes, the library, towards the outside, allows the continued usage without any code changes.
The mechanism uses steps and simplified total steps to provide a way of controlling a dizmo. The developer then needs only to use the helper function to control the dizmo, and allow another dizmo at the same time to control it too. Most race conditions are accounted for through this unified interface.
For example, if a user has several images in a dizmo that can be moved through by another dizmo, the developer would assign a step (from 1 to the maximum amount of images) to each image and then use the helper libraries functions to listen for when a new image should be displayed. To make this work properly, the developer should also use the Controller class to control the dizmo, which means using the setter calls to skip between images and using the callbacks to listen to those steps.
The helper library provides two main entry points: DizmoHelper.Controller and DizmoHelper.RemoteController. dizmoViewer can provide both libraries, and your HTML file does not have to include them. To load them, add the following key to your package.json file:
"settings": {
"helper_version" : "1.0"
}The controller class provides a singleton to be used by a dizmo that can be controlled by other dizmos (for example the Navigator dizmo). To use this class, call DizmoHelper.Controller.init() once. You can then provide several callbacks to the class. The calls are then called when certain events happen.
If you want to stop using the class while the dizmo is running, you can issue a call to DizmoHelper.Controller.deinit() which stops the event handlers from being fired and reset the values to the defaults.
If a function is unavailable or an invalid value entered, an error is thrown. The error is thrown mainly because another dizmo needs the values to be set adequately, to be able to control this dizmo. Thus, values and functions are enforced in the DizmoHelper.Controller to avoid confusion and configurations that do not work.
A call to this function is mandatory if you want to use the library. Initialize the class with default values and start listening on changes. To represent that no steps are available in this dizmo, the class starts with a step of 0 and total steps of 0. The global timer and animation flag are also set to false.
De-initializes the class, resets the values to the defaults and prevents events from being fired. If you want to use the class again, a call to DizmoHelper.Controller.init() has to be made.
All the step callbacks receive the current step and the old step as parameters. It is generally advised to use the positional callbacks: DizmoHelper.Controller.onFirstStep, DizmoHelper.Controller.onPreviousStep, DizmoHelper.Controller.onNextStep, DizmoHelper.Controller.onLastStep and not the general DizmoHelper.Controller.onStep.
The callback provided to this function is invoked whenever a step has occurred. This callback does not provide a direction, meaning that if it was the previous or next step, last or first, is not counted. Use the respective positional callbacks to get a more accurate callback.
A callback that is invoked whenever the first step in the dizmo is reached.
A callback that is invoked when the previous step (i.e., one step before the old one) has been reached. This is not called when reaching the first step. In that case DizmoHelper.Controller.onFirstStep is called instead.
A callback that is invoked when the next step (i.e., one higher than the old one) has been reached. The callback is not called when reaching the last step. In that case, DizmoHelper.Controller.onLastStep is called instead.
A callback that is invoked whenever the last step in the dizmo is reached.
Set the total steps available in this dizmo. Negative numbers are not allowed here. A step of 0 or 1 means that the dizmo should be treated as if it has no steps.
Set the current step. This function only accepts a range between 1 and the total steps set through DizmoHelper.Controller.setTotalSteps. If the total steps are 0 or 1, this function will not accept any value. To control the dizmo effectively, please use the positional calls DizmoHelper.Controller.firstStep, DizmoHelper.Controller.previousStep, DizmoHelper.Controller.nextStep and DizmoHelper.Controller.lastStep.
Jump to the first step in the dizmo. Is unavailable if total steps are 0 or 1.
Jump to the previous step. If the first step is reached and this function is called, the function jumps back to the first step, meaning that no event is fired. This function is unavailable if the total steps are 0 or 1.
Jump to the next step. If the last step is reached and this function is called, it jumps back to the last step, meaning no event is fired. This function is unavailable if the total steps are 0 or 1.
Jump to the last step in the dizmo. This function is unavailable if total steps are 0 or 1.
Return the total steps available in this dizmo.
Return the current step.
When an animation has started to tell listening dizmos to not move to another step, this function should be called.
Should be called once an animation has finished. Thus, listening dizmos know that the next step can be done.
Enable the usage of a global timer.
Disable the usage of a global timer.
Should be called when the timer for this dizmo has started.
Should be called when the timer for this dizmo has stopped.
This class is used by the Navigator to control another dizmo that uses the DizmoHelper.Controller class, or adheres to its standards in regards to tree nodes.
This class requires a dizmo identifier with the dizmo to control. After that, it provides similar functions as the DizmoHelper.Controller class.
This class does not throw errors if a function is unavailable. Instead, it swallows the command and ignores it. As a controlling dizmo needs other dizmos to behave correctly, we don’t want to break the controlling dizmo just because a to be-controlled dizmo is not behaving correctly.
The class still throws errors if a value is entered wrong.
The constructor receives a parameter object that must contain a dizmo instance referring to the dizmo that should be controlled: {dizmo: dizmoinstace}. The three callbacks onAnimationStarted, onTimerStarted, onTimerStopped also have to be provided through the configuration object, but are not required.
DizmoHelper.RemoteController({
dizmo: someDizmoInstance,
onAnimationStarted: function() {},
onAnimationStopped: function() {},
onTimerStarted: function() {},
onTimerStopped: function()
})Set the step to an arbitrary number. If total steps are set to 0 or 1, this function will be unavailable. It is also advised to use the directional functions DizmoHelper.RemoteController.firstStep, DizmoHelper.RemoteController.previousStep, DizmoHelper.RemoteController.nextStep and DizmoHelper.RemoteController.lastStep to control the dizmo.
Go to the first step in the remotely controlled dizmo. The function is unavailable if the total steps of the remotely controlled dizmo are 0 or 1.
Go to the previous step in the remotely controlled dizmo. The function is unavailable if the total steps of the remotely controlled dizmo are 0 or 1.
Go to the next step in the remotely controlled dizmo. The function is unavailable if the total steps of the remotely controlled dizmo are 0 or 1
Go to the last step in the remotely controlled dizmo. The function is unavailable if the total steps of the remotely controlled dizmo are 0 or 1
Returns the current step of the controlled dizmo as a number.
Returns the total steps of the controlled dizmo as a number.
If the timer is enabled in the controlled dizmo. You do not have to worry about timers if this is set to false.
As mentioned above, one does not have to use this helper class to make use of the functionality provided through it (although it is strongly recommended). To control a dizmo from somewhere else, all that is needed are the following 5 tree nodes that reside in the public tree. If a dizmo uses this interface to control itself, it can easily be controlled by any other dizmo accessing this interface.
public/controller/animationRunning // Will be set to true if an animation in the dizmo is running
public/controller/step // The current step the dizmo is on (or should be on)
public/controller/totalSteps // The total steps available in the dizmo
public/controller/timerRunning // Will be set to true/false if a timer is running
public/controller/timerEnabled // Will be set to true/false if a timer is available (enabled)