Web Script Templates Reference

PhotoWarp 2.5.7 uses a new template engine for web scripts. It provides both more capability than the older PHP-only web scripts and an easier interface.

Web script templates are based on the Smarty template engine. While all the features of Smarty templates are supported, PhotoWarp includes some custom template functions and blocks that are particularly designed for embedding panoramas with multiple formats.

Web Script Structure

A web script is simply a folder stored in your Web Scripts folder with a certain structure. The web script folder itself must be named with a .pw extension.

MyWebScript.pw/

• webscript.conf
• templates/
  • index.tpl
  • slideshow.tpl
  • single.tpl
• copy/
• style.css
• logo.png

Web Scripts that intend to use the new Smarty template engine must have a webscript.conf file at the top level of the web script folder. This is a text file that describes each of the templates in the web script and how they will be interpreted. Specifically, the configuration file determines the file naming pattern for each template, how many sources should be applied for each instance of the template, and the output formats to expose to that template.

There are two subfolders for each web script. The "templates" folder contains the actual template files that will be interpreted. Each template file has a .tpl file extension. You can have as many templates in a web script as you'd like. The "copy" folder contains resources that will be copied into the output directory. This is used for things like images or style sheets used in the templates.

WebScript Configuration File (webscript.conf)

Every new web script requires a webscript.conf in the web script folder. The config file uses a very simple format that is read line-by-line. Blank lines and lines beginning with # are ignored. (You can use the # prefix before any comments.) Variables are defined on a line as " variable = value".

The file is divided into sections that restrict the use of variables to specific template files. Initially, variables are global in scope and apply to all templates. You can declare a new section by putting the name of the applicable template (excluding the .tpl file extension) between square brackets on a line, like this: [single]. Lines following the declaration are applied only to the template with the matching name. In this case, the variables will be applied for the single.tpl template.

Here is a sample webscript.conf file for our web script:

# Configuration for MyWebScript

multi_format = true

[index]
sources_per_page = 20      # up to 20 sources on each index page
filename_pattern = index{$pageNumber}.html
formats = thumbnail	

[single]
sources_per_page = 1       # one source per page
filename_pattern = {$sourceName}.html
formats = qtvr,panosalado

[slideshow]
sources_per_page = 0       # all sources on one page
filename_pattern = slideshow.html
formats = any

This configuration file applies to three templates, index.tpl, single.tpl, and slideshow.tpl. The variables shown are required for every template. Here is a description for each of the variables that are defined in the webscript.conf file:

formats

Required.
Synopsis: formats = (any|single|index|formatname), ...

Declares the formats accepted by this template, in order of precedence. Shorthand format lists, such as any, single and index can be used, as well as comma-separated lists of any of the enumerated formats supported:

Format Identifiers

multi_format

Required.
Synopsis: multi_format = (true|false)

Determines if templates are run multiple times for multiple output formats.

If true, a single instance of the template will be used at runtime for all formats. The formats in the job will be filtered by the formats specified in the config file. This is typically used in conjunction with AutoViewer.

If false, an instance of the template will be created for each of the formats in the job that are also accepted by this template. Note that it is possible to have zero, one or more than one instance for a given format, depending on the job.

sources_per_page

Required.
Synopsis: sources_per_page = integer

Determines how many pages this template will produce, based on the number of sources in the job.

If 0, only one page will be produced for all sources (for example, a one-page index).

If 1, one page will be produced for each source. The source variable in the template will be initialized to each source.

If any number n > 1, a page will be produced for every n sources. This is useful for indexes with 20 sources per page, for example.

Note that it is possible to index arbitrary sources from the template using a {source} block, so if you want to have overlapping ranges specify the number of non-overlapping sources here and then index manually.

filename_pattern

Optional, but strongly recommended.
Synopsis: filename_pattern = pattern

Describes a pattern for filenames generated by this template. It is your responsibility to ensure that filename patterns do not produce conflicting names for files of a given template or of different templates in the same web script. The default pattern will produce non-conflicting names. Do not attempt to make paths using path separator characters.

Filename patterns are intepreted Smarty template strings. The following variables will be defined. It is permissible to use Smarty functions and variable modifiers, for example to pad page numbers or conditionalize the filenames.

filename_pattern variables

The filename will be made web ready before returning (whitespace to underscores, ASCII only).

filename_pattern Examples

Web Script Templates

Web Script templates look very much like ordinary HTML files. The template engine works by reading in a template file, replacing or modifying certain parts according to the template tags contained within, and writing out the result. Templates contain special tags wrapped in unique delimiters like this:

{% $variable %}

Anything between the {% and %} delimiters are evaluated by the template engine and used to modify the resulting document. These come in a few flavors.

These template tags can hold variable names prefixed with a dollar sign ($), in which case the string value of the variable will replace the tag. Template tags can also call functions which might modify the template environment in some way, or they may be blocks which affect the enclosed contents.

Template Variables defined by PhotoWarp

PhotoWarp web scripts define variables based on the current job. The following variables are defined:

Global-scope variables

The following variables are defined within the scope of a source block (defined later). For templates with sources_per_page set to 1, a single source is defined automatically. For all other templates, use something like the {% foreachsource %} block to loop through the sources.

Source-scope variables

Template Functions declared by PhotoWarp

Because looping through sources and properly embedding panoramas is challenging without assistance, PhotoWarp provides some custom template functions and blocks to make authoring templates easier.

{% foreachsource %} Block

Synopsis:

{% foreachsource [start=startindex] 
                 [end=endindex] 
                 [count=maxcount] 
                 [step=number] %}
...
[{% nextsource [step=number] %}]
...
{% /foreachsource %}

Loops over the job's sources within the specified range. All attributes are optional. If none are specified, this will loop over all sources for this page.

Attributes

start=startindex	Optional. The index of the first source. Defaults to the starting source for the page.
end=endindex	Optional. The index of the last source, inclusive.
count=maxcount	Optional. The maximum number of sources to loop from the start. Generally this is used as an alternative to end. Defaults to sources_per_page for this template.
step=number	Optional. The increment for each loop. Defaults to 1.

Inner Functions

The {% nextsource %} command may be used within a {% foreachsource %} block in order to increment between loops. This can be used to produce a multi-column table of source thumbnails, where the {% foreachsource %} loop produces each row of the table, and {% nextsource %} is used to increment the source between cells. Here's an example:

<table>
{% foreachsource %}
	<tr>
		<td>{%embed%}{%/embed%}</td>
		{% nextsource %}
		<td>{%embed%}{%/embed%}</td>
		{% nextsource %}
		<td>{%embed%}{%/embed%}</td>
	</tr>
{/foreachsource}
</table>

source Block

Synopsis:

{% source index=sourceIndex %} 
... 
{% /source %}

Specifies a specific indexed source for the content region. Generally this block is only used when representing a source outside the normal range for a template page.

Attributes:

index=sourceIndex

Required. The absolute integer index of the source in the job.

embed Block

Synopsis:

{% embed [id=id]
         [target=idRef]
         [source=sourceIndex]
         [formats=formatList]
         [direct=(true|false)]
         [class=cssClass]
         [style=cssStyle] %}
... fallback contents ...
{% /embed %}

Emits the necessary HTML and JavaScript code to embed a panorama for this source. Valid only within the context of a source. All attributes are optional.

Any contents inside the {% embed %}...{% /embed %} block will be used as alternate display contents in the event the panorama cannot be shown.

Attributes:

id	Optional. The ID of the DOM element to produce. Must be unique among all ID's in the page. If not specified, a unique ID will be generated.
target	Optional. Instead of placing the source where this tag occurs, the panorama will be placed in the DOM element with the specified target ID.
source	Optional. Specifies the index of the source to embed. Default is the current source.
formats	Optional. A comma-separated list of format identifiers to display for the panorama, in order of precedence. If not specified, uses the formats declared in the configuration file. These are the same tokens used in the template configuration file. See: Format Identifiers.
direct	Optional. If true, the panorama will be embedded directly instead of using AutoViewer. Only the first listed and available format will be embedded. Default is false. Recommended for embedding thumbnails.
width height	Optional. If specified, overrides the display dimensions of the panorama in all formats. Otherwise uses the display size from the unwarp job. Either both width and height are defined and > 0, or both are undefined or equal to 0 to use the native dimensions.
class	Optional. The class attribute to apply to the generated element. If not specified, no class attribute will be provided.
style	Optional. The style attribute to apply to the generated element. If not specified no style attribute will be provided.

linkto Function

Synopsis:

{% linkto [source=sourceIndex]
          [page=(next|prev|pageIndex)]
          [template=templateName]
          [format=format] %}

Produces a URL to a template page for a given source. At least one of the following attributes are required.

source	The index of the source to link. Values of this attribute may be any absolute source index. If not specified, the current source index is used.
page	The index of the page to link. Can be the strings "next" or "prev" to refer to the following or preceding page within the same template.
template	The template to link. Commonly used to switch between the same source on different templates. For example, a multi-page index linking to a single page for a source, or the reverse. Defaults to the current template. If the specified template is multi-format, the format attribute is required.
format	The format to link. For single-format templates this will specify a given instance. Comma-separated lists are valid, the first match will be used. Only useful for non-multi-format templates. See: Format Identifiers.

switchto Function

Synopsis:

{% switchto [target=targetID]
            [source=(current|next|prev|sourceIndex)]
            [format=formatIndentifier]
            [mode=(js|url)] %}

Provides JavaScript code to switch AutoViewer to a different format or source. By default this will make the JavaScript code only, but it can alternately produce a "javascript:..." form URL to be used in a hyperlink.

Examples:

• A button to switch all viewers on the page to QuickTime VR:
  

  <button onclick="{% switch format=qtvr %}">Switch to QTVR</button>
  

• A thumbnail for a source that links to display that source in the pano element:
  

  <a href="{% switch target=pano source=current mode=url %}">
  {% embed format=thumbnail %}{% /embed %}
  </a>
  

Attributes:

target	ID of the embedding element to switch. If not specified, all AutoViewers on the page will be switched.
source	Source to switch to. Can be the absolute index of any source, current for the current source in this tag's context, next for the next source available to the target, prev for the previous.
format	The format to switch to. See: Format Identifiers.
mode	The mode to emit the code. Default is "js" which will produce straight JavaScript code. This would be suitable in an event handler attribute such as this: <button onclick="{% switch format=qtvr %}">QTVR</button> In "url" mode, the JavaScript is wrapped into a javascript: URL which may be used as a normal hyperlink: <a href="{% switch format=qtvr mode=url}">QTVR</a>

ifsource Conditional Block

Synopsis:

{% ifsource target=targetId 
            [id=ID] %}
...
{% /ifsource %}

The block will only be displayed when the given source is visible in the targetId embed block.

In the case of multiformat templates, a <div> will be produced with the contents of the block, along with a unique ID (or that specified). The AutoViewer will hide or show the block depending upon the visible format.

This can be useful to include source-specific details in a slideshow-style template.

Attributes:

target	Required. The target ID for the {% embed %} element to test.
id	The ID to use for the generated block. If not specified, an ID will be generated.

ifnosource Conditional Block

Synopsis:

{% ifnosource %}
...
{% /ifnosource %}

A conditional block that will only be included if there is no source in the present context. This might be used to fill in empty table cells, for instance.

ifformat Conditional Block

Synopsis:

{% ifformat format=formatList 
            [id=ID] 
            [class=divClass] 
            [style=divStyle] %} 
...
{% /ifformat %}

The block will only be displayed when the given format or formats is visible. Must be used in the context of a source.

Blocks for formats not available to the template will be omitted.

In the case of multiformat templates, a <div> will be produced with the contents of the block, along with a unique ID (or that specified). The AutoViewer will hide or show the block depending upon the visible format.

This can be useful to include format-specific instructions in the page.

Attributes:

format	Required. The format identifier to test. Standard format tokens can be used.
id	The ID to use for the <div>. If not specified, an ID will be generated.
class	The class attribute to apply to the div. If not specified no class attribute will be provided.
style	The style attribute to apply to the div. If not specified no style attribute will be provided.