close panorama

SWFAddress Plugin sa.swf, sa.js Version 1.3 (Beta 2)
for Flash and HTML5
by Jaydee - info@jaydee.ru

  • Allows for direct links to panoramas and particular views.
  • Both scenes and external files with panoramas are supported.
  • Experimental support for iframes.
  • One codebase works the same on desktops and mobile devices.
  • Provides URL Shortening functionality (via Bit.ly service).
  • Easy intergration with Google Analytics Plugin.
  • Includes example of sharing direct link to specific view on social networks (Facebook, Twitter, Email, Google+ and Pinterest).
  • HTML5 version of the plugin is free.

Plugin documentation topics:

Description

This plugin provides a robust interface to read, parse and modify fragment identifier of URL in a browser. This functionality can be used to providing direct links to panoramas and particular views. Check out the online demo to see how it works. When you virtual tour starts, plugin checks the current URL and its pano subnodes to help you to make a decision what panorama you should load not (only at startup, but also when browser navigation buttons are used). Also, when the user navigates to different panoramas in your virtual tour using hotspots, plugin tracks the changes of current panorama and updates the URL in browser accordingly. Thus, the pano subnodes are used to associate the specific URL in the browser with scene name of XML URL of panorama.

Demo & Downloads

Online demo (Automatic Flash or HTML5)
Important note! The HTML5 version of SWFAddress plugin (sa.js) is free and included in the download package.

Buy / Order

  • The Flash version of SWFAddress Plugin is an additional Commercial Plugin, to use it a full version must be bought.
  • Without buying a full version you will be able to use plugin only on your local computer.
  • The HTML5 version of the plugin is free and included in the download package. You can use it for free without buying anything.
  • Updates - All updates for SWFAddress Plugin are free.
    Please, follow the instructions at this page to get the update. You need to know the email address, which you used to buy the plugin.
Warning! Advanced krpano XML knowledge required in order for plugin to work correctly with your virtual tour. Please, download examples, examine their code and make sure that you'll be able to integrate plugin properly by our own before buying a plugin.
Buy now!

The order transaction and the full version delivering will be done by the Share‑It E‑Commerce provider.

Note - the "Extended Download" / "Erweiterter Download" option for 6.99 USD/EUR in the Share-It order form is not needed but enabled by default! It can be removed by clicking the "Trash"-button!

* VAT: Depending on your location or company status VAT may be added to the price. In the Share‑It order form select your country and enter your VAT/UID number to remove the VAT. The correct price will be shown on the next page in the order form.

Integration

Using the source code of the online demo as the template for your virtual tour is highly recommended.

  • The first thing you need to do is to include the helper swfaddress.js script in your HTML file. This script can be found inside the download package. Make sure to include swfaddress.js script right after the swfkrpano.js.
    <script src="swfkrpano.js"></script>
    <script src="swfaddress.js?tracker=null"></script>
  • Then, include swfaddress.xml file from the demo package into your root XML file using the include tag.
    <include url="swfaddress.xml"/>
  • After that, you should copy the plugin files (sa.swf, sa.js) into your root and change swfaddress.xml according to your tour requirements and architecture.
Check out the Best Practicies & Troubleshooting section for integration tips.

Syntax / XML Usage Example

<plugin name="swfaddress" 
        url="plugins/sa.swf"
	alturl="plugins/sa.js"
	keep="true"
	preload="true"
	randomroot="false"
	titleprefix="Virtual Tour: "
	titlepostfix=""
	bitlyapikey="BITLY_API_KEY"
	bitlylogin="BITLY_LOGIN"
	onurlchange="activatepano(%PANOID%, %TYPE%)"
	onparamschange="paramschangeaction()"
>
   <pano name="pano1"
	 scene="scene1"
	 pageurl="/pano1/"
	 pagetitle="Panorama 1"
   />
   ...
</plugin>

Plugin Attributes

  • randomroot
    • A boolean value, specifying whether plugin should select a random pano subnode as the root (entry point).
    • If set to true, all root attributes of pano subnodes will be ignored.
    • Default: false.
  • titleprefix
    • A string to be added at the beggining of all pagetitle attributes of pano subnodes.
  • titlepostfix
    • A string to be added at the end of all pagetitle attributes of pano subnodes.
  • value
  • path
    • A string, containing deep-linking path of the page.
  • title
    • A string, containing title of the page.
  • fullurl
    • A string, containing a full URL of the page.
    • Read only.
  • fullurlescaped
  • viewurl
    • A string, containing a full URL to the current view of this specific panorama.
    • Read only.
  • viewurlescaped
    • A string, containing a full URL to the current view of this specific panorama in the URL-encoded format.
    • Read only.
  • querystring
  • bitlyapikey
    • A string, containing you API key for URL shortening using Bit.ly service.
  • bitlylogin
    • A string, containing your login for URL shortening using Bit.ly service.
  • hasparams
  • isiframe
    • A boolean value, specifying whether the page containing virtual tour is iframed into another page.
    • Read only.
  • version
    • A string, containing current version of the plugin.
    • Read only.

Plugin Attributes - Events

  • onurlchange
    • Will be called when deep-linking path is externally changed (e.g. at startup or by clicking browser navigations buttons).
    • Use this event to call pano loading actions.
    • The value of this attribute may contain the following placeholders:
      • %PANOID - a scene name or url of XML file, which must be loaded.
      • %TYPE - a type of content, which must be loaded. Either xml or scene.
      • %PATH - a new value of deep-linking path
  • onpathchange
    • Will be called when deep-linking path is changed.
    • Use this event for integration with Google Analytics Plugin.
    • The value of this attribute may contain the following placeholders:
      • %PATH - a new value of deep-linking path
    • Example:
      onpathchange="plugin[ga].trackpageview(%PATH%);"
  • onparamschange
    • Will be called when parameters in query string are changed.
  • onshortensuccess
    • Will be called in case of successful URL shortening.
  • onshortenerror
    • Will be called in case of unsuccessful URL shortening.

Plugin Attributes Explained

  • In case of following URL http://site.com/vt/#/pano1/?p=1&t=2, the attributes of the plugin will contain the following values:
  • You can get the values of parameters in query string using the getparam action. plugin[swfaddress].getparam(fov, target_var);

Plugin Subnodes - <pano>

  • With <pano> subnode it is possible to define which panorama should be loaded when specified URL is used and vice versa.
  • Add one subnode for each scene or XML file with panorama.
  • It is possible to add and remove pano subnodes at runtime using the addpano and removepano actions.

The <pano> node with the example of attributes values:
<pano name="pano1"
      scene="pano1"
      pageurl="/pano1/"
      pagetitle="Panorama 1"
      onxmlcomplete="trace(Panorama 1 loaded);"
      />

<pano> Attributes

  • name
    • The name of the pano.
    • Should start with letter.
  • xmlurl
    • A URL of XML file, which should be associated with specific URL in a browser.
    • May contain any path placeholders (e.g. %SWFPATH%).
  • scene
    • A scene name, which should be associated with specific URL in a browser.
  • pageurl
    • A URL in a browser (deep linking path), which should be associated with specific XML file or scene.
  • pagetitle
    • A page title, which should be associated with specific XML file or scene.
  • root
    • An optional boolean flag, which defines its owner as the root (entry point).
    • By default, the first subnode will be defined as root, if none of them has a root flag.
    • If randomroot attribute is set to true, this flag will be ignored on all subnodes.

<pano> Events

  • onxmlcomplete
    • An optional helper event, which will be called everytime, when linked XML file or scene is loaded. It is similar to onxmlcomplete attrbiute of events tag, but called only for linked panorama.
    • Use this event to call actions related to specific panorama (e.g. to activate a spot on the map).

Plugin Actions

Actions documenation:

  • addpano(name, xmlURLOrScene, isScene, pageURL, pageTitle, onXMLComplete)
    • Adds pano subnode at runtime
    • name - a name of pano subnode
    • xmlURLOrScene - a scene name or URL of XML file with panorama
    • isScene - a boolean flag, which indicates whether the value of second paramter is scene name or URL of xml file
    • pageURL - a page URL for associated panorama
    • pageTitle - an optional page title for associated panorama
    • onXMLComplete - an optional onxmlcomplete event for associated panorama
    • Example:
      plugin[swfaddress].addpano(pano0, scene0, true, /pano1/, Pano 1);
  • removepano(name)
    • Removes pano subnode at runtime
    • name - a name of pano subnode
    • Example:
      plugin[swfaddress].removepano(pano0);
  • removeallpanos()
    • Removes all pano subnodes
    • Example:
      plugin[swfaddress].removeallpanos();
  • shorten(url)
    • Sends an URL shorten request to Bit.ly service
    • url - an URL to be shorten
    • Example:
      plugin[swfaddress].shorten(url);
  • copy(escape)
    • Copies to clipboard a full page URL.
    • Only available in flash version of the plugin.
    • escape - an optional boolean flag, which indicates whether the specified URL should be URL encoded before copying. False by default.
    • Example:
      plugin[swfaddress].copy();
  • getparam(paramName, targetVar)
    • Copies the value of URL parameter with specific name to the krpano variable.
    • paramName - a name of URL parameter which value should be copied.
    • targetVar - a target variable name to store a value of URL parameter.
    • Example:
      plugin[swfaddress].getparam(fov, p_fov);
  • setparam(name, value, append)
    • Sets parameter value.
    • name - name of the parameter.
    • value - value of the parameter.
    • append - an optional boolean flag, which indicates that specified name/value pair must be appended to the query string instead of updating the value of the parameter. False by default.
    • Examples:
      plugin[swfaddress].setparam(atv, view.vlookat);
      plugin[swfaddress].setparam(fov, r(view.fov));
      plugin[swfaddress].setparam(sound, 1, true);
  • setparams(param1, value1, param2, value2, ...)
    • Sets multiple parameters values, cleans out all existed parameters first.
    • Works the same as setparam function, but allows to set multiple parameters.
    • Virtually unlimited number of parameters can be set in one call.
    • The value of paramter should be passed as the next argument after parameter name.
    • Examples:
      plugin[swfaddress].setparams(ath, view.hlookat, atv, view.vlookat);
  • removeparams()
    • Removes all parameters in URL.
    • Example:
      plugin[swfaddress].removeparams();

Examples

Example xml code:
<krpano version="1.16">
	<plugin name="swfaddress"
		url="plugins/sa.swf"
		url="plugins/sa.js"
		keep="true"
		preload="true"
		titleprefix="Virtual tour - "
		
		onurlchange="activatepano(%PANOID%);"
		>
		<pano name="pano1"
		      scene="p1"
		      pageurl="/pano1/"
		      pagetitle="Panorama 1"
		      />
		<pano name="pano2"
		      scene="p2"
		      pageurl="/pano2/"
		      pagetitle="Panorama 2"
		      root="true"
		      />
	</plugin>
	
	<action name="activatepano">
		loadscene(%1,null,MERGE,BLEND(1));
		wait(blend);
	</action>
	
	<scene name="p1">
		...
	</scene>
	
	<scene name="p2">
		...
	</scene>
</krpano>

FAQ

  • Q: Where I can ask a questions about the plugin and its usage?
    A: Please, post your questions and feature requests in the related forum discussion thread.
  • Q: How do I get update for the plugin?
    A: See the Updates section for instructions.
  • Q: How do I get notified about future updates?
    A: You can check the forum discussion thread or subscribe to newsletter at this page.
  • Q: How do I know the version of my plugin?
    A: You can open swf file in a browser, open krpano viewer log panel or trace version attribute of the plugin to find a version code.

Best Practices & Troubleshooting

Important notice! The first thing that all SWFAddress plugin users should understand is that plugin have nothing to do with visual elements. As stated in this documentation - it is a plugin which helps you to work with URL and track its changes. Plugin helps you to read the URL in browser and decide which panorama you should load. Also, it allows you to read view properties in URL so you can move camera to the appropriate position. Plugin could not disable your hotspots or hide button, or do other stuff with visual elements. That's a clue. What code you will use to load panorama or set view properties is only up to you. The example of such code is provided with the examples, but you should understand that in order to work properly this code should be adopted to the specific configuration or just replaced with another. Here are some tips which should help you to avoid errors.
  • You don't need to load first panorama manually by including it in start XML file or calling any loading actions. The SWFAddress plugin will tell you which panorama you should load based on the URL value in a browser. In other words, it will call actions defined in onurlchange attribute, so make sure to check this first.
  • If you are using share view functionality in your tour, then make sure that hlookat, vlookat and fov attributes of view tag are not defined anywhere in your tour as they prevent the plugin from setting these properties from the URL.
  • Check the integration section.
  • Configure Flash Player security settings using this guide if you are testing locally.
  • Make sure to upload the purchased version on webserver instead of the demo. Demo version of the plugin will only work locally.
  • Embed your purchased version to the swf using the krpano Protect Tool.

Changelog

v1.3 (Beta 2)
* [Improved] Support for adding pano subnodes at runtime
* [Improved] Minor improvements and bugfixes

v1.3 (Beta 1)
* [Added] Support for krpano v1.16+
* [Added] mode attribute
* [Added] viewurl attribute
* [Added] viewurlescaped attribute
* [Added] bitlyapikey attribute
* [Added] bitlylogin attribute
* [Added] isiframe attribute
* [Added] onshortensuccess attribute
* [Added] onshortenerror attribute
* [Added] addpano, removepano, removeallpanos actions
* [Added] shorten, getparam, copy actions
* [Removed] escape, replaceampersands, copylink actions
* [Improved] All new codebase for the plugin

v1.2.6
* [Fixed] Iframes support fixes
* [Added] onpathchange attribute

v1.2.5
* [Important] The SWFAddress Library has been downgraded to 2.4 in order
              to work properly in Safari browser.
* [Added] HTML5 version of the plugin
* [Added] randomroot attribute
* [Added] parsepaths attribute
* [Added] titleprefix attribute
* [Added] titlepostfix attribute
* [Added] oninvalidaddress attribute
* [Added] escape() function
* [Added] replaceampersands() function for HTML5 version
* [Added] Support for iframes.
* [Improved] Minor improvements and bugfixes

v1.1
* [Critical] Plugin is no longer works with swfaddress.js script
version 2.4 and lower. At minimum, the 2.5 version is needed
* [Improved] auto|xml and auto|scenes modes are removed.
New auto mode supports using both scenes and external XML files
simultaneously
* [Improved] action attribute removed, more flexible onurlchange event
added instead
* [Improved] path and title attributes now supported in automatic mode
* [Improved] copylink() function now supports the copying URL
to clipboard in URL-encoded format
* [Added] fullurlescaped attribute
* [Added] querystring attribute
* [Added] setparam() function
* [Added] version attribute
* [Added] onxmlcomplete attribute added to pano subnode

v1.0
* initial plugin release