PitchPeek

PitchPeekJS Documentation

Intro Options Public Functions XML Menus XML Sandbox XML Hotspots Option Reference Download

Getting Ready

Include the Google Maps Api and pitchpeek.js in the head of your page.

<script src="//maps.googleapis.com/maps/api/js?v=3"></script>
<script src="//cdn.jsdelivr.net/pitchpeek/1.0/pitchpeek.min.js"></script>

Somewhere on your page, create a div with an id, with width & height.

<div id="sample-panorama" style="width:500px;height:280px;">
  you can put placeholder text or an image in your div
</div>

Hello World

Now we're ready to create our first pitchpeek object using the id of our div.

<script>
  var pano = new pitchpeek('sample-panorama');
</script>

You can click the buttons in this tutorial to watch the code work on the sandbox div to the right, and interact with your new pano object. This seems easiest on a wide screen.

Setting Options

Now we have created the "Hello World" of pitchpeek. A bit more has happened behind the scenes, so now is a good time to understand what we've created and how to work with it. We've created a new object named pano, and we can use that name to access it's properties and call functions on it. We could also have another div somewhere else on the page named example and it would have it's own properties and functions. For the sake of simplicity, we'll just be using one right now and we'll call it pano.

Let's set some fun options and reload the tour. From now on we're just using javascript so remember to code in a js file or wrap your code inside of a <script> tag.

pano.options.rotatingStart=true;
pano.options.initialPano='YuxV_6KDjN0AAAQYn87sYg';
pano.tour();

We just set some properties, and then called the public function tour() which loads the Streetview again using the new values. This is very handy when you want to start with an initial tour and then make some changes based on user interactions, like we're doing right now in the sandbox. But sometimes you just need to set your options once when the page loads and then leave it. So you can pass your options to the pitchpeek constructor, which will override the default values as it's loading the tour.

var myOptions={
  initialPano:'YuxV_6KDjN0AAAQYn87sYg',
  rotatingStart:true,
  rotatingSpeed:-.3
};
var pano=new pitchpeek('sample-panorama',myOptions);

And for minimalists, the one-liner...

var pano = new pitchpeek('sample-panorama',{initialPano:'YuxV_6KDjN0AAAQYn87sYg', rotatingStart:true, rotatingSpeed:-.3});

There are 47 different options that can be set. Most of them apply to styling the menus and hotspots. The reference section describes what they all do and their defaults. If you find yourself always using the same options in every tour on your site, then edit the defaults in your pitchpeek.js and you can shorten your one-liners down to very little. You can probably get away with just setting initialPano or xml. That's the beauty of open source, you can customize this file to your needs, just keep the license and copyright intact.

Public Functions

We've already learned one public function, tour() to reload the Streetview. There are several private functions running inside of the pitchpeek object that you can't control from your pano object, but the public ones can be called from it.

setView()

setView takes a complete or partial "view" object, and uses whatever parts you've given to update the Point-of-View and Node. Here is a complete setView call with all four parts, they can be in any order.

pano.setView({panoid:'T_AD3kCDL2q7R5WTATYMtQ',heading:35.234,pitch:7.4234,zoom:0});

Note that the entire pano didn't need to reload, and tour() wasn't called. (And if you reload the entire page and click this before loading any pitchpeek it won't work) That's a little clearer when we just change the zoom. You can also go back and click on a previous example, then come back and click "Zoom to Level 2", and it will zoom in on whatever Node you're currently on.

pano.setView({zoom:2});

Maps Api Functions

The functions use the existing functions in the Google Maps Api. This one is just too convenient, so I made it a public function and allowed partial views. But it's really not cool to "wrap" api functions! The Google Maps Api and the Streetview Service are just too amazing to conceal, but luckily we can access everything in the api right through pitchpeek. The pano object we made holds a very special object named panorama. It's the same StreetViewPanorama object that you get when you use the api alone. So we can access all of the awesomeness of the api even though we've created it with the pitchpeek constructor.

pano.panorama.setPano('0CZbDohuBIPKkHr3N9AulQ');

The maps api is huge and we're barely going to scratch the surface, so you should really go and check it out. Here's one more that we'll use later, I'm using jquery to put the results into our "console" but you don't need jquery for this to work. (We'll get into the real console later.) For some example code we'll use alert.

alert(pano.panorama.getPano());

Notice how you can move from node to node, and getPano returns a different panoid. We're going to build on that next.

XML Menus

You can store your tour data in xml. So we're going to need to make some xml before we can even try this. We know that to jump to a particular view, we need those 4 peices of information. Let's write a quick function, we'll pass it our pano.panorama object and use the Maps Api to grab those 4 values, and then generate some xml to put in in the console. We can use \t for tabs, and \n for new lines.

function getViewXml(panorama){
  var pov=panorama.getPov();
  var pano=panorama.getPano();
  var output='<VIEW>\n'+
  '\t<PANOID>'+pano+'</PANOID>\n'+
  '\t<TITLE>Title Here</TITLE>\n'+
  '\t<HEADING>'+pov.heading+'</HEADING>\n'+
  '\t<PITCH>'+pov.pitch+'</PITCH>\n'+
  '\t<ZOOM>'+pov.zoom+'</ZOOM>\n'+
  '</VIEW>';
  return output;
}

So if we navigate to some nice places, click the button below, and copy the xml to a new xml file, we're almost ready to load up that xml in pitchpeek.

Ok, by now you have some xml ready to become menus. You've probably even updated the titles, if you forgot what they are then you might want to just give them different names so you can see what you're doing next. Take your xml, wrap it inside of this TOUR tag, and save your file as menu1.xml so it looks similar to what you see below. 

<?xml version="1.0" encoding="ISO-8859-1"?>
<TOUR>
  <VIEW>
    <PANOID>lJx8bcjyxIkAAAQXLB5-ww</PANOID>
    <TITLE>Hostess Station</TITLE>
    <HEADING>31.4052</HEADING>
    <PITCH>0.821235</PITCH>
    <ZOOM>0.66</ZOOM>
  </VIEW>
  <VIEW>
    <PANOID>wTbeLGpIbTwAAAQXL3sjzQ</PANOID>
    <TITLE>Waterfront</TITLE>
    <HEADING>-31.0324</HEADING>
    <PITCH>-2.32015</PITCH>
    <ZOOM>0</ZOOM>
  </VIEW>
</TOUR>

Awesome, now we can use our menu1.xml file to generate the menus!

var pano = new pitchpeek('sample-panorama',{xml:'menu1.xml'});

Hopefully you got that to work, and by setting some of our special options, we can have our new tour land on any of the views in our file or stick with the initialPano. Hey, I just remembered about the great view of the stage, but I only want to show that sometimes... I can load a second xml file using another public function, loadXMLDoc().

pano.options.xml='menu2.xml';
pano.loadXMLDoc(pano.options,pano.panorama);

And we can call xml files all day long! Click it a couple times to add stage over and over. Want to reset? Give it a tour() call, and it will reload with just one file, the last one you set in options.xml.

pano.tour();

XML Sandbox

Drop the peg-person, use previews in the sandbox, get your xml, and wrap it up!

You can copy the wrapped xml into a file. If you've understood the tutorial, you have everything you need to get started.

XML Hotspots

Hotspots can be loaded in the same xml file. I'll let you figure out how to build your hotspot xml on your own. Here's the spec. 

<HOTSPOT>
  <TITLE>Dock</TITLE>
  <LATITUDE>42.5429</LATITUDE>
  <LONGITUDE>-71.4437</LONGITUDE>
  <CONTENT><![CDATA[<p>Take a <b>big leap</b> and learn to swim.</p>]]></CONTENT>
  <SHOW>
    <PANO>lJx8bcjyxIkAAAQXLB5-ww</PANO>
    <PANO>wTbeLGpIbTwAAAQXL3sjzQ</PANO>
  </SHOW>
</HOTSPOT>

Add these HOTSPOT tags right after your VIEW tags in your xml. The panoids that you list inside of SHOW control where this hotspot will be shown, so you can see a hotspot as you walk around but can remove it if you go around a corner or your view of the object you're highlighting is obscured. The hotspots will scale, so if you're walking towards one and it's turned on it several panos, it will grow as you approach. The height (anchor), scaling, colors, and the svg paths of the icons can all be changes by setting options.

pano = new pitchpeek('sample-panorama',{xml:'hotspot.xml', hotspotScale:1});

One last thing before we jump into options. There is a real console in Chrome that you can use on any page. Press F12 to launch the developer tools, and on the top menu click on Console. The console knows what public properties and functions are available to you and will help you finish your own thoughts! Try typing in some of the functions discussed in this tutorial, for example, pano.panorama.getPano() and watch it spit back the panoid. This is very useful for debugging, because you can unit test your functions right on the same page where the action is happening. Ok, that's all for the tutorial, check out the options below and download your copy of pitchpeekJS. Don't forget that there's a new donate button floating around!

All Option Defaults

StreetViewPanorama Settings

	renderMode:'html5', //( webgl | html4 | html5 )
	disableDefaultUI: false,
	addressControl: false,
	zoomControl: false,
	clickToGo: false,
	linksControl: true,
	panControl: false,
	enableCloseButton: false,
	visible:true,

These settings are passed directly into the Google Maps Api, so updated information on them can be found in the amazingly detailed Street View Service Documentation

PitchPeek Startup Settings

	initTour:true, //false and tour() won't be called, allowing you to set additional options before calling tour() manually
	initialPano:'dwFEQYodwY0AAAQXL2YgRA', //you can set this to one of your own panos, it will load if xml fails
	xml:null, //null will skip xml loading, set a path to xml file to enable loading
	menuFirstId:0, //if set to 0, the first view in your xml file will be loaded. if set to -1, the second view will be loaded, -2 for the third ect... If you want a view that won't be in your menu, set it to any positive integer and your tour will load with initialPano

Rotation

	rotatingStart:false, //true will enable rotating
	rotatingStopOnHover:true, //false and it won't stop
	rotatingFramerate:33, //wait in milliseconds before advancing rotation
	rotatingSpeed:.1, //speed of rotation, bigger numbers go faster, negative numbers go counter-clockwise

Menus

	menuPosition:'LEFT_TOP', //see below for accepted values
	menuButtonBackgroundColor:'#fff',
	menuButtonBorder:'2px solid #fff',
	menuButtonBorderRadius:'3px',
	menuButtonBoxShadow:'0 2px 6px rgba(0,0,0,.3)',
	menuButtonCursor:'pointer',
	menuButtonMargin:'3px',
	menuButtonMinWidth:'100px',
	menuButtonOpacity:.9,
	menuButtonTextAlign:'center',
	menuButtonTitlePrepend:'Click to go to ', //before your slide title
	menuButtonTitleAppend:'.', //after your slide title
	menuTextColor:'rgb(25,25,25)',
	menuTextFontFamily:'Roboto,Arial,sans-serif',
	menuTextFontSize:'16px',
	menuTextLineHeight:'38px',
	menuTextPaddingLeft:'5px',
	menuTextPaddingRight:'5px',

Accepted Menu Positions

  • TOP_CENTER top center
  • TOP_LEFT top left, with buttons flowing towards the top center
  • TOP_RIGHT top right, with buttons flowing towards the top center
  • LEFT_TOP top left, but below any TOP_LEFT elements
  • RIGHT_TOP top right, but below any TOP_RIGHT elements
  • LEFT_CENTER left side, centered between the TOP_LEFT and BOTTOM_LEFT positions
  • RIGHT_CENTER right side, centered between the TOP_RIGHT and BOTTOM_RIGHT positions
  • LEFT_BOTTOM bottom left, but above any BOTTOM_LEFT elements
  • RIGHT_BOTTOM bottom right, but above any BOTTOM_RIGHT elements
  • BOTTOM_CENTER bottom center
  • BOTTOM_LEFT bottom left, with buttons flowing towards the bottom center
  • BOTTOM_RIGHT bottom right, with buttons flowing towards the bottom center

Hotspots

	infowindowMaxWidth:null, //400   don't write px
	contentBefore:'<div id="content">', //before and after wrap content
	contentAfter:'</div>', 
	hotspotDraggable:false, //true will allow dragging hotspot icons
	hotspotStrokeColor:'#000',
	hotspotFillColor:'#0266C8',
	hotspotOpacity:.9,
	hotspotRotation:0,
	hotspotScale:2, //blow up your vector icons
	hotspotAnchorX:0, //position your icon left or right
	hotspotAnchorY:0, //position your icon up or down
	hotspotSvgIcon:'M16,1.466C7.973,1.466,1.466,7.973,1.466,16c0,8.027,6.507,14.534,14.534,14.534c8.027,0,14.534-6.507,14.534-14.534C30.534,7.973,24.027,1.466,16,1.466z M14.757,8h2.42v2.574h-2.42V8z M18.762,23.622H16.1c-1.034,0-1.475-0.44-1.475-1.496v-6.865c0-0.33-0.176-0.484-0.484-0.484h-0.88V12.4h2.662c1.035,0,1.474,0.462,1.474,1.496v6.887c0,0.309,0.176,0.484,0.484,0.484h0.88V23.622z' //accepts an svg icon path

Need a bunch of svg icon paths to choose from? I got the default one here.

Simple Fullscreen Webpage Example

<!DOCTYPE html>
<html>
  <head>
    <script src="https://maps.googleapis.com/maps/api/js?v=3"></script>
    <script src="pitchpeek.min.js"></script>
  </head>
  <body>
    <div id="sample-panorama" style="position:absolute; left:0px; top:0px; width:100%; height:100%;" >
      oops, it hasn't loaded
    </div>
    <script>
      var pano = new pitchpeek('sample-panorama',{renderMode:'html5'});
    </script>
  </body>
</html>

View FullScreen Sample

Sandbox


Console