My first plugin (KrPano script)

Panotour - Advanced - Creating text hotspots > Panotour - Advanced - Creating a custom control bar > Panotour - Advanced - Skins Folder > Panotour - Advanced - Different interfaces for different devices > My first plugin (KrPano script)

Intro

Before entering in specific details and pure documentation, I propose to realize a very simple example.

My goal

I want to make a plugin that will display a colored square on top of my tour.
I want to let the end user able to customize the position, size and color of my square.

How to

First I'll have to create a plugin directory. I open my own plugins directory using the "Edit > Open user directory" menu. I step into the "plugins" subdirectory, and I create "myFirstPlugin" subdirectory.

First, I'll hard code my plugin in myTour_skin.xml and have an idea of what should be the XML output.
In a second time, I'll create a PTP UI for my plugin for customization and templating process.

Here is the code needed in myTour_skin.xml to display a red square, 100 x 100pixels :

<layer	name="mySquare" keep="true" type="container" width="100" height="100" bgcolor="0xff0000" bgalpha="1"/>

This code will be soon customizable by the end user in PTP in order to change the position, the size and the color.
To achieve this, we need to create the files needed for a basic plugin : plug_info.xml and myFirstPlugin.tmpl.

Remember that the output code must be in the *.tmpl file, so simply write down the previous snippet in myFirstPlugin.tmpl In order to have the plugin shown in the Panotour style tab you need to create and describe your plugin in plug_info.xml.

Here's what you basically need in your plug_info.xml, it'll be explained in details later.

<plugin id="myFirstPlugin" 
	category="tr:Image zone" 
	name="tr:My super square plugin" 
	version="1.0" 
	isGraphical="true" 
	multipleInstance="false" 
	description="tr:A short description of what the plugin does" 
	author="John Doe">
    <templates>
        <template url="myFirstPlugin.tmpl" />
    </templates>
</plugin>

This file tells to Panotour how to display your plugin UI in the style tab and gives the name of the template that's going to be printed in your output myTour_skin.xml file.
For now, you have access to your hard coded plugin in the style tab ! Try it, you must have a red square at the top left corner.
You should notice that your plugin doesn't offer you the possibility to customize anything for the moment.
Remember that you have to restart Panotour to make changes in your plug_info.xml file effective.

Customization

We now want to offer our end user the possibility to customize the red square with some parameters.
I'll add some data inputs in the Panotour UI to set a position, a size and a color.
To do this, I have to describe this UI in my plug_info.xml.
I will not dig onto parameters details at this point, this is just a basic example.

<parameters>
	<position id="myPosition" 
		name="Position" 
		default="topleft" 
		availableValues="topleft,topright,bottomleft,bottomright,bottom,top,left,right"	/>
	<number id="mySize" name="Size" />
	<color id="myColor" name="Color" />
</parameters>

You can now add this snippet into the <plugin></plugin> block, and test your UI in Panotour.
If everything goes well, you should see our three parameters component in Panotour when you add your plugin : position, size and color.

If you try to build your tour, your square is still red, nothing changed.
We have to impact the myFirstPlugin.tmpl with the user's choices.

Your myFirstPlugin.tmpl file have now access to the data the user sets thanks to Django (templating script).
I can now replace hard coded values with the ones coming from PTP UI.
To do this I use Django to print these values in myFirstPlugin.tmpl with this kind of syntax :

{{ plugin.myComponentID.value }}

Here's what look like myFirstPlugin.tmpl file with Django templating script :

<layer	name="mySquare" keep="true" type="container"
	align="{{ plugin.myPosition.positionString }}"
	width="{{ plugin.mySize.value }}"
	height="{{ plugin.mySize.value }}"
	bgcolor="0x{{ plugin.myColor.colorRRGGBB }}"
	bgalpha="1"/>

You can now test your first plugin and customize it through PTP UI.

Now you can move on to the documentation of various tags to create more in depth plugins, see these pages:

• Plugin description file documentation (plug_info.xml)
• Parameters tags documentation (plug_info.xml)
• Templating tags and custom Kolor tags

BACK TO: Documentation / Panotour Documentation