krpano provides a small and simple interface for developing own plugins.
A plugin can be either a 'code-only' plugin that extends krpano with additional functionality
or controls krpano and / or it can be a 'graphical-plugin' which shows or does something on the screen.
An unloadplugin function - when the plugin will be removed from krpano,
then this function will be called. Here all elements and events that the plugin has added should be removed.
And optionally an onresize function to allow the plugin reacting on size changes of the plugin element.
The plugin itself can add custom functions or attributes to krpano just by adding / setting them
directly to the krpano object or to the plugin object. For custom attributes that can be set from the xml
there is additionally the registerattribute function - it allows adding an
attribute with a default value while keeping the value from the xml.
And the registerattribute function can be used to add setter/getter attributes -
this are attributes which will cause automatically calling a get or set function when accessing the variable -
this can be used to get notified when an attribute will been changed.
Special tools for compiling or building are not necessary, but to reduce the filesize of the final plugin file
Good tools for that are the Google Closure Compiler,
the YUI Compressor or other similar tools.
Both of the above tools can be used offline, but there are also online tools available:
These are the interface functions of the plugin that will be called from krpano.
In Flash/Actionscript3 these functions must be public functions of the startup Flash object.
The onresize() function will be called when the plugin will be resized.
The parameters width and height are the new size in pixels.
Here the plugin can adjust or resize own graphical content.
The onresize() function can optionally return a Boolean value - when it returns true then krpano will try
to scale the plugin automatically, when false will be returned then krpano will not scale the plugin.
The 'krpano' object (the 'krpanointerface' parameter in the registerplugin call)
is the direct interface to krpano. It provides direct access to the whole krpano structure and all functions there.
All mapped xml nodes, arrays, objects and attributes can be accessed directly with it.
Additionally it provides some functions for data access, action-code calling/executing and more - see below.
Call action code to the krpano actions code.
When the action system is currently not blocked, then the given actions will be directly executed.
actionscode = a String with one or more krpano actions.
callerobject(optionally) = the object that was calling the actions
(e.g. the plugin object itself).
This allowes direct access to the object attributes in the actions code, e.g. just set(x,1) instead of set(plugin[name].x,1).
loadImage() - request to load a file as Flash Loader Object (only image/flash files).
Additional to normal files these functions also allow to load embedded and encrypted files. They will be decrypted automatically during loading.
donecallback and errorcallback - these functions will be called when the loading was successfully or has failed.
The usage of the errorcallback is optionally.
Both functions will be called with an Object as parameter, this object has these attributes:
The request url that was used on the loadFile / loadImage call.
The full url of the file - parsed and resolved.
The Flash Loader Object of the loaded image (loadImage only).
A boolean flag with the default value 'true' that indicates if krpano should show an automatic loading error message.
Only for usage in the errorcallback function! Set it to 'false' to disable the default loading error message.
The 'plugin' object (the 'pluginobject' parameter in the registerplugin call)
it the internal representation of the xml <plugin> element.
All plugin attriutes and actions are directly accessible by it.
Special plugin-related attributes of the 'plugin' object:
A special attribute to allow the plugin providing a HTML5 video object for rendering.
The krpano viewer will use that video object for rendering when using the plugin as hotspots
or as pano image (via url="plugin:video").
Setup: videowidth and videoheight attributes with the size of the video need to be added to plugin object,
and once the video is ready for rendering the onvideoreadyCB function of the plugin be called.
For all details please see the example source code of the videoplayer plugin.
Special usage: with some tricks it's also possible to use a HTML5 canvas object
as video source. Use the canvas as videoDOM and add these 'faked'
properties to it: readyState=4, videoWidth=canvas.width, currentTime=time or frame number (should change when the content changes).
Special plugin-related functions of the 'plugin' object:
All krpano mapped-xml-nodes, objects or array-elements and also the krpano Interface Object are derived from a krpano 'Base' object.
The 'base' object has some basic functions for adding / registering new attributes and for creating sub array structures.
Adds a new attribute to the object and sets it the given default value.
When the object already has that attribute (e.g. from xml) then the current value will be kept but the
type of the attribute will be converted to the type of the default value.
The automatic type conversion will work for 'Number' and 'Boolean' datatypes.
For example: When the attribute was set in the xml file to "123" then the type of the attribute is a 'String',
but when registering that attribute with a 'Number' default value, then the attribute will be also converted to 'Number' with the Value 123.
Setter / Getter(optionally)
Optionally it's possible to use setter and getter functions instead of a normal attribute.
In this case when the attribute will be set from xml or via the set interface then the setter function with the new value will be called,
and when the value of the attribute will be read then the getter function will be called to return the value (Note - the setter/getter functions
will need to store the value anywhere in this case).
In Actionscript the setter/getter are special objects. Accessing them direct like normal variables/attributes is not possible
because the Actionscript language doesn't have/support dynamic setter/getters.
For accessing the value these objects have a set(value) function for setting the new value
and a get() function for getting the value.
Notes about setter / getters:
Setter and getters are a very powerful instrument for building data structures.
They can be used to get informed anytime when the value of an attribute will be changed / updated.
With them it possible to check and if necessary correct the value on setting.
And/or to set flags and call other functions when the value will be changed.
An array will be automatically created when a node in the xml has a 'name' attribute or when
a variable with a 'array path' like 'arrayname[itenname].variable' will be set.
The items of the arrays are derived from krpano 'Base' objects and have additional attributes
for name and index.
Beside of that, these objects can store any kind of attributes or functions, also additional krpano arrays.