Creating PHP Web Scripts

Web Scripts folder

Custom web scripts are stored in the PhotoWarp user settings folder on your computer:

• On Mac OS: ~/Library/Application Support/PhotoWarp 2/Web Scripts
• On Windows: %USERPROFILE%\Application Data\EyeSee360\PhotoWarp\2.5.x\Web Scripts

A single sample web script should be present, called Sample. You can download this sample from the EyeSee360 Web Scripts page. Sample is a folder on your computer, which contains a certain set of files and folders within it:

Sample/

• script/
  • index.php
  • singleton.php
• copy/
• Thumbnail 64x64.tif
• Version

Web Script folder must have a .pw extension to be recognized as a Web Script. On Mac OS X, folders with a .pw extension will be shown as PhotoWarp script files. Remove the extension to view or edit their contents in the Finder.

script folder

The script folder contains the actual web scripts that will be run by PhotoWarp. These scripts are written in the PHP scripting language. Traditionally, PHP is a server-side scripting language that is used to dynamically generate content on a web server. For PhotoWarp, this same mechanism is used to generate static web pages from a PhotoWarp Job. No special software is required on your web server, since standard HTML files are created.

Every web script contains at least two script files in this folder. singleton.php is run for each source in the job, possibly more than one time depending upon the formats applied. Web pages for individual panoramas are created from this script. index.php is run once for each job, after all the sources have been unwarped. It is used to generate an index page for the job, typically containing thumbnails and links to HTML pages made for each panorama.

copy folder

The copy folder contains files that are to be copied to the output directory whenever the job is unwarped. If your page layout uses shared files such as style sheets, image files or .swf files, place them here to be copied. All files in this folder will be copied to the output folder directly. Sub-folders will be copied in their entirety.

Thumbnail 64x64.tif

This thumbnail image file is used as the icon in PhotoWarp's listing of web scripts. You can use your favorite image editor to create this image to better suit your script. The size of the image must be 64 by 64 pixels exactly.

Version

The version file is a simple text file containing a version string, such as "1.0". This file is optional, but may be useful for maintaining your web scripts. PhotoWarp's auto update feature uses Version files internally to make sure web scripts are up-to-date with the version stored on our server; since your web script probably doesn't exist on our server, this should not impact your scripts.

Contents of scripts

Examining the singleton.php script

Writing your own scripts is a matter of creating or modifying the singleton.php and index.php files in a web script. To begin, make a copy of the Sample web script and give it a name of your choosing.

Open the singleton.php script file in your favorite text editor, such as Notepad or BBEdit. PHP files contain standard HTML code that should look familiar if you know HTML. The normal HTML is interjected with PHP sequences, which begin with <? or <?php tags and end with a ?> tag. The PHP code itself looks similar to JavaScript or C++ code, but is actually a different language.

The sample file contains lots of comments to explain what the script does at each step. Comments in PHP start with /* and end with */; these are completely ignored when executing the script. Comments on a single line can also be started by //, ending at the end of the line.

Read through the source file to get a feeling for what a web script contains. Below each section of the file will be broken down for discussion. Comments and HTML may be excluded for brevity.

<?php
include($_ENV["PW_PREFIX_FILE"]);

$source = $sources[0];
?>

This should be at the top of every PhotoWarp web script. The first line of PHP includes a file passed to it by PhotoWarp, which is able to parse all the variables sent from PhotoWarp to be used to make the web page. Some useful shorthand functions are also provided through the prefix file.

$source = $sources[0]; sets up a shorthand variable for the current source. In the singleton script, only a single source is passed in. This allows all attributes of that source to be accessed from the $source variable.

<title><? echo $source['name'] ?></title>

Sets the title of the page to the name of the current source. This is a typical pattern to include a variable in your script: <? echo $variable_name; ?>. The name of the current source is stored in the variable $source['name'].

<? ScriptHeader(); ?>

This includes a standard set of values into the <head> of the HTML document. This includes standard CSS style sheets, and possibly JavaScript code used for the Java viewer fallback capability.

<body <? echo BodyArgs(); ?>>

Begins the body of the HTML document. The BodyArgs() PHP function is called inside the tag to include any body attributes needed by the script (such as a JavaScript onLoad() statement).

<div>
<? ShowPano($source); ?>
</div>

ShowPano() is a helper function included in the prefix file. Quite simply, this is what you call to place the panorama on the page. The proper embed, object or applet tags are generated by the script and included here.

<?
if ($source['options']['AnnotationAuthor']) {
    echo ("<p><b>Author:</b> " . 
    $source['options']['AnnotationAuthor'] . "</p>\n\n"); 
}
if ($source['options']['AnnotationDescription']) {
    echo ("<p>" . 
    $source['options']['AnnotationDescription'] . "</p>\n\n"); 
}
if ($source['options']['AnnotationComment']) {
    echo ("<p>" . 
    $source['options']['AnnotationComment'] . "</p>\n\n"); 
}
if ($source['options']['AnnotationCopyright']) {
    echo ("<p>" . 
    $source['options']['AnnotationCopyright'] . "</p>\n\n"); 
}
?>

This block of code is used to include any annotations set for this source. The particular annotations are only included if they were set for this source. A block similar to this should be used in any script where annotations are to be used.

<?
if ($PW_IndexURL) { ?>
<p>
<a href="<? echo $PW_IndexURL; ?>">Return to Index</a>
</p>
<? } ?>

If an index is being created for the job, a link will be added to it here. $PW_IndexURL is a shorthand for the relative address of the index file.

Examining the index.php script

The index.php script will look similar to the singleton script, with the addition of some loop structures needed to produce an index. Open index.php with your text editor. The important differences are shown below.

<table>	
while(list(,$source) = each($sources) ) {
?>
    <tr>
        <td>
            <a href="<? echo $source['pages'][0]['link_url']; ?>">
            <? ShowPano($source); ?></a>
            <br>
            <a href="<? echo $source['pages'][0]['link_url']; ?>">
            <? echo($source['name']); ?></a>
        </td>

Since an index is passed every source in the job, it is necessary to loop across each source in the job and produce an entry for each. The while() block accomplishes this. list(,$source) = each($sources) will loop across every entry in the $sources array, placing the current source into the $source variable (just like in the singleton script).

In this example, we build a table row for each source. The first cell includes the thumbnail image (if selected) by calling ShowPano() for the active source. ShowPano() will return an empty string if Include thumbnails was off. Following the thumbnail, we echo the name of the current source for a text link

        <td>
<?
if ($source['options']['AnnotationAuthor']) {
    echo ("<p><b>Author:</b> " . $source['options']['AnnotationAuthor'] . "</p>\n\n"); 
}
if ($source['options']['AnnotationDescription']) {
    echo ("<p>" . $source['options']['AnnotationDescription'] . "</p>\n\n"); 
}
?>
        </td>
    </tr>
<? } ?>
</table>

Here we echo the author and description annotations for the selected source. This code is nearly identical to the singleton example. We close the while loop with a bracket }, which will repeat the containing code for each source. When every source has been completed, the next line is used to close the table (</table>).

Writing scripts

Writing a web script begins by writing a sample HTML file. Using your favorite HTML editor, produce a web page with the appearance you desire. You can even include an image or panorama as a placeholder for the actual panorama to insert. Save or rename the HTML file to singleton.php, and place a copy in to the script folder.

If you use the web script in this state, you will get a copy of that HTML file for each source panorama in your job. An HTML file saved with a PHP extension is perfectly valid PHP, it simply contains no code.

To turn this into a useful script, open the file in your text editor and make a few modifications:

1. Include the prefix file

Copy the prefix file include at the beginning of your HTML:

<?php
include($_ENV["PW_PREFIX_FILE"]);

$source = $sources[0];
?>

Only copy the $source = $sources[0]; for the singleton script.

2. Script header and body arguments

Before the end of the <head>, paste this code:

<? ScriptHeader(); ?>

Next, include this echo statement inside of your body tag:

<body <? echo BodyArgs(); ?>>

3. Include the panorama

Find the placeholder for your panoramic image in your page. Replace the image or embed tag with this:

<? ShowPano($source); ?>

4. Include annotations and other variables

If you wish to use the name of the source, source annotations, or other variables in your script, just insert the appropriate echo statement. This code will copy the name of the current source:

<? echo $source['name'] ?>

You can include a variable conditionally (only if it is set) by wrapping the echo in an if condition:

<?
if ($source['options']['AnnotationAuthor']) {
    echo ("<p><b>Author:</b> " . 
    $source['options']['AnnotationAuthor'] . "</p>\n\n"); 
}
?>

You can use some of the echoes in the original file as a reference. Also, you can unwarp your job using the Debug script, then copy-and-paste the variables shown there into your script.

5. Prepare the index.php script

Make another copy of your script file to use as an index. Place the while loop around the elements of your file that should be repeated for each source. Here's what this may look like for a table with one row per source:

<table>	
while(list(,$source) = each($sources) ) {
?>
    <tr>
        (Row content goes here)
    </tr>
<? } >
</table>

5. Prepare the script for PhotoWarp

Place any images or style sheets you've used in your HTML into the web script's copy folder. Then, rename the web script with a .pw extension. On Mac OS X, you will see the icon for the web script change from a folder to a PhotoWarp 'Script' icon.

Unwarp a job with your web script selected. You should see the results of your script right away.