SWFAddress Plugin sa.swf, sa.js for Flash and HTML5

by Jaydee - info@jaydee.ru

• Provides a robust interface to read, parse and modify fragment identifier of URL in a browser.
• Allows for direct links to panoramas and particular views.
• Both scenes and external files with panoramas are supported.
• Can work either in automatic or manual mode.
• Includes example of sharing direct link to panorama on social services (Facebook, Twitter, Email).
• Experimental support for iframes.
• One codebase works the same on desktops and devices.
• Comes with free URL shortener plugin - Bitly Plugin (for Flash and HTML5).
• Easy intergration with Google Analytics Plugin.
• HTML5 version of the plugin is free.

• Description
• Demo & Downloads
• Buy / Order
• Updates
• Integration
• Usage Syntax
• Plugin Attributes
• Plugin Subnodes:
  • Pano
• Plugin Actions
• Examples
• FAQ
• Troubleshooting
• Changelog

Description

Demo & Downloads

Buy / Order

• The 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.
• Updates - All updates for the SWFAddress Plugin are free.
  Please, follow the instruction on this page to get an update. You need to know the email address, which you used to buy the plugin. You will receive a zip with updated version in a couple of minutes. If you forget or don't own that address anymore, please write me a short email.

Integration

• The first thing you need to do is to include the SWFAddress 2.4 script in the HTML file. 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 by using the include tag.

  <include url="swfaddress.xml"/>

• After that, you should copy required plugin files (sa.swf, sa.js, bitly.swf, bitly.js) and change swfaddress.xml according to your tour requirements and architecture.

Syntax / XML Usage Example

<plugin name="swfaddress" 
        url="plugins/sa.swf"
	alturl="plugins/sa.js"
	keep="true"
	preload="true"
	mode="auto"
	randomroot="false"
	parsepaths="true"
	titleprefix=""
	titlepostfix=""
	value=""
	path=""
	title=""
	fullurl=""
	fullurlescaped=""
	querystring=""
	hasparams=""
	version=""
	onurlchange=""
	onpathchange=""
	onparamschange=""
	oninvalidaddress=""
>
   <pano name="pano1"
	 xmlurl="pano1.xml"
	 scene="scene1"
	 pageurl="/pano1/"
	 pagetitle="Panorama 1"
	 onxmlcomplete=""
   />
   ...
</plugin>

Plugin Attributes

• mode
  • A string, containing mode of the plugin. Possible values:
    • auto
    • manual (default)
  • Can't be changed at runtime.
• 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.
• parsepaths
  • A boolean value, specifying whether to parse placeholders (e.g. %SWFPATH%) in the xmlurl attribute of pano subnodes.
  • Default: true.
• 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
  • A string, containing fragment identifier of URL in a browser.
  • Read only.
• path
  • A string, containing deep-linking path of the page.
• title
  • A string, containing title of the page.
• fullurl
  • A string, containing full URL of the page.
  • Read only.
• fullurlescaped
  • A string, containing a full URL of the page in the URL-encoded format.
  • Read only.
• querystring
  • A string, containing parameters of fragment identifier.
  • Read only.
• hasparams
  • A boolean value, specifying whether fragment identifier contains a query string.
  • 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. 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
    %PANOID and %TYPE are available in automatic mode only.
• onpathchange
  • Will be called when deep-linking path is changed.
  • Use this event to simplify 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.
• oninvalidaddress
  • Will be called when no matching found between current deep-linking path and existing pano subnodes.
  • Automatic mode only.

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:
  • value = /pano1/?p=1&t=2
  • fullurl = http://site.com/vt/#/pano1/?p=1&t=2
  • querystring = p=1&t=2
  • hasparams = true
• You can get the values of parameters in query string by using special plugin attributes. For example, you can get the value of parameter p1 using this syntax: get(plugin[swfaddress].param_p1);

Plugin Subnodes - <pano>

• With the <pano> subnode it is possible to define which panorama should be loaded when specified URL is entered and vice versa.
• Add one subnode for each scene or XML file with panorama.
• Should be used with automatic mode only.

<pano name="pano1"
      xmlurl="pano.xml"
      scene="pano1"
      pageurl="/pano1/"
      pagetitle="Panorama 1"
      onxmlcomplete="trace(Panorama 1 loaded);"
      root="false"
      />

<pano> Attributes

• name
  • The name of the pano.
• xmlurl
  • A URL of XML file, which should be linked to specific URL in a browser.
  • May contain any path placeholders (e.g. %SWFPATH%).
• scene
  • A scene name, which should be linked to specific URL in a browser.
• pageurl
  • A URL in a browser (deep linking path), which should be linked to specific XML file or scene.
• pagetitle
  • A page title, which should be linked to 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

<krpano version="1.0.8">
	<plugin name="swfaddress"
		url="plugins/sa.swf"
		url="plugins/sa.js"
		preload="true"
		titleprefix="Virtual tour - "
		
		mode="auto"
		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,KEEPALL,BLEND(1));
		wait(blend);
	</action>
	
	<scene name="p1">
		...
	</scene>
	
	<scene name="p2">
		...
	</scene>
</krpano>

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