Using 'scriptlets' in your XML files

After showing you step by step what a basic SPi-V xml file looks like, we will continue to show you how easy it can be to add some of the advanced feature of SPi-V.

In this howto article, we will start out with the script we saw in the last article (note that I have removed the <meta> tag for clarity):

<?xml version="1.0"?>
<tour>
  <scene id="my_scene">
    <panoelement id="my_pano" image="my_image" />
    <image id="my_image">
      <layer class="base" type="bitmap" src="panorama.jpg" />
    </image>
  </scene>
</tour>

As in the previous article, replace "panorama.jpg" with the filename of your panoramic image.

We're going to add a spiffy looking toolbar to this simple scene. You can download the toolbar scriptlet from the downloads page. When you extract the archive, you should end up with a folder named 'scriptlet-toolbar' containing a number of graphics images and a single xml file, and a folder named 'cubic' that contains a single cubic panorama.

If you open the xml file in the SPi-V viewer, you can see what the toolbar looks like. Notice the subtle transparecy effects when rolling over the toolbar area, and be sure to try the 4 buttons. Once you are done playing with the toolbar, you can safely remove the common folder; we will be using the toolbar with one of your panoramas.

If you take a look inside the xml file, you will see that the script for the toolbar is rather complex. The bulk of this complexity is added for the subtle transparecy changes etc, but the nice thing is that you don't have to worry about this xml at all. By adding a single line of xml to your simple xml script, you can include the full toolbar script to your scene:

<?xml version="1.0"?>
<tour>
  <scene id="my_scene>">
    <uigroup src="scriptlet-toolbar/toolbar.xml" />
    <panoelement id="my_pano" image="my_image" />
    <image id="my_image">
      <layer class="base" type="bitmap" src="panorama.jpg" />
    </image>
  </scene>
</tour>

Note: You may have to change the path specified after the "src=" part to match the relative path from your simple xml file to the toolbar xml file.

How scriptlets work

Scriptlets are XML files, just like normal SPi-V xml files. In fact, you have already seen that you can view a scriptlet by itself, with a sample scene. As an alternative to using scriptlets as shown above, you could copy the relevant bits from the scriptlet XML file and paste it into your own XML file. This is essentially what the SPi-V engine does for you on the fly.

Let's look at that line we added more carefully:

<uigroup src="scriptlet-toolbar/toolbar.xml" />

Normally the uigroup node groups a number of uielement nodes. These nodes make up the user interface of a SPi-V tour or scene. In this case, instead of further specifying what is inside the uigroup, you point the SPi-V engine to a file. The engine will then look for the first uigroup it can find in the referenced file and copy that elements and all it's child elements over to the main XML file.

Not all scriptlets use a uigroup node though. Some other scriptlets, like the cap image scriptlet we will see in a minute use a panogroup. To be sure about the way how to include a scriptlet in your file, read the comments included in the scriptlet XML file.

Customising scriptlets

Some scriptlets are rather complex, like the toolbar scriptlet we used above. Other scriptlets are simpler and are more easily customised to suit your own taste and style

The cap scriptlet adds a fieldOfView logo 'cap image' to your scene, like the ones typically used to hide a tripod. When clicked, it will open a link to the fieldOfView.nl homepage. Listed below are the relevant lines in the cap.xml file that allow you to customise the cap image appearance:

...
      <panoelement id="scriptlet#cap-element" type="flat" hfov="30">
        <image id="scriptlet#cap-image">
          <layer class="base"  type="bitmap" src="fov-light.png"/>
          <layer class="hover" type="bitmap" src="fov-over.png"/> 
          <layer class="press" type="bitmap" src="fov-down.png"/> 
        </image>
        <!-- on click, open url in new window -->
        <behavior><action type="getURL" event="release" target="_blank" url="http://fieldofview.nl"/></behavior>
      </panoelement>
...

Replace the highlighted values to add your own cap image and url. If you don't want the cap image to have a different appearance when you move the mouse over it, remove the line with that starts '<layer class "hover" ...'. Likewise, if you don't want the cap image to be clickable, remove the full behavior node (including the action included inside the behavior node).

If you want to understand how this particular scriptlet works, read this howto about how to add a clickable cap image step by step.