ShapeDiver Viewer - Plugin API
The plugin interface is part of the global API.
It allows to
- get the status of currently registered plugin instances, and
- register and deregister plugin instances.
Methods
-
deregisterPluginAsync(id)
-
Deregister a plugin
Parameters:
Name Type Description id
String runtime id of the plugin to deregister
Returns:
-
Type Description Promise.<APIResponse> API response with data of type PluginStatusDescription for the plugin deregister.
-
-
get()
-
Retrieve the current state of plugins
Returns:
-
Type Description APIResponse API response with a data array of type PluginStatusDescription. Description of the current state of all plugins currently known to the viewer. Plugins may be asked for their status individually using their getStatus() method.
-
-
refreshPluginAsync(id [, payload])
-
Refresh the outputs of a plugin by calling its set*ParameterValues function for the current values of its parameters.
Use this to initially load geometry if the plugin was created using 'deferGeometryLoading' set to true.
Parameters:
Name Type Argument Description id
String runtime id of the plugin whose outputs should be refreshed
payload
* <optional>
Payload which will be passed through to the response and events related to a call of this function
Returns:
-
Type Description Promise.<APIResponse> APIResponse with a data array of ParameterUpdateObject objects, corresponding to the parameter state of the plugin.
-
-
registerCommPluginAsync(settings)
-
Create and register a new instance of the ShapeDiver Communication Plugin
Loads the plugin and returns once the plugin attains plugin status ACTIVE or FAILED. Unless the plugin's setting deferGeometryLoading is true, the plugin will be asked to display geometry for default parameter values.
Parameters:
Name Type Description settings
Object Settings to use for creating the CommPlugin instance
Properties
Name Type Argument Default Description ticket
String The ticket defining the model and other attributes of the session
authorization
String <optional>
'' optional authorization token to include with requests to the model view interface (prepend 'Bearer ' yourself if necessary)
ignoreSuperseded
Boolean <optional>
true If truthy ignore intermediate solutions which at the time of their arrival have already been superseded by another customization request. Caution: In case of continuously repeated customization requests this may lead to the scene never being updated.
deferGeometryLoading
Boolean <optional>
Initialise the session but do not load geometry for default parameter values (wait for parameter update)
modelViewUrl
String <optional>
'https://model-view.shapediver.com:443' The model view interface url
runtimeId
String <optional>
Optional runtime id, if none is provided one will be created automatically, must be unique, used for identifying parameters with the same id across multiple plugins
ajaxTimeout
Number <optional>
30000 Timeout in milliseconds for ajax requests
loggingLevel
Number <optional>
Initial logging level - will be overridden once plugin gets registered, hence this is rarely used
messageLoggingLevel
Number <optional>
Initial message logging level - will be overridden once plugin gets registered, hence this is rarely used
Returns:
-
Type Description Promise.<APIResponse> API response with data of type PluginStatusDescription for the newly registered plugin.
-
-
registerPluginAsync(plugin)
-
Register a plugin
Loads the plugin and returns once the plugin attains plugin status ACTIVE or FAILED. Unless the plugin's setting deferGeometryLoading is true, the plugin will be asked to display geometry for default parameter values.
Parameters:
Name Type Description plugin
Object The plugin to register
Returns:
-
Type Description Promise.<APIResponse> API response with data of type PluginStatusDescription for the plugin to register.
-
-
saveDefaultParameterValuesAsync( [id])
-
Save default parameter values for one or all plugins, using the current state of parameter values.
This will fail if the plugin does not provide the capability to store model settings. Instances of the CommPlugin provide this capability in case the model view session allows this.
Be aware of the following: In case multiple instances of the CommPlugin using the same model are registered, and you call this function without specifying a plugin runtime id, it is undefined which state will get stored.
Parameters:
Name Type Argument Description id
String | Array.<String> <optional>
runtime id(s) of the plugin(s) for which default parameter values should be stored, leave this undefined to store default parameter values for all plugin which provide the required capability
Returns:
-
Type Description Promise.<APIResponse> APIResponse whose data property will be true or false depending on success.
-
Members
-
<readonly> STATUS :PluginStatus
-
Enum for plugin status.
Type:
Properties:
Name Type Default Description NONE
PluginStatus none the plugin instance was created, a unique runtime id is not available yet
READY
PluginStatus ready the plugin instance got a unique runtime id and is ready to load
FAILED
PluginStatus failed the plugin instance failed for whatever reason and is not usable
LOADED
PluginStatus loaded the plugin instance successfully loaded, any potential initialization is not yet finished
ACTIVE
PluginStatus active plugin is operating, i.e. any potential initialization that was triggered by loading succeeded, ready to receive parameter updates
UNLOADED
PluginStatus unloaded plugin was unloaded and is ready to be garbage collected
Type Definitions
-
PluginStatus
-
Plugin status type, see STATUS for values
Type:
- Number
-
PluginStatusDescription
-
Plugin state description
Type:
- Object
Properties:
Name Type Description id
String runtime id of the plugin instance
status
PluginStatus status of the plugin instance
name
String name of the plugin
shortName
String short name of the plugin