You are reading the documentation for the version 2 of the ShapeDiver viewer API. Free support for this viewer version will be discontinued on June 1st, 2024.

Please refer to the version 3 documentation here. See also the migration guide from version 2 to version 3 here.

Interface: ApiPluginInterface

api.plugins

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

ShapeDiver 3D Viewer, Copyright © 2015-2019 ShapeDiver GmbH. Documentation generated by JSDoc 3.6.3 on Thu Feb 13th 2020 using the DocStrap template.