Home › Toolkits › Pando Web Services

JavaScript Access: PandoAPI.js

The Pando JavaScript API (PandoAPI.js) provides access to the Pando Web Services for JavaScript code that is running inside a web browser.

To see an example of how to use PandoAPI.js, see Custom Package Previews with PandoAPI.js.

One important limitation of the Javascript XmlHttpRequest function (a cornerstone of AJAX) is that it does not allow a script to load the contents of a file from a domain other than the one on which the script is running. There are good reasons, from a security standpoint, that this limitation exists. There are many workarounds for this for sources you trust (e.g., proxying calls on your own server). We decided to experiment with a Javascript library that allows you to retrieve metadata from packages encoded in JSON without requiring server-side code, just client-side javascript.

The Pando Javascript API library is at http://cache.pando.com/soapservices/PandoAPI.js. To use it, you need to include it in your HTML document in the <head> section: <script src="http://cache.pando.com/soapservices/PandoAPI.js" type="text/javascript"></script>

PandoAPI.toString

The Pando Javascript API has three functions. The simplest (PandoAPI.toString) simply outputs the current version of the PandoAPI and is useful for debugging. For example, 

<html>
  <head>
   <script src="http://cache.pando.com/soapservices/PandoAPI.js" type="text/javascript">
   </script>
  </head>
  <body>
   <script type="text/javascript">
     document.write(PandoAPI.toString());
   </script>
  </body>
</html>

This will output something like: PandoAPI vtrunk

PandoAPI.getPackageURL

The second function (PandoAPI.getPackageURL) is also simple. It requires the package id and key (and optionally accepts the gotPando parameter) and generates a Package URL. 

<html>
  <head>
   <script src="http://cache.pando.com/soapservices/PandoAPI.js" type="text/javascript">
   </script>
  </head>
  <body>
   <script type="text/javascript">
    document.write(PandoAPI.getPackageURL('5AEDE982393976A10050F2EC7C20C3C5EFDE0BBB',
      'C51E9F2767B6747A9C9841AF7EEB9CC0E967D5B37CEC05B8C9DF310A03958AD2'));
   </script>
  </body>
</html>
This will output the URL to the package: 
http://cache.pando.com/soapservices/Package/Package.pando?
	id=5AEDE982393976A10050F2EC7C20C3C5EFDE0BBB
	&key=C51E9F2767B6747A9C9841AF7EEB9CC0E967D5B37CEC05B8C9DF310A03958AD2
You may also set the optional gotPando parameter. By default, it is false. Setting it to true will generate a Package URL that will skip the usual "is Pando installed?" test, and simply deliver the package. For example, replacing the necessary line from the above example: 
document.write(PandoAPI.getPackageURL('5AEDE982393976A10050F2EC7C20C3C5EFDE0BBB',
  'C51E9F2767B6747A9C9841AF7EEB9CC0E967D5B37CEC05B8C9DF310A03958AD2',
  true));
This will result in a URL that looks like 
http://cache.pando.com/soapservices/Package/Package.pando?
	id=5AEDE982393976A10050F2EC7C20C3C5EFDE0BBB
	&key=C51E9F2767B6747A9C9841AF7EEB9CC0E967D5B37CEC05B8C9DF310A03958AD2&hasPando=yes

Note: When a user follows such a link, the Pando services will attempt to set the Pando "installed" cookie.

getPackageInfo

The most powerful tool provided by this API is the PandoAPI.getPackageInfo function. It accepts as parameters the package ID, a callback function and the package key (optional). When called, this function writes another <script> tag into your document that makes available the package info in JSON format, and then calls the provided callback function to process this data. This example simply writes all the available package metadata directly into the page: 
<html>
  <head>
  <script src="http://cache.pando.com/soapservices/PandoAPI.js" type="text/javascript"></script>
  </head>
  <body>
	<script type="text/javascript">
	function printPackageCallBack(packageInfo) {
 	  //print all the properties in the packageInfo object
	  for (var prop in packageInfo) 
		document.write(prop+': <em>'+packageInfo[prop]+'</em><br/>');
	}
		
	//the package id and key (replace with your own values)
	var packageId = '5AEDE982393976A10050F2EC7C20C3C5EFDE0BBB'; 	
	var packageKey = 'C51E9F2767B6747A9C9841AF7EEB9CC0E967D5B37CEC05B8C9DF310A03958AD2';

	//use the API to retrieve the package info - results are returned to the callback function
	PandoAPI.getPackageInfo(packageId,printPackageCallBack, packageKey);

	</script>

	</body>
</html>
The resultant output (with "files" trimmed) looks something like: 
version: 1.0
packageId: 5AEDE982393976A10050F2EC7C20C3C5EFDE0BBB
key: C51E9F2767B6747A9C9841AF7EEB9CC0E967D5B37CEC05B8C9DF310A03958AD2
title: Spring Street Art
description: At 11 Spring St. some of NYC's best street artists have canvassed (literally)
the building with art that is sprayed/painted/glued on the exterior and interior walls.
creationDate: Sun, 17 Dec 2006 14:06:30 -0500
packager: Yaron Samid
thumbnailURL: http://services.pando.com/soapservices/SendToWeb?action=thumbnail
  &id=5AEDE982393976A10050F2EC7C20C3C5EFDE0BBB
packageURL: http://cache.pando.com/soapservices/Package/package.pando?
  id=5AEDE982393976A10050F2EC7C20C3C5EFDE0BBB
  &key=C51E9F2767B6747A9C9841AF7EEB9CC0E967D5B37CEC05B8C9DF310A03958AD2
packageSize: 187249946
fileCount: 91
files: [object Object], ..., [object Object]
downloads: 55
expirationDate: Sat, 12 Dec 2026 15:42:20 -0500
Notice that the file metadata aren't listed. Each file is an object containing name and size properties. If we replace our callback function to just print out a file list, e.g.: 
function printPackageCallBack(packageInfo) {
  files = packageInfo['files'];
  for (var file in files)
	document.write(files[file].name +' : '+ files[file].size +' bytes<br />');
}
We get a (trimmed) list of file names, with sizes in bytes: 
Spring Street Art/IMG_8277.jpg : 2196499 bytes
Spring Street Art/IMG_8368.jpg : 2397601 bytes
Spring Street Art/IMG_8369.jpg : 2432566 bytes
  ...
Spring Street Art/IMG_8366.jpg : 2319711 bytes
Spring Street Art/IMG_8367.jpg : 2071726 bytes

Now go read Custom Package Previews with PandoAPI.js.

PandoAPI.hasPando

This method gives web sites outside of the pando.com domain limited access to the status of the pando.com "installed" cookie. It accepts a callback function as an argument. This callback function accepts one argument, which can be true or false. When you invoke PandoAPI.hasPando, it will call document.write and write a script into your page that runs the callback function with the value set to true or false. Your callback function decides what to do with this information. We recommend running this method in your page's section and then waiting until the page is fully loaded (i.e., window.onload) to make use of the results. Please see "Using PandoAPI.js Installed Cookie Check" for a detailed example.

‹ Package Info Web ServiceupIs Pando Installed? ›

Comments

Fri, 02/16/2007 - 00:05 — Juliette Hartel

When clicking certain links

When clicking certain links (e.g. "proxying calls on your own server" which opens http://developer.yahoo.com/javascript/howto-proxy.html) that take you out of the Pando developer website ... it can be surprising to leave the Pando developer website ... perhaps either putting up a notification page that the viewer is going to leave the Pando developer website or opening the link into a new tab or window ... depending upon the users brower might be a better user experience.

Sun, 02/18/2007 - 13:58 — laird

Good point. I've changed the

Good point. I've changed the links to open new browser windows. Thanks!

- Laird Popkin, CTO, Pando Networks

Sun, 01/20/2008 - 19:17 — formoco

wm. walston, trying to get

wm. walston, trying to get my website in all search engines for free. www.repairmanual.com/ford repair manuals.