Plugin description file documentation (plug info.xml)

Panotour - Notions - Google Maps API > Panotour - Notions - Tour Languages > What is a Panotour plugin? > How to create a Panotour plugin > Plugin description file documentation (plug info.xml)

This XML file contains all that describes your plugin.

The structure of this file is the following :

<plugin>
	<templates/>
	<parameters/>
	<resources/>
	<libraries/>
	<depends/>
	<actions/>
</plugin>

Plugin root node

This main node describes the plugin, its ID, its purpose, its author, etc...

<plugin id="johnDoe-myFirstPlugin" 
        category="tr:Menu"
        categoryIcon="myCategoryIcon.png"
        name="tr:My Plugin Name" 
        version="1.0" 
        isGraphical="true" 
        multipleInstance="false" 
        description="tr:A short description of what the plugin does" 
        author="John Doe"
        authorUrl="http://www.myCompany.com"
       VRCompatible="false">

• id :

This parameter identifies the plugin. This ID must absolutely be unique, so be wordy if needed.
If 2 plugins have identical IDs, only the last plugin found with the ID will be used.
Do not hesitate to be verbose. Use your name as a prefix for example.

• category :

This parameter will be used in Panotour Pro to classify the plugin under categories nodes.
If the category you've set is unknown by PTP, it will create a new one, so you can create your own category.
If you want to classify your plugin in a category already existing in Kolor's plugins, then use one of the already existing values :

category="tr:Menu"
category="tr:Controls"
category="tr:Control Bar"
category="tr:Viewers"
category="tr:Image zone"
category="tr:Text zone"
category="tr:Maps"

The "tr:" prefix indicates that the name of the category will be translated in the language used to display Panotour. The english following string will be used as a key to find the translated string.

• categoryIcon :

Icon used to display the category in Panotour Pro.
This parameter is optional.
If the category is one of the Kolor's plugin. This attribute will not be used.
If there are multiple plugins with the same category, the icon used will be the one described in the first plugin.

• name :

The name of the plugin.
As this name will be used in PTP to display the plugin, it will be easier to find it in PTP if this name is unique.

• description :

The description of the plugin.
This description will be displayed in the plugin selector area in Panotour.

• version :

The version of your plugin.
This attribute will be used by an update manager to notify PTP users when a new version of this plugin is available.

• isGraphical :

Tells to PTP if your plugin is a graphical one or not.
Use a boolean true or false to fill this one.

• multipleInstance :

Tells to PTP if your plugin can be added multiple time in a tour.
By default, a plugin is a single instance one.
Use a boolean true or false to fill this one.

• author :

Name of the author of the plugin.

• authorUrl :

Website URL of the author of the plugin.

• VRCompatible :

Tells to PTP if your plugin is available in VR mode

Templates node

This node is the only mandatory node of the plugin.
It contains the template of the code that Panotour will print as output in your myTour_skin.xml
A plugin without any resources, and any parameters, may not need any other nodes in this file.

<templates>
	<template url="myFirstPlugin.tmpl" />
</templates>

• url :

File name or relative path of the template (relative to my plugin directory). The name of your template file must absolutely be unique, so be wordy if needed.

• type :

The type of your template define where you want it to be printed.
Here are the possible values :

       krpano : this is the default value, your template will be printed in myTour_skin.xml
       html : your template will be printed in 'myTour.html', just under the tourDIV node.

• tourTypes :

The tour type define the kind of build your template will be used for.
If you leave this property undefined, PTP will use your template for every tour types.
Here are the possible values :

       flash : your template will be used only for a flash build and flash krpano viewer.
       html5 : your template will be used only for a html5 build and html5 krpano viewer.

• conditionalParam :

Conditional parameter gives you the possibility to include a template according to a user choice in your plugin PTP UI.
You have to set the id of the UI component you want to check.

• conditionalValues :

Conditional values are the values that will validate the conditional param.

Parameters node

The parameters node describe the user interface of your plugin in Panotour.
Panotour Pro will display interface widgets according to the tags declared in this parameters node.
Several tags are available, a wiki page is dedicated to the documentation of these tags :
Parameters tags documentation (plug_info.xml)

Resources node

This node contains the path of each resource file needed by the plugin.
This could be graphic assets or any other kind of file you need.

<resources>
	<file url="thumb.png" />
	<file url="footer.png" color="myThemeColor" baseColor="#eeeeee" />
	<file url="btn_drag_to.png" color="myThemeColor" baseColor="#eeeeee" conditionalParam="mousecontrol"  conditionalValues="true" />
	<file url="btn_move_to.png" color="myThemeColor" baseColor="#eeeeee" conditionalParam="mousecontrol"  conditionalValues="true" />
	<file url="btn_gyroscope.png" color="myThemeColor" baseColor="#eeeeee" conditionalParam="gyro" conditionalValues="true" tourTypes="html5" />
</resources>

• url :

File path / name of the resource relative to your plugin directory.
This file will be automatically copied in the tour output plugin directory.

• color :

If the resource is an image file, and if this image should be colorized with a color selected by the user, then use the color attribute to identifies the color parameter to use to colorize it.

• baseColor :

Base color of the original color-able resource file. It is used by the colorizing algorithm to ensure that the final color will be as close as possible to the color selected by the user.

• conditionalParam :

ID of a plugin parameter which values are checked to copy or not the resource in the tour. This attribute has to be used with conditionalValues one.

• conditionalValues :

Values of the conditionalParam parameters for which the resource if available.
This attribute can be a single value (true, or false for a bool parameter for example), or a comma separated list (case of a select parameter)

• tourTypes :

If used, then the resource will be copied in the tour only if the generated tour is one of the listed types.
In the previous example, the btn_gyroscope.png file will be copied only if the user wants to create a HTML5 compatible tour, and if the gyro parameter is true.

Libraries node

This node describes all the libraries or files used by the plugin that may be also used by other plugins. All the files described here will be copied only once in the tour. krpano plugins used by the plugin have to be set here.

<libraries>
	<file url="KOLORRES:combobox.js"  tourTypes="html5" />
	<file url="KOLORRES:combobox.swf" tourTypes="flash" />
</libraries>

<libraries>
	<file url="KolorBox" />
</libraries>

• url :

File name or Library directory to be copied in tour.
As Panotour Pro embeds a krpano version, if the plugin is using a krpano plugin, you have to prefix the file name by "KOLORRES:" to be sure to use the version of the krpano plugin corresponding to the version of the player used by Panotour Pro.

• tourTypes :

If used, then the library will be copied in the tour only if the generated tour is one of the listed types.
In the previous example, the combobox.js file will be copied only if the user wants to create a HTML5 compatible tour. Both file "combobox.js" and "combobox.swf" will be copied if the user wants to create a tour compatible with flash and HTML5.

• conditionalParam :

ID of a plugin parameter which values are checked to copy the library files in the tour. This attribute has to be used with conditionalValues one.

• conditionalValues :

Values of the conditionalParam parameters for which the library has to be copied. This attribute can be a single value (true, or false for a bool parameter for example), or a comma separated list (case of a select parameter)

Depends node

This node describes the actions called by the plugin, but that are not coded in the plugin. When Panotour will generate the tour, it will parse all the "depends" nodes of all plugins, and include in the tour all the "depends" actions. If an action is called by different plugins it will be written only once in the code.

See the "Internal actions" section for the list of internal available actions.

<depends>
  <template url="enterfullscreencall.tmpl"/>
  <template url="KOLORRES:loadnextscenecall.tmpl"        conditionalParam="prevnext"             conditionalValues="true"/>
  <template url="KOLORRES:loadprevscenecall.tmpl"        conditionalParam="prevnext"             conditionalValues="true"/>
</depends>

• url

The url of the action template called by the plugin template.

• conditionalParam :

ID of a plugin parameter which values are checked to know if the tour calls the action template. This attribute has to be used with conditionalValues one.

• conditionalValues :

Values of the conditionalParam parameters for which the action is called, and has to be embedded in the tour. This attribute can be a single value (true, or false for a bool parameter for example), or a comma separated list (case of a select parameter)

Actions node

This node describes the public actions of the plugin.

These actions will be added to the action chooser widget.

The user will be able to select them either on spots, or on other plugins.

<actions>
  <action id="myFirstActionID" name="My Action" description="My action does something cool" callTemplate="myactioncalltemplate.tmpl"></action>
  <action id="mySecondActionID" name="My second action" description="This action does something cooler than the previous one" callTemplate="mysecondactioncalltemplate.tmpl">
    <bool   id="actionparameter1" name="an action parameter" default="true"/>
    <number id="actionparameter2" name="another action parameter" default="73"/>
  </action>
</actions>

• id

ID of the public action. The ID must absolutely be unique, so be wordy if needed.

• name

Name/Label of the action

• description

Description of the action

• callTemplate

URL of the template file that will be used to call the action. It is not the template of the action!

An action may need some parameters, that the user of Panotour will have to enter. If the actions needs some parameters, then the action node may contains some parameters sub-nodes.

BACK TO: Documentation / Panotour Documentation