Common entry points

These are common to all plugins regardless of type.

describePlugin(id, lang)

Provides localized information about the plugin. The parameter id is a string key describing the information needed. The parameter lang is a standard language + country code constant. (Currently lang is always "en-US" because there are no localizations yet.)

Example:

this.describePlugin = function(id, lang) {
  switch (id) {
    case 'displayName':
      return "My Brilliant Plugin";
    case 'shortDisplayText':
      return "This plugin creates anything you can dream of by one click of a button.";
    case 'defaultNameForNewInstance':
      return "brilliant";
  }
}

renderIcon(canvas)

Called by the host application to render an icon for this plugin. The canvas parameter is a Canvas object that implements most of the HTML5 Canvas API.

Note that the size of the canvas is not known in advance, so your code should read "canvas.width" and "canvas.height" and render its content accordingly.

It's possible to load your plugin icon from an image resource and draw that image into the canvas. Example:

this.renderIcon = function(canvas) {
  var ctx = canvas.getContext('2d');
  var w = canvas.width;
  var h = canvas.height;
  ctx.save();
  if (this.icon == null) {
    var path = Plugin.getPathForResource("my_brilliant_plugin_logo.png");
    this.icon = Plugin.loadImage(path);
  }
  var iconW = this.icon.width;
  var iconH = this.icon.height;
  var aspectScale = Math.min(w/iconW, h/iconH);
  var scale = 0.9 * aspectScale; // add some margin around icon
  iconW *= scale;
  iconH *= scale;
  ctx.drawImage(this.icon, (w-iconW)*0.5, (h-iconH)*0.5, iconW, iconH);
  ctx.restore();
};

onCreatePlugin()

Called when the plugin instance is created by the user to the project (e.g. the user drags Element plugin to the editing canvas). It means that onCreatePlugin function will be called only once during the lifetime of the plugin instance.

init()

Called when the plugin instance is loaded. That can be when the user creates the plugin instance (e.g. element or Web service), the project is loaded from disk, etc.

persist()

Allows the plugin to write data that needs to persist when the plugin is saved and loaded from disk. Called when the host application saves the project file.

The return value must be a JavaScript object that can be encoded as JSON.

unpersist(obj)

This is the inverse of persist(). The parameter obj is an object that was previously saved by persist(). Called when the host application opens a project file.

inspectorUIDefinition

This property is used to create the user interface displayed in the host application's inspector panel (the right-hand side of the Neonto Studio interface).

The value must be an array containing objects, each of which describes a specific UI element. These elements will be visually stacked in the inspector view.

To respond to UI actions, elements can provide an "actionBinding" property that links to a function in the plugin's object context.

Following is an example taken from the Camera plugin:

this.inspectorUIDefinition = [
  {
    "type": "label",
    "text": "Store photo to data slot:"
  }, {
    "type": "dataslot-picker",
    "id": "dataSlot",
    "actionBinding": "this.onPickDataSlot"
  }, {
    "type": "label",
    "text": "Photo quality:"
  }, {
    "type": "multibutton",
    "id": "photoQuality",
    "labels": ["Best", "High", "Medium", "Low"],
    "actionBinding": "this.onMultiButtonChange"
  }, {
    "type": "label",
    "text": "Camera facing:"
  }, {
    "type": "multibutton",
    "id": "cameraFacing",
    "labels": ["Back", "Front"],
    "actionBinding": "this.onMultiButtonChange"
  }
];

Supported UI element types include:

  • label
  • textinput
  • checkbox
  • multibutton
  • dataslot-picker

This is not complete list. All UI element types, settings and properties for each type are described later in section 'UI element specifications'.

getInspectorUIDefinitionForContext(actionId)

This is used to create the user interface in the inspector panel similar to inspectorUIDefinition property but for some specific purpose. An example of this is Web Service plugin's Send Data interaction. Web Service plugins can implement custom Send Data action and user interface for it.

Example:

this.getInspectorUIDefinitionForContext = function(uiContext) {
	switch (uiContext) {
		case 'action:sendData':
			return [
			  {
			    "type": "label",
			    "text": "Mailing list id (from Mailchimp):"
			  },
			  {
					"type": "textinput",
					"id": "listId",
			    "actionBinding": "this.onUIChange_sendDataAction"
			  }
			];
	}
}

onCreateUI()

Called after the UI specified by inspectorUIDefinition has been created. This allows the plugin to set values in the newly created UI.

Example:

this.onCreateUI = function() {
  var ui = this.getUI();
  ui.getChildById("dataSlot").dataSlotName = this._data.dataSlotName;
}

Note the use of the getUI() method. This gives access to the UI object representing the entire UI created for this plugin, which then has a method named getChildById() to access a specific element by its id.

onDestroyUI()

Called whenever the plugin's inspector UI is destroyed or re-created.

onDestroyUIForContext()

Same as onDestroyUI() but for context specific inspectors created by getInspectorUIDefinitionForContext method.

__pluginHostId

Used by the host application to determine the type of plugin. Example:

this.__pluginHostId = "com.neonto.studio.projectmap.webservice";

It's good practice to include this property so that the plugin's type can be deduced from its JavaScript file. Supported values are:

  • com.neonto.studio.projectmap.webservice -- Web Service plugin
  • com.neonto.studio.element -- Element plugin
  • com.neonto.studio.element.nonvisual -- Non-visual Element plugin
  • com.neonto.studio.animation -- Animation plugin
  • com.neonto.studio.imageeffect -- Image Effect plugin
  • com.neonto.studio.shape -- Vector Graphics Effect plugin

Note that there is a "nonvisual" subtype for Element plugins. This is useful for plugins that need to be instanced within a specific screen but don't actually provide a visible user interface. (Often these nonvisual elements are controller using actions from other elements.) Examples would be an audio player component, a timer, a number generator, etc.